SCOPI DELLA GUIDA:
CONCETTI AFFRONTATI:
|
COMPONENTI SOFTWARE UTILIZZATE:
PREREQUISITI:
DISPOSITIVI FISICI UTILIZZATI:
|
GUIDA indicatA per UTENTI: |
|
Note e disclaimer
|
|
Revisione guida: 1.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.
Scopo della presente guida è quello di installare e configurare ZigBee2MQTT come add-on presso Home Assistant (installato in modalità supervised HASSIO).
Altre guide disponibili su inDomus dedicate a ZigBee2MQTT sono:
- Come installare e configurare ZigBee2MQTT con Docker su Raspbian di Raspberry Pi
- Come installare e configurare ZigBee2MQTT su Raspbian di Raspberry Pi
- Come usare l’interfaccia web di ZigBee2MQTT (per pairing, impostazioni ed altro)
- 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
- Utilità: come aggiornare ZigBee2MQTT
Si parte
- Assunti
- ZigBee Coordinator (antenna)
- Broker e client MQTT
- Installare ZigBee2MQTT
- Configurare ZigBee2MQTT
- Uso
Assunti
Questa guida è dedicata a chi abbia già in uso l’HUB Home Assistant (distribuzione HASSIO).
Il computer ospitante l’HUB può essere qualsiasi, dal tradizionale Raspberry Pi a un computer vero e proprio, o altro.
Le guide disponibili su inDomus per installare HASSIO sono:
- Come installare e configurare Home Assistant (HASSIO) con Docker su un Raspberry Pi già operativo
- Come installare e configurare Home Assistant (HASSIO) su un Raspberry Pi dedicato
- Home Assistant (HASSIO) o Home Assistant CORE: quale installazione fa al caso mio?
- Home Assistant su Raspberry Pi: le varie installazioni, le cose da fare
ZigBee Coordinator (antenna)
Prima cosa, ancor prima di avventurarsi nell’installazione del BRIDGE/Gateway software, è l’installazione dell’antenna, ovvero del componente cardine di una rete mesh ZigBee: lo ZigBee Coordinator. Tale elemento è rappresentato da un’antenna interfacciata al computer ospitante via USB, via seriale o altro.
ZigBee2MQTT supporta molte antenne diverse, tra le quali abbiamo documentato e testato:
- ConBee II (USB, abbastanza potente, supporta fino a 200 componenti ZigBee, già pronta all’uso, compatibile anche con il BRIDGE/Gateway software deCONZ);
- RaspBee II (HAT per Raspberry Pi, discretamente potente, supporta fino a 200 componenti ZigBee, già pronta all’uso, compatibile anche con il BRIDGE/Gateway software deCONZ);
- CC2531 (USB, non troppo potente, molto economica, da riprogrammare manualmente);
- CC2530 (seriale, non troppo potente, molto economica, da riprogrammare manualmente);
- CC2652RB;
- CC2538 (PCB e HAT per Raspberry Pi);
- ZiGate
e svariate altre.
N.b. Sul tema “potenza” si disquisisce quotidianamente nei salotti di domotica quale argomento principe. Parlare di potenza trasmissiva ha talvolta poco senso: le reti mesh come 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. 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 (banalmente, bastano delle lampadine per illuminazione ZigBee, le quali hanno anche questa funzione – anche da “spente” – come le Philips HUE, le IKEA e molte alte) per garantirsi una copertura più che ottimale. |
È quindi necessario installare correttamente l’antenna (se è un dongle USB basta inserirla in una delle porte del computer ospitante) dopodiché appurare che il sistema operativo “veda” tale device, a valle però di un reboot (voce di menu “Supervisor” > “SYSTEM” >”REBOOT“).
VERIFICA POST-INSTALLAZIONE
Dopo aver installato l’antenna e aver avviato HASSIO, accedere a quest’ultimo e, presso la voce di menu “Supervisor” > “SYSTEM” >”HARDWARE” verificare se, nell’elenco dell’hardware installato, appaia o meno il componente, solitamente una voce specifica; nel caso di un’antenna CC2531, per esempio, appare una voce di questo tipo:
/dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B00076887D9-if00
In caso appaia l’installazione sarà considerata valida; segnarsi la stringa da una parte, servirà più avanti.
N.b. A volte l’antenna viene semplicemente riconosciuta come /dev/ttyAMAx.
Broker e client 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 è connesso, nonché la presenza delle funzionalità client MQTT presso Home Assistant.
Per configurare broker e/o client MQTT su HASSIO, si faccia riferimento a questa guida.
N.b. Procedere nella presente guida senza aver provveduto a installare correttamente broker e client MQTT causerà, ovviamente, un malfunzionamento di ZigBee2MQTT. |
Installare ZigBee2MQTT
A questo punto, con MQTT funzionante e antenna installata è possibile provvedere all’installazione di ZigBee2MQTT, il quale viene eseguito come processo tramite l’aggiunta di un add-on HASSIO. Si tratta, però, di un add-on custom pertanto non nativamente disponibile presso l’add-on store di HASSIO. Per installarlo è dunque primariamente necessario aggiungere un repository alla lista di quelli già presenti, nello specifico questo indirizzo:
https://github.com/danielwelch/hassio-zigbee2mqtt
Per aggiungerlo, recarsi alla voce di menu “Supervisor” > “ADD-ON STORE” e cliccare su “Add new repository by URL“:
Una volta inserito l’indirizzo indicato sopra, cliccare “ADD“.
Immediatamente dopo nella lista degli add-on disponibili apparirà anche la voce “zigbee2mqtt”. Cliccarci sopra per accedere alla scheda di dettaglio, poi cliccare su “INSTALL“:
Al termine dell’installazione, non avviare il plugin: è necessario, prima, configurarlo.
Configurare ZigBee2MQTT
La configurazione di ZigBee2MQTT non è particolarmente complessa ma importante. È in questa fase, infatti, che si definisco le caratteristiche di connessione del BRIDGE/Gateway da esso rappresentato verso la rete ZigBee e verso il broker MQTT.
Tale configurazione si effettua sempre dalla pagina di dettaglio dell’add-on ZigBee2MQTT; scendendo nella pagina, il riquadro “Config” riporta una configurazione di default pressapoco così:
data_path: /share/zigbee2mqtt
external_converters: []
devices: devices.yaml
groups: groups.yaml
homeassistant: true
permit_join: false
mqtt:
base_topic: zigbee2mqtt
server: 'mqtt://core-mosquitto'
user: my_user
password: my_password
serial:
port: /dev/ttyACM0
advanced:
log_level: info
pan_id: 6754
channel: 11
network_key:
- 1
- 3
- 5
- 7
- 9
- 11
- 13
- 15
- 0
- 2
- 4
- 6
- 8
- 10
- 12
- 13
availability_blocklist: []
availability_passlist: []
device_options: {}
blocklist: []
passlist: []
queue: {}
frontend:
port: 8099
experimental:
new_api: true
socat:
enabled: false
master: 'pty,raw,echo=0,link=/dev/ttyZ2M,mode=777'
slave: 'tcp-listen:8485,keepalive,nodelay,reuseaddr,keepidle=1,keepintvl=1,keepcnt=5'
restartdelay: 1
initialdelay: 1
options: '-d -d'
log: false
I campi da personalizzare sono, principalmente, quattro: “server“, “user“, “password” e “port“.
Nel primo (“server“) va indicato il nostro broker MQTT: se si usa un proprio broker presente sulla rete, è ovviamente necessario indicare in questo campo l’indirizzo IP corretto; diversamente, se si è seguita la nostra guida per installare Mosquitto Broker come add-on HASSIO, allora è necessario lasciare semplicemente “mqtt://core-mosquitto“.
Nei campi “user” e “password“, invece, è necessario indicare le credenziali d’accesso al broker MQTT, indipendentemente da dove esso sia in esecuzione. Infine, nel campo “port” indicare la porta logica dell’antenna identificata in precedenza.
Una volta terminata la configurazione, cliccare su “SAVE” e poi, sopra, su “START“: il BRIDGE/Gateway andrà in esecuzione:
Si consiglia vivamente di attivare il Watchdog (il quale provvede a riavviare l’add-on in caso di crash) e, per comodità, la presenza in sidebar (“Show in sidebar“).
VERIFICA
Per verificare che tutto sia andato per il verso giusto, recarsi sul fondo della pagina e cliccare “REFRESH” nel box “Log“: se è tutto ok, dovrebbe apparire un log “verde” che, sostanzialmente, identifica un corretto avvio di ZigBee2MQTT e un’avvenuta connessione col broker MQTT.
ATTENZIONE: se l’avvio va in errore, fermare l’add-on, modificare il campo “port” della configurazione indicando il percorso individuato installando l’antenna, salvare e provare ad avviarlo. |
Congratulazioni: ZigBee2MQTT è ora operativo.
Uso
A questo punto il BRIDGE/Gateway ZigBee2MQTT è pronto e utilizzabile al fine di integrare componenti ZigBee compatibili con tale servizio.
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.
![]() |
ATTENZIONE: ricorda che sul nostro community FORUM c'è una sezione ad hoc dedica a Home Assistant, per qualsiasi dubbio, domanda, informazione nel merito specifico di queste componenti. |
