service_hue_collector/README.md

# Lightweight Hue history

A small service for Raspberry Pi that reads the Philips Hue v2 API, stores history in
fixed-size [RRDtool](https://oss.oetiker.ch/rrdtool/) databases, and serves its own web
dashboard. It does not require Grafana, VictoriaMetrics, Node.js, or a browser-side
charting library.

The dashboard contains:

- One graph for every room and zone. Unavailable, off, and on lights form a stacked
  percentage area, with average intensity of shining lights drawn as a line.
- Temperature and illuminance graphs for every available Hue sensor.
- 6-hour, 24-hour, 7-day, and 30-day time ranges.

RRD storage is bounded automatically: raw samples are retained for 7 days,
approximately five-minute averages for 90 days, and hourly averages for two years.

## Configure Hue

Find the bridge IP in the Hue app under **Settings → My Hue system → System
information**. Then 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. The returned
`username` is the application key.

## Run with Docker Compose

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

Open `http://PI_ADDRESS:8000`. RRD data persists in the `hue-rrd-data` Docker volume.
The `--remove-orphans` option removes containers from the previous
VictoriaMetrics/Grafana version; their old named volumes are not deleted.

By default, port 8000 binds to all interfaces. To bind only to the Pi's LAN interface,
put its exact address in `.env`, for example:

```env
PUBLISH_ADDRESS=192.168.178.42
```

## Run directly on Raspberry Pi OS/Debian

This avoids Docker overhead entirely:

```bash
sudo apt update
sudo apt install python3 python3-requests python3-rrdtool fonts-dejavu-core
mkdir -p "$HOME/.local/share/hue-collector"
export HUE_BRIDGE_HOST=192.168.178.2
export HUE_APPLICATION_KEY=your-key
export DATA_DIR="$HOME/.local/share/hue-collector"
python3 -m hue_collector
```

The page is served on port 8000. For continuous operation, run it with systemd or use
the Compose setup with `restart: unless-stopped`.

TLS verification is disabled by default because Hue bridges normally use a
self-signed certificate. Set `HUE_VERIFY_TLS=true` if the bridge has a trusted
certificate. The health check is available at `/healthz`.

## Development

The collector tests do not require RRDtool:

```bash
python3 -m unittest discover -s tests
```