Installare e configurare OpenZWave su Home Assistant OS/Supervised

SCOPI DELLA GUIDA:

Installare e configurare il BRIDGE/Gateway OpenZWave su Home Assistant OS/Supervised, dotandosi così di una rete Z-Wave per la propria domotica personale
Livello di difficoltà: basso

CONCETTI AFFRONTATI:

Utilizzo e configurazione software

COMPONENTI SOFTWARE UTILIZZATE:

Home Assistant OS/Supervised
Add-on “OpenZWave“
Add-on “Mosquitto Broker” (o broker MQTT equivalente)
Componente Home Assistant “MQTT“

PREREQUISITI:

Home Assistant configurato e funzionante

DISPOSITIVI FISICI UTILIZZATI:

Il computer sul quale è in esecuzione Home Assistant
Un’antenna Z-Wave Coordinator compatibile con OpenZWave (illustrato a seguire)

GUIDA indicatA per 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: 2.0

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 OpenZWsve come add-on presso Home Assistant (installato in modalità HassOS o Supervised).

Altre guide disponibili su inDomus dedicate a OpenZWave sono:

Assunti

Questa guida è dedicata a chi abbia già in uso l’HUB Home Assistant OS (aka HassOS, o HASSIO) o Home Assistant Supervised.
Il computer ospitante l’HUB può essere qualsiasi, dal tradizionale Raspberry Pi a un computer vero e proprio, o altro.

Le guide disponibili su inDomus per installare HassOS sono:

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 in una delle porte del computer ospitante) dopodiché appurare che il sistema operativo “veda” tale device, a valle però di un reboot (voce di menu “Configurazione” > “Sistema” > “Hardware” > “Riavvia l’host“).

VERIFICA POST-INSTALLAZIONE

Dopo aver installato l’antenna e aver avviato Home Assistant, accedere a quest’ultimo e, presso la voce di menu “Configurazione” > “Sistema” > “Hardware” > “Tutto l’hardware” (menu puntini) verificare se, nell’elenco dell’hardware installato, appaia o meno il componente, solitamente una voce specifica; nel caso di un’antenna ZWave.me UZB1, per esempio, appare una voce di questo tipo:

/dev/serial/by-id/usb-0658_0200-if00

In caso appaia l’installazione sarà considerata valida; segnarsi la stringa da una parte, servirà più avanti.

N.b. A volte l’antenna viene semplicemente riconosciuta come /dev/ttyAMAx.

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.

Per configurare broker e/o client MQTT su Home Assistant OS/Supervised, si faccia riferimento a questa guida.

N.b. Procedere nella presente guida senza aver provveduto a installare correttamente broker e client MQTT causerà, ovviamente, un malfunzionamento di OpenZWave.

Installare OpenZWave

A questo punto, con MQTT funzionante e antenna installata è possibile provvedere all’installazione di OpenZWave, il quale viene eseguito come processo tramite l’aggiunta di un add-on Home Assistant OS/Supervised.

Per installare l’add-on, cliccare, presso il menu, la voce:

“Configurazione” > “Componenti aggiuntivi” e poi sul pulsante “Raccolta di componenti aggiuntivi“.

Si tratta di accedere ad una vera e propria “vetrina” di componenti aggiuntivi (gratuiti) che, proprio come mattoncini da costruzioni, andranno ad arricchire le funzionalità del nostro HUB.

Cercare dunque “OpenZWave“, selezionarlo e cliccare su “INSTALLA“:

Al termine dell’installazione, non avviare l’add-on: è necessario, prima, configurarlo.

Configurare OpenZWave

La configurazione di OpenZWave non è particolarmente complessa ma importante. È in questa fase, infatti, che si definisco le caratteristiche di connessione del BRIDGE/Gateway da esso rappresentato verso la rete Z-Wave che andiamo a definire.

Tale configurazione si effettua sempre dalla pagina di dettaglio dell’add-on OpenZWave; in alto nella pagina nella pagina, alla voce “CONFIG“.

I campi da personalizzare sono, principalmente, tre: “device“, “network_key” nonché la porta di interfacciamento (web e/o VNC).

Nel campo “port” indicare la porta logica dell’antenna identificata in precedenza (eg. /dev/serial/by-id/usb-0658_0200-if00); nel campo network_key è invece necessario indicare una chiave causare di crittografia da utilizzarsi per il pairing sicuro delle componenti Z-Wave che supportino tale modalità.

Per generare una chiave casuale, eseguire il comando:

cat /dev/urandom | tr -dc '0-9A-F' | fold -w 32 | head -n 1 | sed -e 's/\(..\)/0x\1, /g' -e 's/, $//'

presso l’interfaccia SSH precedentemente installata.
Infine, indicare la porta 1983 nel campo ozw-admin port. Salvo necessità specifiche, configurare la porta VNC non è necessario.

Una volta terminata la configurazione, cliccare su “SAVE” e poi, sopra, su “START“: il BRIDGE/Gateway andrà in esecuzione:

Si consiglia vivamente di attivare il Watchdog (il quale provvede a riavviare l’add-on in caso di crash) e, per comodità, la presenza in sidebar (“Show in sidebar“) nonché l’ovvio “Start on boot“.

VERIFICA

Per verificare che tutto sia andato per il verso giusto, recarsi sul fondo della pagina e cliccare “REFRESH” nel box “Log“: se è tutto ok, dovrebbe apparire un log “verde” che, sostanzialmente, identifica un corretto avvio di OpenZWave e un’avvenuta connessione col broker MQTT.

ATTENZIONE: se l’avvio va in errore, fermare l’add-on, modificare il campo “port” della configurazione indicando il percorso individuato installando l’antenna, salvare e provare ad avviarlo.

Congratulazioni: OpenZWave è ora operativo.

Uso e integrazioni

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

Successivamente, per integrare OpenZWave a Home Assistant, recarsi presso l’elenco delle integrazioni dell’HUB (“Configurazione“, “Integrazioni“) e scegliere “OpenZWave” e seguire i passi di configurazione automatica.

⚠️ Se di Home Assistant ne sai poco ma sei interessato a capirne di più, ti suggeriamo di partire da qui.

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.