homebridge-pentair-cloud

Homebridge plugin for Pentair pool equipment via the Pentair Home cloud API.

Supported Devices

• IntelliFlo VSF / Variable Speed Pump (IF31) — on/off and speed control
• IntelliBrite / Color Sync Light Controller (PLC1) — on/off and color scene selection

Installation

Search for Pentair Cloud in the Homebridge UI plugin search, or run:

npm install -g homebridge-pentair-cloud

Configuration

Add to your Homebridge config.json under platforms:

{
  "platform": "PentairHomebridge",
  "name": "Pentair Cloud",
  "email": "your@email.com",
  "password": "yourpassword",
  "pump": {
    "deviceId": "PNR08XXXXXXXXXX",
    "name": "Pool Pump"
  },
  "light": {
    "deviceId": "PNRAXXXXXXXXXX",
    "name": "Pool Light"
  }
}

Finding device IDs: On first startup, the plugin logs all devices found on your Pentair account with their IDs. Check the Homebridge log and copy the deviceId values into your config.

Config Options

Field	Required	Description
email	Yes	Pentair Home account email
password	Yes	Pentair Home account password
pump	No	Pump accessory config
light	No	Light accessory config
pump.deviceId	Yes (if pump set)	Pump device ID
pump.name	No	HomeKit display name (default: "Pool Pump")
light.deviceId	Yes (if light set)	Light device ID
light.name	No	HomeKit display name (default: "Pool Light")

HomeKit Behaviour

Pump (Fanv2)

• Active — turn the pump on or off
• RotationSpeed — pump speed as a percentage:
  • 1–25% → Program 1 (low)
  • 26–50% → Program 2 (medium)
  • 51–75% → Program 3 (medium-high)
  • 76–100% → Program 4 (high)
  • 0% → off

Light (Lightbulb)

• On/Off — toggle the light
• Hue — selects a color scene:
  • Red (0–20°) / Magenta (291–339°) / Purple (261–290°) / Blue (201–260°)
  • Teal/Caribbean (151–200°) / Green (61–150°) / Orange/Sunset (21–60°)
• Saturation — color intensity; < 20% selects White mode

Troubleshooting

Debug Logging

Enable debug logging to see raw API responses and diagnose issues:

# When starting homebridge
homebridge -D

# Or in config.json log level
"pluginMap": {
  "homebridge-pentair-cloud": {
    "debug": true
  }
}

Raw device status is logged at debug level in both pump and light accessories, which helps identify all status fields available from your device.

Failed to authenticate: USER_PASSWORD_AUTH flow not enabled

Upgrade to v1.1.2 or later. Versions before 1.1.2 used an authentication flow that the Pentair Cognito app client does not enable. v1.1.2 rewrites the auth layer to use the full SRP (USER_SRP_AUTH) flow.

Siri Requests hang or timeout

v1.0.5+ includes a 10-second timeout on all API requests. If requests still time out, check your network connection to api.pentair.cloud.

Device names show as "Unknown"

The device list API sometimes returns empty names. This is cosmetic and does not affect control — use device IDs to identify devices.

Requirements

• Homebridge ≥ 1.6.0
• Node.js ≥ 22.0.0
• Active Pentair Home account with cloud-connected equipment

How It Works

The plugin authenticates with Pentair Home via AWS Cognito (SRP auth), exchanges the ID token for temporary AWS credentials, then signs all API requests with AWS Signature V4.

API endpoints used:

Operation	Endpoint
List devices	GET /device/device-service/user/devices
Device status	POST /device2/device2-service/user/device
Send command	PUT /device/device-service/user/device/{deviceId}

Changelog

See CHANGELOG.md for version history.

License

MIT