HA deCONZ Bridge

ha-deconz-bridge is a Python service that presents clean virtual lights to Home Assistant while translating those requests onto messy physical controllers behind deCONZ.

The core design goals are:

deterministic forward and reverse mapping
typed light definitions instead of unstructured nested dictionaries
one shared core for runtime and debug tooling
exact-target solving first, with clamping only when a request is truly out of gamut

New code lives under src/ha_deconz_bridge. Local/private experiments and archived prototypes should stay ignored.

Project Background

This started as a personal hobby project, was put on ice for a while after motivation ran out, and was later picked up again as a clean rewrite with substantial help from AI. The current public codebase is the rewritten version; old experiments are kept out of the repository history.

What You Need

Python 3.11 or newer.
Home Assistant with MQTT discovery enabled.
deCONZ/Phoscon already controlling the physical lights.
SSH access to the Raspberry Pi or other Linux host if you want to deploy it as a service.

Configuration Files

The project is meant to be self-contained. Public example files live in config.example/, and your real private files live in ignored config/.

Create your private config:

mkdir -p config
cp config.example/*.py config/
cp config.example/service.env.example config/service.env
cp config.example/deploy.env.example config/deploy.env

Then edit:

config/lights_config.py: loads the other config files.
config/lights.py: virtual lights and physical controller/channel definitions.
config/groups.py: room/group definitions.
config/remotes.py and config/actions.py: optional remote button automation.
config/service.env: MQTT and deCONZ connection settings.
config/deploy.env: SSH target and deploy settings for the Pi.

Files under config/ are ignored by Git.

Run Locally

This runs the bridge on the current machine. It is useful for testing the config or running the web debugger before deploying to a Pi.

Create a Python environment:

python3 -m venv .venv

Install the program into that environment:

.venv/bin/pip install .

Load the connection settings and run the service:

set -a
. config/service.env
set +a
.venv/bin/ha-deconz-bridge-service config/lights_config.py

In another terminal, run the browser debugger if you want to inspect solver behavior:

set -a
. config/service.env
set +a
.venv/bin/ha-deconz-bridge-debug-web config/lights_config.py "Living Room Ceiling" --host 127.0.0.1 --port 8765

Then open http://127.0.0.1:8765.

On Windows, use .venv\Scripts\pip and .venv\Scripts\ha-deconz-bridge-service instead of the .venv/bin/... paths.

Deploy To A Pi

This is the normal always-on setup. The deploy script copies the app and config to the target, creates or updates a virtualenv there, installs the package, installs systemd user services, and starts the bridge.

Make sure config/deploy.env contains your SSH target:

DEPLOY_HOST=pi@raspberrypi.local
DEPLOY_REMOTE_DIR=~/ha-deconz-bridge

Deploy:

python deploy/deploy.py

For later config-only changes, redeploy just the config:

python deploy/deploy.py --config-only

Check the service on the Pi:

ssh pi@raspberrypi.local 'systemctl --user status ha-deconz-bridge.service --no-pager'

The optional web debugger service can be started on the Pi with:

ssh pi@raspberrypi.local 'systemctl --user start ha-deconz-bridge-debug.service'

It listens on port 8766 by default.

4.1 KiB Raw Blame History