Zigbee2MQTT: Zigbee Cihazlarını Herhangi Bir MQTT Broker'a Bağlayın

Zigbee2MQTT, bir USB Zigbee koordinatörünü MQTT gateway'ine dönüştürür: eşleştirilen her sensör, ampul ve anahtar bir topic üzerinde JSON mesajı olarak görünür ve /set ile biten her topic bir komuta dönüşür. İçinde broker yoktur; configuration.yaml içinde bir broker'ı gösterirsiniz ve standartlara uygun her MQTT broker çalışır: yerel bir Mosquitto, Home Assistant eklentisi veya bulutta yönetilen bir broker.

Bu eğitim Zigbee2MQTT'yi (2.x) harici bir broker ile yapılandırıyor, topic düzenini açıklıyor ve bağlantıyı doğrulayıp bir cihazı komut satırından nasıl kontrol edeceğinizi gösteriyor.

Parçalar nasıl birleşiyor

Zigbee device ──radio──▶ Coordinator (USB) ──serial──▶ Zigbee2MQTT ──MQTT──▶ Broker ──▶ Home Assistant / Node-RED / your app

Zigbee2MQTT sıradan bir MQTT istemcisidir. Bunun iki pratik sonucu var: broker ağ üzerinden erişilebilen herhangi bir yerde olabilir ve MQTT konuşan her şey — bir dashboard, bir betik, online istemci — ev otomasyonu yazılımınızın gördüğü mesajların aynısını görür.

Minimum yapılandırma

Zigbee2MQTT data/configuration.yaml dosyasını okur. Broker'ınıza bağlantıyı MQTT bölümü sağlar:

mqtt:
  base_topic: testmqtt/z2m          # varsayılan "zigbee2mqtt"
  server: mqtts://broker.connectmq.com:8883
  user: '!secret user'
  password: '!secret password'
  client_id: z2m-living-room
  keepalive: 60
  version: 5                        # 3, 4 (3.1.1) veya 5

serial:
  port: /dev/ttyACM0
  adapter: ember                    # zstack, ember, deconz, zigate, zboss

frontend:
  enabled: true
  port: 8080

homeassistant:
  enabled: false                    # Home Assistant cihazları otomatik bulacaksa true

advanced:
  log_level: info

user: username
password: password

Önemli anahtarlarla ilgili notlar:

• server: şifresiz TCP için mqtt://host:1883, TLS için mqtts://host:8883. Zigbee2MQTT arka planda MQTT.js kullandığı için WebSocket URL'leri (wss://host:8084/mqtt) de çalışır, ancak bir gateway için olağan seçim TCP'dir.
• base_topic: Zigbee2MQTT'nin yayınladığı her şeyin kökü. Özel bir broker'da varsayılan zigbee2mqtt değerini koruyun; paylaşımlı bir test broker'ında diğer kullanıcılarla çakışmamak için yukarıdaki gibi benzersiz bir kök kullanın.
• client_id: broker üzerinde benzersiz olmalıdır. Aynı ID'ye sahip iki instance birbirini döngü halinde düşürür; bkz. client ID en iyi uygulamaları.
• ca, key, cert: yalnızca özel bir CA veya karşılıklı TLS için gerekir. Genel olarak güvenilen sertifikaya sahip bir broker tek başına mqtts:// ile çalışır. Production'da sertifika hatalarını asla reject_unauthorized: false ile "düzeltmeyin".
• !secret: kimlik bilgilerini secret.yaml içinde tutar; böylece configuration.yaml dosyasını güvenle paylaşabilir veya commit edebilirsiniz.

Her seçenek ortam değişkenleriyle de ayarlanabilir; bu container'larda kullanışlıdır: ZIGBEE2MQTT_CONFIG_MQTT_SERVER, ZIGBEE2MQTT_CONFIG_MQTT_USER, ZIGBEE2MQTT_CONFIG_MQTT_PASSWORD vb.

Docker ile çalıştırma

services:
  zigbee2mqtt:
    image: ghcr.io/koenkk/zigbee2mqtt
    restart: unless-stopped
    volumes:
      - ./data:/app/data
      - /run/udev:/run/udev:ro
    ports:
      - "8080:8080"
    environment:
      - TZ=Europe/Berlin
    devices:
      - /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus-if00-port0:/dev/ttyACM0

Koordinatörü /dev/serial/by-id/... yoluyla eşleyin: /dev/ttyUSB0 yeniden başlatmadan sonra veya başka bir USB cihaz takıldığında değişebilir. Aynı Compose dosyasında yerel bir broker çalıştırıyorsanız ona localhost ile değil, servis adıyla (mqtt://mosquitto:1883) erişin; container içinde localhost container'ın kendisidir. Bu kurulumu Docker Compose stack rehberi anlatıyor.

Başlatın ve logu izleyin:

docker compose up -d
docker compose logs -f zigbee2mqtt

Sağlıklı bir başlangıçta önce Connecting to MQTT server at mqtts://broker.connectmq.com:8883, ardından Connected to MQTT server loglanır. MQTT error: Connection refused: Not authorized veya MQTT failed to connect, exiting... görürseniz önce kimlik bilgilerini ve port/şema eşleşmesini kontrol edin; Zigbee2MQTT hataları rehberi her mesajı tek tek ele alıyor.

Topic düzeni

Yeni cihazlar IEEE adresleriyle (0x00158d0001a2b3c4) adlandırılır. Onlara anlamlı adlar verin; addaki eğik çizgi hiyerarşi oluşturur, yani living_room/ceiling adı testmqtt/z2m/living_room/ceiling olur. Bu, düzenli bir akıllı ev topic ağacı elde etmenin en kolay yoludur.

bridge/state, bridge/info ve bridge/devices retained mesajlardır; bu nedenle sonradan abone olan her istemci bridge'in çalışıp çalışmadığını ve hangi cihazların bulunduğunu anında öğrenir.

Her adımı komut satırından test edin

1. Bridge bağlı mı? Bridge durumuna abone olun; retained değer anında gelir:

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'testmqtt/z2m/bridge/state' -v
# testmqtt/z2m/bridge/state {"state":"online"}

2. Bir butona basarken veya kapı sensörünü açarken tüm trafiği izleyin:

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'testmqtt/z2m/#' -v

3. Ağı sınırlı bir süre açarak cihaz eşleştirin (Zigbee2MQTT 2.x time ister; 0 ağı yeniden kapatır):

mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'testmqtt/z2m/bridge/request/permit_join' -m '{"time": 120}'

Yanıt bridge/response/permit_join üzerine gelir; cihaz eşleşirken bridge/event device_joined ve device_interview olaylarını bildirir.

4. Yeniden adlandırın ve kontrol edin:

mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'testmqtt/z2m/bridge/request/device/rename' \
  -m '{"from": "0x00158d0001a2b3c4", "to": "living_room/ceiling"}'

mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'testmqtt/z2m/living_room/ceiling/set' \
  -m '{"state": "TOGGLE", "brightness": 180, "transition": 1}'

Ampulün yeni durumu bir saniye içinde testmqtt/z2m/living_room/ceiling üzerinde görünür. Bir komut hiçbir şey yapmıyorsa bridge/logging topic'ine bakın; Zigbee2MQTT reddedilen payload'ları orada loglar.

Aynı adımları tarayıcıda da yapabilirsiniz: online MQTT istemcisini açın, testmqtt/z2m/# topic'ine abone olun ve publish panelinden /set topic'lerine yayın yapın.

Zigbee2MQTT topic'lerinizi canlı izleyin

Home Assistant ile entegrasyon

homeassistant: enabled: true ayarlandığında Zigbee2MQTT homeassistant/... altında discovery mesajları yayınlar. Home Assistant'ın MQTT entegrasyonu aynı broker'ı göstermelidir; bu durumda cihazlar tüm entity'leriyle otomatik olarak görünür. base_topic değerini değiştirdiyseniz başka bir şeyi değiştirmeniz gerekmez; discovery payload'ları doğru durum ve komut topic'lerini içerir. Broker tarafı için bkz. Home Assistant ve MQTT.

Production kontrol listesi

1. Zigbee2MQTT'ye broker'da ayrı bir kullanıcı verin ve onu <base>/# ile, discovery açıksa ayrıca homeassistant/# ile sınırlayın.
2. Broker aynı makinede değilse her zaman TLS (mqtts://) kullanın.
3. Çevrimdışı cihazların sessizce eskimek yerine raporlanması için availability seçeneğini açın.
4. permit_join'i eşleştirme dışında kapalı tutun.
5. Tüm data/ dizinini yedekleyin; burada yalnızca yapılandırma değil, ağ anahtarı ve koordinatör yedeği de bulunur.

Zigbee2MQTT, Zigbee cihazlarını üretici hub'larından kurtarmanın en basit yoludur: tek bir YAML bloğu onu herhangi bir broker'a yönlendirir ve o andan itibaren her cihaz sadece bir topic'tir. Önce bridge durumunu doğrulayın, eşleştirme sırasında trafiği izleyin ve üzerine otomasyon kurmadan önce cihazları basit bir mosquitto_pub ile kontrol edin.

Sıkça sorulan sorular