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

## Project Layout

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

## Quick Start

Install in editable mode:

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

Run the test suite:

```bash
pytest
```

Create a private config from the public example:

```bash
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`:

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

Run the browser debugger against the same config:

```bash
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`](./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`](./docs/deployment.md) for the generic service layout and deployment expectations.