# 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:

   ```bash
   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:

   ```bash
   cp .env.example .env
   # Edit .env with the bridge IP and application key.
   docker compose up --build -d
   ```
4. Open [Grafana](http://localhost:3000) 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

```bash
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
```