homebridge-rainbird-iq4

Homebridge dynamic platform plugin for Rain Bird IQ4 Cloud controllers (e.g. ESP-ME3 / LNK2). It talks to the same cloud API as the Rain Bird 2.0 app: REST for control, AWS AppSync WebSockets for realtime zone state.

Features

• Username/password login via OIDC authorization code + PKCE
• Persisted refresh tokens (survives Homebridge restarts)
• Auto-discovery of controllers linked to the account
• Per controller, each control is its own accessory (one primary service each, so the Home app renders them as clean, individually named tiles with no duplicated/grouped valves):
  • One irrigation Valve accessory per watering zone (sprinkler icon, on/off, run duration)
  • One Switch accessory for rain delay
• Realtime AppSync subscriptions, with polling as a backup

Requirements

• Homebridge v1.8+ or v2 (Homebridge UI / hb-service supported)
• Node.js matching the plugin engines field (^22 or ^24)
• A Rain Bird IQ4 cloud account
• OAuth clientId / clientSecret captured from the Rain Bird 2.0 app (see below)

This plugin does not ship Rain Bird’s app OAuth credentials. You capture your own once and paste them into config.

Capture OAuth client credentials

Static extraction from the app package does not recover the credentials. Capture a live token request instead.

Requirements

• mitmproxy: brew install mitmproxy or pipx install mitmproxy
• Phone with the Rain Bird 2.0 app, on the same Wi‑Fi as this machine

Steps

1. Start the proxy from the repo root:

   ./tools/run_proxy.sh

   It prints this machine’s LAN IP and listens on port 8080.

2. On the phone: Wi‑Fi → (your network) → Configure Proxy → Manual
   Server = that LAN IP, Port = 8080.

3. First time only (HTTPS intercept): open http://mitm.it on the phone, install the mitmproxy CA, and trust it
   (iOS: Settings → General → About → Certificate Trust Settings).

4. Open the Rain Bird 2.0 app and sign in (log out first if already signed in so it hits the token endpoint).

5. Watch the terminal — on the token request it prints:

   ★ EXTRACTED OAuth client — client_id=… client_secret=…

   and writes captures/rainbird-keys-<stamp>.json.

6. Ctrl‑C, and turn the phone’s Wi‑Fi proxy back Off.

Optional: re-analyze a saved capture:

python tools/analyze_capture.py captures/rainbird-iq4-<stamp>.jsonl

Captures contain tokens and credentials — the captures/ folder is gitignored; never share those files.

Install (Homebridge UI on a Raspberry Pi)

From your Mac (adjust host/user):

rsync -av --exclude node_modules --exclude dist --exclude template --exclude captures \
  ./ pi@raspberrypi:~/homebridge-rainbird-iq4/

On the Pi:

export PATH="/opt/homebridge/bin:$PATH"

cd ~/homebridge-rainbird-iq4
npm install
npm run build

cd /var/lib/homebridge
sudo env PATH="/opt/homebridge/bin:$PATH" npm install --save ~/homebridge-rainbird-iq4
sudo hb-service restart

If /opt/homebridge/bin does not exist on your system, use the Node path shown by Homebridge UI → Settings.

Configuration

In Homebridge UI: Plugins → RainBird IQ4 Cloud → Settings, or in config.json:

{
  "platforms": [
    {
      "platform": "RainBirdIQ4",
      "name": "RainBird IQ4",
      "email": "[email protected]",
      "password": "your-password",
      "clientId": "captured-client-id",
      "clientSecret": "captured-client-secret",
      "defaultZoneMinutes": 5,
      "rainDelayDays": 1,
      "pollingInterval": 600
    }
  ]
}

| Field | Required | Description | |--------|----------|-------------| | email | yes | Rain Bird account email | | password | yes | Rain Bird account password | | clientId | yes | OAuth client ID from capture | | clientSecret | yes | OAuth client secret from capture | | defaultZoneMinutes | no | Default run time when a zone valve is turned on without setting a duration (default 5, min 1, max 240) | | rainDelayDays | no | Days when enabling the Rain Delay switch (default 1) | | pollingInterval | no | Backup status poll interval in seconds (default 600, min 30) |

After saving, restart Homebridge and check Logs for controller discovery and per-zone accessory setup.

Accessory layout

Each watering zone appears as its own irrigation valve accessory (e.g. Front Yard Zone 1), and each controller adds a <controller> Rain Delay switch accessory. There is no master power switch and no grouped irrigation system, which avoids the duplicated/unnamed valve tiles that the Home app can render for grouped IrrigationSystem accessories.

If you are upgrading from an earlier version that used a grouped IrrigationSystem, the old accessories are unregistered automatically on startup (watch for Removing obsolete accessory from cache in the logs). If ghost tiles persist in the Home app afterward, remove and re-add the child bridge once to clear iOS's cache.

Development

npm install
npm run build
npm run lint

License

Apache-2.0