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, shining, off, and unavailable light counts;
  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 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

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