Installare e configurare deCONZ con Docker su Raspberry Pi OS

SCOPI DELLA GUIDA: Installare e configurare il BRIDGE/Gateway deCONZ, usando Docker su sistema operativo Raspberry Pi OS, dotandosi così di una rete Zigbee per la propria domotica personale Livello di difficoltà: medio/basso CONCETTI AFFRONTATI: Installazione e configurazione software	COMPONENTI SOFTWARE UTILIZZATE: Sistema operativo Raspberry Pi OS (aka Raspbian) deCONZ per Docker Docker Docker Compose (opzionale) Broker MQTT PREREQUISITI: Raspberry Pi precedentemente configurato con Raspberry Pi OS e collegato alla rete domestica e, tramite essa, ad Internet DISPOSITIVI FISICI UTILIZZATI: Raspberry Pi Un’antenna ZigBee coordinator compatibile con deCONZ (illustrato a seguire)
GUIDA DEDICATA A utenti:
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.4

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 deCONZ, oggetto della presente guida, componente software che consente per l’appunto di dotarsi gratuitamente di un BRIDGE/Gateway evoluto per la gestione della propria rete ZigBee: una volta installato, tale BRIDGE/Gateway espone delle API per instradare i messaggi da e per i componenti ZigBee tramite esso gestiti.

Tramite esse, sarà poi facile riuscire ad integrare il tutto con i più comuni HUB personali.

Scopo della presente guida è quello di installare e configurare deCONZ istanziato come container Docker 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 deCONZ su qualsiasi HUB personale (Home Assistant, openHAB ecc.) che lo supporti.

Altre guide disponibili su inDomus dedicate a deCONZ sono:

• Come usare l’interfaccia web di deCONZ (per pairing, impostazioni ed altro)
• Configurare a piacimento componenti ZigBee tramite Home Assistant via deCONZ
• Installare e configurare deCONZ con Docker su Linux Debian (Mini PC/Intel NUC o altro)
• Installare e configurare deCONZ su Home Assistant OS/Supervised
• Installare e configurare deCONZ su Raspberry Pi OS
• Integrare componenti ZigBee su Home Assistant via deCONZ
• Integrare ConBee/RaspBee con Home Assistant OS/Supervised via deCONZ
• Integrare ConBee/RaspBee con Home Assistant via deCONZ su Raspberry Pi
• Utilità: come aggiornare deCONZ e il firmware ConBee/RaspBee

Si parte

• Assunti
• ZigBee Coordinator (antenna)
• Aggiornamento firmware
• Installare Docker
• Istanziare deCONZ
  • Tramite comando “docker run”
  • Tramite Docker Compose
• Configurare deCONZ
• Avvio del servizio
• Uso e integrazioni
• Aggiornamento

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:

• per chi abbia a disposizione una tastiera e un mouse USB, è questa;
• per chi non li abbia, è quest’altra.

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 deCONZ (ZHA, ZigBee2MQTT o altri) siano stati preventivamente fermati.

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.

deCONZ supporta alcune diverse antenne, tra le quali abbiamo documentato e testato:

• ConBee (oggi obsoleta);
• ConBee II (USB, supporta fino a 200 componenti ZigBee, compatibile anche con ZigBee2MQTT e ZHA);
• ConBee III (dongle USB, evoluta, supporta fino a 200 componenti ZigBee, compatibile anche con ZigBee2MQTT e ZHA);
• RaspBee (modulo HAT per Raspberry Pi, oggi obsoleto);
• RaspBee II (modulo HAT per Raspberry Pi, supporta fino a 200 componenti ZigBee, compatibile anche con ZigBee2MQTT e ZHA)

e, in futuro, altre che verrano.

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

N.b. Si consiglia, sempre, di utilizzare delle mini prolunghe USB per collegare sulla porta UBS del Raspberry Pi l’antenna ConBee. Questo per evitare più che accertate interferenze.

Dato però che Raspberry dispone di due porte seriali – ma una è disabilitata di default – installando l’antenna potrebbe smettere di funzionare il modulo Bluetooth o comunque non esser riconosciuta l’antenna stessa. Per evitare ciò, basta effettuare una modifica sul file config.txt presente nella root della propria Micro SD.

Eseguire dunque da terminale il seguente comando:

sudo nano /boot/config.txt

per accedere all’editor. 

N.b. questa procedura non è obbligatoria. Potete passare direttamente allo step successivo (“Verifica post-installazione”) e vedere se ConBee/RaspBee sia stato riconosciuto di automaticamente o meno. In caso negativo, la procedura qui descritta va necessariamente eseguita.

La modifica da fare prevede l’aggiunta, in fondo al file, del seguente codice (avere cura di aggiungere una riga vuota dopo le due righe di codice):

Su Raspberry Pi 3B e inferiori:

enable_uart=1
dtoverlay=pi3-disable-bt

Su Raspberry Pi 3B+ e superiori:

enable_uart=1
dtoverlay=pi3-miniuart-bt

Terminata la modifica, salvare il file (CTRL+X, Y, invio), e infine spegnere il Raspberry Pi con:

sudo shutdown now

Completato lo shutdown, spegnere fisicamente l’unità per poi riaccenderla subito dopo.

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

Aggiornamento firmware

Se l’antenna è nuova, non è improbabile – anzi – che monti una versione di firmware non recente. In tal caso, verificare le ultime notizie in merito (in ordine cronologico) e, in caso, applicare l’ultimo aggiornamento disponibile come indicato nell’articolo che lo presenta. Questo passaggio, comunque, è possibile effettuarlo anche dopo l’installazione di deCONZ (la quale è necessaria, dato che installa il tool preposto all’aggiornamento firmware).

Installare Docker

Installare Docker su Raspberry Pi dotato di sistema operativo Raspberry Pi OS è 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 deCONZ

A questo punto, con una antenna compatibile installata, è possibile provvedere all’istallazione di deCONZ, 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.

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 deCONZ su Docker tramite il comando che segue via terminale (da CLI, via SSH oppure con control-alt-t da interfaccia desktop):

docker run -d --name=deconz -e TZ=Europe/Rome -v /opt/deconz:/root/.local/share/dresden-elektronik/deCONZ --device=/dev/ttyXXX -e DECONZ_WEB_PORT=40850 -e DECONZ_VNC_MODE=1 -e DECONZ_VNC_PORT=40851 -e DECONZ_VNC_PASSWORD=mia_password --net=host --restart=always deconzcommunity/deconz

dove ovviamente nel campo “device” vada indicata la porta precedentemente identificata, mentre nel campo “DECONZ_VNC_PASSWORD” è necessario indicare una propria password per l’accesso all’interfaccia VNC di deCONZ.

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

docker logs deconz -f

in fondo al log dovremmo trovare qualcosa come:

[deconzcommunity/deconz] Starting deCONZ...
[deconzcommunity/deconz] Current deCONZ version: x.xx.xx
[deconzcommunity/deconz] Web UI port: 40850
[deconzcommunity/deconz] Websockets port: 443
[deconzcommunity/deconz] VNC port: 40851

Congratulazioni: deCONZ è 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):

  deconz:
    container_name: deconz
    image: deconzcommunity/deconz
    volumes:
    - "/opt/deconz:/root/.local/share/dresden-elektronik/deCONZ"
    devices:
    - "/dev/ttyXXX"
    environment:
    - "TZ=Europe/Rome"
    - "DECONZ_WEB_PORT=40850"
    - "DECONZ_VNC_MODE=1"
    - "DECONZ_VNC_PORT=40851"
    - "DECONZ_VNC_PASSWORD=mia_password"
    network_mode: host
    restart: always

dove ovviamente nel campo “devices” vada popolato con la porta precedentemente identificata (nell’esempio /dev/ttyACM0), mentre nel campo “DECONZ_VNC_PASSWORD” è necessario indicare una propria password per l’accesso all’interfaccia VNC di deCONZ.

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

docker compose up -d deconz

il quale provvederà a istanziare il container.

N.b. In caso il comando “docker compose” dovesse dare errore, verificare di non aver installata la versione applicativa di Docker Compose anzichè la versione plug-in alla quale il comando sopra fa riferimento. In tal caso, adeguare il comando da “docker compose” a “docker-compose” (col trattino in mezzo).

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 deconz -f

in fondo al log dovremmo trovare qualcosa come:

[deconzcommunity/deconz] Starting deCONZ...
[deconzcommunity/deconz] Current deCONZ version: x.xx.xx
[deconzcommunity/deconz] Web UI port: 40850
[deconzcommunity/deconz] Websockets port: 443
[deconzcommunity/deconz] VNC port: 40851

Congratulazioni: deCONZ è ora operativo.

Uso e integrazioni

A questo punto il BRIDGE/Gateway deCONZ è pronto e utilizzabile al fine di integrare componenti ZigBee compatibili con tale servizio. Ogni componente compatibile, una volta associato a deCONZ, può essere comandato, censito e amministrato attraverso la sua interfaccia web.

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.

Ovviamente, il passo successivo è solitamente quello di integrare deCONZ 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 deCONZ ad esso (e con lui quindi le componenti ZigBee da controllare) tramite l’interfaccia di quest’ultimo.

Analogamente, altri HUB o servizi possono utilizzare le API deCONZ per intergrare rapidamente tale BRIDGE/Gateway.

Aggiornamento

Ciclicamente escono aggiornamenti per deCONZ (nonché di firmware per le varie antenne coordinato); per spiegare come aggiornare il BRIDGE/Gateway abbiamo dedicato una guida ad hoc:

Utilità: come aggiornare deCONZ e il firmware ConBee/RaspBee

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.