ESPHome MQTT: MQTT statt der nativen API verwenden

Dank der MQTT-Unterstützung von ESPHome kann ein per YAML konfigurierter ESP32 oder ESP8266 seine Sensorzustände über jeden Standard-Broker veröffentlichen und Befehle empfangen, statt die native API von Home Assistant zu nutzen. In diesem Tutorial konfigurieren Sie die Komponente mqtt:, verstehen die von ESPHome erzeugten Topics, ergänzen TLS und Zugangsdaten für den Produktivbetrieb und reagieren direkt auf dem Gerät auf eingehende Nachrichten.

Native API oder MQTT: Wann sich der Wechsel lohnt

Die native API von ESPHome ist eine effiziente, verschlüsselte Punkt-zu-Punkt-Verbindung zwischen einem Gerät und Home Assistant. Sie ist hervorragend, solange Home Assistant das Einzige ist, das jemals mit dem Gerät spricht. Einschränkend wird sie, sobald andere Software dieselben Daten braucht: ein Node-RED-Flow, ein Python-Logger, eine Grafana-Pipeline über Telegraf oder ein zweiter Standort, der Ihr LAN nicht erreicht.

MQTT löst das, indem ein Broker in die Mitte rückt. Das Gerät veröffentlicht einmal, und beliebig viele Subscriber erhalten den Messwert. Am Gerät ändert sich nichts, wenn Sie einen neuen Konsumenten hinzufügen, und Geräte hinter NAT erreichen trotzdem einen Broker im Internet. Wenn Ihnen das Publish/Subscribe-Modell neu ist, bietet der Überblick was ein MQTT-Broker macht einen guten Einstieg.

Sie können beides gleichzeitig betreiben; wenn aber nichts mehr die native API nutzt, entfernen Sie den Block api:, damit das Gerät keinen Speicher dafür verbraucht.

Eine minimale ESPHome-MQTT-Konfiguration

Das folgende Beispiel ist eine vollständige Konfiguration für einen ESP32 mit einem DHT22-Sensor und einem Relais. Es verbindet sich mit dem öffentlichen MQTT-Broker, der für Tests und Prototypen gedacht ist, sodass Sie innerhalb weniger Minuten Nachrichten sehen. Ersetzen Sie a7k2q9 durch eine eigene Zufallszeichenkette, damit Ihre Topics nicht mit denen anderer kollidieren.

esphome:
  name: greenhouse-node
  friendly_name: Greenhouse Node

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

logger:
  level: INFO

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

ota:
  - platform: esphome
    password: !secret ota_password

mqtt:
  broker: broker.connectmq.com
  port: 1883
  client_id: esphome-greenhouse-a7k2q9
  topic_prefix: connectmq/demo/a7k2q9/greenhouse
  discovery: false
  log_topic: null
  birth_message:
    topic: connectmq/demo/a7k2q9/greenhouse/status
    payload: online
    retain: true
  will_message:
    topic: connectmq/demo/a7k2q9/greenhouse/status
    payload: offline
    retain: true

sensor:
  - platform: dht
    pin: GPIO4
    model: DHT22
    update_interval: 30s
    temperature:
      name: "Air Temperature"
      id: air_temp
    humidity:
      name: "Air Humidity"
      id: air_hum

switch:
  - platform: gpio
    pin: GPIO26
    name: "Vent Fan"
    id: vent_fan

Flashen Sie es mit esphome run greenhouse-node.yaml. Sobald das Gerät online ist, abonnieren Sie von Ihrem Computer aus:

mosquitto_sub -h broker.connectmq.com -p 1883 -i sub-a7k2q9 \
  -t 'connectmq/demo/a7k2q9/greenhouse/#' -v

Sie sollten den retained Status online sehen und alle 30 Sekunden eine Zustandsnachricht für jeden Sensor.

Einstellungen, die Sie verstehen sollten

• client_id: darf nicht leer sein und muss auf dem Broker eindeutig sein. Teilen sich zwei Geräte eine ID, trennt der Broker die ältere Sitzung jedes Mal, wenn sich die neuere verbindet, und beide Geräte flattern.
• topic_prefix: standardmäßig der Knotenname. Explizit gesetzt erhalten Sie eine vorhersehbare Hierarchie und halten den öffentlichen MQTT-Broker aufgeräumt.
• discovery: auf false setzen, es sei denn, Home Assistant nutzt diesen Broker. Discovery veröffentlicht retained Konfigurationsnachrichten unter homeassistant/, die auf einem gemeinsam genutzten öffentlichen Broker für alle sichtbar wären.
• log_topic: ESPHome spiegelt seine Logs standardmäßig nach <prefix>/debug. Mit null verhindern Sie, dass ein gesprächiges Gerät Rate-Limits ausschöpft.

Die Topics, die ESPHome veröffentlicht

ESPHome bildet Topics aus dem Präfix, dem Komponententyp und einer aus dem Entitätsnamen abgeleiteten Object-ID (Kleinbuchstaben, Leerzeichen werden zu Unterstrichen).

Zustände sind einfache Strings: 23.4 für einen Sensor, ON oder OFF für einen Schalter. So schalten Sie den Lüfter über die Kommandozeile ein:

mosquitto_pub -h broker.connectmq.com -p 1883 -i pub-a7k2q9 \
  -t 'connectmq/demo/a7k2q9/greenhouse/switch/vent_fan/command' -m 'ON'

Das Gerät führt den Befehl aus und veröffentlicht anschließend den neuen Zustand auf dem zugehörigen state-Topic, sodass Dashboards immer zeigen, was tatsächlich passiert ist, und nicht, was angefordert wurde.

Wird ein anderes Topic-Layout benötigt, akzeptiert jede Komponente Überschreibungen für state_topic und command_topic. Das ist nützlich, wenn Sie bereits eine Struktur haben, wie sie im Leitfaden zur Smart-Home-MQTT-Topic-Struktur beschrieben ist. In der Industrie legen Sie state_topic auf einen Pfad im Unified Namespace (UNS), dessen Topic-Struktur der ISA-95-Hierarchie folgt, etwa acme/werk-graz/lackiererei/linie-1/zelle-2/temperatur, damit ESPHome-Knoten neben SPS- und OPC-UA-Daten im selben Baum landen.

sensor:
  - platform: dht
    pin: GPIO4
    model: DHT22
    temperature:
      name: "Air Temperature"
      state_topic: connectmq/demo/a7k2q9/site1/greenhouse/temperature

Auf dem Gerät auf MQTT-Nachrichten reagieren

Die MQTT-Komponente ist nicht nur ein Ausgang. Mit on_message oder on_json_message können Sie Automatisierungen von jedem Topic aus auslösen, und mit den Aktionen mqtt.publish und mqtt.publish_json beliebige Payloads veröffentlichen.

mqtt:
  # ... Verbindungseinstellungen von oben ...
  on_message:
    - topic: connectmq/demo/a7k2q9/greenhouse/mode
      payload: "night"
      then:
        - switch.turn_off: vent_fan
  on_json_message:
    topic: connectmq/demo/a7k2q9/greenhouse/setpoint
    then:
      - lambda: |-
          if (x.containsKey("max_temp")) {
            id(max_temp) = x["max_temp"];
          }

globals:
  - id: max_temp
    type: float
    restore_value: true
    initial_value: '28.0'

interval:
  - interval: 60s
    then:
      - if:
          condition:
            lambda: 'return id(air_temp).state > id(max_temp);'
          then:
            - switch.turn_on: vent_fan
            - mqtt.publish_json:
                topic: connectmq/demo/a7k2q9/greenhouse/event
                payload: |-
                  root["event"] = "overheat";
                  root["temp"] = id(air_temp).state;

So bleibt eine einfache Sicherheitsregel auf dem Gerät selbst, damit der Lüfter auch bei Netzwerkausfall läuft, während sich der Sollwert aus der Ferne durch Veröffentlichen von {"max_temp": 30} ändern lässt.

Produktiv-Setup: TLS und Zugangsdaten

Der öffentliche MQTT-Broker eignet sich für Experimente, doch jedes Topic dort ist für jeden lesbar. Für eine echte Installation legen Sie einen privaten Broker an und verwenden die generierten Zugangsdaten. Auf dem ESP32 mit dem ESP-IDF-Framework unterstützt ESPHome TLS, indem Sie das CA-Zertifikat angeben, das das Zertifikat des Brokers signiert hat. ConnectMQ nutzt ein Let's-Encrypt-Zertifikat, die CA ist also ISRG Root X1.

mqtt:
  broker: broker.connectmq.com
  port: 8883
  client_id: YOUR_CLIENT_ID
  username: YOUR_USERNAME
  password: !secret mqtt_password
  topic_prefix: site1/greenhouse
  discovery: false
  log_topic: null
  certificate_authority: |
    -----BEGIN CERTIFICATE-----
    (paste the ISRG Root X1 certificate here)
    -----END CERTIFICATE-----
  birth_message:
    topic: site1/greenhouse/status
    payload: online
    retain: true
  will_message:
    topic: site1/greenhouse/status
    payload: offline
    retain: true

Bewahren Sie das Passwort in secrets.yaml statt in der Hauptdatei auf, damit es nicht in der Versionsverwaltung landet. Da die Client-ID bei ConnectMQ an die ausgegebenen Zugangsdaten gebunden ist, kopieren Sie sie exakt aus dem Portal.

ESP8266-Boards haben deutlich weniger RAM, und eine vollständige Zertifikatsprüfung ist auf ihnen knapp. Wenn Sie TLS auf einem ESP8266 einsetzen müssen, prüfen Sie die aktuelle ESPHome-Dokumentation auf unterstützte Optionen oder verlagern Sie das Projekt auf einen ESP32, der TLS problemlos bewältigt.

Home Assistant und andere Tools versorgen

Sobald das Gerät an einem Broker hängt, wird Home Assistant zu einem Konsumenten unter mehreren. Richten Sie dessen MQTT-Integration auf denselben Broker aus (der Leitfaden zum externen MQTT-Broker für Home Assistant führt Sie durch) und setzen Sie auf dem Gerät discovery: true, damit die Entitäten automatisch erscheinen. Details zur Discovery, einschließlich der retained Config-Payloads, erklärt Home Assistant MQTT Discovery.

Gleichzeitig kann ein Node-RED-Flow site1/+/sensor/+/state abonnieren, um jeden Sensor zu protokollieren, und ein Python-Skript kann Messwerte in einer Datenbank archivieren. Keiner davon muss die IP-Adresse des Geräts kennen.

Fehlersuche bei ESPHome MQTT

1. Das Gerät verbindet sich und trennt sich alle paar Sekunden. Fast immer eine doppelte Client-ID. Prüfen Sie, dass kein anderes Gerät und kein übrig gebliebenes Testskript dieselbe ID verwendet.
2. Es erscheinen keine Nachrichten. Prüfen Sie, ob das Abonnement exakt zum Präfix passt, einschließlich Groß- und Kleinschreibung. Abonnieren Sie connectmq/demo/a7k2q9/#, um alles unter Ihrem Zweig zu sehen.
3. Der TLS-Handshake schlägt fehl. Prüfen Sie, ob das Gerät die korrekte Uhrzeit hat (TLS benötigt sie; ESPHome synchronisiert per SNTP), ob Sie den vollständigen PEM-Block eingefügt haben und ob Sie Port 8883 verwenden.
4. Nachrichten gehen auf dem öffentlichen MQTT-Broker verloren. Er erlaubt 10 Nachrichten pro Sekunde und Client sowie 64 KB pro Nachricht. Logs auf dem Debug-Topic oder sehr kurze Update-Intervalle können das überschreiten.
5. Befehle werden ignoriert. Veröffentlichen Sie auf dem command-Topic, nicht auf dem state-Topic, und verwenden Sie bei Schaltern ON oder OFF in Großbuchstaben.

Wer den Topic-Baum in einem Live-Explorer beobachtet, erkennt die meisten dieser Probleme innerhalb von Sekunden; deshalb lohnt es sich, beim Flashen den Topic-Explorer im Portal oder die ConnectMQ Desktop App zu öffnen.

Über ein paar Knoten hinaus skalieren

Ein einzelner Raspberry Pi mit Broker funktioniert, bis er es nicht mehr tut: Defekte SD-Karten, Stromausfälle und Portweiterleitung für den Fernzugriff werden alle zu Ihrem Problem. Der Umstieg auf einen verwalteten MQTT-Broker nimmt Ihnen diese Wartung ab und gibt jedem ESPHome-Knoten einen stabilen TLS-Endpunkt, der aus jedem Netzwerk funktioniert. Das Gesamtbild aus Geräten, Brokern und Automatisierungslogik behandelt der Leitfaden zur IoT-Automatisierung.

Verbinden Sie Ihre ESPHome-Geräte mit ConnectMQ

ConnectMQ bietet Ihnen einen privaten Broker mit TLS auf Port 8883, generiertem Benutzernamen, Passwort und Client-ID sowie einen Live-Topic-Explorer, in dem Sie Ihre ESPHome-Knoten beim Melden beobachten. Erstellen Sie unter app.connectmq.com einen kostenlosen Serverless-Broker, ganz ohne Kreditkarte, fügen Sie die Zugangsdaten in secrets.yaml ein und flashen Sie.

Häufig gestellte Fragen

Kann ich ESPHome MQTT und die native API gleichzeitig nutzen?

Ja. Beide Komponenten lassen sich zusammen aktivieren, was während einer Migration praktisch ist. Entfernen Sie api:, sobald nichts mehr davon abhängt, um Speicher zu sparen.

Funktioniert ESPHome MQTT ohne Home Assistant?

Ja. Mit discovery: false veröffentlicht das Gerät einfach Zustände und wartet auf Befehle, und jeder MQTT-Client kann sie nutzen.

Warum verbindet sich mein ESPHome-Gerät ständig neu mit dem Broker?

Die häufigste Ursache sind zwei Clients mit derselben Client-ID. Geben Sie jedem Gerät eine eindeutige client_id oder verwenden Sie exakt die ID, die mit Ihren Broker-Zugangsdaten ausgegeben wurde.

Welches QoS verwendet ESPHome?

Zustandsnachrichten verwenden standardmäßig QoS 0. Sie können qos pro Komponente oder in birth_message und will_message setzen, wenn Sie Zustellgarantien benötigen, wie im Leitfaden zu den MQTT-QoS-Stufen erklärt.