SCOPI DELLA GUIDA:
CONCETTI AFFRONTATI:
|
COMPONENTI SOFTWARE UTILIZZATE:
PREREQUISITI:
DISPOSITIVI FISICI UTILIZZATI:
|
GUIDA INDICATA A UTENTI CON ISTALLAZIONE: |
|
NOTE E DISCLAIMER
|
|
| Revisione guida: 2.0 | |
Abstract
Non ci stiamo a dilungare più di tanto: se si è raggiunta questa guida, è perché si sa già che Z-Wave JS è un BRIDGE/Gateway software implementato in proprio per la gestione di componenti Z-Wave diverse (e di diverse marche) e Home Assistant è l’HUB personale per la gestione della propria domotica personale.
Lo scopo di questa guida, quindi, è quello di integrare facilmente Z-Wave JS (e di conseguenza le componenti basate su standard Z-Wave ad esso associate) con il proprio HUB, così da controllare/censire tramite esso le componenti Z-Wave di cui sopra.
| N.b. Questa guida è adatta sia agli utenti Home Assistant CORE che Home Assistant OS (aka HassOS, o HASSIO). |
Si parte
Assunti
Si assume che Z-Wave JS sia già operativo; qualora non lo sia, si rimanda all’elenco di modalità di installazioni disponibili sulla nostra scheda ad esso dedicata. In pratica, questa guida dà per assunto che si sia quindi già provveduto a installare l’elementare Z-Wave JS “server base” (sconsigliato) o Z-Wave JS UI (consigliato).
Si assume altresì che, ovviamente, anche Home Assistant sia già operativo.
Come funziona
Per quanto detto poco sopra, ci si aspetta che l’utente abbia già provveduto all’implementazione di Z-Wave JS; ripetiamo comunque come lo scenario di riferimento possa variare, quindi cercheremo di riassumere quelle che sono le varie possibilità.
Ci sono sostanzialmente tre modalità di integrazione di Z-Wave JS:
- via API, sfruttando il server Z-Wave JS;
- via API, sfruttando il server evoluto Z-Wave JS UI;
- via MQTT, sempre sfruttando il server evoluto Z- Wave JS UI.
Quale che sia la strada intrapresa (a seguire le approfondiremo tutte), un’ulteriore differenza la fa anche il fatto che il coordinator (la propria antenna Z-Wave) sia installata sul medesimo computer che ospita eventualmente Home Assistant OS oppure su un altro computer presente sulla medesima rete LAN.
Sì, perché qualora si usi Home Assistant OS (il discorso non vale per Core) e sul medesimo computer ospitante si installi l’antenna Z-Wave, solitamente prima dell’implementazione di Z-Wave JS presso la sezione “integrazioni” dell’HUB dovrebbe apparire un banner tipo il seguente:
Cliccando su “CONFIGURA”, il supervisor di Home Assistant provvederà a installare, magari non voluto, il semplice add-on Z-Wave JS Server.
IMPORTANTE, DUNQUE:
a prescindere che l’utente possa scegliere Z-Wave JS Server o Z-Wave JS UI, noi sconsigliamo vivamente di cliccare su “CONFIGURA” e seguire la procedura guidata. Questo perché:
- se si desidera utilizzare Z-Wave JS UI, cliccando “CONFIGURA” si installa invece Z-Wave JS (server base);
- se si desidera utilizzare Z-Wave JS Server, abbiamo notato che talvolta alcune impostazioni non vengono comunque configurate in modo appropriato.
QUINDI:
a prescindere che si desideri utilizzare Z-Wave JS server base oppure Z-Wave JS UI, si eviti l’auto-configurazione offerta presso la pagina integrazioni e si provveda all’installazione manuale di una delle due modalità.
Terminata l’installazione – quale che sia – potrete provvedere a seguire la presente guida a partire dal paragrafo che segue.
Home Assistant
Home Assistant è abilitato dall’integrazione Z-Wave JS a definire delle entità le quali accolgano le metriche e i comandi esposti dai componenti Z-Wave associati a Z-Wave JS (server base) o Z-Wave JS UI.
Ripetiamo, approfondendo. Per farlo ci sono due strade: una semplice e una un po’ più complicata:
- VIA API: lasciare fare a tutto a Z-Wave JS server base (o Z-Wave JS UI) / Home Assistant. Configurata l’integrazione tra i due, ogni qual volta un nuovo componente Z-Wave viene associato a Z-Wave JS o a Z-Wave JS UI, automaticamente vengono anche create le relative entità lato Home Assistant;
- VIA MQTT: è lasciare che Z-Wave JS UI (Z-Wave JS non è in grado di comunicare via MQTT) pubblichi su broker MQTT, come da suo design, i topic telemetrici (oltre a stare in ascolto per eventuali topic di comando) e che la definizione delle entità venga effettuata manualmente dall’utente lato Home Assistant.
Terminato uno di questi due percorsi, è possibile (come spiegato in seguito) associare nodi Z-Wave a Z-Wave JS e quindi sfruttarli tramite Home Assistant.
Via API
L’integrazione, in modalità API, è più automatica che mai – indipendentemente dal fatto che si sia scelto di implementare Z-Wave JS server base o Z-Wave JS UI.
| NOTA PER GLI UTENTI Z-Wave JS UI: Affinché la procedura che segue funzioni, è necessario recarsi presso l’interfaccia web di Z-Wave JS UI e attivare, alla voce “Settings” > “Home Assistant“, la voce “WS Server” nonché l’impostazione della “Server Port” a “3000“. |
Recandosi alla voce “Configurazione” > “Dispositivi e servizi” di Home Assistant, oppure direttamente usando il link che segue:
è possibile cercare e configurare l’integrazione “Z-Wave“.
Selezionando l’elemento, al primo step disattivare (se si usa Home Assistant OS) l’offerta dell’interfaccia di installare Z-Wave JS Server add-on:
Dopodiché l’interfaccia chiederà indirizzo IP e porta del server (qualche sia):
naturalmente, sostituire localhost con l’IP del server, qualora Z-Wave JS sia in esecuzione su un computer diverso da quello su cui è in esecuzione Home Assistant.
Infine, cliccare su INVIA.
Se non ci saranno problemi, l’integrazione si concluderà positivamente.
Via MQTT
Diversamente, se si decide di integrare le proprie risorse via MQTT, è sostanzialmente necessario fare tre cose:
- dotarsi di MQTT su Home Assistant;
- attivare MQTT su Z-Wave JS UI;
- configurare le risorse manualmente.
DOTARSI DI MQTT
Prima di proseguire, porsi la domanda: conosco MQTT? Se la risposta sì, bene, altrimenti provvedere a un approfondimento su questo protocollo. La guida dà per scontato che, quando si fa riferimento a comandi e telemetrie MQTT, si sappia di che si sta parlando, almeno a grandi linee.
Dunque, come funziona Z-Wave JS UI, e perché ci consente di integrare componenti Z-Wave?
Arrivati sin qui dovrebbe già essere chiaro, ma qualora non lo fosse, repetita iuvant.
Z-Wave JS UI (volendo) funge (anche) da ponte tra il protocollo Z-Wave e il protocollo MQTT; quest’ultimo è ben compreso e gestito da Home Assistant, il quale riesce così ad integrare eventuali componenti Z-Wave compatibili con Z-Wave JS UI. Questo “fare ponte” significa “tradurre” il protocollo Z-Wave in messaggi MQTT, da e per il componente. Z-Wave JS UI è poi esso stesso un client MQTT pertanto, per comandarne i comportamenti suoi e dei componenti Z-Wave ad esso connessi, va da sé che si si usino messaggi MQTT.
Quando si collega un componente Z-Wave a Z-Wave JS UI (procedura di pairing), esso ne registra – per così dire – l’identità univoca, generando così un set di telemetrie e di comandi MQTT da e per il componente. Quando arriverà una telemetria via Z-Wave dal componente (per esempio, una temperatura da un sensore termico), pubblicherà sul broker MQTT il messaggio di telemetria, ovviamente “battezzato” col “nome” del componente che l’ha generata. Dato che Z-Wave JS UI avrà anche sottoscritto sul broker gli eventuali topic di comando per quel componente, se si pubblicherà un comando MQTT sul broker Z-Wave JS UI lo riceverà e lo girerà al componente via Z-Wave. E via così.
Dunque, è chiaro come Z-Wave JS UI non si colleghi direttamente a Home Assistant, ma si limiti a “parlarci” tramite il broker MQTT.
Dato che questa modalità di integrazione utilizza MQTT come tramite, va da sé che si debba avere a disposizione un broker MQTT (tipo Eclipse Mosquitto): fatto questo, è necessario recarsi alla voce “MQTT” delle impostazioni di Z-Wave JS UI e collegare il BRIDGE/Gateway al broker MQTT.
ATTIVARE MQTT SU HOME ASSISTANT
Assunto quindi che il broker MQTT sia già disponibile, è altresì necessario configurare l’integrazione MQTT presso Home Assistant, al fine di rendere quest’ultimo in grado di dialogare tramite tale protocollo. Se si è già configurata tale integrazione è possibile saltare al prossimo paragrafo; diversamente, qui spieghiamo come provvedere a tale rapida integrazione.
DEFINIRE LE ENTITà
A questo punto possiamo fisiologicamente solo descrivere a grandi linee cosa fare.
Partiamo dal fatto che una volta effettuato il collegamento tra Z-Wave JS UI e il broker MQTT (e infine tra quest’ultimo e Home Assistant): a questo punto i topic telemetrici MQTT verranno pubblicati dal BRIDGE/Gateway, e quest’ultimo si metterà in ascolto di eventuali topic di comando.
Quel che c’è da fare – e qui viene il difficile, non descrivibile puntualmente in guida – è utilizzare il componente MQTT (e le sue declinazioni) per modellare a mano le entità che corrispondano alle funzionalità dei componenti Z-Wave connessi a Z-Wave JS UI.
L’utente dovrà dunque “mettersi in ascolto” sul broker (vedi esempio su Raspberry Pi OS), raccogliere topic e payload, e modellare così le entità MQTT.
Associare nodi Z-Wave a Z-Wave JS (pairing)
A questo punto:
- se si usa uno tra Z-Wave JS server base e Z-Wave JS UI collegato in modalità API, è sufficiente associare un nodo Z-Wave al BRIDGE/Gateway (pairing) e, automaticamente, su Home Assistant apparirà il device e le entità relative;
- se si usa Z-Wave JS UI collegato via MQTT è necessario associare un nodo Z-Wave al BRIDGE/Gateway (pairing), ma poi andranno configurate le entità come sopra spiegato.
A prescindere, vediamo come effettuare il pairing con le due diverse declinazioni di Z-Wave JS.
Su Z-Wave JS server base
Per effettuare il pairing (e altre azioni), recarsi alla voce “Configurazione” > “Dispositivi e servizi” di Home Assistant, oppure direttamente usando il link che segue:
e individuare il riquadro dedicato a Z-Wave JS.
Entrarvi: in questa location è presente una sezione dedicata al trattamento dei nodi Z-Wave, come inclusione, estromissione, verifica eccetera.
Cliccando su “Aggiungi dispositivo“, l’interfaccia consentirà l’associazione tramite ricerca del dispositivo o lettura del relativo codice QR:
Solitamente si utilizza la ricerca: mettendo il BRIDGE/Gateway in ascolto e il dispositivo in modalità di pairing, dovrebbe (se compatibile) venire riconosciuto automaticamente:
Al termine, il dispositivo sarà stato correttamente associato al BRIDGE/Gateway e le entità ad esso afferenti saranno state create sull’HUB.
Su Z-Wave JS UI
Questo BRIDGE/Gateway offre una propria interfaccia web, la quale può essere acceduta tipicamente via browser alla porta 8091 dell’host che la ospita oppure cliccando, in caso si usi Home Assistant OS, sulla barra laterale dell’HUB.
Tramite questa interfaccia, alla sezione “ACTIONS” > “MANAGE NODES” è possibile effettuare la “Inclusion”, ovvero il pairing.
Come spiegato sopra, ogni componente compatibile con Z-Wave JS UI che venga associato al BRIDGE/Gateway “apparirà” automaticamente come device ed entità presso il Home Assistant in caso si utilizzi l’integrazione API, diversamente utilizzando quella MQTT andrà effettuata, dopo il pairing, la configurazione manuale presso l’HUB.
|
⚠️ 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. |