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 Python's virtual-environment support and the native headers needed to build the RRDtool package, then install every Python dependency into .venv:

sudo apt update
sudo apt install python3 python3-venv python3-dev build-essential librrd-dev fonts-dejavu-core
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

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
python -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

The included unit expects this repository at /srv/service_hue_collector, including its .venv and .env files:

sudo chmod 600 /srv/service_hue_collector/.env
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

Create the virtual environment and install all application dependencies from the requirements file:

sudo apt install python3-venv python3-dev build-essential librrd-dev fonts-dejavu-core
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt
python -m unittest discover -s tests