4. Installer et configurer ZWave JS UI

ZWave JS UI (anciennement ZWavejs2Mqtt) est l’add-on recommandé pour intégrer Z-Wave dans Home Assistant. Il remplace l’ancien add-on ‘ZWave JS’ officiel en ajoutant une interface de gestion complète tout en conservant la même intégration native avec Home Assistant.

ZWave JS vs ZWave JS UI : quelle différence ?

Critère	ZWave JS (officiel)	ZWave JS UI (recommandé)
Interface web de gestion	Non	Oui (tableau de bord complet)
Inclusion / exclusion appareils	Via Home Assistant uniquement	Via interface dédiée + HA
Paramètres avancés des appareils	Limité	Complet (tous les paramètres)
Débogage réseau Z-Wave	Limité	Carte du réseau mesh, statistiques
MQTT support	Non	Optionnel (pour Jeedom, Node-RED…)
Compatibilité HA	Native	Native (même intégration)
Recommandé pour	Usage basique	Tout usage — notre recommandation

Installation de l’add-on ZWave JS UI

Méthode 1 : Home Assistant OS (Supervised) — La plus simple

1. Dans Home Assistant, allez dans Paramètres > Modules complémentaires
2. Cliquez sur ‘BOUTIQUE DES MODULES COMPLÉMENTAIRES’ en bas à droite
3. Recherchez ‘Z-Wave JS UI’ dans la barre de recherche
4. Cliquez sur ‘Z-Wave JS UI’ dans les résultats
5. Cliquez sur ‘INSTALLER’ (l’installation prend 2 à 5 minutes)
6. Une fois installé, activez les options : ‘Démarrage automatique’, ‘Chien de garde’, ‘Mise à jour automatique’
7. Cliquez sur ‘DÉMARRER’

Méthode 2 : Home Assistant Container (Docker)

Si vous utilisez Home Assistant en mode Container (Docker), ZWave JS UI s’installe séparément :

# docker-compose.yml
version: '3.8'
services:
  zwavejs-ui:
    image: zwavejs/zwave-js-ui:latest
    container_name: zwavejs-ui
    restart: always
    tty: true
    stop_signal: SIGINT
    environment:
      - SESSION_SECRET=motdepassefort_changez_ceci
      - ZWAVEJS_EXTERNAL_CONFIG=/usr/src/app/store/.config-db
      - TZ=Europe/Paris
    devices:
      - '/dev/ttyUSB0:/dev/ttyUSB0'  # adaptez selon votre dongle
    volumes:
      - ./zwave-config:/usr/src/app/store
    ports:
      - '8091:8091'   # interface web ZWave JS UI
      - '3000:3000'   # port WebSocket pour Home Assistant

Configuration initiale de ZWave JS UI

À la première connexion, ouvrez l’interface web de ZWave JS UI (Ouvrir l’interface web dans l’add-on, ou http://IP_HA:8091 si Docker).

Étape 1 : Configurer le port série

1. Dans ZWave JS UI, cliquez sur l’icône ⚙️ (Settings) en haut à droite
2. Dans l’onglet ‘Zwave’, renseignez le champ ‘Serial Port’
3. Cliquez sur la liste déroulante : votre dongle doit apparaître (ex : /dev/ttyUSB0 ou /dev/serial/by-id/usb-Silicon_Labs…)
4. Préférez toujours le chemin by-id (stable entre les redémarrages) au lieu de /dev/ttyUSB0 qui peut changer

⚠️ Chemin stable recommandé
Utilisez TOUJOURS le chemin /dev/serial/by-id/… plutôt que /dev/ttyUSB0.
Le chemin ttyUSB0 peut changer si vous branchez/débranchez d’autres périphériques USB.
Le chemin by-id est basé sur l’identifiant unique du dongle et reste stable.
Exemple : /dev/serial/by-id/usb-Silicon_Labs_HubZ_Smart_Home_Controller_C1301234-if00-port0

Étape 2 : Configurer la clé de réseau (Network Keys)

Les clés de réseau sont les clés de chiffrement utilisées pour le protocole de sécurité S2 (le protocole sécurisé de Z-Wave). Elles sont générées automatiquement par ZWave JS UI.
IMPORTANT : sauvegardez-les immédiatement dans un endroit sûr.

1. Dans Settings > Zwave > Security Keys, ZWave JS UI affiche les clés générées
2. Copiez les 4 clés dans un gestionnaire de mots de passe ou un fichier sécurisé :
3. S2 Unauthenticated (S2_Unauthenticated)
4. S2 Authenticated (S2_Authenticated)
5. S2 Access Control (S2_AccessControl) — la plus critique pour les serrures
6. S0 Legacy (networkKey) — pour les anciens appareils Z-Wave 300/500
7. Ces clés sont nécessaires pour restaurer votre réseau Z-Wave en cas de panne ou de migration

🔑 Sauvegarde des clés : CRITIQUE
Si vous perdez vos clés de réseau, vous devrez ré-exclure et ré-inclure TOUS vos appareils Z-Wave.
Pour un réseau de 30 appareils, cela représente plusieurs heures de travail.
Sauvegardez les clés dans : un gestionnaire de mots de passe (Bitwarden, 1Password), un fichier texte chiffré, ET une copie physique dans un endroit sûr.

Étape 3 : Paramètres recommandés

Dans l’onglet Zwave de ZWave JS UI, configurez ces options :

Paramètre	Valeur recommandée	Explication
Soft Reset on startup	Activé	Réinitialise le dongle proprement au démarrage
Enable Statistics	Désactivé (vie privée)	Désactiver l’envoi de stats anonymes si souhaité
Log Level	warn	Évite les logs trop verbeux en production
Z-Wave LR (si dongle 800)	Activé	Active le support Long Range sur les dongles compatibles
Heal Network on startup	Désactivé	Évite un heal automatique à chaque redémarrage

Étape 4 : Connecter ZWave JS UI à Home Assistant

1. Dans ZWave JS UI, allez dans Settings > Home Assistant
2. Activez ‘Home Assistant Discovery’
3. Dans Home Assistant, allez dans Paramètres > Appareils et services > Intégrations
4. Cliquez sur ‘+ AJOUTER UNE INTÉGRATION’ et cherchez ‘Z-Wave’
5. HA vous propose de détecter automatiquement l’add-on ZWave JS UI — acceptez
6. Ou saisissez manuellement l’URL WebSocket : ws://localhost:3000 (add-on) ou ws://IP:3000 (Docker)
7. L’intégration Z-Wave apparaît maintenant dans vos intégrations

---