68 lines
2.5 KiB
Markdown
68 lines
2.5 KiB
Markdown
# 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 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
|
|
```
|