service_hue_collector/README.md

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

1. Find your bridge IP in the Hue app under Settings → My Hue system → System information.

2. 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.

3. Configure and start the stack:

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

4. Open Grafana at http://HOST_LAN_IP:3000 and sign in with admin / admin. The dashboard is in the Hue folder. Change this development password if the port is reachable by anyone else on your network.

Useful local endpoints:

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

By default, published ports bind to 0.0.0.0, making them reachable through the host's 192.168.178.x address. Docker cannot bind to a wildcard subnet such as 192.168.178.*; to listen only on the LAN interface, set PUBLISH_ADDRESS in .env to the host's exact address, for example 192.168.178.42. Ensure your host firewall permits access only from trusted networks. 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