# Debugger

The debugger is a browser UI around the real core library. It can run in two modes:

- `virtual`: offline solver only
- `live`: solver plus direct deCONZ reads/writes for the selected lights

## Goals

- use the exact same solver and translation code as runtime
- visualize requested versus achieved color
- show per-controller and per-channel activation
- inspect timing and chosen controller modes

## Current Shape

- `ha-deconz-bridge-debug`: the original local Matplotlib tool
- `ha-deconz-bridge-debug-web`: a browser-accessible debugger for remote development on the VM

Both variants:

- load a config module and one or more initial virtual lights
- use the shared solver and color/translation code
- let the user drive RGB or color temperature plus brightness
- show achieved color, per-channel activation, controller commands, and solver metadata

## Web Debugger

Run:

```bash
.venv/bin/python -m ha_deconz_bridge.debugger.web_debugger ./configs/example.py "Example Mixed North" --host 127.0.0.1 --port 8765
```

Then open `http://127.0.0.1:8765` in a browser. If the debugger runs on the VM, tunnel the port over SSH if needed.

For real hardware, pass your ignored local config instead:

```bash
.venv/bin/python -m ha_deconz_bridge.debugger.web_debugger ./configs/local/lights_config.py "Your Light Name" --host 127.0.0.1 --port 8765
```

Inside the UI:

- `virtual` mode only runs the solver against the selected light set
- `live` mode polls deCONZ for the selected lights and only writes to the backend when you move the sliders
- changing the selected lights or switching between `rgb` and `color_temp` does not write anything to the backend
- in `live` mode, external changes made through Phoscon or elsewhere are pulled back into the debugger on the next poll

- all configured lights are listed with checkboxes
- the selected lights are merged into one temporary solver target
- changing either the sliders or the light selection re-runs the solver

In `live` mode, the current color is reinterpreted for both RGB and CT controls. That means an arbitrary RGB state can still be shown on the CT slider, and switching UI modes does not itself send any backend change.

This is useful both for inspecting a single virtual light and for experimenting with possible grouped-light behavior before adding it to the runtime service.

## Running On The Pi

Once the app has been deployed, you can run the same debugger directly on the Pi:

```bash
ssh user@host.example \
  'cd /path/to/ha-deconz-bridge/app && set -a && . ../config/service.env && set +a && ../.venv/bin/python -m ha_deconz_bridge.debugger.web_debugger ../config/lights_config.py --host 0.0.0.0 --port 8765'
```

Then open `http://host.example:8765` from your browser, or tunnel the port over SSH if you prefer.

There is also a dedicated user service unit for the Pi-hosted debugger:

```bash
ssh user@host.example 'systemctl --user start ha-deconz-bridge-debug.service'
```

That service listens on:

```text
http://host.example:8766
```