Installare e configurare ZigBee2MQTT su Home Assistant OS/Supervised

SCOPI DELLA GUIDA: Installare e configurare il BRIDGE/Gateway ZigBee2MQTT su Home Assistant OS/Supervised, dotandosi così di una rete Zigbee per la propria domotica personale Livello di difficoltà: medio/basso CONCETTI AFFRONTATI: Utilizzo e configurazione software	COMPONENTI SOFTWARE UTILIZZATE: Home Assistant OS/Supervised Add-on “ZigBee2MQTT“ Add-on “Mosquitto Broker” (o broker MQTT equivalente) Componente Home Assistant “MQTT“ PREREQUISITI: Home Assistant configurato e funzionante DISPOSITIVI FISICI UTILIZZATI: Il computer sul quale è in esecuzione Home Assistant Un’antenna coordinator Zigbee compatibile con ZigBee2MQTT, fisicamente collegata o decentrata (illustrato a seguire)
GUIDA INDICATA a UTENTI CON ISTALLAZIONE:
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: 3.1

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à HassOS/Supervised). 

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 QNAP (via Container Station)
• Installare e configurare ZigBee2MQTT con Docker su Raspberry Pi OS
• 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

Si parte

• Assunti
• ZigBee coordinator (l’antenna)
  • Firmware coordinator
  • Verifica post-installazione
• Broker e client MQTT
• Installare ZigBee2MQTT
• Configurare ZigBee2MQTT
• Uso

Assunti

Questa guida è dedicata a chi abbia già in uso l’HUB Home Assistant OS (aka HassOS, o HASSIO) o Home Assistant Supervised.
Il computer ospitante l’HUB può essere qualsiasi, dal tradizionale Raspberry Pi, un Mini PC a un computer vero e proprio, o altro.

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.

Le guide disponibili su inDomus per installare HassOS sono:

• Home Assistant OS, Supervised o Core: quale installazione fa al caso mio?
• Home Assistant su Mini PC/Intel NUC: le varie installazioni, le cose da fare
• Home Assistant su QNAP: la checklist di riferimento per la propria domotica
• Home Assistant su Raspberry Pi: le varie installazioni, le cose da fare
• Installare e avviare Home Assistant OS su SSD esterno su Raspberry Pi 4
• Installare e configurare Home Assistant OS (HassOS/HASSIO) su QNAP (via Virtualization Station)
• Installare e configurare Home Assistant OS (HassOS/HASSIO) su un Mini PC/Intel NUC dedicato
• Installare e configurare Home Assistant OS (HassOS/HASSIO) su un Raspberry Pi dedicato

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 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). Nel caso di un’antenna fisicamente collegata via USB, spesso è necessario collegarla e poi effettuare un reboot di Home Assistant OS (voce di menu “Configurazione” > “Sistema” > “Hardware” > “Riavvia l’host“).

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 le seguenti (le quali risultano buggate)
• riprogrammazione firmware per Z-Wave.Me Z-Station - firmware Multi-PAN (RCP)

VERIFICA POST-INSTALLAZIONE

Dopo aver aggiornato il firmware dell’antenna, averla collegata (in caso sia USB) aver riavviato l’host, accedere a Home Assistant e, presso la voce di menu “Sistema” > “Host” > “Hardware” (menu puntini) 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 (ed è meglio usare questa connotazione).

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 Home Assistant OS/Supervised, si faccia riferimento a questa guida.

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 Home Assistant OS/Supervised. Si tratta, però, di un add-on custom pertanto non nativamente disponibile presso l’add-on store di Home Assistant OS/Supervised.

Per installare l’add-on, cliccare, presso il menu, la voce:

• “Configurazione” > “Componenti aggiuntivi”  e poi sul pulsante “Raccolta di componenti aggiuntivi“.

Si tratta di accedere ad una vera e propria “vetrina” di componenti aggiuntivi (gratuiti) che, proprio come mattoncini da costruzioni, andranno ad arricchire le funzionalità del nostro HUB. Per installarlo è dunque primariamente necessario aggiungere un repository alla lista di quelli già presenti, nello specifico questo indirizzo:

https://github.com/zigbee2mqtt/hassio-zigbee2mqtt

Per farlo, recarsi alla voce di menu (i tre puntini in alto a destra) “Archivi digitali” > “Aggiungi“.

Immediatamente dopo nella lista degli add-on disponibili apparirà anche la voce “zigbee2mqtt”. Cliccarci sopra per accedere alla scheda di dettaglio, poi cliccare su “INSTALLA“:

Al termine dell’installazione, non avviare l’add-on: è 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; presso la sezione “Configurazione“, cliccando poi sui tre puntini in alto a destra, infine alla voce “Modifica in YAML“, l’add-on riporta una configurazione di default pressapoco così (le parti in rosso sono quelle più critiche, come vedremo a seguire):

# Autodiscovery su Home Assistant abilitato
homeassistant: true
# Join alla rete MQTT disabilitato di default
permit_join: false
# MQTT settings
socat:
  enabled: false
  master: pty,raw,echo=0,link=/tmp/ttyZ2M,mode=777
  slave: tcp-listen:8485,keepalive,nodelay,reuseaddr,keepidle=1,keepintvl=1,keepcnt=5
  options: "-d -d"
log: false
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
  version: 5
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
advanced:
  log_level: info
  pan_id: 6754
  channel: 15
  network_key:
    - 0
    - 1
    - 2
    - 3
    - 4
    - 5
    - 6
    - 7
    - 8
    - 9
    - 10
    - 11
    - 12
    - 13
    - 14
    - 15

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

serial:
  port: /dev/ttyXXX
  adapter: deconz

serial:
  port: /dev/ttyXXX

serial:
  port: /dev/ttyXXX
  adapter: ember 

port:
 tcp://indirizzo_ip_tasmota:8888

serial:
  port: /dev/ttyXXX
  adapter: ember 

Una volta terminata la configurazione, cliccare su “SALVA” e poi, sopra, su “AVVIA“: 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 (“Visualizza in barra laterale“).

VERIFICA

Per verificare che tutto sia andato per il verso giusto, recarsi sul fondo della pagina e cliccare “AGGIORNA” nel box “Registro“: se è tutto ok, dovrebbe apparire un log “verde” che, sostanzialmente, identifica un corretto avvio di ZigBee2MQTT e un’avvenuta connessione col broker MQTT.

Congratulazioni: ZigBee2MQTT è ora operativo.

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

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

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.