68 lines
2.6 KiB
Markdown
68 lines
2.6 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.
|
|
|
|
## 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.
|