community italiana di domotica personale
 
Installare e configurare Z-Wave JS su Home Assistant OS/Supervised
Guide

Installare e configurare Z-Wave JS su Home Assistant OS/Supervised

 , , , , ,
SCOPI DELLA GUIDA:
  • Installare e configurare il BRIDGE/Gateway Z-Wave JS 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:
PREREQUISITI:
DISPOSITIVI FISICI UTILIZZATI:
  • Il computer sul quale è in esecuzione Home Assistant
  • Un’antenna Z-Wave Coordinator compatibile con Z-Wave JS (illustrato a seguire)
GUIDA indicatA per UTENTI:

Ambiente HassOS
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;
  • 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

Z-Wave JS - HASSIO

Abstract

Z-Wave, uno standard wireless particolarmente apprezzato in domotica personale, specie in termini di sicurezza e affidabilità.

Spesso in domotica l’interoperabilità tra componenti basati su questo protocollo ma di diverse tipologie e diversi produttori (ne abbiamo testati svariati) 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 Z-Wave JS, 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 le proprie API per instradare i messaggi da e per i componenti Z-Wave tramite esso gestiti.

Tali tramite API sarà poi facile riuscire ad integrare il tutto con Home Assistant, il quale supporta tale integrazione nativamente.

Scopo della presente guida è quello di installare e configurare Z-Wave JS come add-on presso Home Assistant (installato in modalità HassOS o Supervised) in una delle due modalità possibili.

Altre guide disponibili su inDomus dedicate a Z-Wave JS sono:

Si parte

Assunti

Questa guida è dedicata a chi abbia già in uso l’HUB Home Assistant OS (aka HassOS, o HASSIO) o 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.

Z-Wave JS supporta svariate antenne, tra le quali abbiamo documentato e testato con successo:

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 – come questa per esempio – 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 “Sistema” > “Host” > “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.

Scelta del server da installare

Z-Wave JS è disponibile in due diverse modalità, due diversi add-on (mutuamente esclusivi: o uno, o l’altro) dal medesimo scopo:

  • Z-Wave JS (server “base”);
  • ZWaveJS2MQTT (server evoluto con – tra le varie cose – eventuale supporto MQTT).

Il primo è elementare. Si installa, si configura, si mette in esecuzione e il gioco è fatto.
Il secondo, differentemente da come suggerirebbe il nome, non ha necessità di un broker MQTT per funzionare: viene installato e contestualmente eseguito, al ché offre un’interfaccia web (su porta 8091) che permette tra le varie cose di:

  • configurare in dettaglio le caratteristiche della rete Z-Wave;
  • gestire le chiavi di sicurezza;
  • amministrare i nodi della rete Z-Wave;
  • gestire log e debug;
  • effettuare backup e restore della propria rete Z-Wave;
  • attivare il supporto allo standard MQTT;
  • attivare il supporto alle API tramite le quali integrare Home Assistant (a meno che non si prediliga allo scopo il sopracitato MQTT);

e molto altro ancora.

A seguire documentiamo entrambe le modalità, anche se Z-Wave JS UI è quella preferibile e da noi suggerita.

Z-Wave JS

Vediamo dunque come installare la versione “light” di questo BRIDGE/Gateway Z-Wave

Installare Z-Wave JS

A questo punto è possibile provvedere all’installazione di Z-Wave JS, 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 “Z-Wave JS“, selezionarlo e cliccare su “INSTALLA“:

Z-Wave JS HASSIO add-on - installazione

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

Vetrina - Offerte del giorno

Configurare Z-Wave JS

La configurazione di Z-Wave JS 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 vari. In primis, l’antenna; in secondo luogo, i campi “network_key“,  “s0_legacy_key“,  “s2_access_control_key“,  “s2_authenticated_key“,  “s2_unauthenticated_key“.

Nel campo “device” selezionare 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à.

Le chiavi sono tutte diverse, tranne “network_key“,  “s0_legacy_key” che devono coincidere. Non utilizzare quelle esemplificative proposte sulla documentazione ufficiale di Z-Wave: quelle, proprio perché pubbliche e d’esempio, non funzionano.

Per generare dunque le quattro chiavi casuali necessarie, eseguire più volte il comando:

hexdump -n 16 -e '4/4 "%08X" 1 "\n"' /dev/random

presso l’interfaccia SSH precedentemente installata, oppure utilizzare questo sito.
Infine, indicare la porta 3000 nel campo host a seguire. 

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

Z-Wave JS HASSIO add-on

Si consiglia vivamente di attivare il Watchdog (il quale provvede a riavviare l’add-on in caso di crash) 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 tipo:

[services.d] starting services
[services.d] done.

che, sostanzialmente, identifica un corretto avvio di Z-Wave JS.

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: Z-Wave JS è ora operativo.
È dunque possibile saltare direttamente all’integrazione presso Home Assistant.

Z-Wave JS UI

In questa sezione di guida vediamo come installare la versione evoluta di questo BRIDGE/Gateway Z-Wave, alternativa alla precedente “light”. Come detto, malgrado il nome utilizzare Z-Wave JS UI non prevede, obbligatoriamente, l’uso di MQTT, quindi ci disinteresseremo di questo aspetto – comunque, configurabile in proprio dopo l’installazione.

Come già detto, consigliamo l’adozione di Z-Wave JS UI piuttosto che del server Z-Wave JS “light”.

Installare Z-Wave JS UI

A questo punto è possibile provvedere all’installazione di Z-Wave JS UI, 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 “Z-Wave JS to MQTT “, selezionarlo e cliccare su “INSTALLA“:

ZWaveJS2MQTT HASSIO add-on - installazione

Al termine, accedere alla voce “CONFIG” e impostare a 3000 la porta host.
Completata questa breve configurazione, tornare alla schermata principale dell’add-on e cliccare su “AVVIA”:

ZWaveJS2MQTT HASSIO add-on

Ricordarsi di attivare le spunte relative a “watchdog” e “visualizzazione in barra laterale”.

Configurare Z-Wave JS UI

La configurazione di Z-Wave JS UI si effettua sempre dopo l’avvio dell’add-on. Un po’ controintuitivo, ma tant’è.

Presso la barra laterale di Home Assistant, cliccare alla voce “Z-Wave JS”. Si aprirà l’interfaccia web del BRIDGE/Gateway.

Recarsi alla voce “Settings”:

ZWaveJS2MQTT - Impostazioni

dopodiché provvedere come segue:

  • Z-Wave:
    • serial port: selezionale la porta logica dell’antenna identificata in precedenza;
    • S2 Unauthenticated: inserire un codice HEX univoco, casuale da 32 caratteri (usare questo sito per generarne più di uno);
    • S2 Authenticated: inserire un codice HEX univoco, casuale da 32 caratteri;
    • S2 Access Control: inserire un codice HEX univoco, casuale da 32 caratteri;
    • SO Legacy: inserire un codice HEX univoco, casuale da 32 caratteri;
  • Disable MQTT Gateway: ON (a meno che non si voglia utilizzare MQTT);
  • Home Assistant:

Terminata la configurazione, cliccare in basso su SAVE. 
Al termine, recarsi presso la pagina dell’add-on ed effettuare un riavvio dello stesso.

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 tipo:

[services.d] starting services
[services.d] done.

che, sostanzialmente, identifica un corretto avvio di Z-Wave JS UI,e quindi di Z-Wave JS.

Congratulazioni: Z-Wave JS UI è ora operativo.
È dunque possibile proseguire all’integrazione.

Uso e integrazioni

A questo punto il BRIDGE/Gateway Z-Wave JS (indipendentemente se sia stato installato come server base o tramite Z-Wave JS UI) è pronto e utilizzabile quale ponte tra i componenti Z-Wave compatibili con ecco e il proprio HUB personale; per effettuare l’integrazione tra questi due mondi seguire la guida:

Integrare componenti Z-Wave su Home Assistant via Z-Wave JS (server base o Z-Wave JS UI)

⚠️ 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. Se ti sei perso, a tua disposizione c'è la mappa.