Per la gestione dei dispositivi Zigbee possiamo utilizzare il software Zigbee2MQTT che sfrutta appunto il protocollo MQTT per la comunicazione con Home Assistant.

Si tratta di un progetto open source disponibile su GitHub.

Ci sono varie opzioni per l'installazione ma nel nostro caso utilizzeremo un "datato" Raspberry Pi in modo da avere un dispositivo indipendente dal server su cui gira Home Assistant e in grado di funzionare in ogni caso.

La procedura da seguire è quella tipica di una qualsiasi distribuzione Linux.

Naturalmente come prerequisito occorre avere un broker MQTT in esecuzione da qualche parte e accessibile in rete. Nel nostro caso gira su un container LXC di Proxmox all'interno dell'homelab server.

Dal punto di vista hardware utilizziamo una dongle Sonoff ZBDongle-E.

Facendo riferimento alla documentazione ufficiale vediamo in dettaglio i passi da seguire.

Individuare l'adattatore Zigbee e verificare i permessi utenti

Per eseguire la procedura occorre lavorare sul Raspberry, direttamente se dotato di tastiera e mouse o da remoto tramite SSH.

Per prima cosa inseriamo la dongle in una porta USB della board.

Quindi eseguiamo

ls -l /dev/ttyACM0

per verificare che sia riconosciuta correttamente.

Tuttavia è consigliabile ricorrere al mapping by ID che risulta essere decisamente più stabile.

ls -l /dev/serial/by-id 

Installazione

Procediamo con l'installazione di Node.js (se non già presente sul Raspberry) e di tutte le dipendenze richieste.

sudo apt-get install -y curl
sudo curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs git make g++ gcc libsystemd-dev

Terminata la porcedura verifichiamo la correttezza delle versioni installate

node --version  # dovrebbe essere V18.X, V20.x, V21.X
npm --version  # dovrebbe essere 9.X o 10.X

Creiamo la cartella zigbee2mqtt e impostiamo come owner l'utente corrente "pi"

sudo mkdir /opt/zigbee2mqtt
sudo chown -R ${USER}: /opt/zigbee2mqtt

Ora possiamo clonare il repository GitHub contenente il codice sorgente

git clone --depth 1 https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt

Installiamo le dipendenze richieste

cd /opt/zigbee2mqtt
npm ci

Infine facciamo la build dell'applicazione

npm run build

Se non ci sono problemi dovremmo vedere in output l'indicazione del numero di pacchetti installati e del tempo trascorso per completare l'operazione.

N.B. Durante la procedura potrebbero essere mostrati dei warning che si possono ignorare senza problemi.

Configurazione

Prima di avviare il software occorre impostare alcuni parametri di configurazione partendo dal file di esempio disponibile nella cartella di installazione.

Per cui eseguiamo

cp /opt/zigbee2mqtt/data/configuration.example.yaml /opt/zigbee2mqtt/data/configuration.yaml

nano /opt/zigbee2mqtt/data/configuration.yaml

Il file ha la seguente struttura di base

mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://192.168.1.205
  user: <username>
  password: <password>
serial:
  port: >-
    /dev/serial/by-id/usb-ITEAD_SONOFF_Zigbee_3.0_USB_Dongle_Plus_V2_2024012321>
  adapter: ember
  baudrate: 115200
  rtscts: true
advanced:
  homeassistant_legacy_entity_attributes: false
  legacy_api: false
  legacy_availability_payload: false
device_options:
  legacy: false
frontend: true
homeassistant: true
devices:

Possiamo lasciare le impostazioni di default e modificare solo la parte riservata ad MQTT e alla porta a cui è connesso il controller Zigbee.

Bisogna riservare particolare attenzione a questa parte perchè la configurazione cambia in base al coordinator utilizzato.

Nel mio caso ho utilizzato una Sonoff ZBDongle-E con firmware NCP che ho dovuto aggiornare alla versione 7.4.3 per problemi di compatibilità, per cui è stato necessario aggiungere il campo adapter: ember.

L'operazione è stata semplicissima utilizzando il web flasher di Silabs Firmware Flasher accessibile a questo link all'interno del browser che deve supportare le WebSerial API.

Con gli ultimi aggiornamenti di Zigbee2MQTT il sistema di autorilevamento degli adattatori non richiedere più tale parametro, oltre al baudrate ma per ulteriori dettagli si consiglia di leggere la documentazione ufficiale.

Il campo homeassistant impostato a true consente al software domotico (in presenza dell'integrazione MQTT con l'autodiscovering attivo) di creare le relative entità ad ogni associazione di un nuovo dispositivo Zigbee.

Per avviare il software eseguiamo

cd /opt/zigbee2mqtt
npm start

Nella configurazione è stato abilitato il frontend con

frontend
  port:8080
frontend: true

Creare il file per un servizio da avviare al boot

Osserviamo che, ad ogni riavvio del Raspberry, è necessario far partire il servizio manualmente con il precedente comando.

Possiamo creare un servizio che verrà eseguito in automatico al boot della board, lavorando in background.

Quindi prepariamo il file con

sudo nano /etc/systemd/system/zigbee2mqtt.service

Senza sudo è richiesta l'autenticazione con la pwd del Raspberry.

Aggiungiamo le seguenti istruzioni

[Unit]
Description=zigbee2mqtt
After=network.target

[Service]
Environment=NODE_ENV=production
Type=notify
ExecStart=/usr/bin/node index.js
WorkingDirectory=/opt/zigbee2mqtt
StandardOutput=null
# Or use StandardOutput=null if you don't want Zigbee2MQTT messages filling sys>
StandardError=inherit
WatchdogSec=10s
Restart=always
RestartSec=10s
User=pi

[Install]
WantedBy=multi-user.target

Un aspetto importante da tenere presente è che il Raspberry utilizza per lo storage una scheda SD quindi occorre minimizzare il numero di scritture dei log effettuate.

Utilizzando StandardOutput=inherit i log vengono salvati due volte: la prima in journalctl attraverso systemd e l'altra mediante Zigbee2MQTT che di default memorizza ogni cosa in data/log.

Con StandardOutput=null manteniamo i dati solo in data/log.

Per il corretto funzionamento del servizio sono necessari alcuni componenti che si possono installare con

sudo apt install g++ make libsystemd-dev

Al termine possiamo avviarlo con

sudo service zigbee2mqtt start 

e verificare che tutto funzioni con

systemctl status zigbee2mqtt.service

In caso di problemi si può consultare il journal con

sudo journalctl -u zigbee2mqtt.service -f 

Affinchè parta in automatico al boot bisogna abilitarlo con

sudo systemctl enable zigbee2mqtt.service

Per l'aggiornamento basta eseguire lo script

cd /opt/zigbee2mqtt
./update.sh