109 lines
3.4 KiB
Markdown
109 lines
3.4 KiB
Markdown
# Hue RRD Flask dashboard
|
|
|
|
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`:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
systemctl status hue-collector
|
|
journalctl -u hue-collector -f
|
|
```
|
|
|
|
After updating the application files, restart it with:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
```
|