# 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.