2026-04-13 01:48:32 -03:00
|
|
|
# typhon
|
|
|
|
|
|
|
|
|
|
`typhon` is an AC Infinity telemetry exporter that polls the AC Infinity cloud API and exposes Prometheus metrics for Grafana dashboards and alerting.
|
|
|
|
|
|
|
|
|
|
Stage 1 scope:
|
|
|
|
|
- ingest controller climate telemetry (temperature, humidity, VPD)
|
|
|
|
|
- ingest fan/port telemetry (online state, power state, speed, mode)
|
|
|
|
|
- expose `/metrics` + `/healthz`
|
|
|
|
|
|
|
|
|
|
Stage 2 scope:
|
|
|
|
|
- add authenticated control APIs and UI for `climate.bstein.dev`
|
|
|
|
|
|
|
|
|
|
## API behavior (based on homebridge-acinfinity)
|
|
|
|
|
|
|
|
|
|
This implementation follows the same API conventions used by `keithah/homebridge-acinfinity`:
|
|
|
|
|
- host: `http://www.acinfinityserver.com`
|
|
|
|
|
- login endpoint: `/api/user/appUserLogin`
|
|
|
|
|
- list endpoint: `/api/user/devInfoListAll`
|
|
|
|
|
- mode endpoint: `/api/dev/getdevModeSettingList`
|
|
|
|
|
- auth header: `token: <appId>`
|
|
|
|
|
- request headers include `phoneType=1`, `appVersion=1.9.7`, and `User-Agent` matching the official app style
|
|
|
|
|
- password field key is intentionally `appPasswordl`
|
|
|
|
|
- API only honors the first 25 chars of password
|
|
|
|
|
|
|
|
|
|
## Configuration
|
|
|
|
|
|
|
|
|
|
Environment variables:
|
2026-04-13 21:59:42 -03:00
|
|
|
- `TYPHON_MODE` (optional, default `cloud`, values: `cloud|ble`)
|
2026-04-13 01:48:32 -03:00
|
|
|
- `ACI_EMAIL` (required)
|
|
|
|
|
- `ACI_PASSWORD` (required, use <= 25 chars for reliability)
|
|
|
|
|
- `ACI_HOST` (optional, default `http://www.acinfinityserver.com`)
|
|
|
|
|
- `POLL_INTERVAL_SECONDS` (optional, default `30`)
|
|
|
|
|
- `REQUEST_TIMEOUT_MS` (optional, default `10000`)
|
|
|
|
|
- `LISTEN_PORT` (optional, default `9108`)
|
|
|
|
|
- `LOG_LEVEL` (optional, default `info`)
|
2026-04-13 21:59:42 -03:00
|
|
|
- `ENABLE_CONTROL_API` (optional, default `false`)
|
|
|
|
|
- `CONTROL_LISTEN_PORT` (optional, default `9110`)
|
|
|
|
|
- `TY_BLE_DEFAULT_MAC` (optional, default empty)
|
|
|
|
|
- `TY_BLE_ALLOWED_MACS` (optional, comma-delimited)
|
|
|
|
|
- `TY_BLE_DEVICE_TYPE` (optional, default `11` for Controller 69 Pro)
|
|
|
|
|
- `TY_BLE_SCAN_TIMEOUT_MS` (optional, default `20000`)
|
|
|
|
|
- `TY_BLE_PORT_BASE` (optional, `1` by default; set `0` if your controller expects zero-based port bytes)
|
|
|
|
|
|
|
|
|
|
Notes:
|
|
|
|
|
- `TYPHON_MODE=cloud` keeps the existing v1 cloud exporter behavior.
|
|
|
|
|
- `TYPHON_MODE=ble` enables the v2 control API scaffolding and does not require `ACI_EMAIL`/`ACI_PASSWORD`.
|
|
|
|
|
- BLE mode uses BlueZ DBus (`node-ble`) and AC Infinity protocol packets for telemetry + per-port speed writes.
|
2026-04-14 03:48:09 -03:00
|
|
|
- BLE mode includes a Wi-Fi recovery API endpoint (`POST /api/v2/wifi/recover`) for v2 orchestration.
|
|
|
|
|
- Current `node-ble` client returns `501` for Wi-Fi recovery until provisioning packet frames are finalized.
|
2026-04-13 01:48:32 -03:00
|
|
|
|
|
|
|
|
Kubernetes runtime is expected to source `ACI_EMAIL`/`ACI_PASSWORD` from Vault.
|
|
|
|
|
|
|
|
|
|
## Local development
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
npm ci
|
|
|
|
|
npm run lint
|
|
|
|
|
npm test
|
|
|
|
|
npm run build
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Run locally:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
ACI_EMAIL='you@example.com' \
|
|
|
|
|
ACI_PASSWORD='your-password' \
|
|
|
|
|
npm run dev
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Metrics endpoint:
|
|
|
|
|
- `http://localhost:9108/metrics`
|
|
|
|
|
- `http://localhost:9108/healthz`
|
2026-04-14 03:48:09 -03:00
|
|
|
|
|
|
|
|
Control API (when `ENABLE_CONTROL_API=true`):
|
|
|
|
|
- `GET /api/v2/status`
|
|
|
|
|
- `GET /api/v2/ports`
|
|
|
|
|
- `POST /api/v2/pair` `{ "mac_address": "AA:BB:CC:DD:EE:FF" }`
|
|
|
|
|
- `POST /api/v2/ports/:port/speed` `{ "speed_level": 0..10 }`
|
|
|
|
|
- `POST /api/v2/wifi/recover` `{ "ssid": "...", "password": "...", "hidden": false }`
|
