129 lines
4.4 KiB
Markdown
129 lines
4.4 KiB
Markdown
# Docker Zigbee2MQTT on OpenWrt ARM64
|
||
|
||
**Version:** 1.0.0
|
||
**Last Updated:** 2025-12-28
|
||
**Status:** Active
|
||
|
||
This guide explains how to deploy the SecuBox Zigbee2MQTT “app” (Docker-based) on OpenWrt ARM64 targets. It uses the `secubox-app-zigbee2mqtt` package (installer, CLI, procd service) together with the LuCI frontend (`luci-app-zigbee2mqtt`).
|
||
|
||
---
|
||
|
||
## Prerequisites
|
||
|
||
1. **OpenWrt 24.10.x ARM64** (ESPRESSObin, MOCHAbin, RPi4, etc.) with ≥ 256 MB free storage (Docker image + data dir).
|
||
2. **Kernel features**: cgroups (`/sys/fs/cgroup`), USB CDC ACM (`kmod-usb-acm`).
|
||
3. **Hardware**: Zigbee coordinator presented as `/dev/ttyACM0` (e.g., SONOFF ZBDongle-E/MG21).
|
||
4. **Network**: Reachable MQTT broker (local Mosquitto or remote `mqtt://host:1883`).
|
||
5. **Package feeds**: `docker`, `dockerd`, `containerd` available (`opkg update`).
|
||
|
||
---
|
||
|
||
## Installation Steps
|
||
|
||
```sh
|
||
opkg update
|
||
opkg install secubox-app-zigbee2mqtt luci-app-zigbee2mqtt
|
||
```
|
||
|
||
1. **Run prerequisite installer** (checks storage, cgroups, USB, installs Docker, pulls image, enables service):
|
||
```sh
|
||
zigbee2mqttctl install
|
||
```
|
||
2. **Start the service**:
|
||
```sh
|
||
/etc/init.d/zigbee2mqtt start # enable automatically via installer
|
||
```
|
||
3. **LuCI configuration** (optional UI flow): Services → SecuBox → Zigbee2MQTT. Adjust serial port, MQTT host/credentials, base topics, etc., then click “Apply”.
|
||
|
||
The installer writes persistent data under `/srv/zigbee2mqtt/data` (config + DB) and exposes the Zigbee2MQTT web UI on port `8080` by default.
|
||
|
||
---
|
||
|
||
## Command-Line Reference (`/usr/sbin/zigbee2mqttctl`)
|
||
|
||
| Command | Description |
|
||
|---------|-------------|
|
||
| `install` | Full prerequisite setup (Docker packages, data dir, image pull, enable service). |
|
||
| `check` | Rerun prerequisite checks (storage, cgroups, USB module, serial device). |
|
||
| `update` | Pull the latest Zigbee2MQTT image and restart the enabled service. |
|
||
| `status` | Show Docker container status (`docker ps` filter). |
|
||
| `logs [-f]` | Stream Docker logs for the container. |
|
||
| `service-run` / `service-stop` | Internal commands used by the procd init script; not for manual invocation. |
|
||
|
||
All commands must be run as root.
|
||
|
||
---
|
||
|
||
## UCI Configuration (`/etc/config/zigbee2mqtt`)
|
||
|
||
```uci
|
||
config zigbee2mqtt 'main'
|
||
option enabled '1'
|
||
option serial_port '/dev/ttyACM0'
|
||
option mqtt_host 'mqtt://127.0.0.1:1883'
|
||
option mqtt_username ''
|
||
option mqtt_password ''
|
||
option base_topic 'zigbee2mqtt'
|
||
option frontend_port '8080'
|
||
option channel '11'
|
||
option image 'ghcr.io/koenkk/zigbee2mqtt:latest'
|
||
option data_path '/srv/zigbee2mqtt'
|
||
option timezone 'UTC'
|
||
```
|
||
|
||
Edit via `uci` or the LuCI form; commit changes to restart automatically:
|
||
```sh
|
||
uci set zigbee2mqtt.main.mqtt_host='mqtt://192.168.1.10:1883'
|
||
uci commit zigbee2mqtt
|
||
/etc/init.d/zigbee2mqtt restart
|
||
```
|
||
|
||
---
|
||
|
||
## Validation & Smoke Tests
|
||
|
||
- Quick prerequisite check:
|
||
```sh
|
||
zigbee2mqttctl check
|
||
```
|
||
- Repository smoke test (runs service start/stop + optional MQTT pub/sub):
|
||
```sh
|
||
./scripts/smoke_test.sh
|
||
```
|
||
- Diagnostics bundle (general SecuBox):
|
||
```sh
|
||
./scripts/diagnose.sh
|
||
```
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
| Symptom | Resolution |
|
||
|---------|------------|
|
||
| `zigbee2mqttctl install` reports “/sys/fs/cgroup missing” | Enable cgroups in kernel config or upgrade to a build with cgroup support. |
|
||
| USB coordinator not detected | Ensure `kmod-usb-acm` is installed, `cdc_acm` module loaded (`lsmod | grep cdc_acm`), and device appears under `/dev/ttyACM*`. Replug the dongle. |
|
||
| Docker not starting | Check `/etc/init.d/dockerd status`. If `docker info` fails, inspect `/var/log/messages` for storage driver errors. |
|
||
| MQTT authentication failures | Set `mqtt_username`/`mqtt_password` via UCI or LuCI and restart the service. |
|
||
| Port 8080 already used | Change `frontend_port` in UCI, commit, restart service. Update vhost mappings accordingly. |
|
||
|
||
---
|
||
|
||
## Uninstall / Cleanup
|
||
|
||
```sh
|
||
/etc/init.d/zigbee2mqtt stop
|
||
/etc/init.d/zigbee2mqtt disable
|
||
docker rm -f secbx-zigbee2mqtt 2>/dev/null
|
||
opkg remove luci-app-zigbee2mqtt secubox-app-zigbee2mqtt
|
||
rm -rf /srv/zigbee2mqtt
|
||
```
|
||
|
||
---
|
||
|
||
## Next Steps
|
||
|
||
- Use `luci-app-vhost-manager` to publish the Zigbee2MQTT UI under HTTPS (see `luci-app-vhost-manager/README.md`).
|
||
- Integrate with the forthcoming SecuBox App Store by adding a manifest entry referencing this installer.
|
||
- Combine with profiles/wizards once those components are introduced per the project roadmap.
|