Installare e configurare ZigBee2MQTT con Docker su QNAP (via Container Station)

Abstract

ZigBee, uno degli standard più adottati in domotica personale.

Spesso l’interoperabilità tra componenti basati su questo protocollo ma di diverse tipologie e diversi produttori rappresenta un problema. Esistono infatti interessantissimi componenti ma di linee molto diverse tra loro e, non potendo pensare di acquistare un BRIDGE/Gateway per ciascuna delle linee prodotti, spesso ci si trova davanti alla scelta di doversi “accontentare” di una linea prodotti rinunciando magari ad altri singoli componenti che ci interesserebbe introdurre in domotica.

Altro prodotto di questa situazione è, spesso, l’impossibilità di integrare il BRIDGE/Gateway (e quindi i componenti ZigBee ad esso collegati) col proprio HUB personale, come nel caso di quello della linea LUMI Aqara – non fosse che, per fortuna, i componenti (validissimi) di questa linea sono gestibili anche dal gateway Xiaomi Mijia, il quale è integrabile con Home Assistant. Quando dei componenti ZigBee non sono altrimenti controllabili se non col “proprio” gateway (magari non integrabile col nostro Home Assistant), in sostanza diventano inutili, se non nell’ambito del proprio ecosistema e della propria app mobile.

Per salvare capra e cavoli esistono varie possibilità, tra le quali quelle di implementare presso la nostra domotica un BRIDGE/Gateway software avulso dalle logiche dei singoli produttori.

Tra le varie alternative, è il caso di ZigBee2MQTT, oggetto della presente guida, componente software Open Source che consente per l’appunto di dotarsi gratuitamente di un BRIDGE/Gateway piuttosto evoluto per la gestione della propria rete ZigBee: una volta installato, tale BRIDGE/Gateway utilizza MQTT per instradare i messaggi da e per i componenti ZigBee tramite esso gestiti.

Va da sé che essendo MQTT un veicolo ideale per l’integrazione, sarà poi facile riuscire ad integrare il tutto con i più comuni HUB personali.

In questa guida ci concentriamo sulla possibilità di installare ZigBee2MQTT su una NAS del brand QNAP adottando un pratico container Docker, il che consente di isolare i processi del server, di essere facilmente aggiornato e molto altro. A valle di tale messa in opera, sarà possibile provvedere all’integrazione di ZigBee2MQTT su qualsiasi HUB personale (Home Assistant, openHAB ecc.) o generico client MQTT.

Altre guide disponibili su inDomus dedicate a ZigBee2MQTT sono:

• Come usare l’interfaccia web di ZigBee2MQTT (per pairing, impostazioni ed altro)
• Gestire ZigBee sui diversi BRIDGE/Gateway usando coordinator MultiPAN RCP (ZBDongle-E, Z-Station, SkyConnect e affini) via Silicon Labs
• Installare e configurare ZigBee2MQTT con Docker su Linux Debian (Mini PC/Intel NUC o altro)
• Installare e configurare ZigBee2MQTT con Docker su Raspberry Pi OS
• Installare e configurare ZigBee2MQTT su Home Assistant OS/Supervised
• Installare e configurare ZigBee2MQTT su Raspberry Pi OS
• Integrare componenti ZigBee su Home Assistant via ZigBee2MQTT
• Riprogrammare il firmware del dongle USB CC2531 tramite Raspberry Pi e senza CC Debugger
• Riprogrammare il firmware del dongle USB CC2531 via CC Debugger
• Riprogrammare il firmware dello ZigBee Coordinator Dongle USB Z-Bee Duo
• Riprogrammare il firmware di ITEAD Sonoff ZBDongle-E (ZigBee 3.0 USB Dongle Plus)
• Riprogrammare il firmware di ITEAD Sonoff ZBDongle-E (ZigBee 3.0 USB Dongle Plus) – v2
• Riprogrammare il firmware di ITEAD Sonoff ZBDongle-P (ZigBee 3.0 USB Dongle Plus)
• Utilità: come aggiornare ZigBee2MQTT

Procedimento

• Assunti
• ZigbBee coordinator (l’antenna)
  • Firmware coordinator
  • Driver
  • Verifiche post installazione
• Broker MQTT
• Definizione configurazione
• File Station
• Container Station
• Aggiornamento
• Uso

Assunti

Questa guida è dedicata a chi abbia già un QNAP in uso.

Si assume che il sistema operativo del QNAP sia aggiornato, così come le componenti Docker, File Station e Container Station che andremo ad utilizzare; è necessario che QNAP sia ovviamente collegato in rete e che la rete gli consenta libero accesso alla rete Internet. Altra assunzione è la presenza di almeno un hard disk presente nella NAS correttamente configurato.

Per istanziare il container docker di ZigBee2MQTT utilizzeremo l’interfaccia Container Station di QNAP, mentre utilizzeremo File Station per indicare alla NAS dove salvare i file di configurazione e di storage.

Si assume altresì che eventuali altri BRIDGE/Gateway software o comunque software che utilizzino l’antenna coordinator che utilizzeremo per ZigBee2MQTT (ZHA, deCONZ o altri) siano stati preventivamente fermati.

ZigBee coordinator (l’antenna)

Prima cosa, ancor prima di avventurarsi nell’installazione del BRIDGE/Gateway software, è l’implementazione dell’antenna, ovvero del componente cardine di una rete mesh ZigBee: il cosiddetto ZigBee coordinator. Tale elemento è rappresentato da un’antenna interfacciata al computer ospitante ZigBee2MQTT via USB, via seriale oppure decentrata, gestita remotamente via LAN/Wi-Fi (o altro).

ZigBee2MQTT supporta molte antenne diverse, tra le quali abbiamo documentato e testato:

e svariate altre. 

È quindi necessario installare correttamente l’antenna (se è un dongle USB basta inserirlo nella porta del QNAP e installare i driver di gestione USB, come spiegato a seguire) oppure fare sì che l’antenna decentrata scelta sia correttamente configurata e pronta a recepire comunicazioni (eg. Sonoff ZigBee Bridge Pro con firmware Tasmota).

FIRMWARE COORDINATOR

• aggiornamento firmware per ITEAD Sonoff ZigBee 3.0 Dongle Plus;
• aggiornamento firmware per ITEAD Sonoff ZigBee 3.0 Dongle Plus v2 (ZBDongle-E) - firmware NCP
• aggiornamento firmware per Z-Wave.Me Z-Station - firmware NCP
• aggiornamento firmware per ConBee/Raspbee;
• aggiornamento firmware per Z-Bee Duo ("quella di Giovanni");
• aggiornamento firmware per ITEAD Sonoff ZigBee Bridge (con firmware Tasmota);
• aggiornamento firmware per CC2531 (anche senza debugger);
• aggiornamento firmware per CC2530.

• riprogrammazione con firmware Zigbee2Tasmota per Sonoff ZigBee Bridge Pro (ZB Bridge-P).
• riprogrammazione firmware per ITEAD Sonoff ZigBee 3.0 Dongle Plus v2 (ZBDongle-E) - firmware Multi-PAN (RCP) - si consiglia l'uso della versione 4.3.1 e non della 4.4 (la quale risulta buggata)
• riprogrammazione firmware per Z-Wave.Me Z-Station - firmware Multi-PAN (RCP)

DRIVER

Dopo aver aggiornato il firmware dell’antenna, averla collegata (in caso sia USB) e aver riavviato QNAP, è dunque il momento di installare l’app “USB Serial“.

insmod /usr/local/modules/cp210x.ko

Per farlo è necessario aprire App Center, cliccare sull’icona delle impostazioni in alto a destra e poi, sul tab “Archivio di app“, ciccare su “Aggiungi“. A questo punto va scelto un nome arbitrario da assegnare al repository e, sopratutto, va aggiunta la seguente URL:

https://qnapclub.eu/en/repo.xml

come da immagine:

A questo punto tra le varie fonti di App Center avremo aggiunto anche qnapclub.eu; cliccado sul repository e cercando nella barra in alto “USB Serial“, apparirà l’applicazione di cui abbiamo bisogno. Clicchiamo quindi su “Installa“.

Apparirà un avviso che avvertirà che l’app non è firmata digitalmente: ignorare l’avviso e, selezionando “Comprendo i rischi“, clicchiamo infine su “Installa“.

Al termine, riavviare QNAP.

VERIFICA POST-INSTALLAZIONE

Dopo aver installato l’antenna e aver riavviato QNAP è il momento di effettuare una verifica per verificare che l’antenna funzioni.
A tal scopo, collegarsi via SSH al QNAP ed eseguire il comando:

ls -lart /dev | grep USB

Il quale dovrà fornire un output di questo tipo:

crw------- 1 admin administrators 188, 0 1980-01-07 00:00 ttyUSB0

il che confermerà l’avvenuta configurazione della porta logica assegnata all’antenna USB.

Broker MQTT

Come suggerisce il nome, il software ZigBee2MQTT, per funzionare, necessita della presenza di un broker MQTT sulla rete locale sulla quale il computer che lo esegue – in questo caso il nostro QNAP – è connesso.

Per configurare il broker MQTT su QNAP, si faccia riferimento a questa guida.

Definizione configurazione

Prima cosa, aprire un qualsiasi editor di testo e creare un file chiamato configuration.yaml in notazione YAML, appunto, che contenga il seguente codice:

# Autodiscovery su Home Assistant abilitato
homeassistant: true
# Join alla rete MQTT disabilitato di default
permit_join: false
# MQTT settings
mqtt:
  # MQTT base topic per i messaggi di zigbee2mqtt
  base_topic: zigbee2mqtt
  # MQTT server - URL (indirizzo LAN)
  server: 'mqtt://IP_DEL_BROKER_MQTT'
  # MQTT server - Parametri di autenticazione (decommentare e popolare correttamente se si utilizzano credenziali per la connessione al broker MQTT
  user: username
  password: password
  include_device_information: true
serial:
  # Porta su cui è mappata l'antenna zigbee
advanced:
  # Directory in cui verrà salvato il file di log
  log_directory: /var/log
experimental: {}
frontend:
  # porta su cui verrà esposta la webGUI
  port: 8080
ota:
  update_check_interval: 10
disable_automatic_update_check: false

• "homeassistant";
• "server";
• "user" e "password";
• "serial".

serial:
  port: /dev/ttyXXX
  adapter: deconz

serial:
  port: /dev/ttyXXX

serial:
  port: /dev/ttyXXX
  adapter: ember 

serial:
  port: /dev/ttyXXX
  adapter: ember 

port:
 tcp://indirizzo_ip_tasmota:8888

File Station

Definita la propria configurazione, il passo seguente da eseguire è quello di definire un percorso presso lo storage nel quale salvare i file di configurazione di cui sopra.

Dall’interfaccia web della NAS QNAP avviamo quindi l’applicazione File Station.
Selezionare il volume prescelto per ospitare i file di ZigBee2MQTT (nel nostro caso “Volume1“) cliccando sui tre puntini in alto a destra, selezionando poi “Crea cartella condivisione“:

Nel nostro caso abbiamo deciso di creare una directory principale (“domotica-indomus“) nella quale posizionare tutte le sotto-directory relative ai progetti dedicati alla domotica. Gli altri parametri possono esser lasciati così come sono, di default:

Creare quindi una sotto-directory dedicata a ZigBee2MQTT. Per farlo, cliccare sull’icona della cartella con il “+” selezionando poi “Cartella/e“:

Chiamiamola, con poca fantasia, “zigbee2mqtt“:

A questo punto è necessario caricare i propri file di configurazione. Portiamoci sulla directory appena creata e clicchiamo sull’icona per l’upload dei file (“freccia verso l’alto”), selezioniamo “File” e carichiamo il file configuration.yaml creato in precedenza sul proprio computer d’appoggio.

A questo punto siamo pronti a istanziare il container di ZigBee2MQTT tramite Container Station.

Container Station

In questo passaggio – cardinale – si andrà a istanziare ZigBee2MQTT come container Docker presso Container Station: dall’interfaccia web della NAS QNAP avviare quindi tale applicazione.

Cercare quindi “zigbee2mqtt” nell’elenco delle immagini disponibili (consultate da QNAP su Internet) selezionando come fonte “Docker Hub“.

Cliccando quindi su “Installa” verrà mostrato un menu a tendina da cui scegliere la versione da utilizzare.
Selezioniamo la “Latest“. Apparirà un warning relativo alla fonte dell’immagine. Non preoccuparsene e andare avanti.

Nella schermata successiva si attribuirà un nome al container:

Si seleziona quindi “Impostazioni avanzate” > “Rete“.
Impostare “NAT” quale modalità di rete, avendo poi cura di configurare l’inoltro porte con:

• host: 8080
• contenitore: 8080
• protocollo: TCP.

Alla voce “Dispositivi” impostiamo modalità privilegiata. Clicchiamo su “Aggiungi” e selezioniamo i device “TTY”:

Portandosi poi alla voce “Cartelle Condivise“, andrà selezionato:

1) a sinistra, la directory di configurazione dell’host da utilizzare per la configurazione (definita in precedenza);
2) a destra, la directory di configurazione di HA prevista nella configurazione dell’immagine Docker di ZigBee2MQTT, ovvero “/app/data” assicurandosi di fornire permessi di lettura e scrittura:

Infine, cliccare su “Crea“: verrà mostrato il riepilogo della configurazione.
Premendo su “OK” verrà avviata la creazione del container e, dopo qualche momento, si completerà positivamente.

Una volta completato il processo, cliccando sulla voce “Panoramica” del menù si potrà apprezzare l’esistenza del nuovo container di ZigBee2MQTT. L’interfaccia ci permetterà, alla bisogna, di riavviare, fermare, eliminare o modificare il container:

Presso la sezione “Log“, invece, sarà possibile verificare il corretto funzionamento del software e i vari stati da esso prodotti:

PROBLEMI? In caso ZigBee2MQTT non parta, ti consiglio di leggere qui:

Troubleshooting ZigBee2MQTT: perché “non parte” e come risolvere

Aggiornamento

Per aggiornare ZigBee2MQTT implementato come container Docker su Container Station è sufficiente rimuovere il container per poi crearlo nuovamente:

Ovviamente, è necessario conoscere prima le modalità con cui era stato creato. Se si è seguita questa  nostra guida, è sufficiente rimuoverlo e rifare la procedura; differentemente, assicurarsi prima di avere tutte le coordinate necessarie. Comunque sia è difficile “far danni”: la cartella contenente la configurazione non viene toccata dalla rimozione del container, quindi è facile ricrearlo puntando ad essa e ritrovare perfettamente funzionante il proprio BRIDGE/Gateway ZigBee.

Uso

A questo punto il BRIDGE/Gateway ZigBee2MQTT è pronto e utilizzabile al fine di integrare componenti ZigBee compatibili con tale software, alcuni dei quali da noi testati e recensiti in dettaglio.

Ogni componente compatibile, una volta associato a ZigBee2MQTT, può essere comandato e censito tramite MQTT e amministrato attraverso la sua interfaccia web. Ovviamente, il passo successivo è quello di integrare ZigBee2MQTT col proprio HUB personale, al fine di utilizzare le risorse delle varie componenti ZigBee all’interno della propria domotica personale.

In caso il proprio HUB personale sia il diffusissimo Home Assistant è possibile integrare ZigBee2MQTT ad esso (e con lui quindi le componenti ZigBee da controllare) sia tramite una modalità automatica che una manuale. Tali tecniche sono descritte in questa guida.
Analogamente, altri HUB o servizi possono utilizzare MQTT per interfacciarsi rapidamente con ZigBee2MQTT.