bstein/typhon
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
typhon/README.md

2.5 KiB
Raw Blame History

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:

  • TYPHON_MODE (optional, default cloud, values: cloud|ble)
  • 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)
  • 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.

Kubernetes runtime is expected to source ACI_EMAIL/ACI_PASSWORD from Vault.

Local development

npm ci
npm run lint
npm test
npm run build

Run locally:

ACI_EMAIL='you@example.com' \
ACI_PASSWORD='your-password' \
npm run dev

Metrics endpoint:

  • http://localhost:9108/metrics
  • http://localhost:9108/healthz