Z-Wave JS UI MQTT Gateway Kurulumu: Z-Wave Cihaz Değerlerini Bir Broker'a Yayınlayın

zwave-js-ui MQTT gateway'i, kapı sensörlerinden dimmer seviyelerine kadar her Z-Wave değerini herhangi bir dashboard, betik veya otomasyon aracının kullanabileceği MQTT mesajları olarak yayınlar. Bu rehberde Z-Wave JS UI'ı Docker'da çalıştıracak, MQTT ve gateway ayarlarını yapılandıracak, /set topic'leriyle değerleri geri yazacak ve verileri TLS üzerinden bir bulut broker'a ileteceksiniz.

Z-Wave JS UI MQTT Gateway Ne Yapar?

Z-Wave JS UI (eski adıyla zwavejs2mqtt), Z-Wave JS sürücüsünü cihaz ekleme, ağı onarma ve yapılandırma parametrelerini düzenleme için bir web arayüzüyle sarmalar. Ağı iki şekilde dışarı açar: Home Assistant'ın Z-Wave JS entegrasyonunun kullandığı bir WebSocket sunucusu ve değerleri bir broker'a yayınlayıp ondan gelen yazma isteklerini kabul eden bir MQTT gateway.

Tüketiciler Home Assistant değilse ihtiyacınız olan MQTT tarafıdır: Node-RED akışları, bir zaman serisi veritabanını besleyen Telegraf, özel bir backend veya uzak bir dashboard. Bunların her biri broker üzerindeki topic'lere abone olmaktan ibarettir. Broker'ın rolü sizin için yeniyse önce bir MQTT broker'ın ne yaptığını okuyun.

Adım 1: Z-Wave JS UI'ı Çalıştırın

En yaygın çalıştırma yöntemi Docker'dır. Z-Wave çubuğunuzun kalıcı yolunu ls -l /dev/serial/by-id/ ile bulun ve container'ı başlatın:

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

Cihaz yolunu kendi yolunuzla değiştirin. http://<host>:8091 adresini açın, Settings ve ardından Z-Wave bölümüne gidin, seri portu /dev/zwave olarak ayarlayın, güvenlik anahtarlarını üretin ve kaydedin. Devam etmeden önce bir iki cihaz ekleyin ki yayınlanacak bir şey olsun.

Adım 2: Topic Yapısını Anlayın

Değerler şu desenle yayınlanır:

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

office konumunda, desk_lamp adlı ve prefix'i zwave olan bir dimmer için mevcut seviye zwave/office/desk_lamp/38/0/currentValue topic'indedir; burada 38, Multilevel Switch command class'ıdır. Değeri değiştirmek için aynı topic'e sonuna /set ekleyerek yayın yaparsınız, genellikle targetValue üzerinde:

Gateway durum topic'i özellikle kullanışlıdır: Herhangi bir cihazdan bağımsız olarak Z-Wave JS UI'ın kendisinin bağlı olup olmadığını uzak tüketicilere bildirir.

Adım 3: zwave-js-ui MQTT Gateway'i Herkese Açık Bir Broker'da Test Edin

Kalıcı bir şey kurmadan önce gateway'in çalıştığını broker.connectmq.com adresindeki herkese açık MQTT test broker'ı ile doğrulayın. Bu broker, benzersiz herhangi bir client ID ile anonim bağlantıları kabul eder. Burada iki ayrıntı önemlidir:

1. Z-Wave JS UI client ID'sini ZWAVE_GATEWAY-<Name> şeklinde oluşturur, bu yüzden Name alanı benzersiz olmalıdır. Rastgele bir sonek kullanın.
2. Herkese açık alan en fazla sekiz topic seviyesine izin verir. Uzun bir prefix ile konum, node adı, command class, endpoint, property ve /set bu sınırı kolayca aşar; bu yüzden kısa bir prefix kullanın ve topic'lerde konumu kapatın.

Settings ve ardından MQTT bölümünde şunları girin:

Ardından Settings ve Gateway bölümünde şunları seçin:

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

Kaydedin, ardından bir terminalden abone olun:

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

Önce gateway durumunu, ardından her node'un değerlerini göreceksiniz. Lambayı değiştirin:

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}'

Birkaç saniye sonra currentValue 40 olarak güncellenir. Herkese açık alanın herkes tarafından görülebildiğini unutmayın; onu yalnızca zararsız testler için kullanın, asla kilitler, alarmlar veya garaj kapıları için değil.

Adım 4: Yerel Köprü ile Üretim Kurulumu

Özel broker'lar kimlik bilgilerini sabit bir client ID ile birlikte verir. ConnectMQ, client ID'yi verilen kullanıcı adı ve parolaya bağlar; Z-Wave JS UI ise client ID'sinin başına her zaman ZWAVE_GATEWAY- ekler. Pratikte bu, Z-Wave JS UI'ın verilen ID'yi birebir sunamayacağı anlamına gelir.

Temiz çözüm, Z-Wave JS UI'ın yanında küçük bir Mosquitto köprüsüdür. Z-Wave JS UI yerel Mosquitto'ya TLS olmadan bağlanır, Mosquitto da zwave/# topic'lerini size verilen client ID, kullanıcı adı ve parola ile TLS üzerinden bulut broker'a iletir. Üstelik internet kesintisi sırasında yerel otomasyonlar çalışmaya devam eder.

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

1883 portu host'a yayınlanmadığı için yerel listener'a yalnızca Compose ağı içinden erişilebilir. Z-Wave JS UI'da MQTT ayarlarını Host url mqtt://mosquitto, Port 1883, Prefix zwave, Auth kapalı olarak değiştirin. Özel broker'lar herkese açık alandaki sekiz seviye sınırına tabi olmadığından Ignore location seçeneğini yeniden kapatabilirsiniz.

try_private false önemlidir: Diğer broker'ların anlamadığı, Mosquitto'ya özgü bir köprü el sıkışmasını devre dışı bırakır. topic zwave/# both 1 her iki yönde iletim yapar, böylece buluttan gelen /set mesajları Z-Wave JS UI'a ulaşır.

Z-Wave Verilerini Uzaktan Tüketmek

Kendi kimlik bilgilerine sahip herhangi bir MQTT istemcisi artık ağı her yerden okuyabilir. Kapı sensörlerini ve gateway durumunu kaydeden minimal bir Python tüketicisi (paho-mqtt 2.x):

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)  # Binary Sensor command class

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

Bu tüketici için ayrı bir kimlik bilgisi seti kullanın; köprünün client ID'sini paylaşamaz.

Sorun Giderme Kontrol Listesi

1. Gateway durumu false olarak kalıyor - host url şemasını (mqtt:// ve mqtts://) ve port eşleşmesini kontrol edin: TLS olmadan 1883, TLS ile 8883.
2. Yazma işlemleri hiçbir şey yapmıyor - currentValue yerine targetValue/set topic'ine yayın yapın ve value alanı içeren JSON gönderin.
3. Bazı topic'ler herkese açık broker'da hiç görünmüyor - sekiz seviyeyi aşıyorlardır. Prefix'i kısaltın veya konumu yok sayın.
4. Köprü bağlanıyor, sonra kopuyor - başka bir istemci aynı verilen client ID'yi kullanıyor.
5. Değerler devasa JSON nesneleri olarak geliyor - payload türü "Entire ValueId Object" olarak ayarlı; JSON Time-Value veya Just value seçeneğine geçin.

Resmi Z-Wave JS UI dokümantasyonu tüm API adlarını ve gateway seçeneklerini listeler.

İlgili Akıllı Ev Rehberleri

Z-Wave nadiren tek başına kullanılır. Zigbee2MQTT bulut broker rehberi aynı uzak erişim desenini Zigbee'ye uygular, rtl_433 MQTT rehberi ise ucuz 433 MHz sensörleri ekler. Tutarlı bir akıllı ev MQTT topic yapısı hepsini düzenli tutar, IoT otomasyon rehberi de parçaların nasıl bir araya geldiğini gösterir.

Z-Wave Ağınızı ConnectMQ ile Çevrimiçi Hale Getirin

Bir yönetilen MQTT broker, internette bir sunucu bakımı yapmadan köprünüze kararlı ve TLS korumalı bir uç nokta sağlar. ConnectMQ; MQTT 3.1.1 ve 5.0, Z-Wave topic'lerini kontrol etmek için canlı bir topic gezgini ve sıcaklık ya da pil seviyesi gibi değerler için eşik tabanlı uyarı kuralları sunar. app.connectmq.com adresinde kredi kartı gerekmeden ücretsiz bir Serverless broker oluşturun.

Sık Sorulan Sorular

Z-Wave JS UI MQTT için hangi client ID'yi kullanır?

MQTT ayarlarındaki Name değerinin önüne ZWAVE_GATEWAY- ekleyerek oluşturulan ID'yi kullanır. İki gateway'in asla aynı client ID'yi paylaşmaması için adı benzersiz yapın.

MQTT üzerinden bir Z-Wave değerini nasıl değiştiririm?

{"value":100} gibi bir JSON'u, değerin topic'inin sonuna /set ekleyerek yayınlayın; genellikle .../38/0/targetValue/set. Yeni değer currentValue topic'inde görünür.

Home Assistant kullanıyorsam MQTT gateway'e ihtiyacım var mı?

Mutlaka değil. Home Assistant'ın Z-Wave JS entegrasyonu WebSocket sunucusunu kullanır; MQTT gateway ise Node-RED, veritabanları veya uzak dashboard'lar gibi diğer tüketiciler içindir.

Neden doğrudan bağlanmak yerine Mosquitto köprüsü kullanılmalı?

Z-Wave JS UI client ID'sine önek eklediği için, broker'ın kimlik bilgilerine bağladığı verilen client ID'yi kullanamaz. Köprü tam ID'yi sunar ve ayrıca çevrimdışıyken yerel trafiğin çalışmaya devam etmesini sağlar.