Home Assistant MQTT einrichten: Broker, Integration & Discovery

Über MQTT spricht Home Assistant mit einer riesigen Bandbreite an Geräten: Zigbee2MQTT, Tasmota, ESPHome (optional), Shelly, Frigate, OpenMQTTGateway und unzählige DIY-Sensoren. Für das Setup brauchst du drei Teile – einen Broker, die MQTT-Integration in Home Assistant und idealerweise MQTT Discovery, damit Geräte automatisch erscheinen. Dieses Tutorial behandelt alle drei und zeigt, wie du das Setup mit einem MQTT-Client testest.

Schritt 1: Einen Broker wählen – Mosquitto-Add-on oder extern

Home Assistant enthält selbst keinen MQTT-Broker; die Integration ist ein Client. Du hast zwei Hauptoptionen:

Option A: das Mosquitto-Broker-Add-on

1. Gehe zu Einstellungen → Add-ons → Add-on Store, suche nach Mosquitto broker und installiere es.
2. Starte es und aktiviere Beim Booten starten sowie Watchdog.
3. Lege einen eigenen Home-Assistant-Benutzer für deine Geräte an (Einstellungen → Personen → Benutzer, z. B. mqtt-user). Das Add-on authentifiziert gegen Home-Assistant-Benutzer, deine Geräte nutzen also diese Zugangsdaten. Verwende nicht dein Admin-Konto.
4. Home Assistant zeigt nun unter Einstellungen → Geräte & Dienste eine erkannte MQTT-Integration an. Klicke auf Konfigurieren und bestätige.

Geräte in deinem Netzwerk verbinden sich mit deinem Home-Assistant-Host auf Port 1883 (und 8883, wenn du in den Add-on-Optionen TLS konfigurierst).

Option B: ein externer Broker

Bei Home Assistant Container oder Core gibt es keinen Add-on Store, also betreibst du Mosquitto daneben – am einfachsten als Mosquitto in Docker oder per Paketinstallation wie unter Mosquitto installieren beschrieben. Denk daran, dass Mosquitto 2.x einen expliziten listener und Authentifizierung braucht, bevor sich andere Hosts verbinden können; der mosquitto.conf-Generator erzeugt eine funktionierende Datei, und Mosquitto absichern behandelt Benutzer und ACLs.

Schritt 2: Die MQTT-Integration konfigurieren

Bei einem externen Broker fügst du die Integration manuell hinzu: Einstellungen → Geräte & Dienste → Integration hinzufügen → MQTT. Gib Folgendes ein:

• Broker – Hostname oder IP (in einem gemeinsamen Docker-Netzwerk der Containername, etwa mosquitto)
• Port – 1883 oder 8883 für TLS (siehe MQTT-Ports)
• Benutzername / Passwort – ein für Home Assistant angelegter Broker-Benutzer

Über die erweiterten Optionen (aktiviere dafür den Erweiterten Modus in deinem Benutzerprofil, dann Konfigurieren → MQTT neu konfigurieren) stellst du TLS-Zertifikate, die Client-ID, die Protokollversion (3.1, 3.1.1 oder 5), das Discovery-Präfix sowie die Birth- und Will-Nachrichten ein. Die Verbindungsdaten zum Broker werden in der Oberfläche konfiguriert; in der configuration.yaml lassen sie sich nicht mehr setzen.

Schritt 3: MQTT Discovery

Bei Discovery meldet sich ein Gerät selbst an, indem es eine JSON-Config auf ein festgelegtes Topic publisht, und Home Assistant legt die Entität automatisch an – ganz ohne YAML. Das Topic-Format lautet:

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

• discovery_prefix – standardmäßig homeassistant
• component – der Entitätstyp: sensor, binary_sensor, switch, light, cover, climate usw.
• node_id – optionale Gruppierung, meist die Geräte-ID
• object_id – eine ID für diese Entität (Buchstaben, Ziffern, _ und -)

Hier ein Temperatursensor. Publishe ihn auf homeassistant/sensor/garage_temp/config mit dem Retain-Flag, damit Home Assistant ihn nach einem Neustart wiederfindet:

{
  "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 macht die Entität in der Oberfläche bearbeitbar, und der device-Block gruppiert Entitäten unter einem Gerät. Das Gerät publisht seine Messwerte dann auf das State-Topic:

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

Retained Messages sind hier unverzichtbar – lies MQTT Retained Messages, falls das Konzept neu für dich ist. Schalter und Lichter nutzen zusätzlich ein command_topic, auf das Home Assistant publisht, wenn du die Entität umschaltest.

Schritt 4: Mit einem MQTT-Client testen

Mit den Mosquitto-Clients kannst du das gesamte Gerät im Terminal simulieren (alle Flags im Cheat Sheet zu mosquitto_pub/sub):

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

Die Entität erscheint unter Einstellungen → Geräte & Dienste → MQTT. Um alles zu sehen, was Home Assistant und deine Geräte austauschen, abonniere das Discovery-Präfix:

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

Die Seite der MQTT-Integration in Home Assistant bringt außerdem eingebaute Werkzeuge zum Mithören eines Topics und zum Publishen eines Pakets mit. Und um das Discovery-Format zu üben, ohne deinen heimischen Broker anzufassen, publishe das obige JSON im Browser auf ein Test-Topic eines öffentlichen Brokers:

Im Online-MQTT-Client ausprobieren

Häufige Probleme

• Integration kann sich nicht verbinden – falsche Zugangsdaten, oder der Broker lauscht nur auf localhost. Prüfe das Broker-Log und den Leitfaden zu MQTT-Verbindungsfehlern.
• Entität fehlt nach einem Neustart – die Config war nicht retained, oder das Gerät publisht sie nicht erneut, wenn homeassistant/status = online kommt.
• Entität zeigt „unbekannt“ – das value_template passt nicht zur Payload, oder auf das State-Topic wurde noch nichts gepublisht.
• Eine Entität entfernen – publishe eine leere Retained Message auf ihr Config-Topic (-r -n).

Häufig gestellte Fragen