Z-Wave JS
Come configurare Z-Wave JS in Home Assistant
Configura un controller Z-Wave con l’app Z-Wave JS e l’integrazione Home Assistant, usando percorso USB stabile, chiavi S2 e WebSocket corretti.
Prerequisiti & Hardware Necessario
- Hardware: controller USB Z-Wave compatibile con Z-Wave JS, prolunga USB schermata e host Home Assistant. Un Raspberry Pi 5 è un possibile host: Raspberry Pi 5 4GB con alimentatore ufficiale.
- Software: Home Assistant OS aggiornato, app Z-Wave JS e integrazione Z-Wave. Il controller è hardware, Z-Wave JS è il server/driver software e l’integrazione Home Assistant espone dispositivi ed entità.
- Sicurezza: prepara quattro chiavi esadecimali casuali da 32 caratteri per S0/S2. Non usare chiavi di esempio e non pubblicarle in screenshot o repository.
- Rete: per l’app ufficiale non serve un WebSocket esposto su Internet. Se usi Home Assistant Container, devi gestire separatamente Z-Wave JS Server o Z-Wave JS UI e collegare Home Assistant via WebSocket.
Procedura passo-passo
- Verifica il controller. Controlla che il firmware e lo SDK siano supportati da Z-Wave JS; per controller della serie 800 usa una versione firmware raccomandata dal produttore. Non confondere un controller Z-Wave con un coordinatore Zigbee.
- Collega il controller con una prolunga USB. Allontanalo da porte USB 3, SSD NVMe e altre sorgenti di interferenza. Se il server è una VM, assegna il dispositivo USB alla VM prima di configurare l’app.
- Trova il percorso stabile. In Home Assistant apri Impostazioni → Sistema → Hardware → Tutto l’hardware e individua il percorso
/dev/serial/by-id/.... Usa il percorso by-id, non un nome volatile come/dev/ttyUSB0. - Installa l’app ufficiale. Vai in Impostazioni → App → Negozio delle app, cerca Z-Wave JS, installa l’app e non avviarla finché non hai impostato device e chiavi.
- Configura device e chiavi. Nella configurazione dell’app inserisci il percorso seriale e chiavi uniche da 32 caratteri esadecimali, ad esempio:
device: /dev/serial/by-id/CONTROLLER_ZWAVE_REALE s0_legacy_key: INSERISCI_32_CARATTERI_ESACDECIMALI s2_access_control_key: INSERISCI_32_CARATTERI_ESACDECIMALI s2_authenticated_key: INSERISCI_32_CARATTERI_ESACDECIMALI s2_unauthenticated_key: INSERISCI_32_CARATTERI_ESACDECIMALI lr_s2_access_control_key: INSERISCI_32_CARATTERI_ESACDECIMALI lr_s2_authenticated_key: INSERISCI_32_CARATTERI_ESACDECIMALICompila le chiavi richieste dalla tua versione dell’app e conservale in un password manager. Le chiavi devono restare identiche per accedere ai dispositivi inclusi in sicurezza.
- Avvia l’app e controlla i log. Salva la configurazione, avvia Z-Wave JS e verifica che il controller venga aperto senza errori. Se il log indica device inesistente o accesso negato, correggi il percorso e il passthrough USB.
- Aggiungi l’integrazione Z-Wave. Vai in Impostazioni → Dispositivi e servizi → Aggiungi integrazione → Z-Wave. Quando Home Assistant propone l’app ufficiale, conferma solo se stai effettivamente usando quella; non creare un secondo server Z-Wave.
- Includi il primo dispositivo. Dal pannello Z-Wave avvia l’inclusione, porta il dispositivo vicino al controller e completa il processo secondo il manuale. Per serrature e dispositivi S2, verifica che la sicurezza sia stata negoziata.
- Configura area e nome. Assegna il dispositivo a un’area, controlla entità e stato del nodo e attendi l’interrogazione completa prima di creare automazioni.
- Fai un backup. Conserva backup Home Assistant, configurazione dell’app e chiavi Z-Wave in una destinazione esterna. Senza le chiavi non puoi recuperare correttamente dispositivi inclusi con sicurezza.
Verifica del funzionamento
La configurazione è corretta quando l’app Z-Wave JS è attiva, il controller è disponibile, l’integrazione Z-Wave mostra il server e almeno un nodo risponde. Riavvia Home Assistant e controlla che il controller venga riaperto usando il percorso by-id. Un dispositivo alimentato a rete dovrebbe contribuire alla mesh come router; un dispositivo a batteria normalmente entra in sleep.
Problemi comuni
| Problema | Causa | Soluzione |
|---|---|---|
| Controller non rilevato | Device path errato o USB passthrough assente | Usa il percorso by-id e controlla assegnazione USB della VM. |
| WebSocket non raggiungibile | Server Z-Wave esterno non attivo o URL errato | Con Home Assistant Container verifica il server e usa il suo hostname/IP e porta WebSocket. |
| Inclusione S2 fallisce | Chiavi mancanti o dispositivo fuori portata | Configura chiavi uniche corrette e includi vicino al controller. |
| Dispositivi lenti o intermittenti | Controller vicino a USB 3 o mesh senza nodi alimentati | Usa prolunga USB e aggiungi dispositivi mains-powered compatibili come router. |
| È stato creato un secondo server | App ufficiale e Z-Wave JS UI avviati insieme | Arresta uno dei due server e collega l’integrazione a un solo WebSocket. |
FAQ essenziali
Z-Wave JS e Z-Wave JS UI sono la stessa cosa?
Entrambi possono fornire il server Z-Wave JS, ma sono componenti distinti. Per una nuova installazione Home Assistant OS usa l’app ufficiale Z-Wave JS salvo esigenze specifiche di Z-Wave JS UI.
Posso riutilizzare le chiavi di un altro impianto?
Solo se stai ripristinando la stessa rete e possiedi le chiavi originali. Per una nuova rete genera chiavi casuali e conservale fuori dal server.
Prodotti consigliati
Hardware pertinente alla guida
I collegamenti portano alle pagine dei prodotti indicati. Il prezzo Amazon, quando disponibile, proviene dall’API ufficiale ed è aggiornato con data e ora; prezzo e disponibilità finali sono quelli della pagina Amazon.