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 integration
• hue.py — dependency-free command-line client and registration tool
• config.yaml — reverse-proxy settings
• hue.yaml — button, group, and scene configuration
• static/ and templates/ — phone interface