AquaIllumination Hydra and Prime HD Lights

AquaIllumination have a range of WiFi enabled aquarium lights, which are controllable from a mobile app, or via a web app. They don’t publish any APIs for their range of lights but I managed to reverse engineer their API and created a python module AquaIPy to allow control of the lights.

I’ve created a HA component to support these lights, which can be found here:

Currently it supports:

  • Individual control of each light channel, as a seperate light entity in HA.
  • Control over if the light is in ‘Schedule Mode’, via a switch entity.
  • A separate sensor entity for each light channels brightness value (making graphing easier).

Some caveats:

  • Although these lights support boosting some light channels to more than 100%, this component doesn’t yet support this.
  • Adjusting the light channels when ‘Schedule Mode’ is enabled will cause the lights to flash the new light level, before returning to the previous light level.


The required config in configuration.yaml, is very simple. Both host and name are required but nothing else is required. If you have multiple lights paired together, then you should specify the parent light. If you don’t you will get an error. Here is an example of a config with two lights.

  - host:
    name: sump ai
  - host:
    name: dt ai

I’m using this component with a custom Lovelace entity, lovelace-slider-entity-row. It’s not required to use this entity but it makes the component more usable. The screenshot above shows this Lovelace UI in action. Here’s my config, as an example, for one light.

  - entity: light.sump_ai_uv
    step: 1
    type: 'custom:slider-entity-row'
  - entity: light.sump_ai_violet
    step: 1
    type: 'custom:slider-entity-row'
  - entity: light.sump_ai_royal
    step: 1
    type: 'custom:slider-entity-row'
  - entity: light.sump_ai_blue
    step: 1
    type: 'custom:slider-entity-row'
  - entity: light.sump_ai_green
    step: 1
    type: 'custom:slider-entity-row'
  - entity: light.sump_ai_deep_red
    step: 1
    type: 'custom:slider-entity-row'
  - entity: light.sump_ai_cool_white
    step: 1
    type: 'custom:slider-entity-row'
title: Prime HD
type: entities

Next Steps

  • I intend to contribute this back into HA, if they will accept it, since I think it’s a good candidate for a new platform. I’ll probably remove the sensor when submitting it, as the HA way of doing this would probably be to use a template sensor for each light channel.

  • Support for setting multiple light channels at once. It’s quite jarring as it is, since there is a slight delay in each channel adjusting, if you do it in a script. This will be implemented by adding a service for this component.

  • Support for the HD range of these lights (ie. driving channels over 100%. Not sure how I will support this yet, it may have to be via custom front end code, since it really needs the UI to be aware of the max power output limitations. The underlying python module supports it, so it’s just down to how to integrate that into HA.

  • It would be nice to have the graph and the UI use an appropriate colour for each color channel. There doesn’t seem to be a great way of doing any of that though, so it may remain a pipe dream.

I created the python module late last year and then built a test platform for HA soon afterward. I never did a write up on this at the time, as I was working out some kinks. I made some major changes recently and finally I’m pretty happy with how this all works. I’m keen for any feedback, if anyone has any?


Nice! I was looking for a way to get my Prime HD integrated with HA. (The fish we’re feeling sad… they were the only thing in my house not on HA. :smiley: )

Any plans to get this into the HACS store?

Thanks. Yes, hopefully I’ll get a chance to add it to the HACS store…just started a new job, so I’ve been pretty busy. I’ve a got a few HA projects to catch back up on :slight_smile:

1 Like

Does it support old version hydra light controlled by director ?

Not yet. I haven’t had access to the old model to try to add support. I’m keen to work with you to add that support, if you want to?

If we could try it will be fine. What do yo need ? You did you use an API with Ai web site ?

I used the unpublished API that is used by the phone app, when it is connecting to the device locally on your network.

Are you able to reach the device through it’s IP address on your network? When we do it for the newer models it shows a webpage

I could fine IP of the director.

Hi Stephen.
I could me connect directly by browser with the director IP. How to proceed next ?

I am just about to change my lights to the 32HD so really looking forward for this to work. Has anyone tried these on the new range of AI lights?

Quite dissapointed. The new range of Prime 16HD, Hydra 32HD and 64HD are now bluetooth based and not Wifi/AiFi based though the light quality is far better than the previous models but unfortunately that means that for now there is no way to control the lights using HA. Wish I knew as I would have gone for Radions instead.

That is disappointing. I’m sure there will be a way to integrate them still but it will be quite different.

Hey Stephen, thank you for the work on they Hydra’s. I have 3 Hydra52s on my reef.
Ive been attempting to get your component to work but have been unsuccessful at doing so.
Im running home assistant 0.104.0 on hassio and firmware version 2.5.1 on the hydras. Ive put the aquaillumation as well as AquaIPy components in the custom_components folder and added the corresponding information to my configuration.yaml file
On restart, I get a notification that about a failure to load the component and to check the config.
Can you point me in the right direction?

Many Thanks! :slight_smile:

I came here looking for this. I use HomeAssistant and I’m looking for better integration with my aquarium.

My 73 gallon reef tank has two AI Prime HD’s and one Hydra. Yeah, the Hydra is bluetooth only and I wish I’d realized that before buying it. But I’d love to at least get the Prime’s in Home Assistant.

Are there lights that are more natively suited to working with HomeAssistant? I’m not beyond making some hardware swaps. Or is this integration on any kind of path to being included in Home Assistant? If so, I’d load up on Primes.

Thanks for this!

I’m running a AI Prime Freshwater light (2 soon!) and this works well. Awesome stuff!

i’m new to this integration, so i’m not sure if this is a new issue or not. but on my hydra26, the “Scheduled Mode” can’t be turned on/off via this integration. which means setting any light values will reset to the prior state after a few seconds.

anyone else having this issue or a fix?

Hmm, strange. Is there any error in the log for HA? What version of the firmware are you running?

no errors in the logs. firmware version 2.5.1

What version of HA are you using?

sorry i thought you meant hydra firmware. ha version is 2020.12.1