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": "[email protected]",
  "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