Hue collector

A local-only monitoring stack for a Philips Hue bridge. The Python service reads the Hue v2 API, exposes Prometheus metrics, VictoriaMetrics stores them, and Grafana ships with a provisioned dashboard.

Metrics

For every room and zone: available lights, shining lights, percentages shining, off, and unavailable, plus average brightness of the shining lights.
For every temperature and illuminance sensor: availability and its latest reading, labelled with its room and zones.

A device is available when its Hue zigbee_connectivity resource is connected. A light is shining when it is available and reports on=true. If a device has no connectivity resource (for example some bridge-owned resources), it is considered available.

Setup

Find your bridge IP in the Hue app under Settings → My Hue system → System information.
Create an application key while physically near the bridge:
```
curl -k -X POST https://BRIDGE_IP/api \
  -H 'Content-Type: application/json' \
  -d '{"devicetype":"local-hue-collector"}'
```
Press the bridge link button immediately before running the command. Copy the returned username; that is the application key.

Configure and start the stack:

cp .env.example .env
# Edit .env with the bridge IP and application key.
docker compose up --build -d

Open Grafana and sign in with admin / admin. The dashboard is in the Hue folder. Change this development password if the port will ever be exposed beyond localhost.

Useful local endpoints:

Collector metrics: http://localhost:8000/metrics
VictoriaMetrics UI: http://localhost:8428/vmui/
Grafana: http://localhost:3000

All published ports bind to 127.0.0.1. Named Docker volumes retain metrics and Grafana state across restarts. TLS verification is off by default because Hue bridges normally use a self-signed certificate; set HUE_VERIFY_TLS=true if yours has a trusted certificate.

Development

python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
python -m unittest discover -s tests
HUE_BRIDGE_HOST=... HUE_APPLICATION_KEY=... python -m hue_collector