homebridge-iaqualink

A Homebridge plugin for Jandy/Zodiac iAquaLink pool and spa controllers. Control your pool equipment — pumps, heaters, lights, auxiliary devices, and more — directly from the Apple Home app and Siri.

---

Features

• 🏊 Pool & spa pump on/off control
• 🔥 Heater control with temperature set point (pool and spa)
• 💡 Lights — simple on/off, dimmable (25% increments), and multi-color effects
• 🔧 Auxiliary devices — auto-discovered; fans, valves, and switches all supported
• 🌡️ Temperature sensors — pool, spa, air, and solar temps
• ❄️ Freeze protection indicator
• 🔁 Automatic polling — keeps HomeKit state in sync (configurable interval)
• 🔐 Token auto-refresh — stays authenticated without re-entering credentials
• ✅ Homebridge Config UI X support

---

Requirements

• Homebridge v1.6.0 or later
• Node.js v18.0.0 or later
• A Jandy/Zodiac iAquaLink controller with an active iAquaLink account
  • Compatible with iAqua systems (iaqualink.net API)
  • Pool controllers: iAquaLink 2.0, iAquaLink RS, etc.

---

Installation

Option 1 — Homebridge Config UI X (recommended)

1. Open the Plugins tab in Homebridge Config UI X.
2. Search for homebridge-iaqualink.
3. Click Install.
4. Fill in your credentials in the plugin settings and click Save.
5. Restart Homebridge.

Option 2 — Manual

npm install -g homebridge-iaqualink

Then add the platform to your ~/.homebridge/config.json (see Configuration below) and restart Homebridge.

---

Configuration

Minimal config

{
  "platforms": [
    {
      "platform": "iAquaLink",
      "name": "iAquaLink",
      "username": "your@email.com",
      "password": "your-password"
    }
  ]
}

All options

{
  "platforms": [
    {
      "platform": "iAquaLink",
      "name": "iAquaLink",
      "username": "your@email.com",
      "password": "your-password",
      "pollingInterval": 30,
      "temperatureUnit": "F"
    }
  ]
}

Option	Type	Default	Description
platform	string	required	Must be "iAquaLink"
name	string	"iAquaLink"	Display name for the platform
username	string	required	Email address for your iAquaLink account
password	string	required	Password for your iAquaLink account
pollingInterval	number	30	How often (seconds) to poll for state updates. Min: 10, Max: 300
temperatureUnit	"F" | "C"	auto-detected	Override the temperature unit. If omitted, the unit is read from your controller.
auxiliaryDevices	array	—	Optional overrides for individual auxiliary outputs. See Auxiliary Devices below.

---

Supported Devices

All devices are auto-discovered from your iAquaLink account on startup. No manual configuration is needed for pumps, heaters, temperatures, or named auxiliary devices.

Pool & Spa Equipment

iAquaLink Device	HomeKit Service	Notes
Pool Pump	Switch	On/Off
Spa Pump	Switch	On/Off
Pool Heater	Switch	On/Off; also controls the Pool Thermostat heating mode
Spa Heater	Switch	On/Off; also controls the Spa Thermostat heating mode
Pool Set Point	Thermostat	Current temp (from sensor), target temp, heater on/off
Spa Set Point	Thermostat	Current temp (from sensor), target temp, heater on/off
Pool Temperature	Temperature Sensor	Read-only
Spa Temperature	Temperature Sensor	Read-only
Air Temperature	Temperature Sensor	Read-only
Solar Temperature	Temperature Sensor	Read-only
Freeze Protection	Occupancy Sensor	Active = freeze protection is enabled

Auxiliary Devices

Auxiliary outputs are auto-discovered. The HomeKit service is determined by the iAquaLink type field:

iAquaLink type	HomeKit Service	Example devices
0 — generic switch	Switch	Spa jets, cleaners, chlorinators
1 — dimmable light	Lightbulb (with brightness)	Dimmable pool/spa lights
2 — color light	Lightbulb (with effect selector)	Jandy WaterColors, Pentair SAm/SAL

Only named devices appear. Auxiliary outputs that have not been given a name in the iAquaLink app (i.e. their label is still aux_1, aux_2, etc.) are automatically hidden. Name them in the iAquaLink app and they will appear on the next Homebridge restart.

Overriding the HomeKit service type

Use auxiliaryDevices in your config to override how a specific output is presented in HomeKit — useful for fans, water valves, and bubblers that iAquaLink reports as a generic switch:

{
  "platforms": [{
    "platform": "iAquaLink",
    "username": "your@email.com",
    "password": "your-password",
    "auxiliaryDevices": [
      { "aux": "1", "type": "switch", "name": "Spa Jets" },
      { "aux": "2", "type": "fan",    "name": "Aerator" },
      { "aux": "3", "type": "valve",  "name": "Waterfall", "valveType": "faucet" },
      { "aux": "4", "type": "valve",  "name": "Bubblers",  "valveType": "generic" }
    ]
  }]
}

aux	The auxiliary output number ("1" = Aux 1, "2" = Aux 2, …)
type	"switch", "fan", or "valve"
name	Optional display-name override shown in the Home app
valveType	Only for "valve": "generic", "irrigation", "shower", or "faucet"

Config overrides take priority over the auto-detected type from iAquaLink.

---

Building from Source

# Clone the repo
git clone https://github.com/dcmarine/iaqualink.git
cd iaqualink

# Install dependencies
npm install

# Compile TypeScript
npm run build

# Watch mode (auto-recompile on save)
npm run watch

Linking to Homebridge for local development

# From the plugin directory
npm link

# In your Homebridge install directory
npm link homebridge-iaqualink

---

Docker / Homebridge Container

If you're running Homebridge in Docker (as in the included homebridge/compose.yaml):

Install from npm (recommended)

docker exec homebridge npm install -g homebridge-iaqualink
docker restart homebridge

Install from local source

The dist/ folder is pre-built and included in the repository, so no compilation step is needed inside the container.

# Copy the whole repo (including dist/) into the container
docker cp . homebridge:/tmp/homebridge-iaqualink

# Install from the local directory
docker exec homebridge npm install -g /tmp/homebridge-iaqualink

# Restart Homebridge
docker restart homebridge

Reinstall after source changes

After editing src/ files, rebuild locally first, then re-copy:

npm run build   # regenerates dist/
docker cp . homebridge:/tmp/homebridge-iaqualink
docker exec homebridge npm install -g /tmp/homebridge-iaqualink
docker restart homebridge

---

Troubleshooting

Pool/spa devices not appearing in HomeKit

• Ensure your iAquaLink system type is iaqua (standard Jandy/Zodiac pool controller). eXO chlorinators and Zodiac robotic cleaners use different APIs and are not currently supported.
• Check the Homebridge logs for login or API errors.

Auxiliary devices not appearing

• Auxiliary outputs must be named in the iAquaLink app before they appear in HomeKit. Outputs still using the default name (Aux 1, aux_1, etc.) are intentionally hidden.
• Name the device in the iAquaLink app, then restart Homebridge.
• Enable Homebridge debug logging (-D) to see a line like Skipping unnamed aux device: aux_3 which confirms the device is being discovered but filtered out.

Auxiliary device shows as wrong type (Switch instead of Fan/Valve)

• iAquaLink only reports type 0/1/2 (switch/dimmable/color). For fans and valves add an entry to auxiliaryDevices in your config with the correct type. See Auxiliary Devices.

"Service Communication Failure" in Home app

• Verify your iAquaLink credentials are correct.
• Confirm the iAquaLink app itself can connect to your system.
• Try increasing the pollingInterval to reduce API load.

Temperatures showing as "Not Available"

• The controller may report empty temperature values when sensors are not connected or the system is offline. This is normal.

Homebridge log shows 429 errors

• You are being rate-limited by the iAquaLink API. Increase your pollingInterval (e.g., 60 or higher).

---

Compatibility

System	Status
Jandy iAquaLink 2.0 / RS	✅ Supported
Zodiac iAquaLink	✅ Supported
eXO Chlorinator	⚠️ Not yet supported
Zodiac Robotic Cleaners (Polaris, Cyclonext)	⚠️ Not yet supported

Note: This plugin uses the reverse-engineered iAquaLink REST API (r-api.iaqualink.net). It is not affiliated with, endorsed by, or supported by Jandy, Zodiac, or Fluidra.

---

License

MIT — see LICENSE.