6.3 KiB
FastHue
A local, iPhone-first Philips Hue dashboard and command-line client. It works with a Hue Bridge or Hue Bridge Pro on the same network.
Dashboard
The dashboard fills an iPhone screen with eight dark controls in a 2 × 4 grid.
- A blue edge means at least one light in that room or zone is on.
- The subtitle is the active Hue scene, when one is active.
- Tap a button to activate the next configured scene.
- Press and hold a button for about 0.65 seconds to turn its lights off.
Start it
First register the app with the bridge (you only need to do this once):
python3 hue.py register
Press the physical button on the bridge when prompted. Then install the small web app dependencies and run it:
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python app.py
On the iPhone, open http://YOUR-COMPUTER-IP:5000/ in Safari. The iPhone and
computer must be on the same local network.
Configure buttons and scenes
hue.yaml controls the dashboard. The buttons entries define button order,
the target room/zone, and the ordered scenes to cycle through:
buttons:
1:
name: Ground floor
scenes:
- Sunset allure
- Relax
Each button name must match a rooms or zones entry. Scene names must match
scenes for that same group in the main scenes catalog. The app expects exactly
eight buttons.
Command line client
# Find local bridges
python3 hue.py discover
# List rooms, zones, and scenes
python3 hue.py list
# Activate a scene or control a group directly
python3 hue.py scene "Evening relax"
python3 hue.py on "Living room"
python3 hue.py off "zone:Downstairs"
Credentials are saved with owner-only permissions in
secrets.yaml:
bridge: 192.168.1.10
app_key: your-hue-application-key
The file is ignored by Git and should not be shared. hue.py register creates
or updates it. You can override the bridge values with environment variables:
HUE_BRIDGE=192.168.1.10 HUE_APP_KEY=YOUR_HUE_KEY .venv/bin/python app.py
The reverse-proxy path is configured separately in config.yaml:
url_prefix: /hue
Set it to an empty value when FastHue is served at /.
HTTP API
The dashboard API does not require a key. Do not expose it to untrusted users: every client that can reach it can read and control the configured lights.
curl http://localhost:5000/api/groups
curl -X POST \
http://localhost:5000/api/groups/GROUP_UUID/next-scene
curl -X POST \
http://localhost:5000/api/groups/GROUP_UUID/off
curl -X POST \
-H 'Content-Type: application/json' \
-d '{"name":"Relax"}' \
'http://localhost:5000/api/groups/Ground%20floor/scene'
GET /api/groups returns each configured group ID, its power state, and its
active scene. Use those IDs for the next-scene and off endpoints. The
scene endpoint uses the URL-encoded room or zone name (not its UUID), and
activates the named scene only when it belongs to that group. Keep this service on
a trusted network; the included Flask server uses HTTP, so place it behind an
HTTPS reverse proxy if it needs to cross an untrusted network.
Deploy with Gunicorn and Nginx
These instructions target a Linux host running systemd. Gunicorn listens on a Unix socket; Nginx is the only public-facing process.
Install the project and dependencies under a service account, then place its credentials outside the web root:
sudo useradd --system --create-home --shell /usr/sbin/nologin fasthue
sudo mkdir -p /srv/fasthue /etc/fasthue
sudo chown fasthue:fasthue /srv/fasthue /etc/fasthue
# Copy this project into /srv/fasthue, then:
sudo -u fasthue python3 -m venv /srv/fasthue/.venv
sudo -u fasthue /srv/fasthue/.venv/bin/pip install -r /srv/fasthue/requirements.txt
sudo install -o fasthue -g fasthue -m 600 secrets.yaml /etc/fasthue/secrets.yaml
Create /etc/systemd/system/fasthue.service:
[Unit]
Description=FastHue dashboard
After=network-online.target
Wants=network-online.target
[Service]
Type=exec
User=fasthue
# Use your Nginx worker group (commonly www-data; use nginx on some distros).
Group=www-data
WorkingDirectory=/srv/fasthue
Environment=FASTHUE_SECRETS_FILE=/etc/fasthue/secrets.yaml
RuntimeDirectory=fasthue
RuntimeDirectoryMode=0750
ExecStart=/srv/fasthue/.venv/bin/gunicorn --workers 1 --umask 007 --bind unix:/run/fasthue/fasthue.sock app:gunicorn_app
Restart=on-failure
RestartSec=3
[Install]
WantedBy=multi-user.target
Enable it:
sudo systemctl daemon-reload
sudo systemctl enable --now fasthue
sudo systemctl status fasthue
Configure Nginx with a TLS-enabled virtual host (replace the hostname and
certificate paths). This example publishes FastHue at /hue:
server {
listen 443 ssl http2;
server_name hue.example.com;
ssl_certificate /etc/letsencrypt/live/hue.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/hue.example.com/privkey.pem;
location = /hue {
return 302 /hue/;
}
location /hue/ {
# The trailing slash strips /hue before proxying to Flask.
proxy_pass http://unix:/run/fasthue/fasthue.sock:/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Prefix /hue;
}
}
The www-data group in the systemd unit and --umask 007 make the socket
readable by Nginx. If your Nginx workers use another group, replace www-data
in the unit with that group. Test and reload Nginx with
sudo nginx -t && sudo systemctl reload nginx.
Use the HTTPS URL on the iPhone with /hue/. Set url_prefix in config.yaml
to another leading-slash prefix when needed, and use the same value in Nginx's location and
X-Forwarded-Prefix. Keep
secrets.yaml readable only by the service account.
The bridge typically has a locally issued TLS certificate, so certificate
verification is disabled by default. Add --verify-tls only when your computer
trusts that certificate.
Files
app.py— Flask dashboard and Hue API integrationhue.py— dependency-free command-line client and registration toolconfig.yaml— reverse-proxy settingshue.yaml— button, group, and scene configurationstatic/andtemplates/— phone interface