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.

Project Layout

docs/semantics.md: runtime behavior and mapping rules
docs/architecture.md: package structure and data flow
docs/configuration.md: typed light definitions
docs/deployment.md: Raspberry Pi deploy and service flow
docs/debugger.md: shared-core simulator
docs/plan.md: implementation plan that drove this reboot

Quick Start

Install in editable mode:

python3 -m pip install -e '.[dev]'

Run the test suite:

pytest

Create a private config from the public example:

mkdir -p configs/local
cp configs/example.py configs/local/lights_config.py
cp configs/example_*.py configs/local/

Edit configs/local/lights_config.py and the copied split files for your real controller IDs, light names, groups, and calibration values. Files under configs/local/ are ignored by Git.

Run the service with a Python config path that exports SETTINGS and LIGHTS:

ha-deconz-bridge-service configs/local/lights_config.py

Run the browser debugger against the same config:

ha-deconz-bridge-debug-web configs/local/lights_config.py "Example Mixed North" --host 127.0.0.1 --port 8765

Configuration And Deployment

The public repository includes sanitized example configs under configs/example.py. Keep real room names, controller IDs, hostnames, user names, and deployment scripts in ignored local files such as configs/local/.

See docs/deployment.md for the generic service layout and deployment expectations.