Home Assistant MQTT-Integration: Vollständige Einrichtungsanleitung

Mit der MQTT-Unterstützung von Home Assistant binden Sie jedes Gerät, das MQTT spricht, in Ihr Smart Home ein: selbst gebaute ESP32-Sensoren, Tasmota-Steckdosen, Zigbee2MQTT-Netzwerke und industrielle Gateways gleichermaßen. In dieser Anleitung konfigurieren Sie die Home-Assistant-MQTT-Integration, legen Sensoren und Schalter in YAML an, testen alles mit dem öffentlichen MQTT-Broker unter broker.connectmq.com und wechseln dann auf einen privaten ConnectMQ-Broker mit TLS.

Wie Home Assistant MQTT nutzt

Home Assistant ist kein MQTT-Broker. Seine MQTT-Integration ist ein Client, der sich mit einem Broker verbindet, Zustands-Topics abonniert und auf Befehls-Topics veröffentlicht. Die Geräte sind Clients desselben Brokers. Der Broker sitzt in der Mitte und leitet Nachrichten weiter; ausführlich erklärt wird das in Was ein MQTT-Broker macht.

Damit haben Sie zwei Hosting-Optionen:

Dieses Tutorial verwendet einen Cloud-Broker, weil er gleich funktioniert, egal ob Home Assistant auf einem Raspberry Pi, einem NUC oder einer virtuellen Maschine läuft. Die ausführliche Begründung und die Bridge-Variante finden Sie in Einen externen MQTT-Broker mit Home Assistant nutzen.

Schritt 1: Die MQTT-Integration hinzufügen

1. Öffnen Sie Einstellungen > Geräte & Dienste.
2. Klicken Sie auf Integration hinzufügen und suchen Sie nach MQTT.
3. Wählen Sie MQTT (kein Add-on) und geben Sie die Broker-Daten ein:
   • Broker: broker.connectmq.com
   • Port: 1883
   • Benutzername und Passwort: beim öffentlichen MQTT-Broker leer lassen
4. Absenden. Home Assistant verbindet sich und legt den Eintrag der MQTT-Integration an.

Um Client ID, TLS oder Protokollversion festzulegen, aktivieren Sie zunächst den Erweiterten Modus in Ihrem Benutzerprofil. Der Konfigurationsdialog der Integration zeigt dann zusätzliche Felder wie Client ID, Keep Alive, Validierung des Broker-Zertifikats, Transport (TCP oder WebSockets) und MQTT-Protokollversion. Diese benötigen Sie in Schritt 6.

Der öffentliche MQTT-Broker braucht eine nicht leere Client ID. Home Assistant erzeugt automatisch eine zufällige, wenn das Feld leer bleibt, was zum Testen völlig ausreicht.

Schritt 2: Die Verbindung prüfen

Öffnen Sie Einstellungen > Geräte & Dienste > MQTT > Konfigurieren. Diese Seite enthält ein Formular zum Veröffentlichen eines Pakets und eines zum Abhören eines Topics.

Geben Sie beim Abhören eines Topics connectmq/demo/ha-x7m2/# ein und klicken Sie auf Abhören starten. Veröffentlichen Sie dann von einem beliebigen Computer eine Testnachricht:

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

Die Nachricht erscheint innerhalb einer Sekunde in Home Assistant. Falls nicht, prüfen Sie, ob der Home-Assistant-Host ausgehend Port 1883 erreichen kann; manche Netzwerke blockieren ihn. Verwenden Sie in diesem Fall 8883 mit TLS.

Schritt 3: Einen MQTT-Sensor in YAML anlegen

Angenommen, ein ESP32 veröffentlicht Temperatur und Luftfeuchte als JSON auf connectmq/demo/ha-x7m2/livingroom/climate:

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

Fügen Sie Folgendes in configuration.yaml ein (oder in eine daraus eingebundene Datei):

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

Mit unique_id können Sie die Entität in der Oberfläche umbenennen und einem Bereich zuordnen. expire_after markiert den Sensor als nicht verfügbar, wenn zehn Minuten lang keine Nachricht eintrifft; so bemerken Sie eine leere Batterie. state_class: measurement sorgt dafür, dass Langzeitstatistiken funktionieren.

Laden Sie die Konfiguration über Entwicklerwerkzeuge > YAML > Manuell konfigurierte MQTT-Entitäten neu und simulieren Sie dann das Gerät:

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}'

Schritt 4: Einen MQTT-Schalter anlegen

Ein Schalter braucht ein Befehls-Topic, auf das Home Assistant veröffentlicht, und ein Zustands-Topic, auf dem das Gerät meldet:

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

Legen Sie Sensoren und Schalter in Ihrer Konfiguration unter denselben einzigen mqtt:-Schlüssel; YAML erlaubt den Schlüssel nicht zweimal. Wenn Sie noch keine Hardware haben, spielen Sie das Gerät selbst:

# als Gerät agieren: Verfügbarkeit ankündigen und Zustand melden
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"

# die Befehle beobachten, die Home Assistant beim Umschalten sendet
mosquitto_sub -h broker.connectmq.com -p 1883 -i ha-dev2-x7m2 \
  -t "connectmq/demo/ha-x7m2/desk-lamp/set" -v

Wenn Sie den Schalter im Dashboard umlegen, erscheint ON im Terminal. Veröffentlichen Sie zur Bestätigung ON auf dem Zustands-Topic, und der Schalter bleibt eingeschaltet. Ohne Zustands-Topic betreibt Home Assistant den Schalter im optimistischen Modus und nimmt einfach an, dass der Befehl funktioniert hat.

Für Leuchten mit Helligkeit verwenden Sie die Plattform light mit schema: json; das Payload-Format entspricht dem Dimmer aus unserem Tutorial zu intelligenter Beleuchtung mit MQTT.

Schritt 5: Ein echtes Gerät

Das schnellste echte Gerät ist ein ESP32 mit einem kurzen Sketch wie im ESP32-MQTT-Tutorial, der auf dasselbe Klima-Topic veröffentlicht. Auch ESPHome- und Tasmota-Geräte können über MQTT veröffentlichen; siehe ESPHome MQTT. Statt für jede Entität YAML zu schreiben, können sich diese Geräte über Home Assistant MQTT Discovery automatisch anmelden.

Schritt 6: Wechsel auf einen privaten Broker mit TLS

Der kostenlose öffentliche MQTT-Broker ist für die erste Stunde und für Prototypen perfekt, aber alles darauf ist für jeden lesbar, und jeder kann auf das Befehls-Topic Ihres Schalters veröffentlichen. Ihre Heimdaten gehören auf einen privaten Broker. Es gibt auch einen praktischen Grund: Der öffentliche MQTT-Broker erlaubt 10 Subscriptions pro Client, und Home Assistant abonniert ein Topic pro Entität plus Discovery-Topics, sodass Sie das Limit schnell erreichen.

1. Registrieren Sie sich im ConnectMQ-Portal, erstellen Sie einen Broker und kopieren Sie den generierten Benutzernamen, das Passwort und die Client ID.
2. Öffnen Sie in Home Assistant Einstellungen > Geräte & Dienste > MQTT, öffnen Sie das Menü des Eintrags und wählen Sie Neu konfigurieren (oder je nach Version Konfigurieren und dann MQTT neu konfigurieren).
3. Setzen Sie den Port auf 8883, geben Sie Benutzername und Passwort ein, setzen Sie die Client ID auf den ausgegebenen Wert und stellen Sie die Validierung des Broker-Zertifikats auf Auto, damit der CA-Speicher des Systems das Let's-Encrypt-Zertifikat validiert.
4. Ändern Sie Ihre Topics von connectmq/demo/ha-x7m2/... auf Ihren eigenen Stamm, zum Beispiel home/livingroom/climate, sowohl in den Geräten als auch im YAML.

Die Client ID muss exakt mit der ausgegebenen übereinstimmen, denn ConnectMQ bindet Client IDs an Zugangsdaten. Eine Abweichung zeigt sich im Home-Assistant-Log als wiederholte Zeilen "connection refused, not authorized".

Checkliste zur Fehlersuche

1. Die Integration verbindet sich nicht. Testen Sie denselben Host, Port und dieselben Zugangsdaten mit mosquitto_sub von einem anderen Rechner.
2. Entität zeigt "unbekannt". Das Gerät hat seit dem Start von Home Assistant nichts veröffentlicht. Veröffentlichen Sie den Zustand mit Retain-Flag.
3. Entität zeigt "nicht verfügbar". Entweder ist expire_after abgelaufen, oder das Verfügbarkeits-Topic meldet offline.
4. Template-Fehler im Log. Die Payload ist nicht das erwartete JSON; hören Sie das Topic ab und vergleichen Sie.
5. Zwei Broker streiten sich um ein Gerät. Ein Gerät kann sich nur mit einem Broker gleichzeitig verbinden; wählen Sie einen aus oder verbinden Sie beide per Bridge.
6. Verbindungsabbrüche alle paar Sekunden. Zwei Clients verwenden dieselbe Client ID und werfen sich gegenseitig hinaus.

Home Assistant mit ConnectMQ betreiben

Erstellen Sie unter app.connectmq.com einen kostenlosen Serverless-Broker, ohne Kreditkarte. Bis zu 25 Verbindungen reichen für ein typisches Zuhause, und der Live-Topic-Explorer in ConnectMQ hilft Ihnen, Payloads zu debuggen, ohne den Browser zu verlassen. Wenn Sie sich fragen, wie ein verwalteter MQTT-Broker im Vergleich zum selbst betriebenen Mosquitto abschneidet, helfen Ihnen der Vergleich oben und der Leitfaden zur IoT-Automatisierung bei der Entscheidung.

Häufig gestellte Fragen

Enthält Home Assistant einen MQTT-Broker?

Nein. Die MQTT-Integration ist ein Client. Sie installieren entweder das Mosquitto-Add-on oder verbinden sich mit einem externen Broker wie ConnectMQ.

Kann ich YAML und Discovery gemeinsam nutzen?

Ja. In YAML definierte und per Discovery erkannte Entitäten existieren in derselben Integration nebeneinander, solange sich ihre Unique IDs unterscheiden.

Welchen Port sollte Home Assistant für einen Cloud-Broker verwenden?

Verwenden Sie 8883 mit TLS. Port 1883 überträgt Zugangsdaten und Daten unverschlüsselt und sollte nur für öffentliche Testdaten genutzt werden.

Warum schaltet sich mein Schalter von selbst wieder aus?

Das Gerät veröffentlicht OFF auf dem Zustands-Topic, oder eine retained OFF-Nachricht wird erneut zugestellt. Prüfen Sie das Zustands-Topic mit einem Subscriber und löschen Sie veraltete retained Messages.