TAPPaaS

deconz

Primary audience: home user with Zigbee devices; Home Assistant administrator; SysAP (free@home) users.

Standalone Zigbee gateway (ConBee II) with a diyHue Hue-bridge front-end. deCONZ runs the Zigbee network on a dedicated NixOS VM instead of inside Home Assistant. Two consumers, two faces:

Why this exists

Architecture (who talks to whom)

  Home Assistant ──native REST+ws──▶ deCONZ ──Zigbee──▶ 24 IKEA lights + 8 Aqara sensors
  SysAP/free@home ──Hue API──▶ diyHue ──localhost REST──▶ deCONZ ──Zigbee──▶ lights

deCONZ is internalised from the SysAP — only diyHue faces free@home; HA keeps its native path. diyHue has no radio and never touches the Zigbee network → the ConBee/coordinator stays the single source of truth, migration is safe.

What you get

Capability Consumer Access How
zigbee Home Assistant (srvHome→iotCloud) TCP 8080 (REST) + 8443 (ws) official deconz integration
hue-bridge SysAP (iotCloud, intra-zone) TCP 80/443 (Hue API) + UDP 1900 (SSDP) diyHue genuine Hue bridge (= hue:bridge capability)
Admin UI mgmt TCP 8080 via reverse proxy Phoscon web UI

SSOT for grouping

deCONZ is the SSOT for lights + Zigbee groups; diyHue / HA / SysAP are satellites. Maintain your own device-fleet + grouping declaration outside this module. A physical multi-lamp fixture (e.g. "bedroom south" = 4 lamps) is one deCONZ group. To present it to the SysAP as a single entity (not 4 lamps) — and get one atomic Zigbee groupcast — expose the deCONZ group as one diyHue entity rather than importing the member lights individually (see UPGRADE.md → grouping).

Performance — diyHue latency patch (required)

Upstream diyHue's deCONZ adapter (lights/protocols/deconz.py) has an unconditional sleep(0.7) after each state write — it fires on every on/off/dim, so one light = 0.7 s and a 24-light group action ≈ 17 s (diyHue iterates per-light; it does not groupcast). deconz.nix ships a patched adapter (bind-mounted via environment.etc."diyhue/deconz.py") that only waits when a colour change follows. Measured: single light 0.707 s → 0.007 s, group of 24 16.9 s → 0.10 s; colour change keeps its 0.71 s power-on delay. Because the patch tracks the upstream file, the diyHue image is pinned by digest (not :latest).

Device support

Firmware (OTA) over iotCloud

deCONZ keeps iotCloud internet egress so it can pull Zigbee OTA bulb-firmware (IKEA mfr 117C / Signify 100B). Per-device, manual flow — see UPGRADE.md.

Hardware + availability

Dependencies

Depends on Purpose
cluster:vm the NixOS VM (clone of the golden template)
templates:nixos NixOS base image
backup:vm full-VM PBS backup (includes the Zigbee DB + diyHue config)
network:proxy Phoscon admin UI behind the reverse proxy (mgmt only)
network:rules pinholes for the zigbee + hue-bridge services

For installation steps see INSTALL.md; upgrades see UPGRADE.md.