SCOPI DELLA GUIDA:
CONCETTI AFFRONTATI:
|
COMPONENTI SOFTWARE UTILIZZATE:
PREREQUISITI:
DISPOSITIVI FISICI UTILIZZATI:
|
GUIDA INDICATA PER: |
|
NOTE E DISCLAIMER
|
|
Revisione guida: 2.0 |
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 RCP MultiPAN (ZBDongle-E, Z-Station, ZBT-1 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 OpenMediaVault (NAS o host analoghi)
- 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)
- Usare Sonoff ZBDongle-E come ripetitore di segnale mesh ZigBee (“router”)
- 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:
Antenna coordinator | Caratteristiche |
ConBee III | dongle USB, di buona potenza, stack 3.0, supporta fino a 200 componenti ZigBee, già pronta all'uso, compatibile anche con il BRIDGE/Gateway software deCONZ e ZHA. Tecnicamente multistandard. |
🔆 Z-Wave.Me Z-Station | dongle USB multistandard (ZigBee, Z-Wave, Thread): segnale molto potente, stack 3.0, supporta fino a 200 componenti ZigBee, già pronta all'uso. Compatibile anche con il BRIDGE/Gateway software ZigBee2MQTT e utilizzabile contemporaneamente anche per Matter over Thread (tramite firmware RCP) nonché con Z-Wave JS e altri BRIDGE compatibili Z-Wave |
🔆 ITEAD Sonoff ZigBee 3.0 Dongle Plus v2 (ZBDongle-E) | dongle USB multistandard, segnale molto potente, stack 3.0, supporta fino a 200 componenti ZigBee, già pronta all'uso. Compatibile anche con il BRIDGE/Gateway software ZHA di Home Assistant e utilizzabile contemporaneamente anche per Matter over Thread (tramite firmware RCP) |
Connect ZBT-1 (SkyConnect) | sostanzialmente identica alla precedente ZBDongle-E, ma senza antenna esterna (quindi meno potente in termini di trasmissione radio) |
Z-Bee Duo | "quella di Giovanni", fatta a mano, dongle USB, piuttosto potente e versatile basato su stack 3.0 |
USB Stick CC2652P | dongle USB, abbastanza potente e versatile, stack 3.0, supporta fino a 200 componenti ZigBee, già pronta all'uso |
RaspBee II | HAT specifico per Raspberry Pi, non particolarmente potente, supporta fino a 200 componenti ZigBee, già pronta all'uso, compatibile anche con il BRIDGE/Gateway software deCONZ. |
CC2531 | dongle USB, non troppo potente, molto economica, da riprogrammare manualmente - sconsigliato per obsolescenza |
CC2530 | seriale, poco potente, molto economica, da riprogrammare manualmente - sconsigliato per obsolescenza |
CC2538 | PCB e HAT specifico per Raspberry Pi |
Bitronvideo QIVICON Homebase | dongle USB |
🔆 Sonoff ZigBee Bridge Pro (ZB Bridge-P) | utilizzabile come antenna coordinator decentrata, via firmware ZigBee2Tasmota: è infatti un'antenna non collegata fisicamente all'host che ospita ZigBee2MQTT, ma via Wi-Fi (quindi posizionabile dove meglio si crede nell'ambiente, al fine di posizionare il "centro stella" in un luogo magari più consono) |
SMLIGHT SLZB-06 | utilizzabile come antenna coordinator decentrata. Può essere utilizzata alimentandola ai PoE |
e svariate altre.
IMPORTANTE. Sul tema "potenza" si disquisisce quotidianamente nei salotti di domotica quale argomento principe. Parlare di potenza trasmissiva ha per lo più poco senso: le reti mesh come quelle basate su ZigBee sono concepite per esser ripetute e non per aver un singolo nodo di potenza massima che provveda a coprire tutta la superficie - la differenza vera semmai la fa, piuttosto, l'affidabilità del componente stesso. In caso di ambienti ampi e/o con muri spessi, se i componenti ZigBee risultano irraggiungibili la scelta dell'antenna può quindi non essere legata alla sua potenza: basta infatti introdurre, oltre all'antenna principale, dei repeater ZigBee ("router") per garantirsi una copertura più che ottimale. Ne abbiamo testati svariati: semplificando, sono repeater quasi tutti i componenti ZigBee alimentati a tensione di rete (lampadine, attuatori ecc.) ma anche chiavette dongle come per esempio la Sonoff ZBDongle-E opportunamente riprogrammate con firmware "router". |
È 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
Prima di iniziare a utilizzare la propria antennza coordinator, si consiglia di provvedere all'eventuale aggiornamento firmware. Non potendo documentare qualunque procedura per qualunque antenna, abbiamo documentato quelle che seguono.Antenne fisicamente collegate all'host:
- 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 le seguenti (le quali risultano buggate)
- riprogrammazione firmware per Z-Wave.Me Z-Station - firmware Multi-PAN (RCP)
N.b. L'aggiornamento potrebbe anche non essere necessario (magari la versione del firmware è già quella più recente), ma è bene controllare prima di procedere. Nel caso delle antenne coordinator decentrate, solitamente è necessario. |
DRIVER
IMPORTANTE: Se il coordinator scelto non è un’antenna fisicamente collegata all’host ospitante ZigBee2MQTT, questo paragrafo può essere saltato per passare a quello successivo.
Sono da considerarsi “non fisicamente collegate” anche quelle che magari lo sono, ma in effetti sono gestite tramite software intermedi come Silicon Labs Multiprotocol, come per esempio una Sonoff ZBDongle-E con firmware Multi-PAN (RCP). |
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“.
N.b. In caso questo componente dia problemi, come è capitato ad alcuni, provvedere ad usare un altro approccio, come spiegato nel commento linkato, ovvero adottando il comando:
insmod /usr/local/modules/cp210x.ko
in autorun.sh. |
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.
N.b. Noi abbiamo testato una CC2530, la quale viene montata in automatico come /dev/ttyUSB0, ma per altri device potrebbe essere diverso (eg. /dev/ttyACM0 o altro). |
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.
N.b. Procedere nella presente guida senza aver provveduto a installare correttamente broker MQTT causerà, ovviamente, il malfunzionamento di ZigBee2MQTT. |
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:
serial:
# Porta su cui è mappata l'antenna zigbee
mqtt:
base_topic: zigbee2mqtt
server: 'mqtt://IP_DEL_BROKER_MQTT'
user: username
password: password
version: 5
reject_unauthorized: true
include_device_information: true
permit_join: false
frontend:
port: 8080
homeassistant:
legacy_triggers: true
legacy_entity_attributes: false
ota:
update_check_interval: 1440
disable_automatic_update_check: false
availability:
enabled: true
advanced:
cache_state: true
cache_state_persistent: true
cache_state_send_on_startup: true
channel: 19
transmit_power: 20
legacy_api: false
legacy_availability_payload: false
log_level: info
log_namespaced_levels:
z2m:mqtt: warning
I campi da personalizzare sono, principalmente:
- "homeassistant";
- "server";
- "user" e "password";
- "serial".
PORTE COORDINATOR La porzione in rosso nella configurazione di cui sopra (campo "serial") è particolarmente critica, perché prevede configurazioni specifiche in base al coordinator in uso. Se si sbaglia tale configurazione, il BRIDGE/Gateway non partirà. Vediamo alcune configurazione specifiche:Phoscon ConBee o RaspBeeSe si utilizza un'antenna ConBee II, ConBee III o RaspBee II, aggiungere questa porzione:serial: port: /dev/ttyXXX adapter: deconz baudrate: XXXXXdove /dev/ttXXX va sostituito con la porta logica assegnata al coordinator e individuata precedentemente, mentre il baudrate va impostato in base al modello. Sonoff ZBDongle-PSe invece si usa la ITEAD Sonoff ZigBee 3.0 USB Dongle v1 (ZBDongle-P) con firmware di fabbrica o Koenkk, aggiungere questa:serial:
port: /dev/ttyXXX
adapter: zstack
dove /dev/ttXXX va sostituito con la porta logica assegnata al coordinator e individuata precedentemente.
Sonoff ZBDongle-E con firmware NCPSe invece si usa la ITEAD Sonoff ZigBee 3.0 USB Dongle Plus v2 (ZBDongle-E) con firmware NCP (di fabbrica), aggiungere questa:serial:
port: /dev/ttyXXX
adapter: ember
dove /dev/ttXXX va sostituito con la porta logica assegnata al coordinator e individuata precedentemente.
Sonoff ZBDongle-E con firmware RCPSe invece si utilizza il firmware MultiPan RCP per l'uso contemporaneo anche dello standard Thread (comunque non consigliato per questioni di stabilità), la configurazione cambia; l'abbiamo spiegata qui.Sonoff ZigBee Bridge Pro (ZB Bridge-P)Dopo aver provveduto alla configurazione del firmware Tastmota sul coordinator, la configurazione è la seguente:port: tcp://indirizzo_ip_tasmota:8888dove indirizzo_ip_tasmota va sostituito con l'indirizzo IP assegnato (staticamente) al coordinator dotato di firmware Tasmota. Z-Wave.Me Z-Station con firmware NCPSe invece si usa la Z-Station di Z-Wave.ME con firmware NCP (di fabbrica), aggiungere questa:serial:
port: /dev/ttyXXX
adapter: ember
dove /dev/ttXXX va sostituito con la porta logica assegnata al coordinator e individuata precedentemente.
Z-Wave.Me Z-Station con firmware RCPSe invece si utilizza il firmware MultiPan RCP per l'uso contemporaneo anche dello standard Thread (comunque non consigliato per questioni di stabilità), la configurazione cambia; l'abbiamo spiegata qui.AltroUlteriori dettagli relativi alle configurazioni (queste o altre possibili) sono forniti qui. |
|
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.
ATTENZIONE: tramite la configurazione è anche possibile definire il canale radio da utilizzare. (parametro channel). Non è affatto un argomento secondario: “sbagliarlo” significa incappare quasi sicuramente in problemi di interferenza (e quindi di fruizione degli end-device wireless). Per approfondire il tema, si consiglia la lettura di questo FOCUS. |
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.
Questa pagina è redatta, manutenuta e aggiornata dallo staff di inDomus, un gruppo di persone molto diverse tra loro che trovi, per domande e supporto, sul forum e sulla chat del sito. Alcuni link sono taggati in qualità di affiliati Amazon e riceviamo un compenso dagli acquisti idonei, utile al sostenimento del sito, ma le nostre recensioni sono tutte indipendenti e non sponsorizzate. Se ti sei perso, a tua disposizione c'è la mappa. |