Configurer la passerelle MQTT de Z-Wave JS UI : publier les valeurs des appareils Z-Wave vers un broker

La passerelle MQTT de zwave-js-ui publie chaque valeur Z-Wave, des détecteurs d'ouverture aux niveaux des variateurs, sous forme de messages MQTT exploitables par n'importe quel tableau de bord, script ou outil d'automatisation. Dans ce guide, vous allez lancer Z-Wave JS UI dans Docker, configurer ses réglages MQTT et de passerelle, modifier des valeurs via des topics /set et transférer les données vers un broker cloud en TLS.

Ce que fait la passerelle MQTT de Z-Wave JS UI

Z-Wave JS UI (anciennement zwavejs2mqtt) enveloppe le pilote Z-Wave JS dans une interface web permettant d'inclure des appareils, de réparer le réseau et de modifier les paramètres de configuration. Il expose le réseau de deux façons : un serveur WebSocket, utilisé par l'intégration Z-Wave JS de Home Assistant, et une passerelle MQTT, qui publie les valeurs vers un broker et accepte des écritures en retour.

Le côté MQTT est celui qu'il vous faut lorsque les consommateurs ne sont pas Home Assistant : flux Node-RED, Telegraf alimentant une base de séries temporelles, backend sur mesure ou tableau de bord distant. Chacun s'abonne simplement à des topics sur le broker. Jeedom et Domoticz savent aussi communiquer en MQTT. Si le rôle du broker est nouveau pour vous, lisez d'abord ce que fait un broker MQTT.

Étape 1 : lancer Z-Wave JS UI

Docker est la manière la plus courante de le faire tourner. Trouvez le chemin stable de votre clé Z-Wave avec ls -l /dev/serial/by-id/ et démarrez le conteneur :

docker run -d --name zwave-js-ui --restart unless-stopped \
  -p 8091:8091 -p 3000:3000 \
  --device=/dev/serial/by-id/usb-Silicon_Labs_CP2102N_USB_to_UART_Bridge-if00-port0:/dev/zwave \
  -v zwave-config:/usr/src/app/store \
  zwavejs/zwave-js-ui:latest

Remplacez le chemin du périphérique par le vôtre. Ouvrez http://<host>:8091, allez dans Settings puis Z-Wave, réglez le port série sur /dev/zwave, générez les clés de sécurité et enregistrez. Incluez un ou deux appareils avant de continuer, pour avoir quelque chose à publier.

Étape 2 : comprendre la structure des topics

Les valeurs sont publiées selon ce schéma :

<prefix>/<location>/<node name>/<command class>/<endpoint>/<property>

Pour un variateur nommé desk_lamp dans l'emplacement office, avec le préfixe zwave, le niveau actuel se trouve sur zwave/office/desk_lamp/38/0/currentValue, 38 étant la command class Multilevel Switch. Pour le modifier, publiez sur le même topic suivi de /set, généralement sur targetValue :

Le topic de statut de la passerelle est particulièrement utile : il indique aux consommateurs distants si Z-Wave JS UI lui-même est connecté, indépendamment de tout appareil.

Étape 3 : tester la passerelle zwave-js-ui MQTT sur le serveur MQTT public gratuit

Avant de construire quoi que ce soit de permanent, vérifiez que la passerelle fonctionne avec le serveur MQTT public gratuit broker.connectmq.com, réservé aux tests et aux prototypes. Il accepte les connexions anonymes avec n'importe quel client ID unique. Deux détails comptent ici :

1. Z-Wave JS UI construit son client ID sous la forme ZWAVE_GATEWAY-<Name> ; le champ Name doit donc être unique. Utilisez un suffixe aléatoire.
2. L'espace public autorise au maximum huit niveaux de topic. Un préfixe long, plus l'emplacement, le nom du nœud, la command class, l'endpoint, la propriété et /set, dépasse facilement cette limite ; utilisez donc un préfixe court et désactivez les emplacements dans les topics.

Dans Settings, puis MQTT, saisissez :

Puis, dans Settings, puis Gateway, choisissez :

• Type : ValueId topics.
• Payload type : JSON Time-Value.
• Use nodes name instead of numeric nodeIDs : activé.
• Ignore location : activé.

Enregistrez, puis abonnez-vous depuis un terminal :

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -i watch-h2k8tp -t 'connectmq/demo/h2k8tp/#' -v

Vous verrez le statut de la passerelle, puis les valeurs de chaque nœud. Commandez la lampe :

mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -i send-h2k8tp -t 'connectmq/demo/h2k8tp/desk_lamp/38/0/targetValue/set' \
  -m '{"value":40}'

Quelques instants plus tard, currentValue passe à 40. N'oubliez pas que l'espace public est visible par tous ; ne l'utilisez que pour des tests sans enjeu, jamais pour des serrures, des alarmes ou des portes de garage.

Étape 4 : installation de production avec un pont local

Les brokers privés émettent des identifiants accompagnés d'un client ID fixe. ConnectMQ lie le client ID au nom d'utilisateur et au mot de passe émis, et Z-Wave JS UI préfixe toujours son client ID par ZWAVE_GATEWAY-. En pratique, Z-Wave JS UI ne peut donc pas présenter exactement l'identifiant émis.

La solution propre est un petit pont Mosquitto à côté de Z-Wave JS UI. Z-Wave JS UI se connecte au Mosquitto local sans TLS, et Mosquitto transfère les topics zwave/# vers le broker cloud avec votre client ID, votre nom d'utilisateur et votre mot de passe émis, en TLS. En prime, les automatisations locales continuent de fonctionner pendant une coupure Internet.

docker-compose.yml :

services:
  mosquitto:
    image: eclipse-mosquitto:2
    restart: unless-stopped
    volumes:
      - ./mosquitto.conf:/mosquitto/config/mosquitto.conf:ro
      - /etc/ssl/certs:/etc/ssl/certs:ro

  zwave-js-ui:
    image: zwavejs/zwave-js-ui:latest
    restart: unless-stopped
    ports:
      - "8091:8091"
      - "3000:3000"
    devices:
      - /dev/serial/by-id/usb-Silicon_Labs_CP2102N_USB_to_UART_Bridge-if00-port0:/dev/zwave
    volumes:
      - zwave-config:/usr/src/app/store
    depends_on:
      - mosquitto

volumes:
  zwave-config:

mosquitto.conf :

listener 1883
allow_anonymous true

connection connectmq
address broker.connectmq.com:8883
remote_clientid YOUR_CLIENT_ID
remote_username YOUR_USERNAME
remote_password YOUR_PASSWORD
bridge_capath /etc/ssl/certs
bridge_protocol_version mqttv311
try_private false
cleansession true
topic zwave/# both 1

Le listener local n'est joignable qu'à l'intérieur du réseau Compose, car le port 1883 n'est pas publié sur l'hôte. Dans Z-Wave JS UI, modifiez les réglages MQTT : Host url mqtt://mosquitto, Port 1883, Prefix zwave, Auth désactivé. Vous pouvez désactiver à nouveau Ignore location, car les brokers privés ne sont pas soumis à la limite publique de huit niveaux.

try_private false est important : il désactive une négociation de pont propre à Mosquitto que les autres brokers ne comprennent pas. topic zwave/# both 1 transfère dans les deux sens, si bien que les messages /set venant du cloud atteignent Z-Wave JS UI.

Consommer les données Z-Wave à distance

N'importe quel client MQTT disposant de ses propres identifiants peut désormais lire le réseau depuis n'importe où. Un consommateur Python minimal (paho-mqtt 2.x) qui journalise les détecteurs d'ouverture et le statut de la passerelle :

import json
import paho.mqtt.client as mqtt

def on_connect(client, userdata, flags, reason_code, properties):
    client.subscribe("zwave/_CLIENTS/+/status", qos=1)
    client.subscribe("zwave/+/48/0/+", qos=1)  # command class Binary Sensor

def on_message(client, userdata, msg):
    try:
        data = json.loads(msg.payload)
        value = data["value"] if isinstance(data, dict) else data
    except ValueError:
        value = msg.payload.decode()
    print(msg.topic, "->", value)

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="YOUR_CLIENT_ID")
client.username_pw_set("YOUR_USERNAME", "YOUR_PASSWORD")
client.tls_set()
client.on_connect = on_connect
client.on_message = on_message
client.connect("broker.connectmq.com", 8883, keepalive=60)
client.loop_forever()

Utilisez un jeu d'identifiants distinct pour ce consommateur ; il ne peut pas partager le client ID du pont.

Liste de contrôle de dépannage

1. Le statut de la passerelle reste à false - vérifiez le schéma de l'URL d'hôte (mqtt:// ou mqtts://) et l'association avec le port : 1883 sans TLS, 8883 avec TLS.
2. Les écritures n'ont aucun effet - publiez sur targetValue/set, pas sur currentValue, et envoyez du JSON avec un champ value.
3. Certains topics n'apparaissent jamais sur le serveur MQTT public gratuit - ils dépassent huit niveaux. Raccourcissez le préfixe ou ignorez l'emplacement.
4. Le pont se connecte puis décroche - un autre client utilise le même client ID émis.
5. Les valeurs arrivent sous forme d'énormes objets JSON - le type de payload est réglé sur « Entire ValueId Object » ; passez à JSON Time-Value ou Just value.

La documentation officielle de Z-Wave JS UI liste chaque nom d'API et chaque option de passerelle.

Guides maison connectée associés

Z-Wave vit rarement seul. Le guide Zigbee2MQTT avec un broker cloud applique le même schéma d'accès distant à Zigbee, et le guide rtl_433 MQTT ajoute des capteurs 433 MHz bon marché. Une structure de topics MQTT cohérente pour la maison connectée garde l'ensemble bien rangé, et le guide de l'automatisation IoT montre comment les éléments se combinent.

Mettez votre réseau Z-Wave en ligne avec ConnectMQ

Un broker MQTT managé offre à votre pont un point d'accès stable et protégé par TLS, sans serveur à maintenir sur Internet. ConnectMQ prend en charge MQTT 3.1.1 et 5.0, propose un explorateur de topics en direct pour vérifier les topics Z-Wave et des règles d'alerte sur seuil pour des valeurs comme la température ou le niveau de batterie. Créez un broker Serverless gratuit sur app.connectmq.com, sans carte bancaire.

Questions fréquentes

Quel client ID Z-Wave JS UI utilise-t-il pour MQTT ?

Il utilise ZWAVE_GATEWAY- suivi du Name défini dans les réglages MQTT. Choisissez un nom unique pour que deux passerelles ne partagent jamais le même client ID.

Comment modifier une valeur Z-Wave via MQTT ?

Publiez du JSON comme {"value":100} sur le topic de la valeur suivi de /set, généralement .../38/0/targetValue/set. La nouvelle valeur apparaît sur le topic currentValue.

Ai-je besoin de la passerelle MQTT si j'utilise Home Assistant ?

Pas nécessairement. L'intégration Z-Wave JS de Home Assistant utilise le serveur WebSocket ; la passerelle MQTT sert aux autres consommateurs comme Node-RED, les bases de données ou les tableaux de bord distants.

Pourquoi utiliser un pont Mosquitto plutôt qu'une connexion directe ?

Parce que Z-Wave JS UI préfixe son client ID, il ne peut pas utiliser un client ID émis que le broker lie aux identifiants. Le pont présente l'identifiant exact et maintient aussi le trafic local hors connexion.