SCOPI DELLA GUIDA:
CONCETTI AFFRONTATI:
|
COMPONENTI SOFTWARE UTILIZZATE:PREREQUISITI:
DISPOSITIVI FISICI UTILIZZATI:
|
GUIDA DEDICATA A SISTEMI:
|
|
NOTE E DISCLAIMER
|
|
| Revisione guida: 1.1 | |
ATTENZIONE: OpenZWave è deprecato. Si consiglia di adottare, nelle medesime modalità, il BRIDGE/Gateway software ZWaveJS2MQTT.
Abstract
Z-Wave, uno degli standard più apprezzati in domotica personale, specie in termini di sicurezza e affidabilità.
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 Z-Wave ad esso collegati) col proprio HUB personale: quando dei componenti Z-Wave non sono altrimenti controllabili se non col “proprio” BRIDGE/Gateway, in sostanza diventano inutili – se non per il solo ambito del proprio ecosistema e della propria relativa app mobile di gestione. 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 OpenZWave, 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 Z-Wave: una volta installato, tale BRIDGE/Gateway utilizza MQTT per instradare i messaggi da e per i componenti Z-Wave 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 OpenZWave come applicativo 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 OpenZWave su qualsiasi HUB personale (Home Assistant, openHAB ecc.) o generico client MQTT.
Altre guide disponibili su inDomus dedicate a OpenZWave sono:
- Come usare l’interfaccia web di OpenZWave (per il pairing, le impostazioni ed altro)
- Installare e configurare OpenZWave su Home Assistant OS/Supervised
- Integrare componenti Z-Wave su Home Assistant via OpenZWave
Si parte
- Assunti
- Z-Wave Coordinator (antenna)
- Broker e client MQTT
- Installare Docker
- Istanziare OpenZWave
- Uso
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.
Z-Wave 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 Z-Wave: lo Z-Wave Coordinator. Tale elemento è rappresentato da un’antenna interfacciata al computer ospitante via USB, via seriale o altro.
OpenZWave supporta svariate antenne, tra le quali abbiamo documentato e testato:
e molte 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 Z-Wave 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 Z-Wave risultano irraggiungibili la scelta dell’antenna può quindi non essere legata alla sua potenza: basta infatti introdurre, oltre all’antenna principale, dei repeater Z-Wave (banalmente, bastano delle spine intelligenti Z-Wave, le quali hanno anche questa funzione – anche da “spente”) 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 è 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
Il software OpenZWave, 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 OpenZWave. |
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 OpenZWave
A questo punto, con MQTT funzionante e antenna installata è possibile provvedere all’installazione di OpenZWave, 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 ed eventuali file statici.
Una volta collegati via SSH al Raspberry Pi tramite utenza “pi“, provvedere a creare la cartella:
mkdir -p /home/pi/ozw
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 OpenZWave su Docker tramite il comando:
docker run --init -d -it --name ozw --device=/dev/ttyXXX -v /home/pi/ozw:/opt/ozw/config -e MQTT_SERVER="IP_DEL_BROKER" -e MQTT_USERNAME="NOME_UTENTE" -e MQTT_PASSWORD="PASSWORD" -e USB_PATH=/dev/ttyXXX --restart always --net=host openzwave/ozwdaemon:allinone-latest
dove ovviamente nei campo “device” e “USB_PATH” andrà indicata la porta precedentemente identificata.
Nel campo “MQTT_SERVER” va invece indicato l’indirizzo IP del Broker MQTT, mentre nei campi “MQTT_USERNAME” e “MQTT_PASSWORD” vanno indicate le credenziali di accesso a tale servizio.
Al termine, verifichiamo che tutto sia andato per il verso giusto:
docker logs ozw
in fondo al log dovremmo trovare qualcosa come:
[ozwdaemon]: ========================================================================
[ozwdaemon]: Detailed Logging is available in the logs directory of the mapped volume
[ozwdaemon]: ========================================================================
[ozwdaemon]:
[ozwdaemon]: Waiting until the MQTT broker at xxx.xxx.xxx.xxx:1883 is available...
[ozwdaemon]: Starting...
[ozwdaemon]: Executing: /usr/local/bin/ozwdaemon
Congratulazioni: OpenZWave è 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):
ozw:
container_name: ozw
image: "openzwave/ozwdaemon:allinone-latest"
volumes:
- "/home/pi/ozw:/opt/ozw/config"
devices:
- "/dev/ttyXXX"
environment:
- "MQTT_SERVER=IP_DEL_BROKER"
- "MQTT_USERNAME=NOME_UTENTE"
- "MQTT_PASSWORD=PASSWORD"
- "USB_PATH=/dev/ttyXXX"
network_mode: host
restart: always
dove ovviamente nei campo “devices” e “USB_PATH” andrà indicata la porta precedentemente identificata.
Nel campo “MQTT_SERVER” va invece indicato l’indirizzo IP del Broker MQTT, mentre nei campi “MQTT_USERNAME” e “MQTT_PASSWORD” vanno indicate le credenziali di accesso a tale servizio.
Una volta salvato il file docker-compose.yaml, eseguire il comando:
docker compose up -d ozw
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 ozw -f
in fondo al log dovremmo trovare qualcosa come:
[ozwdaemon]: ========================================================================
[ozwdaemon]: Detailed Logging is available in the logs directory of the mapped volume
[ozwdaemon]: ========================================================================
[ozwdaemon]:
[ozwdaemon]: Waiting until the MQTT broker at xxx.xxx.xxx.xxx:1883 is available...
[ozwdaemon]: Starting...
[ozwdaemon]: Executing: /usr/local/bin/ozwdaemon
Congratulazioni: OpenZWave è ora operativo.
Uso
A questo punto il BRIDGE/Gateway OpenZWave è pronto e utilizzabile al fine di integrare componenti Z-Wave compatibili con tale servizio.
Ogni componente compatibile, una volta associato a OpenZWave, può essere comandato e censito tramite MQTT e amministrato attraverso la sua interfaccia web. Ovviamente, il passo successivo è quello di integrare OpenZWave col proprio HUB personale, al fine di utilizzare le risorse delle varie componenti Z-wave all’interno della propria domotica personale. In caso il proprio HUB personale sia il diffusissimo Home Assistant, sarà sufficiente accedere alla pagina delle integrazioni e scegliere “OpenZWave”.
| 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. Se ti sei perso, a tua disposizione c'è la mappa. |