tudattr/ansible
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: add zigbee2mqtt design spec for naruto

Browse Source
This commit is contained in:
Tuan-Dat Tran
2026-06-03 02:54:18 +02:00
parent f6e2ce8c1a
commit 29cc38872c
1 changed files with 82 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

82
docs/superpowers/specs/2026-06-03-naruto-zigbee2mqtt-design.md Normal file
View File

@@ -0,0 +1,82 @@
# Zigbee2MQTT + Mosquitto on naruto — Design Spec
**Date:** 2026-06-03
## Goal
Run Zigbee2MQTT and Mosquitto as Docker containers on naruto, managed by the `raspberry_pi` Ansible role. Home Assistant (running in k3s) connects to Mosquitto over the LAN.
## Hardware
- Host: naruto (Pi 4, 192.168.20.13)
- Zigbee coordinator: SONOFF Dongle Lite MG21 on `/dev/ttyUSB0`
- Stable by-id path: `/dev/serial/by-id/usb-SONOFF_SONOFF_Dongle_Lite_MG21_0263f93f46a2ef11b078926661ce3355-if00-port0`
## Architecture
Two containers via Docker Compose on naruto. Ansible templates all configs and manages the stack. Home Assistant adds the MQTT integration pointing at `192.168.20.13:1883`.
```
[SONOFF Dongle /dev/ttyUSB0]
|
[zigbee2mqtt container]
| MQTT (internal docker network)
[mosquitto container] :1883
|
[Home Assistant in k3s] — via LAN 192.168.20.13:1883
```
## Directory Layout on naruto
```
/opt/docker/
config/
mosquitto/
mosquitto.conf
data/
log/
zigbee2mqtt/
configuration.yaml
data/
compose/
docker-compose.yml
```
## Mosquitto Config
- Listens on port 1883
- No authentication (internal LAN only)
- Persistence enabled, logs to `/opt/docker/config/mosquitto/log/`
## Zigbee2MQTT Config
- Serial port: `/dev/serial/by-id/usb-SONOFF_SONOFF_Dongle_Lite_MG21_0263f93f46a2ef11b078926661ce3355-if00-port0`
- MQTT broker: `mqtt://mosquitto:1883` (internal docker network)
- Network key: stored in `vars/group_vars/raspberry_pi/secrets.yaml` as `vault_raspberry_pi.zigbee2mqtt.network_key`
- Frontend enabled on port 8080 for local device management
## Secrets
`vars/group_vars/raspberry_pi/secrets.yaml` (vault-encrypted, placeholder for now):
```yaml
vault_raspberry_pi:
zigbee2mqtt:
network_key: "YOUR_ZIGBEE_NETWORK_KEY"
```
## Ansible Changes
| Action | Path | Responsibility |
|--------|------|----------------|
| Modify | `roles/raspberry_pi/tasks/main.yaml` | Include numbered task files |
| Create | `roles/raspberry_pi/tasks/10_directories.yaml` | Create `/opt/docker/` tree |
| Create | `roles/raspberry_pi/tasks/20_zigbee2mqtt.yaml` | Template configs, start compose |
| Create | `roles/raspberry_pi/templates/zigbee2mqtt/docker-compose.yml.j2` | Compose file |
| Create | `roles/raspberry_pi/templates/zigbee2mqtt/mosquitto.conf.j2` | Mosquitto config |
| Create | `roles/raspberry_pi/templates/zigbee2mqtt/z2m-configuration.yaml.j2` | Zigbee2MQTT config |
| Create | `vars/group_vars/raspberry_pi/secrets.yaml` | Network key placeholder |
## Host Constraint
The `raspberry_pi` role applies to both naruto and pi. The Zigbee2MQTT tasks must be guarded with `when: inventory_hostname == 'naruto'` since the USB dongle is only on naruto.