mirror of
https://github.com/CyberMind-FR/secubox-deb.git
synced 2026-07-29 15:37:03 +00:00
cb319b9ddd
Replaces the v1.0.0 host-bound skeleton with the canonical SecuBox LXC
pattern (sibling of mqtt v2.4.0). Depends `secubox-mqtt (>= 2.4)` —
credentials are read from /etc/secubox/secrets/mqtt-z2m at install time
and rendered into z2m's configuration.yaml.
Minimum viable v2.4.0 (operator scope choice 2026-05-20):
* LXC at 10.100.0.111 on br-lxc. Node 20 from NodeSource (Debian
bookworm only ships Node 18, too old for z2m 2.x).
* zigbee2mqtt 2.10.1 installed from the npm registry (NOT from the
GitHub tag — the tag ships only TypeScript sources and `npm start`
requires a working pnpm build chain that broke on v2.0.0 with a
TS error in worker-timers-broker. The npm tarball ships a pre-built
dist/ which sidesteps the entire build dance.)
* Hard limits per docs/superpowers/specs/2026-05-20-secubox-zigbee-mqtt-iot-stack.md:
- permit_join: false in configuration.yaml
- network_key / pan_id / ext_pan_id: GENERATE
- daemon User=zigbee2mqtt + dialout group + NoNewPrivileges=true +
ProtectSystem=strict
* udev rule /etc/udev/rules.d/99-secubox-zigbee.rules creates
/dev/secubox-zgb when a Sonoff CC2652P (1a86:55d4), ConBee II
(1cf1:0030), or CP210x (10c4:ea60) is plugged in. LXC config
bind-mounts /dev/secubox-zgb with create=file,optional so the LXC
starts whether or not the dongle is present.
* zigbeectl follows the SecuBox CTL grammar:
- introspection: components / status / access
- lifecycle: install / reload (+ stubs)
- module nouns: device / network / topology / permit-join
* Host control plane: FastAPI on /run/secubox/zigbee.sock with
/components, /status, /access, /healthz. Reverse-proxied at
/api/v1/zigbee/. Reads zigbee2mqtt/bridge/state from the broker
to populate the bridge component state.
Board-validated on gk2 (no dongle plugged):
$ zigbeectl status
lxc running zigbee @ 10.100.0.111 on br-lxc
device absent no Zigbee dongle plugged — z2m will idle
daemon running zigbee2mqtt, frontend port 8080
bridge unknown zigbee2mqtt/bridge/state @ 10.100.0.110:1883
host-api running secubox-zigbee.service (uvicorn)
overall: yellow
$ curl -I http://10.100.0.111:8080/
HTTP/1.1 200 OK # z2m onboarding page (radio absent → onboarding)
$ curl -sk -H 'Host: admin.gk2.secubox.in' https://192.168.1.200:9443/api/v1/zigbee/status
{"overall": "yellow", "states": {"lxc":"running","device":"absent",
"daemon":"running","bridge":"unknown"}}
Lessons folded in during the board cycle:
1. z2m 2.x GitHub tags ship only TS sources. The npm tarball ships
pre-built dist/ — install via `npm install zigbee2mqtt@<ver>`,
not `git clone + pnpm run build`.
2. `sudo` is broken inside unprivileged LXCs (/etc/sudo.conf is owned
by mapped uid 100000). Use `runuser -u <user> --` instead.
3. `install -d` on an existing directory doesn't always re-apply
mode/owner on bookworm — chmod/chown explicitly when widening
/etc/secubox/secrets/ from the mqtt-default 0700 root:root.
4. Long-standing bug in `config_get` (shared with sibling ctls):
`cut | tr` returns 0 even when grep matches nothing, so the
`|| echo $default` never fires. Capture into a variable, test
empty, then fall back to default.
Out of scope for v2.4.0 (deferred to v2.5):
* Z2MBridge async pub/sub pattern (full /devices, /topology,
/permit_join, /bind, /ota/* endpoints with request/response
correlation IDs)
* Frontend authentication (currently LAN-only no-auth)
* Coordinator firmware OTA via the host API
Closes #241
Co-authored-by: CyberMind-FR <gandalf@Gk2.net>
44 lines
1.5 KiB
Plaintext
44 lines
1.5 KiB
Plaintext
Source: secubox-zigbee
|
|
Section: net
|
|
Priority: optional
|
|
Maintainer: Gerald KERMA <devel@cybermind.fr>
|
|
Build-Depends: debhelper-compat (= 13)
|
|
Standards-Version: 4.6.2
|
|
Homepage: https://cybermind.fr/secubox
|
|
|
|
Package: secubox-zigbee
|
|
Architecture: all
|
|
Depends: ${misc:Depends},
|
|
secubox-core (>= 1.0),
|
|
secubox-mqtt (>= 2.4),
|
|
lxc,
|
|
lxc-templates,
|
|
debootstrap,
|
|
python3-uvicorn,
|
|
python3-fastapi,
|
|
python3-toml,
|
|
openssl,
|
|
udev
|
|
Recommends: secubox-iot-hub
|
|
Description: SecuBox Zigbee — Coordinator RF IoT (MIND layer)
|
|
Hosts zigbee2mqtt 2.x in a Debian bookworm LXC at 10.100.0.111 on br-lxc.
|
|
.
|
|
Wraps the upstream zigbee2mqtt daemon (Apache-2.0) with a SecuBox host
|
|
control plane: FastAPI on /run/secubox/zigbee.sock, reverse-proxied at
|
|
/api/v1/zigbee/ on the canonical hub vhost.
|
|
.
|
|
The Sonoff Zigbee 3.0 USB Plus dongle (CC2652P, VID:PID 1a86:55d4) is
|
|
detected by a shipped udev rule and exposed inside the LXC at
|
|
/dev/secubox-zgb. ConBee II (1cf1:0030) and generic CP210x (10c4:ea60)
|
|
are also recognized.
|
|
.
|
|
zigbee2mqtt is wired to the SecuBox broker (secubox-mqtt v2.4) as user
|
|
z2m on topic zigbee2mqtt/# — credentials are read from
|
|
/etc/secubox/secrets/mqtt-z2m at install time and rendered into
|
|
configuration.yaml. network_key and pan_id are GENERATEd by zigbee2mqtt
|
|
on first run; never hard-coded.
|
|
.
|
|
zigbeectl follows the SecuBox CTL grammar: components / status /
|
|
access + install / reload + device / network / topology / permit-join
|
|
nouns (list-only in v2.4.0).
|