ha-deconz-bridge/docs/debugger.md

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:

.venv/bin/python -m ha_deconz_bridge.debugger.web_debugger ./config.example/lights_config.py "Living Room Ceiling" --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:

.venv/bin/python -m ha_deconz_bridge.debugger.web_debugger ./config/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:

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:

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

That service listens on:

http://host.example:8766