1sT poc

README.md

@@ -1,2 +1,63 @@
-# service_hue_collector
+# 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
+```