Zodiac / Jandy iAquaLink smart home integration, free and open source
Zodiac / Jandy iAquaLink pools: temperatures, pumps, heating, lights, eXO chlorinators.
Published by LM1LC3N7
- Devices
- Version 0.1.2
- Requires Gladys >=5.1.0
- ★ 0
Brings your iAquaLink pool systems into Gladys, through the iAquaLink cloud (the one of the iAquaLink mobile app):
- Jandy iAquaLink panels (iQ20, AquaLink RS with an iAquaLink module): pool, spa and air temperatures, pool and spa pumps, pool, spa and solar heaters, pool and spa set points, lights (on/off, brightness of dimmable lights), auxiliary outputs, and pH, ORP and salinity when the panel reports them;
- Zodiac eXO iQ chlorinators: water temperature, pH, ORP, their set points, chlorine production level, chlorine production on/off, boost, low mode, filter pump, auxiliary outputs, heating (on/off and set point) when a heating module is present, and a status text (error code, low salt).
This integration has never been tested on a real iAquaLink account or system yet: it is a port of the iaqualink-py library used by Home Assistant, checked against sample answers only. Feedback is welcome on the Gladys forum.
Unofficial: not affiliated with Zodiac, Jandy or Fluidra.
Set up
- In Gladys, open Integrations, install Zodiac / Jandy iAquaLink.
- In its configuration, enter the email and password of your iAquaLink account (the ones you use in the iAquaLink app). The password is a secret field: Gladys never shows it again, and the integration sends it only to the iAquaLink sign-in service.
- The status shows Connected to iAquaLink and the number of pool systems. Open the Discovery tab and add your systems.
The Test the connection button signs in and reads the account at once (at most every 30 seconds), and gives a short summary.
Options
| Option | Default | What it does |
|---|---|---|
| Allow commands from Gladys | off | The pool is only read until you tick it. Then: pumps, heaters, set points, lights and the eXO switches. |
| Also allow the auxiliary outputs | off | The plain auxiliaries and valve actuators of the panel, and the aux outputs of the eXO. Needs the option above too. |
| Show the unnamed auxiliaries | off | Auxiliaries still named "Aux 3", "Aux V12" or "Extra Aux" on the panel are left out unless this box is ticked. |
| Refresh interval (seconds) | 60 | How often the pool is read: 30 seconds at the fastest. |
| Language | French | Names of the features of the systems added from now on, and the status text. |
An auxiliary output can drive anything wired to it: a cleaner, a water feature, but also a valve (spa spillover, solar...), and the iAquaLink valve actuators (SJVA) are auxiliaries too. That is why they have their own option, off by default: tick it only if commanding them from Gladys is safe for your installation.
Limits of use
- iAquaLink publishes no API nor quota: the integration uses the endpoints of the iAquaLink app, like Home Assistant. It reads every system at the refresh interval (two requests for a panel, one for an eXO), the list of systems every 30 minutes, and never sends more than 20 requests a minute, commands included.
- After an error it waits 1, 2, 5, 10 then 15 minutes; when iAquaLink asks to slow down (HTTP 429) it pauses for the time asked (15 minutes otherwise), commands included.
- A refused email or password is not tried again for 6 hours, or at once after you change it (or with the Test button), so the account is not locked.
- The session (IdToken) is renewed before it expires; a refused refresh token leads to one new sign-in, never more than one every 5 minutes. A sign-in without any answer (internet box still starting after a power cut...) follows the normal pauses of 1 to 15 minutes. After three sign-ins in a row that the service answers badly (5xx error, unreadable answer), the next try waits 1 hour, or a change of the email or the password, or the "Test the connection" button.
How commands work
The pumps, heaters and plain auxiliaries of an iAquaLink panel only know a toggle command. So, for each command, the integration:
- reads the state of the panel again, right before (within 4 seconds: Gladys waits 5 seconds for the answer; a slower read sends nothing);
- refuses when the panel is offline, or when the state of the equipment cannot be read;
- sends nothing when the equipment is already in the asked state;
- otherwise toggles once. For the next 60 seconds, unless the panel already reports the change, the equipment is expected in its new state: asking it again succeeds without sending anything, asking the old state is refused (a second toggle would undo the first one).
Commands of one system run one at a time. Dimmable and colour lights, set points and every eXO command take an absolute value instead. Set points must stay between 1 and 40 °C (34 and 104 °F); a panel paired with a heat pump receives them through the heat pump command, like in the iAquaLink app.
A colour light turned on starts on its first colour (the effects are not handled yet).
Not supported yet
- Robot cleaners (i2d, Vortex, Cyclobat), standalone Zodiac heat pumps and iQPump: they are counted as "not supported yet" in the status.
- OneTouch scenes, the variable-speed pumps of a panel, IntelliCenter light zones, colour effects, the controls of a heat pump paired with a panel.
Privacy
The email and password stay in the Gladys configuration. The integration
keeps only, in its /data volume, the features and auxiliaries already seen
and the temperature unit of each system, so the Discovery tab stays the same
after a restart. No token or password is ever written to disk or to the logs.
Licence and credits
Apache License 2.0. The iAquaLink logic is ported from
flz/iaqualink-py (BSD-3-Clause, see
THIRD_PARTY_NOTICES.md).
Configuration settings
These are the settings Zodiac / Jandy iAquaLink asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Your iAquaLink pool | section | No | Brings your iAquaLink pool systems into Gladys through the iAquaLink cloud: Jandy iAquaLink panels (pool, spa and air temperatures, pumps, heaters and set points, lights, auxiliaries) and Zodiac eXO iQ chlorinators (chlorine production, boost, pH, ORP, water temperature, status). Enter the email and password of your iAquaLink app account, then add your systems from the Discovery tab. Commands stay off until you allow them below. The cloud is read every minute by default (30 seconds at the fastest), with longer pauses after errors. Unofficial, not affiliated with Zodiac, Jandy or Fluidra; never tested on a real system yet. |
| iAquaLink email | string | Yes | The email you sign in to the iAquaLink app with. |
| iAquaLink password | secret | Yes | Kept by Gladys, sent only to the iAquaLink sign-in service, never shown again nor logged. |
| Allow commands from Gladys | boolean | No | Off by default: the pool is only read. Once ticked: pumps, heaters, set points, lights and the switches of the eXO chlorinator. Each command reads the state again just before it is sent. |
| Also allow the auxiliary outputs | boolean | No | The plain auxiliaries of the panel, its valve actuators and the aux outputs of the eXO can drive anything, a valve included: they stay read-only unless this box (and the one above) is ticked. |
| Show the unnamed auxiliaries | boolean | No | Auxiliaries still named "Aux 3", "Aux V12" or "Extra Aux" on the panel are usually unused: they are left out unless this box is ticked. |
| Refresh interval (seconds) | number | No | How often the pool is read: 30 seconds at the fastest, to stay gentle with the iAquaLink cloud. |
| Language of the feature names | select | No | Used for the names of the features of the systems added from now on, and for the status text. |
How to install Zodiac / Jandy iAquaLink in Gladys
- In Gladys, open Integrations: Zodiac / Jandy iAquaLink appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/lm1lc3n7/gladys-iaqualink:0.1.2), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/LM1LC3N7/gladys-iaqualink.
Zodiac / Jandy iAquaLink requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.
Not running Gladys yet? It is free and open source: follow the installation guide to get started.
About external integrations
Zodiac / Jandy iAquaLink is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by LM1LC3N7, not by the Gladys core team.
- Browse all integrations, native and community
- Build and publish your own external integration
- Source code on GitHub — source of this documentation