community italiana di domotica personale
 
Installare e configurare Z-Wave JS con Docker su Linux Debian (Mini PC/Intel NUC o altro)
Guide

Installare e configurare Z-Wave JS con Docker su Linux Debian (Mini PC/Intel NUC o altro)

 , , , , , ,
SCOPI DELLA GUIDA:
  • Installare e configurare il BRIDGE/Gateway Z-Wave JS, usando Docker su sistema operativo Linux Debian (o più genericamente, su Linux), dotandosi così di una rete Z-Wave per la propria domotica personale
  • Livello di difficoltà: basso
CONCETTI AFFRONTATI:
  • Installazione e configurazione software
COMPONENTI SOFTWARE UTILIZZATE:
PREREQUISITI:
DISPOSITIVI FISICI UTILIZZATI:
  • Mini PC/Intel NUC (o computer generico)
  • Un’antenna Z-Wave Coordinator compatibile con Z-Wave JS (illustrato a seguire)
GUIDA DEDICATA A utenti:
Debian
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.2

Z-Wave JS - Docker

Abstract

Z-Wave, uno standard wireless particolarmente apprezzato in domotica personale, specie dal punto di vista della sicurezza e dell’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.

Sensore Z-WaveAltro 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 sganciato 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.

Scopo della presente guida è quello di installare e configurare Z-Wave JS istanziato presso Docker.

Z-Wave JS è disponibile in due diverse modalità dal medesimo scopo:

  • Z-Wave JS (server “base”);
  • Z-Wave JS UI (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 suggeriva il nome iniziale (ZWaveJS2MQTT), 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 documenteremo al seconda modalità (Z-Wave JS UI), quella formalmente consigliata per l’istanziamento su Docker.

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

Si parte

Assunti

Questa guida è dedicata a chi abbia già un computer con sistema operativo Linux Debian. Per coloro che non abbiano ancora provveduto e si trovino ad avere un Mini PC/Intel NUC, 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 Linux Debian.

Una volta terminata la configurazione di Linux Debian (inclusa la possibilità di collegarvisi tramite SSH nonché aver effettuato il perfezionamento) è 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.

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

VERIFICA POST-INSTALLAZIONE

Dopo aver installato l’antenna e aver riavviato (opzionalmente) il computer ospitante Linux Debian è 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 da parte tale stringa, servirà a seguire.

Installare Docker

Installare Docker su Linux Debian è piuttosto semplice, esiste una procedura completamente automatica e una manuale. Entrambe le procedure sono illustrate in dettaglio in questa breve guida.

Se si ha già provveduto all’installazione di Docker, va da sé che questo passaggio possa essere saltato.

ATTENZIONE: affinché i comandi a seguire funzionino, è necessario aver aggiunto Docker al gruppo sudoers, come spiegato in guida.
Vetrina Promo

Istanziare Z-Wave JS UI

Arrivati a questo punto è possibile provvedere all’installazione di Z-Wave JS UI, 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 computer ospitante tramite una propria utenza (eg. “deb“), provvedere a creare la cartella:

mkdir -p /home/deb/zwavejsui

avendo cura di adeguare il comando in funzione dell’utenza in uso (nell’esempio, appunto, “deb“).

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 Z-Wave JS UI su Docker tramite il comando:

docker run --init -d -it --name zwavejsui -p 8091:8091 -p 3000:3000 --device=PORTA_COORDINATOR:/dev/zwave -v $/home/deb/zwavejsui:/usr/src/app/store --restart always zwavejs/zwave-js-ui:latest

dove ovviamente nei campo “device” al posto di “PORTA_COORDINATOR” andrà indicata la porta precedentemente identificata e avendo cura di adeguare il comando in funzione dell’utenza in uso (nell’esempio, appunto, “deb“).

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

docker logs zwavejsui

in fondo al log dovremmo trovare qualcosa come:

1980-01-01 00:00:00.000 INFO APP: Listening on port 8091 host 0.0.0.0 protocol HTTP
1980-01-01 00:00:00.001 ERROR GATEWAY: Zwave settings are not valid

Congratulazioni: Z-Wave JS UI è ora operativo.

Nota bene: l’errore indicato è più che normale dato che il BRIDGE/Gateway è sì in esecuzione, ma non è ancora configurato. Configurarlo è proprio ciò che faremo ora.

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

   zwavejsui:
    container_name: zwavejsui
    image: zwavejs/zwave-js-ui:latest
    restart: unless-stopped
    devices:
      - "PORTA_COORDINATOR:/dev/zwave"
    volumes:
      - "/home/deb/zwavejsui:/usr/src/app/store"
    ports:
      - "3000:3000"
      - "8091:8091"

dove ovviamente nei campo “devices” al posto di “PORTA_COORDINATOR” andrà indicata la porta precedentemente identificata e avendo cura di adeguare il comando in funzione dell’utenza in uso (nell’esempio, appunto, “deb“).

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

docker compose up -d zwavejsui

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

in fondo al log dovremmo trovare qualcosa come:

1980-01-01 00:00:00.000 INFO APP: Listening on port 8091 host 0.0.0.0 protocol HTTP
1980-01-01 00:00:00.001 ERROR GATEWAY: Zwave settings are not valid

Congratulazioni: Z-Wave JS UI è ora operativo.

Nota bene: l’errore indicato è più che normale dato che il BRIDGE/Gateway è sì in esecuzione, ma non è ancora configurato. Configurarlo è proprio ciò che faremo ora, subito a seguire.

Configurare Z-Wave JS UI

La configurazione di dettaglio di Z-Wave JS UI si effettua sempre dopo il primo avvio del container. Forse un po’ controintuitivo, ma tant’è.

L’interfaccia di Z-Wave JS UI viene esposta sulla porta 8091 del computer ospitante tale BRIDGE/Gateway. Pertanto, è sufficiente collegarsi tramite browser all’indirizzo:

http://INDIRIZZO_IP_DEL_COMPUTER:8091

Dove ovviamente INDIRIZZO_IP_DEL_COMPUTER andrà sostituito con l’indirizzo IP del computer ospitante.

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, effettuare un riavvio di Z-Wave JS UI tramite il comando:

docker restart zwavejsui

Uso e integrazioni

A questo punto il BRIDGE/Gateway Z-Wave JS è pronto e utilizzabile al fine di gestire componenti Z-Wave compatibili con tale servizio.

Ogni componente compatibile, una volta associato a Z-Wave JS, può essere comandato e censito tramite API e/o MQTT e amministrato attraverso l’interfaccia web di Z-Wave JS UI. Ovviamente, il passo successivo è quello di integrare Z-Wave JS col proprio HUB personale, al fine di utilizzare le risorse delle varie componenti Z-Wave all’interno della propria domotica personale.

Per quanto riguarda l’integrazione con Home Assistant, la guida è questa:

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

Qualsiasi altro HUB personale dotato di componenti d’integrazioni che sfruttino le API di Z-Wave JS UI oppure lo standard MQTT potranno altrettanto facilmente integrarne le funzioni, così come spiegato nella guida qui sopra relativa a Home Assistant.

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.