Come installare e configurare ZigBee2MQTT con Docker su Raspbian di Raspberry Pi

9 minuti di lettura
SCOPI DELLA GUIDA:
  • Installare e configurare il BRIDGE/Gateway ZigBee2MQTT, usando Docker su sistema operativo Raspbian di Raspberry Pi (o più genericamente, su Linux), dotandosi così di una rete Zigbee per la propria domotica personale
  • Livello di difficoltà: basso
CONCETTI AFFRONTATI:
  • Installazione e configurazione software
COMPONENTI SOFTWARE UTILIZZATE:
PREREQUISITI:
DISPOSITIVI FISICI UTILIZZATI:
  • Raspberry Pi
  • Un’antenna ZigBee coordinator compatibile con ZigBee2MQTT (illustrato a seguire)
GUIDA DEDICATA A SISTEMI:

Raspbian

Note e disclaimer
  • qualsiasi eventuale modifica agli impianti domestici dev'essere progettata ed realizzata SOLO da personale qualificato;
  • qualsiasi modifica attuata in proprio è a propria responsabilità personale nonché a proprio rischio e pericolo (i contenuti della presenta pagina hanno puro scopo didattico);
  • qualsiasi modifica attuata in proprio a un dispositivo ne fa decadere garanzia, omologazioni e certificazioni di qualità.
Revisione guida: 1.5

ZigBee2MQTT - Docker

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

La guida da seguire:

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

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 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 (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 nella porta del Raspberry Pi o del computer ospitante) dopodiché appurare che il sistema operativo “veda” tale device.

VERIFICA POST-INSTALLAZIONE

Dopo aver installato l’antenna e aver riavviato Raspberry Pi è 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.

Installare Docker

Installare Docker su Raspberry Pi dotato di sistema operativo Raspbian è piuttosto rapido e semplice: esiste infatti sia una procedura completamente automatica oppure una manuale. Entrambe le procedure sono illustrate in dettaglio in questa breve guida.

Se si dispone già di Docker, va da sé che questo passaggio possa essere saltato.

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 al Raspberry Pi tramite utenza “pi“, provvedere a creare la cartella:

mkdir -p /home/pi/zigbee2mqtt

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

nano /home/pi/zigbee2mqtt/configuration.yaml

all’interno copiare 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
serial:
  # Porta su cui è mappata l'antennza zigbee
  port: /dev/ttyXXX
advanced:
  # Directory in cui verrà salvato il file di log
  log_directory: /var/log
experimental:
  # abilita le nuove API e l'esposizione della webGUI
  new_api: true
frontend:
  # porta su cui verrà esposta la webGUI
  port: 8080

Inoltre, se si utilizza un’antenna ConBee II o RaspBee II, aggiungere questa porzione:

serial:
  port: /dev/ttyXXX
  adapter: deconz

I campi da personalizzare nel file di configurazione sono, principalmente: “server“, “user” e “password” e infine “port“.

Il campo “homeassistant” è necessario impostare “true” al fine di far sì che, usando Home Assistant quale proprio HUB personale, esso riconosca automaticamente il BRIDGE ZigBee2MQTT; 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://localhost“.

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.

N.b. Piccola nota sul 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

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

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.

ATTENZIONE: affinché i comandi a seguire funzionino, è necessario aver aggiunto Docker al gruppo sudoers, come spiegato in guida d’installazione Docker.

Tramite comando “docker run”

Istanziamo dunque ZigBee2MQTT su Docker tramite il comando:

docker run --init -d --name="zigbee2mqtt" -e TZ=Europe/Rome -v /home/pi/zigbee2mqtt:/app/data --device=/dev/ttyXXX --network host --restart unless-stopped koenkk/zigbee2mqtt

dove ovviamente nel campo “device” vada indicata la porta precedentemente identificata.
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.

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:
    - "/home/pi/zigbee2mqtt:/app/data"
    devices:
    - "/dev/ttyACM0"
    environment:
    - "TZ=Europe/Rome"
    network_mode: host
    restart: unless-stopped

dove ovviamente nel campo “devices” vada popolato con la porta precedentemente identificata (nell’esempio /dev/ttyACM0).

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

docker-compose up -d

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.

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.

Aggiornamento

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

Utilità: come aggiornare ZigBee2MQTT

   
Telegram News Channel