Zigbee2MQTT Kurulum Rehberi: Koordinatörden Panoya

Bir Zigbee2MQTT kurulumu, pek çok markanın Zigbee sensörlerini, ampullerini ve anahtarlarını onların hub'ları veya bulutları olmadan kullanmanızı sağlar ve her cihazı basit MQTT topic'leri olarak sunar. Bu rehberde bir koordinatör seçecek, Zigbee2MQTT'yi Docker'da çalıştıracak, onu bir broker'a bağlayacak, cihazları eşleştirip yeniden adlandıracak, komut satırından kontrol edecek ve durumlarını bir panoda izleyeceksiniz. Her şey önce benzersiz bir temel topic ile ücretsiz herkese açık test broker'ına karşı test edilir.

Zigbee2MQTT'nin Parçaları Nasıl Bir Araya Gelir?

Zigbee2MQTT bir köprüdür. Bir tarafta Zigbee ağınızı (mesh) oluşturan bir Zigbee koordinatörünü (bir USB çubuk veya ağ adaptörü) sürer. Diğer tarafta her cihazın durumunu JSON olarak yayınlayan ve komutları dinleyen bir MQTT client'tır. Home Assistant, Node-RED, bir Python betiği veya bir telefon uygulaması gibi MQTT konuşan her şey bu cihazları kullanabilir.

[Zigbee devices] ~~radio~~ [Coordinator] --USB/TCP-- [Zigbee2MQTT] --MQTT-- [Broker] -- [Dashboards, automations]

Broker ortada durur ve her tüketicinin bağlandığı tek şeydir. Bir MQTT broker'ın ne yaptığına dair bilginizi tazelemek isterseniz başlamadan önce hızlıca okumaya değer.

Koordinatör Seçimi

Koordinatör, hangi adapter ayarını kullanacağınızı belirler. Popüler ve iyi desteklenen seçenekler:

İki pratik ipucu büyük fark yaratır. Çubuğu, girişimi Zigbee menzilini ciddi biçimde düşürebilen USB 3 portlarından ve SSD'lerden uzaklaştırmak için yaklaşık yarım metrelik bir USB uzatma kablosu kullanın. Ayrıca erkenden birkaç şebekeden beslenen router (akıllı priz veya ampul) ekleyin; çünkü pilli cihazlar yönlendirme yapmaz ve yalnızca uç cihazlardan oluşan bir mesh kırılgandır.

Zigbee2MQTT'yi Docker ile Kurma

Adaptörünüzün yeniden başlatmalar arasında değişmeyen kalıcı yolunu bulun:

ls -l /dev/serial/by-id/

İçinde bir docker-compose.yml bulunan bir klasör oluşturun:

services:
  zigbee2mqtt:
    container_name: zigbee2mqtt
    image: ghcr.io/koenkk/zigbee2mqtt:latest
    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_XXXX-if00-port0:/dev/ttyACM0

Cihaz yolunu sisteminizdekiyle değiştirin ve saat diliminizi ayarlayın. Uzun süre çalışacak bir kurulumda, güncellemelerin sizin seçtiğiniz zaman yapılması için imajı latest yerine belirli bir sürüm etiketine sabitleyin.

Zigbee2MQTT Kurulum Yapılandırması

İlk başlatmadan önce data/configuration.yaml dosyasını oluşturun. Herkese açık test broker'ı paylaşımlı ve herkes tarafından okunabilir olduğu için temel topic'te rastgele bir bölüm seçin:

homeassistant:
  enabled: false
frontend:
  enabled: true
  port: 8080
mqtt:
  base_topic: connectmq/demo/z7q4/z2m
  server: mqtt://broker.connectmq.com:1883
  client_id: z2m-z7q4-bridge
serial:
  port: /dev/ttyACM0
  adapter: zstack
availability:
  enabled: true
advanced:
  log_level: info
  channel: 25
  network_key: GENERATE
  pan_id: GENERATE
  ext_pan_id: GENERATE

Önemli noktalar:

• base_topic, Zigbee2MQTT'nin yayınladığı her şeyin önekidir. Burada dört seviyesi vardır ve herkese açık broker'ın 8 topic seviyesi sınırı içinde yer bırakır.
• client_id broker'da benzersiz ve boş olmayan bir değer olmalıdır.
• channel her cihazı yeniden eşleştirmeden sonradan değiştirilemez. 15, 20 ve 25 numaralı kanallar en yaygın Wi-Fi çakışmasından kaçınır; çevrenizde hangi Wi-Fi kanallarının yoğun olduğunu kontrol edin.
• GENERATE, Zigbee2MQTT'nin ilk başlatmada rastgele bir ağ anahtarı ve ID'ler oluşturmasını ve bunları dosyaya geri yazmasını sağlar. Ardından veri klasöründeki configuration.yaml ve coordinator_backup.json dosyalarını yedekleyin.
• availability, her cihaz için {"state":"online"} veya offline yayınlar; bu, panolarda çok kullanışlıdır.

Başlatın ve günlüğü izleyin:

docker compose up -d
docker compose logs -f zigbee2mqtt

Koordinatör firmware sürümünü, ardından MQTT broker bağlantısını doğrulayan bir satırı görmelisiniz. Yapılandırma dosyası olmadan başlatırsanız yeni sürümler, aynı değerleri bir forma girebileceğiniz 8080 portunda bir ilk kurulum sayfası açar.

Cihazları Eşleştirme ve Adlandırma

Ön yüzü http://<host>:8080 adresinde açın ve Permit join (All) düğmesine tıklayın ya da MQTT üzerinden 254 saniyeye kadar katılıma izin verin:

mosquitto_pub -h broker.connectmq.com -p 1883 -i z2m-cli-z7q4 \
  -t "connectmq/demo/z7q4/z2m/bridge/request/permit_join" -m '{"time": 254}'

Cihazı eşleştirme moduna alın (genellikle düğmesine uzun basarak veya ampullerde bir açıp kapama dizisiyle). Cihaz 0x00158d0001abcd12 gibi bir IEEE adresiyle görünür. Adı topic'i haline geleceği için onu hemen anlamlı bir adla yeniden adlandırın:

mosquitto_pub -h broker.connectmq.com -p 1883 -i z2m-cli-z7q4 \
  -t "connectmq/demo/z7q4/z2m/bridge/request/device/rename" \
  -m '{"from": "0x00158d0001abcd12", "to": "living_room_lamp"}'

İşiniz bittiğinde katılımı {"time": 0} ile kapatın. Ağı açık bırakmak, komşuların cihazlarının yanlışlıkla katılmasına davetiye çıkarır.

Herkese açık broker'da test ederken kolay adlarda (friendly name) eğik çizgi yerine alt çizgi kullanın. living_room/lamp gibi bir ada izin verilir ve daha güzel hiyerarşiler oluşturur, ancak her eğik çizgi bir topic seviyesi ekler ve bu temel topic ile bridge/request/device/rename zaten 8 seviyenin tamamını kullanır.

Cihazları MQTT Üzerinden Okuma ve Kontrol Etme

Temel topic altındaki her şeye abone olun:

mosquitto_sub -h broker.connectmq.com -p 1883 -i z2m-watch-z7q4 -t "connectmq/demo/z7q4/z2m/#" -v

Bir sıcaklık sensörü connectmq/demo/z7q4/z2m/hallway_sensor üzerinde yayın yapar:

{"battery": 97, "humidity": 48.2, "linkquality": 116, "temperature": 21.4, "voltage": 2995}

Bir ampulü set topic'ine yayın yaparak kontrol edin:

mosquitto_pub -h broker.connectmq.com -p 1883 -i z2m-cli-z7q4 \
  -t "connectmq/demo/z7q4/z2m/living_room_lamp/set" \
  -m '{"state": "ON", "brightness": 180, "color_temp": 370, "transition": 2}'

Bir cihazdan güncel durumunu istemek için get topic'ine {"state": ""} yayınlayın. Cihaz topic'leri tam durumu taşır; bu nedenle bir pano cihaz başına yalnızca bir aboneliğe ihtiyaç duyar.

MQTT'den Panoya

Zigbee2MQTT düz MQTT konuştuğu için birkaç pano seçeneğiniz vardır:

1. Yönetim için Zigbee2MQTT ön yüzü: cihaz listesi, ağ haritası, OTA güncellemeleri ve günlükler.
2. MQTT entegrasyonu üzerinden Home Assistant. homeassistant.enabled: true ayarlayın; Zigbee2MQTT discovery mesajları yayınlar ve varlıklar otomatik olarak görünür. O taraf Home Assistant MQTT rehberinde ele alınmıştır.
3. Cihaz topic'lerine bir mqtt in düğümü ve bir JSON düğümüyle abone olan Node-RED Dashboard.
4. wss://broker.connectmq.com:8084/mqtt adresine bağlanan, WebSocket üzerinden MQTT kullanan bir tarayıcı panosu.

Hiçbir şey kurmadan hızlı kontroller için ConnectMQ portalının canlı topic gezgini, her Zigbee2MQTT topic'ini güncellendiği anda gösterir; bu, eşleştirme ve yeniden adlandırma sırasında kullanışlıdır.

Zigbee2MQTT Kurulumunda Sorun Giderme

Herkese açık test broker'ı ayrıca her client'ı saniyede 10 mesajla sınırlar; küçük bir test ağı bunun çok altında kalır, ancak büyük bir ağ başlangıçta bu sınırı aşabilir. Bu, herkese açık alanın yalnızca denemeler için olmasının bir nedeni daha; ücretsiz herkese açık MQTT broker makalesi tüm sınırlarını listeler.

Özel Bir Broker'a Geçiş

Zigbee2MQTT kilitleri, ışıkları ve alarmları kontrol eder; bu yüzden üretim ortamı kimlik bilgileri ve TLS gerektirir. ConnectMQ gibi yönetilen bir MQTT broker ile portalda bir broker oluşturur, üretilen kullanıcı adını, parolayı ve client ID'yi kopyalar ve yalnızca mqtt bloğunu değiştirirsiniz:

mqtt:
  base_topic: zigbee2mqtt
  server: mqtts://broker.connectmq.com:8883
  user: YOUR_USERNAME
  password: YOUR_PASSWORD
  client_id: YOUR_CLIENT_ID
  version: 5

Let's Encrypt sertifikası konteynerdeki sistem CA paketiyle doğrulanır; bu yüzden ek sertifika dosyalarına gerek yoktur. Ücretsiz Serverless planı 256 KB'a kadar mesajlara izin verir, bu da tipik köprü payload'ları için yeterlidir; ücretli planlar bu sınırı 1 MB'a çıkarır. Bulut broker ile Zigbee2MQTT rehberi uzaktan erişim ve çok sahalı kurulumları daha derinlemesine ele alır; IoT otomasyon rehberi ise Zigbee'nin daha büyük bir ev veya bina sisteminde nereye oturduğunu gösterir.

Zigbee2MQTT'yi ConnectMQ Üzerinde Çalıştırın

ConnectMQ, Zigbee2MQTT köprünüze TLS'li özel bir MQTT broker, tarayıcı panoları için Secure WebSocket ve her cihaz topic'ini canlı izleyebileceğiniz bir portal sunar. app.connectmq.com adresinde kredi kartı gerektirmeden ücretsiz bir Serverless broker oluşturun ve mqtt.server ayarınızı ona yönlendirin.

Sık Sorulan Sorular

Yeni bir Zigbee2MQTT kurulumu için en iyi koordinatör hangisi?

zstack adaptörlü Texas Instruments CC2652P tabanlı bir çubuk veya ember adaptörlü Silicon Labs EFR32MG21 çubuk, en yaygın ve iyi desteklenen seçeneklerdir. Sunucu cihazlardan uzaktaysa ağa bağlı adaptörler kullanışlıdır.

Zigbee kanalını sonradan değiştirebilir miyim?

Teknik olarak evet, ancak bu durumda cihazların çoğunun yeniden eşleştirilmesi gerekir. Herhangi bir şeyi eşleştirmeden önce kanalı dikkatle seçin.

Zigbee2MQTT için Home Assistant gerekli mi?

Hayır. Zigbee2MQTT yalnızca bir MQTT broker'a ihtiyaç duyar. Home Assistant; Node-RED, betikler ve panolarla birlikte pek çok isteğe bağlı tüketiciden yalnızca biridir.

Zigbee2MQTT'yi herkese açık bir broker'da çalıştırmak güvenli mi?

Yalnızca test için. Herkes set topic'leriniz dahil herkese açık topic'leri okuyabilir ve onlara yayın yapabilir; bu nedenle gerçek cihazlar için kimlik bilgileri ve TLS içeren özel bir broker kullanın.