ESPHome MQTT Yapılandırma Rehberi: Discovery, Birth/Will ve Harici Broker'lar

ESPHome, MQTT'yi tek bir YAML bloğuyla konuşur. Bir broker adresiyle mqtt: ekleyin; cihazdaki her sensör, switch ve ışık durumunu öngörülebilir topic'lere yayınlar ve komut kabul eder, tek satır C++ yazmadan. Home Assistant ile MQTT discovery üzerinden çalışır; Home Assistant olmadan da aynı şekilde çalışarak herhangi bir broker'dan Node-RED'i, Grafana'yı veya kendi backend'inizi besler.

Bu rehber harici bir broker'a karşı eksiksiz bir yapılandırmayı, ESPHome'un ürettiği topic düzenini, discovery'yi, birth ve will mesajlarını, TLS'i, özel abonelikleri ve her parçanın tarayıcıdan nasıl doğrulanacağını anlatıyor.

Çalışan minimal bir yapılandırma

esphome:
  name: livingroom

esp32:
  board: esp32dev
  framework:
    type: esp-idf

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

logger:

ota:
  - platform: esphome
    password: !secret ota_password

mqtt:
  broker: broker.connectmq.com
  port: 1883
  username: !secret mqtt_user
  password: !secret mqtt_password
  client_id: esphome-livingroom
  topic_prefix: testmqtt/esphome/livingroom
  discovery: false

sensor:
  - platform: wifi_signal
    name: "WiFi Signal"
    update_interval: 30s
  - platform: uptime
    name: "Uptime"

switch:
  - platform: gpio
    pin: GPIO2
    name: "Relay"
    id: relay

wifi_ssid: "your-ssid"
wifi_password: "your-wifi-password"
ota_password: "change-me"
mqtt_user: "username"
mqtt_password: "password"

esphome run livingroom.yaml ile yükleyin. Log'da Connecting to MQTT... ve ardından MQTT Connected! görmelisiniz.

Varsayılanlara güvenmek yerine açıkça ayarlamaya değer üç ayar var:

• topic_prefix varsayılan olarak node adıdır (livingroom). Paylaşımlı bir broker'da bu, herkesin oturma odasıyla çakışır. testmqtt/esphome/livingroom gibi benzersiz bir önek topic'lerinizi size ait tutar.
• client_id her cihaz için benzersiz olmalıdır. Aynı ID'ye sahip iki cihaz döngü hâlinde birbirinin bağlantısını keser. Belirtmezseniz ESPHome addan ve MAC'ten bir ID üretir, bu gayet iyidir; yalnızca sabit bir ID'yi YAML dosyaları arasında asla kopyalamayın.
• discovery: false: herkese açık veya paylaşımlı bir broker'da test ederken, başkalarının okuduğu bir isim alanına Home Assistant yapılandırma mesajları yayınlamamak için. Kendi broker'ınızı kullandığınızda açın.

ESPHome'un ürettiği topic'ler

Her entity bir state topic'i, kontrol edilebilen entity'ler ayrıca bir command topic'i alır. Object ID, entity adının küçük harfli ve boşlukları alt çizgiyle değiştirilmiş hâlidir:

Mevcut bir topic tasarımına uymanız gerektiğinde bunların her birini entity bazında state_topic: ve command_topic: ile değiştirebilirsiniz. log_topic: seçeneği debug topic'ini kontrol eder; log'ları MQTT üzerinden yayınlamayı durdurmak için null yapın, yoğun cihazlarda bant genişliği kazandırır.

Birth, will ve shutdown mesajları

ESPHome bağlandıktan sonra bir birth mesajı gönderir ve broker'a bir Last Will kaydeder. Varsayılan olarak ikisi de <topic_prefix>/status topic'ine, retained olarak, online ve offline payload'larıyla gider. Home Assistant entity erişilebilirliği için tam olarak bunu kullanır. Bunları özelleştirebilirsiniz:

mqtt:
  # ...
  birth_message:
    topic: testmqtt/esphome/livingroom/availability
    payload: "connected"
    retain: true
  will_message:
    topic: testmqtt/esphome/livingroom/availability
    payload: "lost"
    retain: true
  shutdown_message:
    topic: testmqtt/esphome/livingroom/availability
    payload: "shutdown"
    retain: true
  keepalive: 30s

Will'i cihaz değil broker yayınlar; cihaz sustuktan yaklaşık 1,5 × keepalive sonra. Shutdown mesajını ise planlı bir yeniden başlatma veya OTA güncellemesinden önce cihazın kendisi gönderir; böylece "bilerek yeniden başlıyor" ile "elektrik kesildi" durumlarını ayırt edebilirsiniz. Zamanlama MQTT Last Will yazısında, retained bayrağı ise retained mesajlar yazısında anlatılıyor.

Home Assistant discovery

discovery: true (varsayılan) ile ESPHome her entity için <discovery_prefix>/<component>/<node>/<object_id>/config altında retained bir yapılandırma mesajı yayınlar. Home Assistant'ın MQTT entegrasyonu bu öneke subscribe olur ve entity'leri otomatik oluşturur.

mqtt:
  broker: broker.connectmq.com
  port: 1883
  username: !secret mqtt_user
  password: !secret mqtt_password
  discovery: true
  discovery_prefix: homeassistant
  discovery_retain: true

Bilmeniz gerekenler:

• Önek eşleşmelidir. MQTT entegrasyonu seçeneklerinde değiştirmediyseniz Home Assistant homeassistant önekini dinler. Birini değiştirirseniz ikisini de değiştirin.
• Discovery mesajları retained'dır. Bir entity'yi yeniden adlandırır veya silerseniz eski yapılandırma broker'da kalır. Eski config topic'ine boş bir retained mesaj yayınlayarak temizleyin.
• İkisi için tek broker. Home Assistant, cihazla aynı broker'a bağlanmalıdır. Home Assistant tarafı için Home Assistant MQTT yazısını okuyun.

YAML'dan subscribe ve publish

ESPHome yalnızca kendi command topic'lerine değil, herhangi bir topic'e tepki verebilir ve istediğiniz mesajı yayınlayabilir:

mqtt:
  # ...
  on_message:
    - topic: testmqtt/esphome/livingroom/cmd/toggle
      qos: 1
      then:
        - switch.toggle: relay
  on_json_message:
    topic: testmqtt/esphome/livingroom/cmd/json
    then:
      - if:
          condition:
            lambda: 'return x["relay"] == "on";'
          then:
            - switch.turn_on: relay
          else:
            - switch.turn_off: relay

interval:
  - interval: 60s
    then:
      - mqtt.publish:
          topic: testmqtt/esphome/livingroom/heartbeat
          payload: "alive"
          qos: 0
          retain: false

on_json_message payload'u ArduinoJson ile ayrıştırır ve x olarak sunar. Payload'ları küçük tutun: çok büyük mesajlar, belleği kısıtlı kartlarda istemcinin buffer'ını aşabilir.

Harici bir broker ile TLS kullanma

ESP32'de broker'ın CA sertifikasını ekleyin ve 8883 portuna geçin:

mqtt:
  broker: broker.connectmq.com
  port: 8883
  username: !secret mqtt_user
  password: !secret mqtt_password
  certificate_authority: |
    -----BEGIN CERTIFICATE-----
    ... root CA of your broker's certificate chain ...
    -----END CERTIFICATE-----

Sunucu sertifikasının kendisini değil, broker'ın sunduğu zincirin kök CA'sını kullanın. ESP32'de TLS üzerinden MQTT için önerilen seçim ESP-IDF framework'üdür. ESP8266 desteği çok daha sınırlıdır (Arduino framework'ünde yalnızca fingerprint); bu yüzden TLS'in kritik olduğu cihazlarda ESP32 seçin ya da ESP8266 cihazlarını güvenilir bir yerel ağda tutun. ESP32 TLS rehberimiz doğru sertifikayı openssl s_client ile nasıl çıkaracağınızı anlatıyor.

Her parçayı tarayıcıdan test edin

1. Online MQTT istemcisini açın, 8084 portundan (path /mqtt) broker.connectmq.com adresine bağlanın ve testmqtt/esphome/livingroom/# topic'ine subscribe olun.
2. status = online (retained) ve her 30 saniyede bir wifi_signal ile uptime durumlarını görmelisiniz.
3. testmqtt/esphome/livingroom/switch/relay/command topic'ine ON yayınlayın. Röle konum değiştirir ve switch/relay/state ON bildirir.
4. on_message'ı denemek için testmqtt/esphome/livingroom/cmd/toggle topic'ine herhangi bir şey yayınlayın.
5. Kartın gücünü kesin. Yaklaşık 1,5 × keepalive sonra will, status değerini offline yapar. Bunun yerine dashboard'dan yeniden başlatırsanız önce shutdown mesajını görürsünüz.

ESPHome node'unuzu online istemcide izleyin

Bir entity beklenen topic'te görünmüyorsa, önekteki bir yazım hatasını bulmak için topic'i ve filtrenizi topic matcher aracına yapıştırın.

Sorun giderme hızlı başvuru

Adım adım teşhis için ESPHome MQTT bağlanmıyor yazısını okuyun.

ESPHome'u MQTT için yapılandırmak büyük ölçüde bir adlandırma meselesidir: benzersiz bir topic öneki ve client ID, yalnızca Home Assistant'ın bulunduğu yerde açık discovery ve güvenebileceğiniz erişilebilirlik topic'leri. Bunları doğru yapın, durumu, komutları ve will'i online istemciden doğrulayın; aynı YAML yalnızca bir hostname ve bir secret değiştirerek test broker'ınızdan production'a geçer.

Sıkça sorulan sorular