community italiana di domotica personale
 
Installare e configurare ZigBee2MQTT su Raspberry Pi OS

Installare e configurare ZigBee2MQTT su Raspberry Pi OS

SCOPI DELLA GUIDA:
  • Installare e configurare il BRIDGE/Gateway ZigBee2MQTT su sistema operativo Raspberry Pi OS, dotandosi così di una rete Zigbee per la propria domotica personale
  • Livello di difficoltà: medio
CONCETTI AFFRONTATI:
  • Installazione e configurazione software
COMPONENTI SOFTWARE UTILIZZATE:
  • Sistema operativo Raspberry Pi OS (aka Raspbian)
  • ZigBee2MQTT
  • Broker MQTT
PREREQUISITI:
DISPOSITIVI FISICI UTILIZZATI:
  • Raspberry Pi
  • Un’antenna coordinator Zigbee compatibile con ZigBee2MQTT, fisicamente collegata o decentrata (illustrato a seguire)
GUIDA DEDICATA A utenti:
Raspbian
NOTE E DISCLAIMER
  • qualsiasi eventuale modifica agli impianti domestici dev'essere progettata e realizzata SOLO da personale qualificato;
  • qualsiasi modifica non prevista attuata in proprio è a propria responsabilità personale nonché a proprio rischio e pericolo (i contenuti della presenta pagina hanno infatti puro scopo didattico) e fa decadere garanzia, omologazioni e certificazioni di qualità; dei dispositivi interessati;
  • tutte le tecniche descritte si intendono applicate a software e firmware aggiornati alle ultime versioni disponibili;
  • gli articoli di inDomus sono totalmente indipendenti e non sponsorizzati. Se mai questo cambiasse, verrà segnalato chiaramente sulle pagine oggetto di sponsorizzazione;
  • questa pagina è materialmente scritta e manutenuta da più individui: non ci si aspetti né si pretenda un supporto personale. In caso di difficoltà, chiedere supporto alla community sul nostro forum o sulla nostra chat;
  • se hai bisogno di orientarti, c'è la mappa.
Revisione guida: 2.3

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 applicativo presso il sistema operativo Raspberry Pi OS di Raspberry Pi. La guida è sostanzialmente valida anche per qualsiasi altro sistema Linux. 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:

Si parte

Assunti

Questa guida è dedicata a chi abbia già un Raspberry in uso con sistema operativo Raspberry Pi OS (aka Raspbian). Per coloro che non abbiano ancora provveduto e si trovino ad avere un Raspberry nuovo, magari acquistato appositamente per realizzare la propria domotica, allora questo passo della guida va smarcato seguendo prima un’altra guida, che spiega passo passo come configurare il sistema operativo Raspberry Pi OS.

La guida da seguire:

Una volta terminata la configurazione di Raspberry Pi OS (inclusa la possibilità di collegarvisi tramite SSH) è possibile procedere nella presente guida.

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)

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 Raspberry Pi o del computer host dopodiché appurare che il sistema operativo “veda” tale device) 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: Antenne decentrate (collegate per esempio via LAN/Wi-Fi):
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.
VERIFICA POST-INSTALLAZIONE
IMPORTANTE: Se il coordinator scelto non è un’antenna fisicamente collegata all’host ospitante ZigBee2MQTT, questo paragrafo può essere saltato per passare a quello successivo (“Broker e client MQTT”).

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 Raspberry Pi, è dunque il momento di effettuare una verifica per appurare porta logica sia stata assegnata all’antenna dal sistema operativo. A questo scopo andiamo a definire uno script come da nostra guida.

Eseguito lo script, l’elemento che inizia con “tty” e prosegue con la descrizione dell’antenna (per esempio dresden_elektronik_ingenieurtechnik_GmbH_ConBee” per la ConBee II, Texas_Instruments_TI_CC2531_USB_CDC per la CC2531, e così via) è quello che identifica la porta che ci interessa (per esempio /dev/ttyACM0).

In presenza di questo elemento, l’antenna è riconosciuta correttamente dal sistema. Segnarsi tale stringa, servirà a seguire.

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.

Come sempre, in caso di questa necessità consigliamo l’installazione di Eclipse Mosquitto.

N.b. Procedere nella presente guida senza aver provveduto a installare correttamente broker e client MQTT causerà, ovviamente, un malfunzionamento di ZigBee2MQTT.

Installazione

A questo punto, con MQTT funzionante e antenna installata è possibile provvedere all’installazione di ZigBee2MQTT, il quale viene eseguito come processo tramite un’installazione specifica.

Per installare ZigBee2MQTT, sempre da terminare, cominciare con la clonazione del repository:

sudo git clone https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt
sudo chown -R pi:pi /opt/zigbee2mqtt

creiamo poi l’ambiente virtuale “venv” nel quale eseguire ZigBee2MQTT:

cd /opt/zigbee2mqtt
python3 -m venv .
source /opt/zigbee2mqtt/bin/activate
pip install --upgrade pip wheel setuptools
pip install nodeenv
nodeenv -p -n 20.12.2

installiamo infine le dipendenze:

cd /opt/zigbee2mqtt
npm ci
deactivate

Configurazione

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, nonché le coordinate dell’antenna.

Tale configurazione si effettua modificando il file “configuration.yaml” presente presso il path “/opt/zigbee2mqtt/“.

Eseguire, sempre da terminale, il seguente comando:

sudo nano /opt/zigbee2mqtt/data/configuration.yaml

e copiare all’interno del file 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
I campi da personalizzare sono, principalmente:
  • "homeassistant";
  • "server";
  • "user" e "password";
  • "serial".
Il campo homeassistant nella configurazione proposta è impostato a true. Tale impostazione fa sì che - laddove lato Home Assistant l'integrazione MQTT abbia attiva "l'auto identificazione" (autodiscovery), questo fa sì che ogni qual volta venga associato un nuovo componente a ZigBee2MQTT automaticamente vengano create le relative entità lato Home Assistant. Se si adotta ZigBee2MQTT per usarlo con Home Assistant, il nostro consiglio è di lasciare inizialmente tale campo a false, così da concedere all'utente la possibilità di di definire eventualmente la proprie entità a mano (in ottica di "pulizia" e di maggiore versatilità). Diversamente, lasciare true.  Nel campo "server" va indicato il nostro broker MQTT: se si usa un proprio broker presente sulla rete, sarà ovviamente necessario indicare in questo campo l'indirizzo IP corretto; diversamente, se si è seguita la nostra guida per installare Mosquitto Broker, allora sarà necessario indicare semplicemente "mqtt://core-mosquitto" su Home Assistant Core/Supervised o "mqtt://ip-del-broker-mqtt" sulle altre installazioni (eg. su Docker). 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 precedentemente identificata. In ultimo, si noti il campo finale, "frontend", presso il quale è indicata al porta TCP/IP (tipicamente la 8080) presso la quale risponderà l'interfaccia web di gestione di ZigBee2MQTT.

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 RaspBee

Se si utilizza un'antenna ConBee II, ConBee III o RaspBee II, aggiungere questa porzione:
serial:
  port: /dev/ttyXXX
  adapter: deconz
dove /dev/ttXXX va sostituito con la porta logica assegnata al coordinator e individuata precedentemente.

Sonoff ZBDongle-P

Se 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
dove /dev/ttXXX va sostituito con la porta logica assegnata al coordinator e individuata precedentemente.

Sonoff ZBDongle-E con firmware NCP

Se 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 RCP

Se 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:8888
dove indirizzo_ip_tasmota va sostituito con l'indirizzo IP assegnato (staticamente) al coordinator dotato di firmware Tasmota.

Z-Wave.Me Z-Station con firmware NCP

Se 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 RCP

Se 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.

Altro

Ulteriori dettagli relativi alle configurazioni (queste o altre possibili) sono forniti qui.
 

Una volta terminata la personalizzazione della configurazione, uscire salvando (CTRL+X, Y, invio).

Vetrina - Offerte del giorno

Avvio del servizio

Dopo aver installato e configurato ZigBee2MQTT è necessario creare un servizio al fine di eseguirlo automaticamente all’avvio del Raspberry. Per farlo, va creato innanzitutto il file di configurazione del servizio stesso tramite il comando:

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

Si aprirà l’editor nano nel quale copia-incollare la seguente configurazione:

[Unit]
Description=zigbee2mqtt
After=network.target

[Service]
ExecStart=/bin/bash -c 'source /opt/zigbee2mqtt/bin/activate; /opt/zigbee2mqtt/bin/npm start'
WorkingDirectory=/opt/zigbee2mqtt
StandardOutput=inherit
StandardError=inherit
Restart=always
User=pi

[Install]
WantedBy=multi-user.target

Dopo aver copiato il testo, uscire salvando (CTRL+X, Y, invio).
A questo punto abilitare e avviare il servizio ZigBee2MQTT tramite i comandi:

sudo systemctl enable zigbee2mqtt.service
sudo systemctl start zigbee2mqtt.service

VERIFICA

Per verificare che tutto sia andato per il verso giusto, eseguire il seguente comando:

sudo systemctl status zigbee2mqtt.service

L’output dovrebbe essere all’incirca il seguente:

zigbee2mqtt service status

il quale status (“active (running)“) identifica un corretto avvio di ZigBee2MQTT e un’avvenuta connessione col broker MQTT.

In caso di problemi con l’avvio del servizio, consultare il journal tramite il comando

sudo journalctl -u zigbee2mqtt.service -f

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

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

Uso e integrazioni

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.

N.b. ATTENZIONE: tramite l’interfaccia web (il “frontend”) è anche possibile definire il canale radio da utilizzare. 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.

Aggiornamento

Ciclicamente escono aggiornamenti per ZigBee2MQTT; per spiegare come aggiornare il BRIDGE/Gateway abbiamo dedicato una guida ad hoc:

Utilità: come aggiornare 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.