Home Assistant – MQTT Broker hinzufügen und einrichten

MQTT begegnet einem bei Home Assistant früher oder später fast automatisch. Tasmota-Geräte, Zigbee2MQTT, selbst gebaute Sensoren und viele andere Smart-Home-Systeme können ihre Daten über MQTT austauschen. Damit das funktioniert, braucht es einen MQTT-Broker.

Für Home Assistant ist Mosquitto die naheliegende Lösung. Der Broker läuft lokal und lässt sich bei Home Assistant OS direkt installieren. In dieser Anleitung richten wir Mosquitto ein, verbinden Home Assistant mit MQTT und testen anschließend, ob Nachrichten korrekt übertragen werden.

Hinweis: Home Assistant bezeichnet die früheren Add-ons inzwischen als Apps. Je nach installierter Version kann in deiner Oberfläche deshalb noch „Add-ons“ stehen. Die Funktion ist dieselbe.

Was ist MQTT überhaupt?

MQTT ist ein leichtgewichtiges Nachrichtenprotokoll. Geräte schicken ihre Daten dabei an einen zentralen Broker. Andere Geräte oder Programme können diese Nachrichten anschließend abonnieren.

Ein Temperatursensor könnte seinen aktuellen Wert zum Beispiel unter folgendem Topic veröffentlichen:

haus/keller/temperatur

Home Assistant hört dieses Topic ab und übernimmt den empfangenen Wert. Der Sensor muss Home Assistant dabei nicht direkt kennen. Beide Systeme kommunizieren über den MQTT-Broker.

Dieses Prinzip wird zum Beispiel von Zigbee2MQTT genutzt. Wenn du Zigbee-Geräte über Zigbee2MQTT einbinden möchtest, findest du dazu eine eigene Anleitung unter Zigbee2MQTT mit Home Assistant einrichten.

Was brauche ich für MQTT in Home Assistant?

• eine laufende Home-Assistant-Installation
• Home Assistant OS oder eine Installation mit Unterstützung für Apps/Add-ons, wenn Mosquitto direkt dort laufen soll
• den Mosquitto Broker
• die MQTT-Integration von Home Assistant

Wer Home Assistant als Container betreibt, kann Mosquitto ebenfalls nutzen. Der Broker läuft dann beispielsweise in einem eigenen Docker-Container oder auf einem anderen Rechner im Netzwerk. In diesem Fall trägst du später dessen IP-Adresse in der MQTT-Integration ein.

Schritt 1: Mosquitto Broker installieren

Öffne in Home Assistant die Einstellungen und anschließend den Bereich Apps. Bei älteren Versionen heißt dieser Bereich noch Add-ons.

Wähle App installieren beziehungsweise den Add-on-Store und suche nach Mosquitto broker. Öffne den Eintrag und starte die Installation.

Nach der Installation startest du Mosquitto. Ein Blick in das Protokoll lohnt sich. Dort sollte nach kurzer Zeit zu erkennen sein, dass der Broker ohne Fehler läuft.

Für eine normale Home-Assistant-Installation musst du an der Mosquitto-Konfiguration zunächst nichts verändern.

Schritt 2: MQTT mit Home Assistant verbinden

Nach dem Start von Mosquitto erkennt Home Assistant den Broker normalerweise automatisch.

Gehe dazu auf:

Einstellungen → Geräte & Dienste

Unter den neu entdeckten Geräten sollte jetzt MQTT beziehungsweise Mosquitto auftauchen. Klicke auf Konfigurieren und folge dem kurzen Einrichtungsdialog.

Falls MQTT dort nicht automatisch erscheint, kannst du die Integration auch selbst hinzufügen. Klicke unten rechts auf Integration hinzufügen, suche nach MQTT und öffne die Integration.

Bei einem externen Broker musst du an dieser Stelle die IP-Adresse oder den Hostnamen, den MQTT-Port und die Zugangsdaten angeben. Der normale MQTT-Port ist 1883.

MQTT-Benutzer für Geräte anlegen

Home Assistant und die Mosquitto-App kümmern sich um ihre interne Verbindung weitgehend selbst. Möchtest du weitere Geräte mit dem Broker verbinden, zum Beispiel einen Tasmota-Sensor oder einen anderen MQTT-Client, solltest du dafür einen eigenen Benutzer verwenden.

Öffne Einstellungen → Personen → Benutzer und lege einen neuen Benutzer an. Ein Name wie mqtt oder mqtt-device ist ausreichend. Verwende ein eigenes, starkes Passwort.

Falls der Bereich für Benutzer nicht angezeigt wird, aktiviere in deinem Home-Assistant-Profil den erweiterten Modus.

Die Namen homeassistant und addons solltest du nicht verwenden. Diese Namen sind für interne Verbindungen reserviert.

Schritt 3: MQTT-Verbindung testen

Bevor du erste Geräte einrichtest, kannst du testen, ob der Broker funktioniert.

Öffne wieder Einstellungen → Geräte & Dienste und wähle die MQTT- beziehungsweise Mosquitto-Integration. Über Konfigurieren findest du Werkzeuge zum Senden und Empfangen von MQTT-Nachrichten.

Trage zum Beispiel folgendes Topic ein:

smarthome/test

Als Nachricht kannst du einfach schreiben:

Hallo MQTT

Starte anschließend das Abhören des Topics smarthome/test und veröffentliche die Nachricht. Taucht „Hallo MQTT“ im Fenster auf, funktioniert die Verbindung.

Zum Testen aller Nachrichten kannst du außerdem das Topic # abonnieren. Auf einem produktiven System rauschen hier allerdings schnell sehr viele Nachrichten durch.

MQTT Discovery: Geräte automatisch erkennen

Viele Geräte und Anwendungen unterstützen MQTT Discovery. Damit kann ein Gerät Home Assistant selbst mitteilen, welche Sensoren, Schalter oder anderen Entitäten es bereitstellt.

MQTT Discovery ist in Home Assistant standardmäßig aktiviert. Das übliche Discovery-Prefix lautet:

homeassistant

Genau deshalb erscheinen beispielsweise Geräte aus Zigbee2MQTT häufig automatisch in Home Assistant, sobald MQTT korrekt eingerichtet wurde.

Die Discovery-Einstellungen findest du über Einstellungen → Geräte & Dienste → MQTT → Konfigurieren.

MQTT-Sensor manuell in Home Assistant anlegen

Für viele Geräte ist heute keine manuelle YAML-Konfiguration mehr notwendig. MQTT Discovery übernimmt die Einrichtung automatisch. Für eigene Projekte kann ein manuell angelegter Sensor trotzdem sinnvoll sein.

Ein einfacher Temperatursensor könnte in der configuration.yaml so aussehen:

mqtt:
  sensor:
    - name: "Keller Temperatur"
      unique_id: keller_temperatur_mqtt
      state_topic: "haus/keller/temperatur"
      unit_of_measurement: "°C"
      device_class: temperature
      state_class: measurement

Sendet ein Gerät beispielsweise den Wert 21.8 an das Topic haus/keller/temperatur, kann Home Assistant daraus den entsprechenden Temperatursensor aktualisieren.

Nach einer Änderung an der YAML-Konfiguration solltest du die Konfiguration prüfen und Home Assistant anschließend neu laden beziehungsweise neu starten.

MQTT-Gerät wird in Home Assistant nicht angezeigt

Wenn der Broker läuft, aber ein Gerät nicht auftaucht, liegt das häufig an einem der folgenden Punkte.

• Falsche Broker-Adresse: Das Gerät muss die IP-Adresse des Rechners verwenden, auf dem Mosquitto läuft.
• Falsche Zugangsdaten: Benutzername und Passwort im MQTT-Gerät kontrollieren.
• Falscher Port: Für eine normale unverschlüsselte Verbindung im lokalen Netzwerk wird meist Port 1883 verwendet.
• MQTT Discovery fehlt: Nicht jedes Gerät meldet sich automatisch bei Home Assistant an.
• Falsches Topic: Schon ein Schreibfehler sorgt dafür, dass Home Assistant keine Werte empfängt.
• Broker nicht gestartet: In der Mosquitto-App prüfen, ob der Dienst tatsächlich läuft.

Bei der Fehlersuche ist die Funktion zum Abhören von Topics besonders hilfreich. Trage dort zunächst # ein. Sendet das Gerät überhaupt Daten, solltest du seine Nachrichten dort sehen.

Verbindung zum MQTT-Broker fehlgeschlagen

Zeigt Home Assistant oder ein externes Gerät einen Verbindungsfehler, solltest du zuerst die Zugangsdaten prüfen. Mosquitto erlaubt in der Home-Assistant-App keine anonymen Verbindungen. Ein MQTT-Client benötigt daher gültige Zugangsdaten.

Prüfe danach die IP-Adresse. Eine typische Adresse im Heimnetz könnte beispielsweise 192.168.178.50 lauten. Verwende bei externen Geräten nicht localhost oder 127.0.0.1. Diese Adressen verweisen immer auf das Gerät selbst.

Hilft das nicht weiter, öffne das Protokoll der Mosquitto-App. Fehler bei der Anmeldung oder beim Start des Brokers werden dort angezeigt.

MQTT mit Tasmota und Zigbee2MQTT

Besonders häufig wird MQTT zusammen mit Tasmota und Zigbee2MQTT eingesetzt. Bei Tasmota trägst du die IP-Adresse des Mosquitto Brokers sowie den zuvor erstellten Benutzer ein. Danach veröffentlicht das Gerät seine Zustände über MQTT und kann Befehle darüber empfangen.

Zigbee2MQTT nutzt MQTT als Verbindung zwischen dem Zigbee-System und Home Assistant. Wer Zigbee2MQTT einsetzen möchte, sollte deshalb zuerst Mosquitto und die MQTT-Integration einrichten.

Unsere vollständige Anleitung findest du hier: Zigbee2MQTT mit Home Assistant einrichten.

Brauche ich MQTT für ESPHome?

Für ESPHome brauchst du MQTT normalerweise nicht. ESPHome kann über seine eigene API direkt mit Home Assistant kommunizieren. Das ist für eine normale Installation meist einfacher.

Wie das funktioniert, zeigen wir in der Anleitung ESPHome mit Home Assistant verbinden.

Fazit: Mosquitto ist in wenigen Minuten eingerichtet

Die MQTT-Einrichtung in Home Assistant ist heute wesentlich einfacher als noch vor einigen Jahren. Mosquitto installieren, Broker starten und die erkannte MQTT-Integration bestätigen. Für externe Geräte legst du anschließend passende Zugangsdaten an.

Ob du MQTT überhaupt brauchst, hängt von deinen Geräten ab. Für Zigbee2MQTT, Tasmota und zahlreiche Eigenbau-Projekte bleibt MQTT eine wichtige Schnittstelle. Durch MQTT Discovery tauchen viele Geräte nach der Einrichtung automatisch in Home Assistant auf.

Weitere aktuelle Anleitungen findest du in unserer Home-Assistant-Übersicht.