A small service for Raspberry Pi that reads the Philips Hue v2 API, stores history in fixed-size 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:

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

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:

PUBLISH_ADDRESS=192.168.178.42

Run directly on Raspberry Pi OS/Debian

This avoids Docker overhead entirely:

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:

python3 -m unittest discover -s tests