131 lines
4.1 KiB
Markdown
131 lines
4.1 KiB
Markdown
# 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`](./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/`](./config.example/), and your real private files live in ignored `config/`.
|
|
|
|
Create your private config:
|
|
|
|
```bash
|
|
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.
|
|
|
|
1. Create a Python environment:
|
|
|
|
```bash
|
|
python3 -m venv .venv
|
|
```
|
|
|
|
2. Install the program into that environment:
|
|
|
|
```bash
|
|
.venv/bin/pip install .
|
|
```
|
|
|
|
3. Load the connection settings and run the service:
|
|
|
|
```bash
|
|
set -a
|
|
. config/service.env
|
|
set +a
|
|
.venv/bin/ha-deconz-bridge-service config/lights_config.py
|
|
```
|
|
|
|
4. In another terminal, run the browser debugger if you want to inspect solver behavior:
|
|
|
|
```bash
|
|
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.
|
|
|
|
1. Make sure `config/deploy.env` contains your SSH target:
|
|
|
|
```bash
|
|
DEPLOY_HOST=pi@raspberrypi.local
|
|
DEPLOY_REMOTE_DIR=~/ha-deconz-bridge
|
|
```
|
|
|
|
2. Deploy:
|
|
|
|
```bash
|
|
python deploy/deploy.py
|
|
```
|
|
|
|
3. For later config-only changes, redeploy just the config:
|
|
|
|
```bash
|
|
python deploy/deploy.py --config-only
|
|
```
|
|
|
|
4. Check the service on the Pi:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
ssh pi@raspberrypi.local 'systemctl --user start ha-deconz-bridge-debug.service'
|
|
```
|
|
|
|
It listens on port `8766` by default.
|
|
|
|
## More Documentation
|
|
|
|
- [`docs/configuration.md`](./docs/configuration.md): config format and examples.
|
|
- [`docs/deployment.md`](./docs/deployment.md): deployment details and service layout.
|
|
- [`docs/debugger.md`](./docs/debugger.md): web debugger behavior.
|
|
- [`docs/semantics.md`](./docs/semantics.md): solver and Home Assistant behavior.
|
|
- [`docs/architecture.md`](./docs/architecture.md): package structure and data flow.
|