Z-Wave JS UI als MQTT-Gateway einrichten: Z-Wave-Gerätewerte an einen Broker senden

Das zwave-js-ui-MQTT-Gateway veröffentlicht jeden Z-Wave-Wert, vom Türsensor bis zur Dimmerstufe, als MQTT-Nachricht, die jedes Dashboard, Skript oder Automatisierungswerkzeug nutzen kann. In dieser Anleitung betreiben Sie Z-Wave JS UI in Docker, konfigurieren die MQTT- und Gateway-Einstellungen, schreiben Werte über /set-Topics zurück und leiten die Daten per TLS an einen Cloud-Broker weiter.

Was das MQTT-Gateway von Z-Wave JS UI macht

Z-Wave JS UI (früher zwavejs2mqtt) verpackt den Z-Wave-JS-Treiber in eine Weboberfläche, mit der Sie Geräte inkludieren, das Netzwerk heilen und Konfigurationsparameter bearbeiten. Es stellt das Netzwerk auf zwei Wegen bereit: über einen WebSocket-Server, den die Z-Wave-JS-Integration von Home Assistant nutzt, und über ein MQTT-Gateway, das Werte an einen Broker veröffentlicht und Schreibzugriffe von dort annimmt.

Die MQTT-Seite ist das, was Sie brauchen, wenn die Abnehmer nicht Home Assistant sind: Node-RED-Flows, Telegraf, das eine Zeitreihendatenbank befüllt, ein eigenes Backend oder ein entferntes Dashboard. Jeder davon abonniert einfach Topics auf dem Broker. Wenn Ihnen die Rolle des Brokers neu ist, lesen Sie zuerst, was ein MQTT-Broker macht.

Schritt 1: Z-Wave JS UI starten

Docker ist der gängigste Weg. Ermitteln Sie den stabilen Pfad Ihres Z-Wave-Sticks mit ls -l /dev/serial/by-id/ und starten Sie den Container:

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

Ersetzen Sie den Gerätepfad durch Ihren eigenen. Öffnen Sie http://<host>:8091, gehen Sie zu Settings und dann Z-Wave, setzen Sie den seriellen Port auf /dev/zwave, generieren Sie die Sicherheitsschlüssel und speichern Sie. Inkludieren Sie ein, zwei Geräte, bevor Sie weitermachen, damit es etwas zu veröffentlichen gibt.

Schritt 2: Die Topic-Struktur verstehen

Werte werden nach diesem Muster veröffentlicht:

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

Bei einem Dimmer namens desk_lamp im Ort office mit dem Präfix zwave liegt die aktuelle Stufe unter zwave/office/desk_lamp/38/0/currentValue, wobei 38 die Command Class Multilevel Switch ist. Um sie zu ändern, veröffentlichen Sie auf demselben Topic mit angehängtem /set, meist auf targetValue:

Das Gateway-Status-Topic ist besonders nützlich: Es teilt entfernten Abnehmern mit, ob Z-Wave JS UI selbst verbunden ist, unabhängig von einzelnen Geräten.

Schritt 3: Das zwave-js-ui-MQTT-Gateway auf dem öffentlichen MQTT-Broker testen

Bevor Sie etwas Dauerhaftes aufbauen, prüfen Sie das Gateway mit dem öffentlichen MQTT-Broker unter broker.connectmq.com. Er akzeptiert anonyme Verbindungen mit jeder eindeutigen Client ID. Zwei Details sind hier wichtig:

1. Z-Wave JS UI bildet seine Client ID als ZWAVE_GATEWAY-<Name>, daher muss das Feld Name eindeutig sein. Verwenden Sie ein zufälliges Suffix.
2. Der öffentliche MQTT-Broker erlaubt höchstens acht Topic-Ebenen. Ein langes Präfix plus Ort, Node-Name, Command Class, Endpoint, Property und /set überschreitet das leicht; verwenden Sie daher ein kurzes Präfix und schalten Sie Orte in Topics ab.

Tragen Sie unter Settings und dann MQTT ein:

Wählen Sie dann unter Settings und Gateway:

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

Speichern Sie und abonnieren Sie dann in einem Terminal:

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

Sie sehen den Gateway-Status und danach die Werte jedes Nodes. Schalten Sie die 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}'

Kurz darauf wechselt currentValue auf 40. Denken Sie daran, dass der öffentliche MQTT-Broker für alle sichtbar ist; nutzen Sie ihn nur für harmlose Tests, niemals für Schlösser, Alarmanlagen oder Garagentore.

Schritt 4: Produktiv-Setup mit einer lokalen Bridge

Private Broker stellen Zugangsdaten zusammen mit einer festen Client ID aus. ConnectMQ bindet die Client ID an den ausgestellten Benutzernamen und das Passwort, und Z-Wave JS UI stellt seiner Client ID immer ZWAVE_GATEWAY- voran. In der Praxis bedeutet das: Z-Wave JS UI kann die exakt ausgestellte ID nicht verwenden.

Die saubere Lösung ist eine kleine Mosquitto-Bridge neben Z-Wave JS UI. Z-Wave JS UI verbindet sich ohne TLS mit dem lokalen Mosquitto, und Mosquitto leitet die Topics zwave/# mit Ihrer ausgestellten Client ID, Ihrem Benutzernamen und Passwort per TLS an den Cloud-Broker weiter. Als Bonus funktionieren lokale Automatisierungen auch bei einem Internetausfall weiter.

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

Der lokale Listener ist nur innerhalb des Compose-Netzwerks erreichbar, weil Port 1883 nicht an den Host weitergegeben wird. Ändern Sie in Z-Wave JS UI die MQTT-Einstellungen auf Host url mqtt://mosquitto, Port 1883, Prefix zwave, Auth aus. Ignore location können Sie wieder ausschalten, da private Broker nicht dem Limit von acht Ebenen des öffentlichen MQTT-Brokers unterliegen.

try_private false ist wichtig: Es deaktiviert einen Mosquitto-spezifischen Bridge-Handshake, den andere Broker nicht verstehen. topic zwave/# both 1 leitet in beide Richtungen weiter, sodass /set-Nachrichten aus der Cloud Z-Wave JS UI erreichen.

Z-Wave-Daten aus der Ferne nutzen

Jeder MQTT-Client mit eigenen Zugangsdaten kann das Netzwerk nun von überall lesen. Ein minimaler Python-Abnehmer (paho-mqtt 2.x), der Türsensoren und den Gateway-Status protokolliert:

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

Verwenden Sie für diesen Abnehmer einen separaten Satz Zugangsdaten; er kann die Client ID der Bridge nicht mitbenutzen.

Checkliste zur Fehlersuche

1. Gateway-Status bleibt false - prüfen Sie das Schema der Host url (mqtt:// oder mqtts://) und die passende Portwahl: 1883 ohne TLS, 8883 mit TLS.
2. Schreibzugriffe bewirken nichts - veröffentlichen Sie auf targetValue/set, nicht auf currentValue, und senden Sie JSON mit einem Feld value.
3. Manche Topics erscheinen nie auf dem öffentlichen MQTT-Broker - sie haben mehr als acht Ebenen. Kürzen Sie das Präfix oder ignorieren Sie den Ort.
4. Bridge verbindet sich und bricht dann ab - ein anderer Client verwendet dieselbe ausgestellte Client ID.
5. Werte kommen als riesige JSON-Objekte an - der Payload-Typ steht auf „Entire ValueId Object“; wechseln Sie zu JSON Time-Value oder Just value.

Die offizielle Dokumentation von Z-Wave JS UI listet jeden API-Namen und jede Gateway-Option auf.

Verwandte Smart-Home-Anleitungen

Z-Wave kommt selten allein. Die Anleitung zu Zigbee2MQTT mit Cloud-Broker wendet dasselbe Fernzugriffsmuster auf Zigbee an, und die rtl_433-MQTT-Anleitung ergänzt günstige 433-MHz-Sensoren. Eine einheitliche MQTT-Topic-Struktur fürs Smart Home hält alles ordentlich, und der IoT-Automatisierungsleitfaden zeigt, wie die Bausteine zusammenspielen. In gewerblichen Gebäuden oder Werkhallen geht man einen Schritt weiter und ordnet das Präfix in einen Unified Namespace (UNS) ein, dessen Topic-Struktur der ISA-95-Hierarchie aus Werk, Bereich und Linie folgt, etwa acme/werk-muenchen/halle-2/zwave.

Bringen Sie Ihr Z-Wave-Netzwerk mit ConnectMQ online

Ein verwalteter MQTT-Broker gibt Ihrer Bridge einen stabilen, TLS-geschützten Endpunkt, ohne dass Sie einen Server im Internet pflegen müssen. ConnectMQ bietet MQTT 3.1.1 und 5.0, einen Live-Topic-Explorer zum Prüfen von Z-Wave-Topics und Schwellwert-Alarmregeln für Werte wie Temperatur oder Batteriestand. Erstellen Sie einen kostenlosen Serverless-Broker unter app.connectmq.com, ganz ohne Kreditkarte.

Häufig gestellte Fragen

Welche Client ID verwendet Z-Wave JS UI für MQTT?

Es verwendet ZWAVE_GATEWAY- gefolgt vom Namen aus den MQTT-Einstellungen. Wählen Sie den Namen eindeutig, damit sich zwei Gateways nie eine Client ID teilen.

Wie ändere ich einen Z-Wave-Wert per MQTT?

Veröffentlichen Sie JSON wie {"value":100} auf dem Topic des Werts mit angehängtem /set, typischerweise .../38/0/targetValue/set. Der neue Wert erscheint auf dem Topic currentValue.

Brauche ich das MQTT-Gateway, wenn ich Home Assistant nutze?

Nicht unbedingt. Die Z-Wave-JS-Integration von Home Assistant nutzt den WebSocket-Server; das MQTT-Gateway ist für andere Abnehmer wie Node-RED, Datenbanken oder entfernte Dashboards gedacht.

Warum eine Mosquitto-Bridge statt einer direkten Verbindung?

Weil Z-Wave JS UI seiner Client ID ein Präfix voranstellt, kann es keine ausgestellte Client ID verwenden, die der Broker an Zugangsdaten bindet. Die Bridge präsentiert die exakte ID und hält den lokalen Verkehr auch offline am Laufen.