homebridge-poolcontroller-clocklear/README.md

A (semi) private Homebridge plugin for my custom Pool Controller app

# homebridge-poolcontroller

A (semi) private Homebridge plugin for my [homegrown Raspberry Pi-based pool controller](https://github.com/clocklear/poolcontroller).

## What it exposes

One HomeKit accessory (**Pool Controller**) with multiple services:

- **Switch** per configured relay (names come from the poolcontroller API)
- Optional **Scheduler** switch (master schedule enable/disable)
- Optional **Contact Sensor** per relay for load faults (`health: load_absent`)

Home can show the accessory as multiple tiles. State is refreshed on a configurable poll interval (default 30s) via `updateCharacteristic`, so schedule/web UI changes show up in Home without opening the tile.

## Configuration

Use **Homebridge UI → Plugins → Pool Controller → Settings**. You should not need to edit raw JSON.

| Field | Description |
|-------|-------------|
| Accessory Name | HomeKit display name (default `Pool Controller`) |
| API URL | Must include `/api`, e.g. `https://poolcontroller.example.com/api` |
| API Key | Same value as `API_KEY` on the Pi |
| Relays | Which relays (1–4) to expose |
| Expose Scheduler Switch | Default on |
| Expose Load Fault Sensors | Default off |
| Poll Interval | Seconds between API polls (5–300, default 30) |

Example config block (written by the Settings form):

```json
{
  "platform": "PoolControllerPlugin",
  "name": "Pool Controller",
  "url": "https://poolcontroller.example.com/api",
  "apiKey": "your-api-key",
  "relays": ["1", "2"],
  "exposeScheduler": true,
  "exposeLoadSensors": false,
  "pollIntervalSeconds": 30
}
```

## Notes

- Relay on/off uses `POST /api/relays/{id}/state` (absolute set). Leaving a scheduled state uses the server’s default override TTL.
- Upgrading from older plugin versions that registered one accessory per relay: legacy accessories are unregistered automatically on launch.
- SSE live sync is not used yet; polling is enough for v1.