Installare e configurare ZigBee2MQTT con Docker su OpenMediaVault (NAS o host analoghi)

SCOPI DELLA GUIDA: Installare e configurare il BRIDGE/Gateway ZigBee2MQTT, usando Docker su sistema operativo OpenMediaVault, 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 OpenMediaVault 7 “Sandworm” (OMV) ZigBee2MQTT per Docker Docker per OpenMediaVault Docker Compose per OpenMediaVault (facoltativo) Broker MQTT	PREREQUISITI: un NAS (o host alternativo) precedentemente configurato con OpenMediaVault, per esempio TerraMaster, collegato alla rete domestica e, tramite essa, ad Internet DISPOSITIVI FISICI UTILIZZATI: un NAS (o host alternativo) Un’antenna coordinator Zigbee compatibile con ZigBee2MQTT, fisicamente collegata o decentrata (illustrato a seguire)
GUIDA MAGGIORMENTE INDICATA PER:
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: 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 istanziato come container Docker presso il sistema operativo OpenMediaVault in uso su NAS (per esempio TerraMaster, o altro host analogo). 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:

• Come usare l’interfaccia web di ZigBee2MQTT (per pairing, impostazioni ed altro)
• Gestire ZigBee sui diversi BRIDGE/Gateway usando coordinator RCP MultiPAN (Dongle Plus MG24, ZBDongle-E, 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 Home Assistant OS
• Installare e configurare ZigBee2MQTT su Raspberry Pi OS
• Integrare componenti ZigBee su Home Assistant via ZigBee2MQTT
• Integrare componenti ZigBee su Homey 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)
• Riprogrammare il firmware ZigBee/Thead di SMLIGHT SLZB-06M (con firmware stock o custom)
• 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
• Installare Docker
• Broker e client MQTT
• Istanziare ZigBee2MQTT
  • Tramite comando “docker run”
  • Tramite Docker Compose
• Configurare ZigBee2MQTT
• Avvio del servizio
• Uso
• Aggiornamento

Assunti

Questa guida è dedicata a chi abbia già un host con sistema operativo OpenMediaVault. Per coloro che non abbiano ancora provveduto e si trovino ad avere un NAS, 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 OpenMediaVault (OMV).

Una volta terminata la configurazione di OpenMediaVault (inclusa la possibilità di collegarvisi tramite SSH nonché aver effettuato il perfezionamento) è 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:

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

FIRMWARE COORDINATOR

• aggiornamento firmware per ITEAD Sonoff Dongle Plus MG24 - firmware NCP
• aggiornamento firmware per ITEAD Sonoff ZigBee 3.0 Dongle Plus v2 (ZBDongle-E) - firmware NCP
• aggiornamento firmware per ITEAD Sonoff ZigBee 3.0 Dongle Plus;
• aggiornamento firmware per SMLIGHT SLZB: vedere presso l'interfaccia del device alla sezione "aggiornamento firmware"
• 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.

• aggiornamento firmware per Sonoff Dongle Max: vedere presso l'interfaccia del device alla sezione "aggiornamento firmware"
• aggiornamento firmware per SMLIGHT SLZB: vedere presso l'interfaccia del device alla sezione "aggiornamento firmware"
• riprogrammazione con firmware Zigbee2Tasmota per Sonoff ZigBee Bridge Pro (ZB Bridge-P).
• riprogrammazione firmware per ITEAD Sonoff Dongle Plus MG24 - firmware Multi-PAN (RCP)
• 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) e aver riavviato il computer host, è 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.

Installare Docker

Installare Docker su OpenMediaVault è piuttosto semplice, esiste una procedura completamente automatica e una manuale. Entrambe le procedure sono illustrate in dettaglio in questa breve guida.

Se si ha già provveduto all’installazione di Docker, va da sé che questo passaggio possa essere saltato.

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; agli utenti Homey Self-Hoster Server, invece, suggeriamo l’uso del broker MQTT disponibile presso Homey.

Istanziare ZigBee2MQTT

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

In ambito Docker, l’istanziamento dell’applicazione può essere effettuato tramite esecuzione di un comando manuale (più immediato) oppure tramite una configurazione del tool di gestione Docker Compose, approccio inizialmente più ostico ma che consigliamo per tutta una serie di motivi. Entrambe le scelte sono valide, ma in prospettiva (specie in ottica di aggiornamento) imparare ad usare Docker Compose è altamente consigliato.

Prima di procedere, però, è necessario creare una cartella la quale conterrà la sua configurazione.

Una volta collegati via SSH a OpenMediaVault, eseguiamo:

mkdir -p ~/zigbee2mqtt

Creare poi un file il file di configurazione in formato YAML (chiamato “configuration.yaml“):

nano ~/zigbee2mqtt/configuration.yaml

all’interno copiare 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

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

serial:
  port: /dev/ttyXXX
  adapter: deconz
  baudrate: XXXXX

serial:
  port: /dev/ttyXXX
  adapter: zstack

serial:
  port: /dev/ttyXXX
  adapter: ember 

port:
 tcp://indirizzo_ip_tasmota:8888

serial:
  port: /dev/ttyXXX
  adapter: ember 

Provvediamo ora all’istanziamento vero e proprio dell’applicazione, utilizzando come spiegato prima o il comando “docker run” o la più versatile configurazione Docker Compose.

Tramite comando “docker run”

Istanziamo dunque ZigBee2MQTT su Docker tramite il comando:

docker run --init -d \
  --name="zigbee2mqtt" \
  -e TZ=Europe/Rome \
  -v ~/zigbee2mqtt:/app/data \
  --device=/dev/ttyXXX \
  --network host \
  --restart always \
  koenkk/zigbee2mqtt

dove ovviamente nel campo “device” vada indicata la porta precedentemente identificata, così com’è necessario adeguare eventualmente il nome della cartella di configurazione. Se invece si utilizza una antenna coordinator decentrata, questo campo non solo non va personalizzato, ma va tolto.

Al termine, verifichiamo che tutto sia andato per il verso giusto:

docker logs zigbee2mqtt

in fondo al log dovremmo trovare qualcosa come:

Zigbee2MQTT:info 1980-01-01 00:00:00: Logging to console and directory: '/var/log' filename: log.txt
Zigbee2MQTT:info 1980-01-01 00:00:00: Starting Zigbee2MQTT version x.xx.x (commit #xxxxxx)
Zigbee2MQTT:info 1980-01-01 00:00:00: Starting zigbee-herdsman (x.xx.xx)
Zigbee2MQTT:info 1980-01-01 00:00:00: zigbee-herdsman started

Congratulazioni: ZigBee2MQTT è ora operativo.

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

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

Tramite Docker Compose

Se astutamente si sceglie di utilizzare Docker Compose, allora è semplicemente necessario aggiungere al proprio file docker-compose.yaml la seguente configurazione (sotto il bocco services):

  zigbee2mqtt:
    container_name: zigbee2mqtt
    image: koenkk/zigbee2mqtt
    volumes:
    - "~/zigbee2mqtt:/app/data"
    devices:
    - "/dev/ttyACM0"
    environment:
    - "TZ=Europe/Rome"
    network_mode: host
    restart: always

dove ovviamente nel campo “devices” vada popolato con la porta precedentemente identificata (nell’esempio /dev/ttyACM0); se invece si utilizza una antenna coordinator decentrata, questo campo non solo non va personalizzato, ma va tolto. È altresì necessario adeguare eventualmente il nome della cartella di configurazione sotto la voce “volumes“.

Una volta salvato il file docker-compose.yaml, eseguire il comando:

docker compose up -d zigbee2mqtt

il quale provvederà a istanziare il container.

Lanciato il comando, attendere il completamente del primo avvio. Ci potrebbe volere un po’: per leggere in tempo reale i log e verificare quindi cosa stia succedendo all’interno del container, eseguire il comando:

docker container logs zigbee2mqtt -f

in fondo al log dovremmo trovare qualcosa come:

Zigbee2MQTT:info 1980-01-01 00:00:00: Logging to console and directory: '/var/log' filename: log.txt
Zigbee2MQTT:info 1980-01-01 00:00:00: Starting Zigbee2MQTT version x.xx.x (commit #xxxxxx)
Zigbee2MQTT:info 1980-01-01 00:00:00: Starting zigbee-herdsman (x.xx.xx)
Zigbee2MQTT:info 1980-01-01 00:00:00: zigbee-herdsman started

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.

Aggiornamento

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

Utilità: come aggiornare ZigBee2MQTT