Alpine's pipewire-pulse package ships the daemon binary but doesn't
auto-load the PA bridge module on alpine. We need to start pipewire-pulse
as a separate process with -a tcp:4713 so PA clients (librespot, mopidy)
can connect via TCP.
Layout:
- pipewire: audio server (native protocol)
- pipewire-pulse: PA-compat bridge, listens on tcp:4713 + unix:/tmp/pulse-socket
- wireplumber: session manager (loads BT modules, hot-plug handling)
- bluetoothd at /usr/lib/bluetooth/bluetoothd (not in PATH on alpine)
- Add session dbus via dbus-daemon --session (pipewire needs it)
- Clean up stale dbus.pid files on startup (host volume persists)
oauth2 crate gates TLS backends behind features; without native-tls,
librespot-oauth fails to compile with compile_error!. The default
features include native-tls, but we use --no-default-features for
minimal build.
Cross-compile on x86_64 with qemu emulation takes >30min and hits
60-90min ceiling due to slow crate-by-crate aarch64 build under qemu.
Native ARM64 build on RPi 3B+ with --jobs 2 (1GB RAM) is much faster.
Rust 1.85.1 installed via rustup on RPi (precompiled aarch64 toolchain).
- audio-bridge: alpine + pipewire + pipewire-pulse + wireplumber + bluez + dbus + tini
Routes audio from librespot/mopidy/phone-BT to USB DAC (Q5K) via ALSA.
Privileged + host network for bluetoothd HCI access.
- mopidy: built from python:3.12-slim-bookworm + pip (no ghcr.io dep).
Qobuz (auth from developer.qobuz.com) + local files. PA bridge to audio-bridge.
- librespot: built from rust:1.85.1 on RPi (cross-compile too slow under qemu).
Spotify Connect target named 'Klubhaus'. PA bridge to audio-bridge.
Both mopidy and librespot build locally to avoid ghcr.io auth/rate-limit issues.
PEQ stays on Q5K side (Qudelix app, 20 bands) for source-independent EQ.
ntfy /json?poll=1 is regular polling, not long-poll. Worst-case
lag = 2 × POLL_INTERVAL × N_topics = 120s at 30s. Reducing to 5s
caps lag at ~20s with 2 topics. For sub-second latency, switch to
ntfy SSE (/<topic>/sse) - tracked separately.
The NR base image's /data has restrictive ACLs that block chmod on
COPY'd files even as root. Writing start.sh inline with printf + chmod
sidesteps this.
NR's automatic package.json install at container start was slow and
required internet. Move npm install to image build time, preserve the
installed node_modules via an anonymous volume so the bind mount of
./nodered:/data doesn't clobber them.
Document the ThirdReality Smart Button (3RSB22BZ) pairing mode quirk
that bit us today: the button has Standard ZigBee (blue only) and
Echo ZigBee (blue + red) modes, and only the former works with
zigbee2mqtt. Switching requires 5 quick presses of the back reset
button (firmware >= 1.00.22), NOT holding the front button.
Also document the Smart Plug Zigbee PROD pairing procedure and the
BLE->ZigBee mode switch.
Add scripts/z2m_repair.py that:
- Opens permit_join for N seconds (default 120)
- Subscribes to bridge/event on the local MQTT broker
- For each device_joined event, auto-renames the device back to its
original friendly name (hardcoded IEEE->name mapping from the
last known good state, overridable via --mapping).
After the zigbee2mqtt database was wiped, the user had to manually
pair each device via the web UI. With this recipe, devices rejoin
automatically when woken (network_key preserved), and the script
restores friendly names as they join.
Add justfile recipes:
just z2m-repair [TIME=120] - run the auto-repair script
just z2m-rename IEEE NAME - rename a single device by IEEE
The Pine64 BLZ fork's zigbee2mqtt image crashes on start because
Bridge.start() calls firstCoordinatorEndpoint().deviceIeeeAddress
before the onMQTTMessage listener is registered. The BLZ coordinator
does not register its endpoint (the coordinator is the dongle itself,
no ZDO loopback), so firstCoordinatorEndpoint() returns undefined.
The crash happens in publishInfo() BEFORE onMQTTMessage is wired up,
which means every bridge MQTT request (permit_join, device rename,
group ops, etc.) silently no-ops — even though the message is
received.
Add infra/zigbee2mqtt/scripts/blz-bridge-patch.js that applies two
surgical fixes (idempotent):
1. Optional chain on the .deviceIeeeAddress access so the missing
endpoint doesn't throw.
2. Move onMQTTMessage registration BEFORE publishInfo/devices/
groups/definitions, and wrap each publish in try/catch so
Bridge.start() completes even if a single publish fails.
Add 'just z2m-patch-bridge' to apply the patch on the live container
after fresh image pulls.
- FLASH_INTERVAL_SECONDS 3 -> 2 (user preference)
- Add network_key / pan_id / ext_pan_id to zigbee2mqtt configuration
so paired devices can rejoin after a config wipe. Network key
preserved from previous working state on RPi.
- Doorbell listener flash logic with even toggle count so plug ends
at starting state
On a fresh (< MAX_AGE_SECONDS) ntfy message, spawn a thread that
publishes N TOGGLEs spaced FLASH_INTERVAL_SECONDS apart so total
runtime is FLASH_DURATION_SECONDS. Defaults: 5 toggles @ 3s = 15s.
Env vars (all in compose.yaml):
FLASH_INTERVAL_SECONDS default 3
FLASH_DURATION_SECONDS default 15
MAX_AGE_SECONDS default 180 (replay protection)
Each alert gets its own thread; concurrent alerts spawn concurrent
flashes. z2m just flips state per toggle, so the lamp alternates
regardless of overlap.
uv run without a project file (pyproject.toml/requirements.txt) won't
auto-resolve from script imports — needs inline metadata per PEP 723.
Fix: add # /// script block declaring requests + paho-mqtt>=2.0.
Polls ntfy.sh for ALERT_klubhaus_topic(_test) and publishes
{state: TOGGLE} to zigbee2mqtt/Sideboard Lamp/set on each new
message event. Dual-topic subscription so switching from test to
production requires no code change; sender still uses test topic.
- infra/doorbell-listener/: uv-based Docker service (arm64)
- compose: depends_on mosquitto, persists last_id per topic
- justfile: doorbell-publish, doorbell-logs, doorbell-rebuild,
restart-all now includes doorbell-listener
output/ is in .gitignore but the file was tracked before .gitignore
was added. Random uuid ids make every regen produce a new diff, so
build artifacts shouldn't live in version control.
Regenerate anytime with: just generate
zigbee-monitor.yaml:
- Single click (action=single) toggles Squiggle, Sideboard Lamp,
Bamboo Lights
- Press-hold-release (action=release after hold) toggles DJ Booth
only
- Two filter functions: "Single click" and "Hold release", button-in
fan-out wires to both
- DJ Booth added to zigbee-state-in and ui-text widgets for visibility
- "plugs:" list replaced with "single_plugs:" and "hold_plugs:" for
declarative clarity (generator doesn't use them, but documents intent)
infra/zigbee2mqtt/configuration.yaml:
- Removed DJ Booth from "all_plugs" group (now Squiggle, Sideboard
Lamp, Bamboo Lights only)
- Pushed same change to live /root/zigbee2mqtt/configuration.yaml and
restarted zigbee2mqtt container
Diagnostics in justfile + scripts/:
justfile:
- Constants: RPI_HOST, MQTT_HOST, MQTT_PORT, RPI_DIR, NR_PORT
- rpi, mqtt-pub, mqtt-sub, mqtt-watch, mqtt-button
- nr-show, nr-diff, nr-logs, nr-editor, nr-dashboard
- z2m-devices, z2m-logs, z2m-state
- mqtt-logs, restart, restart-all
scripts/mqtt.py:
- MQTT publish/subscribe/watch helpers using paho-mqtt v2.x
- Run via uv run --with paho-mqtt (no global install needed)
scripts/diag.py:
- nr-show: live flow summary with mqtt-out topic list
- nr-diff: structural diff deployed vs repo, normalizes random uuids
- z2m-devices: paired devices + group membership
- mqtt-button: publish action and watch /set topics (E2E test)
Verified end-to-end via `just mqtt-button`:
single → 3 messages on .../set (Squiggle, Sideboard Lamp, Bamboo Lights)
release → 1 message on .../set (DJ Booth)
Captures everything needed to rebuild the stack from scratch:
infra/compose.yaml
- mosquitto (eclipse-mosquitto:latest)
- zigbee2mqtt (ghcr.io/pine64/zigbee2mqtt:latest-dev, BLZ fork)
- nodered (nodered/node-red:latest)
infra/mosquitto/config/mosquitto.conf
- anonymous listener on 1883, file logging, persistence on
infra/zigbee2mqtt/
- configuration.yaml: 5 paired devices with friendly names, 1 group
- coordinator_backup.json: zigbee network key + pan id (recovery)
- state.json: per-device persisted state (ON/OFF, linkquality)
infra/nodered/
- settings.js: nodered defaults (flowFile: flows.json, no auth)
- start.sh: patches Dashboard 2.0 SPA with <base href> at startup
Also:
- Updated z2m groups section to rename Laser & Fog -> DJ Booth
(matches the friendly_name already in devices section)
- Pushed the same change to live /root/zigbee2mqtt/configuration.yaml
and restarted the zigbee2mqtt container
- .gitignore: output/ (regenerated on every build, churns uuid ids)
- README.md: link to infra/README.md for rebuild procedure
Closes#1.
Generator (scripts/flow2json.py):
- Emit all nodes at top level with z field (no wrapped tabs)
- Set icon: "" on ui-button to avoid Dashboard 2.0 prependIcon TypeError
- Set z field on ui-* widgets so they render in Dashboard 2.0 SPA
- Use ui-text label from spec, not name
Policy (policy/flow.rego) — 9 new deny rules:
- deny_wrapped_tab: tab with internal nodes[] (nodered 5.0 bug)
- deny_missing_wires: missing or non-array wires (Flow.js rewireNode crash)
- deny_no_autoconnect: mqtt-broker must reconnect
- deny_invalid_protocol: protocolVersion must be 3/4/5
- deny_unused_broker: broker declared but never referenced
- Plus deny_broker_port / deny_group_ref / deny_page_ref / deny_wire_ref refinements
Flow (zigbee-monitor.*):
- 22-node flat flow: button-in → btn-filter → 4 parallel plug-outs
- 4 ui-text widgets + ui-button for permit-join (60s)
- Renamed plug: "Laser & Fog" → "DJ Booth" (matches z2m friendly_name)
Repo hygiene:
- justfile: fix host IP 192.168.9.147 → 192.168.81.147, /ui → /dashboard
- README.md: document 8 generation invariants and rule table
Verified end-to-end: publishing {"action":"single"} on
zigbee2mqtt/Door Button triggers {"state":"TOGGLE"} on all four
.../set topics including the renamed DJ Booth.
462/462 conftest tests pass.
Button (Door Button) now toggles Squiggle, Sideboard Lamp, and Bamboo Lights
via three parallel mqtt-out publishes.
Key fix: avoid subscribing to a wildcard '#' topic alongside a specific topic
in the same Node-RED instance. The mqtt-broker re-adds its handler as an
EventEmitter listener on each subscribe call (file:
/usr/src/node-red/node_modules/@node-red/nodes/core/network/10-mqtt.js
_clientOn('message', subscription.handler) is unconditional), so after
each deploy/restart the same message arrives N times to internal listeners.
Each mqtt-in node now uses a unique topic (zigbee2mqtt/<device>).
Removed zigbee-in # wildcard and plug-state ui-text widgets (state now
displayed via per-plug ui-text widgets).
Added function node support to flow2json.py for msg filtering logic.
Added ui-text format/width/height defaults support.
Added dashboard 2.0 config node defaults matching reference flow:
ui-base, ui-theme, ui-page, ui-group with full property set.
david