A lightweight Flask application for Raspberry Pi that reads the Philips Hue v2 API, stores history in fixed-size RRDtool databases, and serves a local web dashboard.

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 Hue sensor.
6-hour, 24-hour, 7-day, and 30-day time ranges.

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

Install on Raspberry Pi OS or Debian

Install the native RRDtool binding and Python dependencies:

sudo apt update
sudo apt install python3 python3-flask python3-requests python3-rrdtool fonts-dejavu-core

Create the Hue application key if you do not have one yet. Press the bridge link button immediately before running:

curl -k -X POST https://BRIDGE_IP/api \
  -H 'Content-Type: application/json' \
  -d '{"devicetype":"local-hue-collector"}'

The returned username is the application key.

Configure and run the Flask application from the project directory:

cp .env.example .env
# Edit .env with the bridge IP and application key.
set -a
. ./.env
set +a
python3 -m hue_collector

Open http://PI_ADDRESS:8000. The RRD files are written to DATA_DIR, which defaults to the project's data/ directory.

Run continuously with systemd

Install the project and environment file:

sudo install -d /opt/hue-collector
sudo cp -r hue_collector /opt/hue-collector/
sudo cp .env /etc/hue-collector
sudo chmod 600 /etc/hue-collector
sudo cp hue-collector.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now hue-collector

The included unit uses a restricted dynamic service account and stores RRD files in /var/lib/hue-collector. Inspect it with:

systemctl status hue-collector
journalctl -u hue-collector -f

After updating the application files, restart it with:

sudo systemctl restart hue-collector

Configuration

HUE_BRIDGE_HOST: Hue bridge IP or hostname; required.
HUE_APPLICATION_KEY: Hue v2 application key; required.
HUE_VERIFY_TLS: verify the bridge certificate; defaults to false because Hue bridges normally use a self-signed certificate.
COLLECT_INTERVAL_SECONDS: sampling interval; defaults to 30 seconds. Changing it after RRD files have been created does not change those existing files' step.
LISTEN_HOST: Flask bind address; defaults to 0.0.0.0 for LAN access.
LISTEN_PORT: dashboard port; defaults to 8000.
DATA_DIR: RRD directory; defaults to data.

The application is intended for a trusted home network and does not provide authentication or TLS. Restrict access with the Pi firewall if the network is not trusted.

Development

On a Debian-based machine, install python3-rrdtool through apt. Flask and Requests can alternatively be installed from requirements.txt. When using a virtual environment, create it with --system-site-packages so it can see the apt-installed RRDtool module.

python3 -m unittest discover -s tests