Home Assistant MQTT Entegrasyonu: Eksiksiz Kurulum Rehberi

Home Assistant'ın MQTT desteği, MQTT konuşan her cihazı akıllı evinize dahil etmenizi sağlar: kendi yaptığınız ESP32 sensörleri, Tasmota prizleri, Zigbee2MQTT ağları ve endüstriyel ağ geçitleri dahil. Bu rehberde Home Assistant MQTT entegrasyonunu yapılandıracak, YAML ile sensörler ve anahtarlar oluşturacak, her şeyi broker.connectmq.com adresindeki herkese açık broker üzerinde test edecek ve ardından TLS'li özel bir ConnectMQ broker'ına geçeceksiniz.

Home Assistant MQTT'yi Nasıl Kullanır?

Home Assistant bir MQTT broker değildir. MQTT entegrasyonu, bir broker'a bağlanan, durum topic'lerine abone olan ve komut topic'lerine yayın yapan bir client'tır. Cihazlar da aynı broker'ın client'larıdır. Broker ortada durur ve mesajları yönlendirir; bu konu bir MQTT broker'ın ne yaptığı yazısında ayrıntılı olarak anlatılmıştır.

Bu da size iki barındırma seçeneği sunar:

Bu eğitim bulut broker kullanır, çünkü Home Assistant ister bir Raspberry Pi'da, ister bir NUC'ta, ister sanal makinede çalışsın aynı şekilde işler. Ayrıntılı gerekçeyi ve köprülü seçeneği görmek isterseniz Home Assistant ile harici bir MQTT broker kullanmak yazısını okuyun.

Adım 1: MQTT Entegrasyonunu Ekleyin

1. Ayarlar > Cihazlar ve hizmetler (Settings > Devices & services) bölümünü açın.
2. Entegrasyon ekle (Add integration) düğmesine tıklayın ve MQTT arayın.
3. MQTT'yi seçin (eklentiyi değil) ve broker bilgilerini girin:
   • Broker: broker.connectmq.com
   • Port: 1883
   • Kullanıcı adı ve parola: herkese açık test broker'ı için boş bırakın
4. Gönderin. Home Assistant bağlanır ve MQTT entegrasyon kaydını oluşturur.

Client ID, TLS veya protokol sürümünü ayarlamak için önce kullanıcı profilinizde Gelişmiş mod'u (Advanced mode) etkinleştirin. Entegrasyonun yapılandırma penceresi bu durumda client ID, keep alive, broker sertifika doğrulaması, aktarım (TCP veya WebSocket) ve MQTT protokol sürümü gibi ek alanlar gösterir. Bunlara Adım 6'da ihtiyacınız olacak.

Herkese açık broker boş olmayan bir client ID gerektirir. Alan boş bırakıldığında Home Assistant otomatik olarak rastgele bir ID üretir; bu, test için yeterlidir.

Adım 2: Bağlantıyı Kontrol Edin

Ayarlar > Cihazlar ve hizmetler > MQTT > Yapılandır (Configure) sayfasını açın. Bu sayfada bir Paket yayınla (Publish a packet) formu ve bir Topic'i dinle (Listen to a topic) formu bulunur.

Topic'i dinle alanına connectmq/demo/ha-x7m2/# girin ve Dinlemeye başla'ya tıklayın. Ardından herhangi bir bilgisayardan bir test mesajı yayınlayın:

mosquitto_pub -h broker.connectmq.com -p 1883 -i ha-test-x7m2 \
  -t "connectmq/demo/ha-x7m2/test" -m "hello from the terminal"

Mesaj bir saniye içinde Home Assistant'ta görünür. Görünmezse Home Assistant sunucusunun dışarıya doğru 1883 portuna erişebildiğini kontrol edin; bazı ağlar bu portu engeller, bu durumda TLS ile 8883 kullanın.

Adım 3: YAML ile Bir MQTT Sensörü Oluşturun

Bir ESP32'nin sıcaklık ve nemi JSON olarak connectmq/demo/ha-x7m2/livingroom/climate topic'ine yayınladığını varsayalım:

{"temperature": 22.7, "humidity": 48.1, "battery": 87}

Bunu configuration.yaml dosyasına (veya ondan dahil edilen bir dosyaya) ekleyin:

mqtt:
  sensor:
    - name: "Living Room Temperature"
      unique_id: livingroom_temperature_x7m2
      state_topic: "connectmq/demo/ha-x7m2/livingroom/climate"
      value_template: "{{ value_json.temperature }}"
      unit_of_measurement: "°C"
      device_class: temperature
      state_class: measurement
      expire_after: 600

    - name: "Living Room Humidity"
      unique_id: livingroom_humidity_x7m2
      state_topic: "connectmq/demo/ha-x7m2/livingroom/climate"
      value_template: "{{ value_json.humidity }}"
      unit_of_measurement: "%"
      device_class: humidity
      state_class: measurement
      expire_after: 600

unique_id, varlığı arayüzden yeniden adlandırmanıza ve bir alana atamanıza olanak tanır. expire_after, on dakika boyunca mesaj gelmezse sensörü kullanılamaz olarak işaretler; biten bir pili bu şekilde fark edersiniz. state_class: measurement ise uzun vadeli istatistiklerin çalışmasını sağlar.

Geliştirici araçları > YAML > Elle yapılandırılmış MQTT varlıkları ile yeniden yükleyin, ardından cihazı simüle edin:

mosquitto_pub -h broker.connectmq.com -p 1883 -i ha-test-x7m2 \
  -t "connectmq/demo/ha-x7m2/livingroom/climate" \
  -m '{"temperature": 22.7, "humidity": 48.1, "battery": 87}'

Adım 4: Bir MQTT Anahtarı Oluşturun

Bir anahtar, Home Assistant'ın yayın yaptığı bir komut topic'ine ve cihazın durumunu bildirdiği bir durum topic'ine ihtiyaç duyar:

mqtt:
  switch:
    - name: "Desk Lamp"
      unique_id: desk_lamp_x7m2
      command_topic: "connectmq/demo/ha-x7m2/desk-lamp/set"
      state_topic: "connectmq/demo/ha-x7m2/desk-lamp/state"
      availability_topic: "connectmq/demo/ha-x7m2/desk-lamp/availability"
      payload_on: "ON"
      payload_off: "OFF"
      state_on: "ON"
      state_off: "OFF"
      qos: 1
      retain: false

Sensörleri ve anahtarları yapılandırmanızda aynı tek mqtt: anahtarı altına yerleştirin; YAML aynı anahtarın iki kez kullanılmasına izin vermez. Henüz donanımınız yoksa cihazı kendiniz canlandırın:

# cihaz gibi davran: erişilebilirliği duyur ve durumu bildir
mosquitto_pub -h broker.connectmq.com -p 1883 -i ha-dev-x7m2 -r \
  -t "connectmq/demo/ha-x7m2/desk-lamp/availability" -m "online"
mosquitto_pub -h broker.connectmq.com -p 1883 -i ha-dev-x7m2 -r \
  -t "connectmq/demo/ha-x7m2/desk-lamp/state" -m "OFF"

# anahtarı çevirdiğinizde Home Assistant'ın gönderdiği komutları izle
mosquitto_sub -h broker.connectmq.com -p 1883 -i ha-dev2-x7m2 \
  -t "connectmq/demo/ha-x7m2/desk-lamp/set" -v

Panodaki anahtarı değiştirdiğinizde terminalde ON görünür. Onaylamak için durum topic'ine ON yayınlayın; anahtar açık kalır. Durum topic'i olmadan Home Assistant anahtarı iyimser (optimistic) modda çalıştırır ve komutun başarılı olduğunu varsayar.

Parlaklık ayarlı ışıklar için schema: json ile light platformunu kullanın; payload biçimi MQTT ile akıllı aydınlatma eğitimimizdeki dimmer ile örtüşür.

Adım 5: Gerçek Bir Cihaz

En hızlı gerçek cihaz, ESP32 MQTT eğitimindeki gibi kısa bir sketch çalıştıran ve aynı climate topic'ine yayın yapan bir ESP32'dir. ESPHome ve Tasmota cihazları da MQTT üzerinden yayın yapabilir; bkz. ESPHome MQTT. Bu cihazlar, her varlık için YAML yazmak yerine kendilerini Home Assistant MQTT discovery aracılığıyla otomatik olarak duyurabilir.

Adım 6: TLS'li Özel Bir Broker'a Geçin

Ücretsiz herkese açık MQTT broker ilk saat için mükemmeldir, ancak üzerindeki her şeyi herkes okuyabilir ve herkes anahtarınızın komut topic'ine yayın yapabilir. Ev verileriniz özel bir broker'da olmalıdır. Pratik bir neden de var: herkese açık broker client başına 10 aboneliğe izin verir; Home Assistant ise varlık başına bir topic'e ve ek olarak discovery topic'lerine abone olduğu için bu sınıra hızla ulaşırsınız.

1. ConnectMQ portalında kaydolun, bir broker oluşturun ve üretilen kullanıcı adını, parolayı ve client ID'yi kopyalayın.
2. Home Assistant'ta Ayarlar > Cihazlar ve hizmetler > MQTT bölümünü açın, kaydın menüsünü açın ve Yeniden yapılandır'ı (Reconfigure) seçin (sürümünüze bağlı olarak Yapılandır ve ardından MQTT'yi yeniden yapılandır).
3. Portu 8883 yapın, kullanıcı adı ve parolayı girin, client ID'yi verilen değere ayarlayın ve sistem CA deposunun Let's Encrypt sertifikasını doğrulaması için broker sertifika doğrulamasını Otomatik (Auto) olarak ayarlayın.
4. Topic'lerinizi hem cihazlarda hem de YAML'da connectmq/demo/ha-x7m2/... yerine kendi kök yapınıza, örneğin home/livingroom/climate olarak değiştirin.

Client ID, verilenle tam olarak eşleşmelidir, çünkü ConnectMQ client ID'leri kimlik bilgilerine bağlar. Bir uyuşmazlık, Home Assistant günlüğünde tekrarlanan "connection refused, not authorized" satırları olarak görünür.

Sorun Giderme Kontrol Listesi

1. Entegrasyon bağlanmıyor. Aynı sunucu, port ve kimlik bilgilerini başka bir makineden mosquitto_sub ile test edin.
2. Varlık bilinmiyor (unknown) gösteriyor. Cihaz, Home Assistant başladığından beri yayın yapmamıştır. Durumu retain bayrağıyla yayınlayın.
3. Varlık kullanılamıyor (unavailable) gösteriyor. Ya expire_after süresi dolmuştur ya da erişilebilirlik topic'i offline diyordur.
4. Günlükte şablon hataları. Payload beklediğiniz JSON değildir; topic'i dinleyin ve karşılaştırın.
5. İki broker tek bir cihaz için çekişiyor. Bir cihaz aynı anda yalnızca bir broker'a bağlanabilir; birini seçin veya ikisini köprüleyin.
6. Birkaç saniyede bir bağlantı kopuyor. İki client aynı client ID'yi kullanıyor ve birbirini düşürüyordur.

Home Assistant'ı ConnectMQ Üzerinde Çalıştırın

app.connectmq.com adresinde kredi kartı gerektirmeden ücretsiz bir Serverless broker oluşturun. 25 bağlantıya kadar kapasite tipik bir evi karşılar ve ConnectMQ'daki canlı topic gezgini, tarayıcıdan çıkmadan payload'larda hata ayıklamanıza yardımcı olur. Barındırılan bir MQTT broker'ın Mosquitto'yu kendiniz çalıştırmakla nasıl karşılaştırıldığını merak ediyorsanız yukarıdaki karşılaştırma ve IoT otomasyon rehberi karar vermenize yardımcı olacaktır.

Sık Sorulan Sorular

Home Assistant bir MQTT broker içerir mi?

Hayır. MQTT entegrasyonu bir client'tır. Ya Mosquitto eklentisini kurarsınız ya da ConnectMQ gibi harici bir broker'a bağlanırsınız.

YAML ve discovery'yi birlikte kullanabilir miyim?

Evet. Unique ID'leri farklı olduğu sürece YAML ile tanımlanan varlıklar ve keşfedilen varlıklar aynı entegrasyonda bir arada bulunabilir.

Home Assistant bir bulut broker için hangi portu kullanmalı?

TLS ile 8883 kullanın. Port 1883 kimlik bilgilerini ve verileri şifrelemeden gönderir ve yalnızca herkese açık test verileri için kullanılmalıdır.

Anahtarım neden kendiliğinden kapanıyor?

Cihaz durum topic'ine OFF yayınlıyordur ya da retained bir OFF mesajı yeniden oynatılıyordur. Durum topic'ini bir aboneyle kontrol edin ve eskimiş retained mesajları temizleyin.