community italiana di domotica personale
 
Installare e configurare ZigBee2MQTT con Docker su QNAP (via ContainerStation)

Installare e configurare ZigBee2MQTT con Docker su QNAP (via ContainerStation)

7 minuti di lettura
SCOPI DELLA GUIDA:
  • Installare e configurare il BRIDGE/Gateway ZigBee2MQTT come container Docker su QNAP, dotandosi così di una rete ZigBee per la propria domotica personale
  • Livello di difficoltà: basso
CONCETTI AFFRONTATI:
  • installazione e configurazione software
COMPONENTI SOFTWARE UTILIZZATE:
  • Ambiente operativo FileStation di QNAP
  • Ambiente operativo ContainerStation di QNAP
  • ZigBee2MQTT per Docker
  • Docker
PREREQUISITI:
DISPOSITIVI FISICI UTILIZZATI:
GUIDA INDICATA PER:

QNAP

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

ZigBee2MQTT - Docker su QNAP

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.

In questa guida ci concentriamo sulla possibilità di installare ZigBee2MQTT su una NAS del brand QNAP adottando un pratico container Docker, il che consente di isolare i processi del server, di essere facilmente aggiornato e molto altro. 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:

Procedimento

Assunti

Questa guida è dedicata a chi abbia già un QNAP in uso.

Si assume che il sistema operativo del QNAP sia aggiornato, così come le componenti Docker, FileStation e ContainerStation che andremo ad utilizzare; è necessario che QNAP sia ovviamente collegato in rete e che la rete gli consenta libero accesso alla rete Internet. Altra assunzione è la presenza di almeno un hard disk presente nella NAS correttamente configurato.

Per istanziare il container docker di ZigBee2MQTT utilizzeremo l’interfaccia ContainerStation di QNAP, mentre utilizzeremo FileStation per indicare alla NAS dove salvare i file di configurazione e di storage dell’HUB.

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 collegata al QNAP ospitante via USB.

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);
  • CC2531 (USB, non troppo potente, molto economica, da riprogrammare manualmente);
  • CC2530 (seriale, non troppo potente, molto economica, da riprogrammare manualmente);
  • CC2652RB;
  • Z-Bee Duo (USB, potente e versatile);
  • 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 (basta inserirla nella porta USB del QNAP) dopodiché appurare che il sistema operativo “veda” tale dispositivo. A tal scopo, però, è prima necessario installare i driver di gestione USB.

DRIVER

Per far sì che l’antenna collegata via USB funzioni è necessario installare l’app “USB Serial“.

Per farlo è necessario aprire App Center, cliccare sull’icona delle impostazioni in alto a destra e poi, sul tab “Archivio di app“, ciccare su “Aggiungi“. A questo punto va scelto un nome arbitrario da assegnare al repository e, sopratutto, va aggiunta la seguente URL:

https://qnapclub.eu/en/repo.xml

come da immagine:

QNAP - USB Serial - 1

A questo punto tra le varie fonti di App Center avremo aggiunto anche qnapclub.eu; cliccado sul repository e cercando nella barra in alto “USB Serial“, apparirà l’applicazione di cui abbiamo bisogno. Clicchiamo quindi su “Installa“.

QNAP - USB Serial - 2

Apparirà un avviso che avvertirà che l’app non è firmata digitalmente: ignorare l’avviso e, selezionando “Comprendo i rischi“, clicchiamo infine su “Installa“.

Al termine, riavviare QNAP.

VERIFICA POST-INSTALLAZIONE

Dopo aver installato l’antenna e aver riavviato QNAP è il momento di effettuare una verifica per verificare che l’antenna funzioni.
A tal scopo, collegarsi via SSH al QNAP ed eseguire il comando:

ls -lart /dev | grep USB

Il quale dovrà fornire un output di questo tipo:

crw------- 1 admin administrators 188, 0 1980-01-07 00:00 ttyUSB0

il che confermerà l’avvenuta configurazione della porta logica assegnata all’antenna USB.

Broker 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 – in questo caso il nostro QNAP – è connesso.

Per configurare il broker MQTT su QNAP, si faccia riferimento a questa guida.

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

Definizione configurazione

Prima cosa, aprire un qualsiasi editor di testo e creare un file chiamato configuration.yaml in notazione YAML, appunto, che contenga il seguente codice:

homeassistant: true
permit_join: false
mqtt:
  base_topic: zigbee2mqtt
  server: 'mqtt://INDIRIZZO_IP_BROKER_MQTT'
  user: username
  password: password
serial:
  port: /dev/ttyUSB0
advanced:
  pan_id: 9876
  channel: 15
  log_directory: /var/log/zigbee2mqtt
experimental:
  new_api: true
frontend:
  port: 8080

Tale file verrà poi copiato sul NAS e verrà utilizzato come file di configurazione dell’istanza ZigBee2MQTT che andremo a creare; si noti come la sezione mqtt: vada arricchita di informazioni proprie, ovvero l’indirizzo del nostro broker MQTT nel campo server nonché le relative credenziali d’accesso presso i campi user e password.

Per quanto riguarda la porta dell’interfaccia web di ZigBee2MQTT abbiamo impostato la tradizionale porta 8080 (ovviamente può essere impostata qualunque porta, purché sia libera).

FileStation

Definita la propria configurazione, il passo seguente da eseguire è quello di definire un percorso presso lo storage nel quale salvare i file di configurazione di cui sopra.

Dall’interfaccia web della NAS QNAP avviamo quindi l’applicazione FileStation.
Selezionare il volume prescelto per ospitare i file di ZigBee2MQTT (nel nostro caso “Volume1“) cliccando sui tre puntini in alto a destra, selezionando poi “Crea cartella condivisione“:

QNAP - FileStation - Creazione Path inDomus - 1

Nel nostro caso abbiamo deciso di creare una directory principale (“domotica-indomus“) nella quale posizionare tutte le sotto-directory relative ai progetti dedicati alla domotica. Gli altri parametri possono esser lasciati così come sono, di default:

QNAP - FileStation - Creazione Path inDomus - 2

Creare quindi una sotto-directory dedicata a ZigBee2MQTT. Per farlo, cliccare sull’icona della cartella con il “+” selezionando poi “Cartella/e“:

QNAP - FileStation - Creazione Path inDomus - Creazione sottocartella

Chiamiamola, con poca fantasia, “zigbee2mqtt“:

A questo punto è necessario caricare i propri file di configurazione. Portiamoci sulla directory appena creata e clicchiamo sull’icona per l’upload dei file (“freccia verso l’alto”), selezioniamo “File” e carichiamo il file configuration.yaml creato in precedenza sul proprio computer d’appoggio.

QNAP - FileStation - File di configurazione ZigBee2MQTT

A questo punto siamo pronti a istanziare il container di ZigBee2MQTT tramite ContainerStation.

ContainerStation

In questo passaggio – cardinale – si andrà a istanziare ZigBee2MQTT come container Docker presso ContainerStation: dall’interfaccia web della NAS QNAP avviare quindi tale applicazione.

Cercare quindi “zigbee2mqtt” nell’elenco delle immagini disponibili (consultate da QNAP su Internet) selezionando come fonte “Docker Hub“.

QNAP - FileStation - ZigBee2MQTT Docker - 1

Cliccando quindi su “Installa” verrà mostrato un menu a tendina da cui scegliere la versione da utilizzare.
Selezioniamo la “Latest“. Apparirà un warning relativo alla fonte dell’immagine. Non preoccuparsene e andare avanti.

Nella schermata successiva si attribuirà un nome al container:

QNAP - FileStation - ZigBee2MQTT Docker - 2

Si seleziona quindi “Impostazioni avanzate” > “Rete“.
Impostare “NAT” quale modalità di rete, avendo poi cura di configurare l’inoltro porte con:

  • host: 8080
  • contenitore: 8080
  • protocollo: TCP.

Alla voce “Dispositivi” impostiamo modalità privilegiata. Clicchiamo su “Aggiungi” e selezioniamo i device “TTY”:

QNAP - FileStation - ZigBee2MQTT Docker - 4

Portandosi poi alla voce “Cartelle Condivise“, andrà selezionato:

1) a sinistra, la directory di configurazione dell’host da utilizzare per la configurazione (definita in precedenza);
2) a destra, la directory di configurazione di HA prevista nella configurazione dell’immagine Docker di ZigBee2MQTT, ovvero “/app/data” assicurandosi di fornire permessi di lettura e scrittura:

QNAP - FileStation - ZigBee2MQTT Docker - 5

Infine, cliccare su “Crea“: verrà mostrato il riepilogo della configurazione.
Premendo su “OK” verrà avviata la creazione del container e, dopo qualche momento, si completerà positivamente.


Una volta completato il processo, cliccando sulla voce “Panoramica” del menù si potrà apprezzare l’esistenza del nuovo container di ZigBee2MQTT. L’interfaccia ci permetterà, alla bisogna, di riavviare, fermare, eliminare o modificare il container:

QNAP - FileStation - ZigBee2MQTT Docker - 7Presso la sezione “Log“, invece, sarà possibile verificare il corretto funzionamento del software e i vari stati da esso prodotti:

QNAP - FileStation - ZigBee2MQTT Docker - 8

Aggiornamento

Per aggiornare ZigBee2MQTT implementato come container Docker su ContainerStation è sufficiente rimuovere il container per poi crearlo nuovamente:

QNAP Container Station - Rimozione containerOvviamente, è necessario conoscere prima le modalità con cui era stato creato. Se si è seguita questa  nostra guida, è sufficiente rimuoverlo e rifare la procedura; differentemente, assicurarsi prima di avere tutte le coordinate necessarie. Comunque sia è difficile “far danni”: la cartella contenente la configurazione non viene toccata dalla rimozione del container, quindi è facile ricrearlo puntando ad essa e ritrovare perfettamente funzionante il proprio BRIDGE/Gateway ZigBee.

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.

   
Telegram News Channel