Home Assistant MQTT Kurulumu: Broker, Entegrasyon ve Discovery

MQTT, Home Assistant’ın çok geniş bir cihaz yelpazesiyle konuşma yoludur: Zigbee2MQTT, Tasmota, ESPHome (isteğe bağlı olarak), Shelly, Frigate, OpenMQTTGateway ve sayısız DIY sensör. Kurulum üç parçadan oluşur — bir broker, Home Assistant’taki MQTT entegrasyonu ve ideal olarak cihazların otomatik olarak görünmesini sağlayan MQTT discovery. Bu eğitim üçünü de ele alıyor ve kurulumu bir MQTT client ile nasıl test edeceğinizi gösteriyor.

Adım 1: Broker seçin — Mosquitto eklentisi mi, harici broker mı

Home Assistant’ın kendi içinde bir MQTT broker’ı yoktur; entegrasyon bir client’tır. İki ana seçeneğiniz var:

Seçenek A: Mosquitto broker eklentisi

1. Ayarlar → Eklentiler → Eklenti Mağazası’na gidin, Mosquitto broker’ı arayın ve kurun.
2. Eklentiyi başlatın ve Önyüklemede başlat ile Watchdog seçeneklerini etkinleştirin.
3. Cihazlarınız için ayrı bir Home Assistant kullanıcısı oluşturun (Ayarlar → Kişiler → Kullanıcılar, ör. mqtt-user). Eklenti, kimlik doğrulamayı Home Assistant kullanıcılarına karşı yapar; bu yüzden cihazlar bu kimlik bilgilerini kullanır. Admin hesabınızı tekrar kullanmayın.
4. Home Assistant artık Ayarlar → Cihazlar ve hizmetler altında keşfedilmiş bir MQTT entegrasyonu gösterir. Yapılandır’a tıklayın ve onaylayın.

Ağınızdaki cihazlar, Home Assistant host’unuza 1883 portundan (eklenti seçeneklerinde TLS’i yapılandırırsanız 8883 portundan da) bağlanır.

Seçenek B: harici bir broker

Home Assistant Container veya Core’da eklenti mağazası yoktur; bu yüzden Mosquitto’yu onun yanında çalıştırırsınız — en kolay yol Docker’da Mosquitto’dur ya da Mosquitto nasıl kurulur yazısında anlatıldığı gibi paket kurulumudur. Mosquitto 2.x’in, diğer host’lar bağlanabilmeden önce açıkça tanımlanmış bir listener’a ve kimlik doğrulamaya ihtiyaç duyduğunu unutmayın; mosquitto.conf oluşturucu çalışan bir dosya üretir, Mosquitto’yu güvenli hâle getirme yazısı da kullanıcıları ve ACL’leri ele alır.

Adım 2: MQTT entegrasyonunu yapılandırın

Harici bir broker için entegrasyonu elle ekleyin: Ayarlar → Cihazlar ve hizmetler → Entegrasyon ekle → MQTT. Şunları girin:

• Broker — hostname veya IP (paylaşılan bir Docker ağında mosquitto gibi container adı)
• Port — 1883 veya TLS için 8883 (bkz. MQTT portları)
• Kullanıcı adı / Parola — Home Assistant için oluşturulmuş bir broker kullanıcısı

Gelişmiş seçenekler (kullanıcı profilinizde Gelişmiş mod’u etkinleştirip ardından Yapılandır → MQTT’yi yeniden yapılandır ile açılır) TLS sertifikalarını, client ID’yi, protokol sürümünü (3.1, 3.1.1 veya 5), discovery prefix’ini ve birth ile will mesajlarını ayarlamanızı sağlar. Broker bağlantı ayrıntıları arayüzden yapılandırılır; artık configuration.yaml içinde ayarlanamazlar.

Adım 3: MQTT discovery

Discovery ile bir cihaz, iyi bilinen bir topic’e JSON bir config publish ederek kendini duyurur ve Home Assistant entity’yi otomatik olarak oluşturur — YAML gerekmez. Topic formatı şöyledir:

<discovery_prefix>/<component>/[<node_id>/]<object_id>/config

• discovery_prefix — varsayılan olarak homeassistant
• component — entity türü: sensor, binary_sensor, switch, light, cover, climate vb.
• node_id — isteğe bağlı gruplama, genellikle cihaz ID’si
• object_id — bu entity için bir ID (harfler, rakamlar, _ ve -)

İşte bir sıcaklık sensörü. Home Assistant’ın yeniden başlatmadan sonra onu tekrar bulabilmesi için bunu homeassistant/sensor/garage_temp/config topic’ine retain flag’i ile publish edin:

{
  "name": "Garage temperature",
  "unique_id": "garage_env_temp",
  "state_topic": "garage/env/state",
  "value_template": "{{ value_json.temperature }}",
  "unit_of_measurement": "°C",
  "device_class": "temperature",
  "state_class": "measurement",
  "device": {
    "identifiers": ["garage_env_01"],
    "name": "Garage environment sensor",
    "manufacturer": "DIY",
    "model": "ESP32 + BME280"
  }
}

unique_id, entity’yi arayüzden düzenlenebilir yapar; device bloğu ise entity’leri tek bir cihaz altında gruplar. Cihaz daha sonra ölçümlerini state topic’ine publish eder:

{ "temperature": 21.4, "humidity": 48 }

Burada retained mesajlar şarttır — kavram size yeniyse MQTT retained mesajlar yazısını okuyun. Switch’ler ve lamba (light) entity’leri ek olarak, entity’yi açıp kapattığınızda Home Assistant’ın publish ettiği bir command_topic kullanır.

Adım 4: Bir MQTT client ile test edin

Cihazın tamamını bir terminalden Mosquitto client’larıyla simüle edebilirsiniz (flag’lerin tam listesi mosquitto_pub/sub kopya kâğıdında):

BROKER=homeassistant.local
AUTH="-u mqtt-user -P your-password"

mosquitto_pub -h $BROKER $AUTH -r -t 'homeassistant/sensor/garage_temp/config' -m '{
  "name": "Garage temperature",
  "unique_id": "garage_env_temp",
  "state_topic": "garage/env/state",
  "value_template": "{{ value_json.temperature }}",
  "unit_of_measurement": "°C",
  "device_class": "temperature",
  "device": { "identifiers": ["garage_env_01"], "name": "Garage environment sensor" }
}'

mosquitto_pub -h $BROKER $AUTH -t 'garage/env/state' -m '{"temperature": 21.4, "humidity": 48}'

Entity, Ayarlar → Cihazlar ve hizmetler → MQTT altında görünür. Home Assistant’ın ve cihazlarınızın birbirleriyle paylaştığı her şeyi izlemek için discovery prefix’ine abone olun:

mosquitto_sub -h homeassistant.local -u mqtt-user -P your-password -t 'homeassistant/#' -v

Home Assistant’taki MQTT entegrasyon sayfasında ayrıca yerleşik Bir topic’i dinle ve Bir paket yayınla araçları da bulunur. Discovery formatını ev broker’ınıza dokunmadan denemek için yukarıdaki JSON’u tarayıcıda, herkese açık bir broker üzerindeki bir test topic’ine publish edin:

Online MQTT istemcisinde deneyin

Sık karşılaşılan sorunlar

• Entegrasyon bağlanamıyor — kimlik bilgileri yanlış ya da broker yalnızca localhost’u dinliyor. Broker log’unu ve MQTT bağlantı hataları rehberini kontrol edin.
• Yeniden başlatmadan sonra entity kayboluyor — config retained değildi ya da cihaz homeassistant/status = online geldiğinde yeniden publish etmiyor.
• Entity "unknown" gösteriyor — value_template payload ile eşleşmiyor ya da state topic’ine henüz hiçbir şey publish edilmedi.
• Bir entity’yi kaldırmak — config topic’ine boş bir retained mesaj publish edin (-r -n).

Sıkça sorulan sorular