Wenn du Home Assistant technisch auf das nächste Level bringen möchtest, ist die MQTT Integration ein essenzieller Baustein. MQTT (Message Queuing Telemetry Transport) ist ein leichtgewichtiges Publish/Subscribe-Protokoll, das perfekt für IoT-Geräte geeignet ist. Dieses Tutorial führt dich Schritt für Schritt durch die Einrichtung und Konfiguration der MQTT Integration in Home Assistant – vom Aufsetzen des Brokers über die Einrichtung von Discovery bis zu fortgeschrittenen Automatisierungen.

Inhaltsverzeichnis

1. MQTT Integration in Home Assistant einrichten

1.1 MQTT Integration hinzufügen

Du kannst die MQTT Integration ganz einfach über die Benutzeroberfläche einbinden oder manuell konfigurieren.

1.1.1 Integration via Home Assistant UI hinzufügen

Öffne deine Home Assistant Instanz.
Navigiere zu Einstellungen > Geräte & Dienste.
Klicke unten rechts auf Integration hinzufügen.
Wähle MQTT aus der Liste.
Folge den Anweisungen auf dem Bildschirm, um die Einrichtung abzuschließen.

1.1.2 Manuelle Einrichtung (Alternative)

Falls der automatische Weg nicht funktioniert, kannst du MQTT manuell konfigurieren, indem du relevante Einstellungen in configuration.yaml vornimmst oder Erweiterungen installierst (z.B. Broker).

mqtt:
  broker: 192.168.1.10
  port: 1883
  username: dein_benutzername
  password: dein_passwort
  client_id: homeassistant-client
  discovery: false  # Automatische Erkennung deaktiviert

1.2 MQTT Geräte und Entities einrichten

Du hast komplette Freiheit, Geräte entweder via MQTT Discovery automatisch erkennen zu lassen oder manuell per YAML-Konfiguration hinzuzufügen.

1.2.1 MQTT Discovery nutzen

Viele Geräte unterstützen die automatische Erkennung durch MQTT Discovery. Dabei sendet das Gerät eine Konfigurationsnachricht an Home Assistant, damit dieses es direkt einbinden kann.

1.2.2 Manuelle MQTT YAML Konfiguration

Alternativ kannst du Entities in YAML konfigurieren (über die configuration.yaml).

Hier ein Beispiel, wie es aussehen könnte:

sensor:
  - platform: mqtt
    name: "Temperatur Wohnzimmer"
    state_topic: "home/sensor/wohnzimmer/temperature"
    unit_of_measurement: "°C"
    value_template: "{{ value | float }}"
    qos: 1
    device_class: temperature

Erläuterung:

sensor: – Legt einen Sensor fest, der Daten über ein bestimmtes Topic empfängt.
state_topic: – Hier lauscht Home Assistant auf MQTT-Nachrichten.
value_template: – Wandelt den empfangenen Wert ggf. um (z. B. in Float).

2. MQTT Broker auswählen und konfigurieren

Der MQTT Broker ist das Herzstück jeder MQTT-Kommunikation. Hier laufen alle Nachrichten zusammen.

2.1 MQTT Broker Setup: Mosquitto Add-on

Die einfachste Möglichkeit ist das Mosquitto MQTT Broker Add-on, welches du direkt über Home Assistant installieren kannst.

Home Assistant generiert automatisch sichere Zugangsdaten.
Du kannst zusätzliche Accounts leicht im Add-on konfigurieren.
Hinweis: Bei Neuinstallation sollten Zugangsdaten gesichert werden.

2.2 Alternative Broker

Natürlich kannst du auch einen anderen MQTT Broker selbst hosten (z.B. EMQX, HiveMQ), solange er mit Home Assistant kompatibel ist. ActiveMQ MQTT Broker und RabbitMQ MQTT Plugin werden nicht empfohlen, wegen bekannter Stabilitätsprobleme.

2.3 Broker Konfiguration in Home Assistant

2.3.1 Grundkonfiguration

Hostname/IP-Adresse deines Brokers
Port (Standard: 1883)
Benutzername & Passwort falls aktiviert

Diese Einstellungen kannst du jederzeit in Einstellungen > Geräte & Dienste > MQTT ändern.

2.3.2 Erweiterte Broker-Konfiguration

Aktiviere in den Broker-Einstellungen die erweiterten Optionen und konfiguriere z.B.:

Custom Client-ID (für Debugging)
TLS-Zertifikatvalidierung (Auto, Custom, oder ignorieren)
MQTT Protokollversion (3.1.1 oder 5)
Verwendung von Client-Zertifikaten für sichere Authentifizierung
Transport via WebSockets (inkl. Pfad und Header in JSON)

3. MQTT Optionen und Discovery anpassen

3.1 MQTT Optionen konfigurieren

Du kannst MQTT-Einstellungen wie Discovery-Prefix, Birth & Last-Will Nachrichten anpassen.
Discovery ist standardmäßig aktiviert und der Topic-Prefix ist homeassistant.
Die Birth-Nachricht signalisiert, dass Home Assistant online ist, Last-Will-Nachrichten signalisieren Offline-Zustand.

3.2 MQTT Discovery Optionen ändern

So kannst du Discovery abschalten oder den Topic-Prefix ändern:

Gehe zu Einstellungen > Geräte & Dienste.
Wähle die MQTT Integration und klicke auf Konfigurieren.
Unter MQTT Optionen kannst du Discovery-Einstellungen anpassen.

In der MQTT-Integration findest du in der Regel folgende Optionen:

MQTT Discovery aktivieren/deaktivieren
- Beschreibung: Aktiviert oder deaktiviert die automatische Erkennung neuer MQTT-Geräte.
- Typ: Checkbox
- Standard: Aktiviert
Discovery Prefix
- Beschreibung: Gibt an, unter welchem Topic-Pfad Geräte ihre Konfiguration veröffentlichen sollen.
- Standard: homeassistant
- Beispiel: Wenn ein Gerät seine Konfiguration unter homeassistant/sensor/temp/config veröffentlicht, wird es erkannt.
Geräte beim Entfernen von Config-Topics automatisch löschen
- Beschreibung: Wenn das entsprechende Discovery-Topic entfernt wird, entfernt Home Assistant automatisch auch die Entität.
- Typ: Checkbox
- Nützlich bei: dynamischen Geräten oder Integrationen
Manuelle Discovery aktivieren
- Beschreibung: Nützlich, wenn du z. B. ein Gerät per Skript oder externem Tool hinzufügen willst, ohne dass es selbstständig ein Discovery-Topic sendet.

Hinweis: Meist nur über Skripte oder erweiterte Automationen relevant.

4. MQTT Setup testen

4.1 Mit mosquitto_pub und mosquitto_sub testen

Falls du direkt auf der Kommandozeile arbeitest, helfen dir die Tools:

mosquitto_pub zum Publizieren von Nachrichten, z.B.:

  mosquitto_pub -h 127.0.0.1 -t homeassistant/switch/1/on -m "ON"

mosquitto_sub zum Abonnieren und Mitlesen von Nachrichten:
```
  mosquitto_sub -h 127.0.0.1 -v -t "homeassistant/#"
```

4.2 MQTT Integration im UI nutzen

Navigiere zu Einstellungen > Geräte & Dienste > MQTT Broker > Konfigurieren
Nutze “Publish a packet” zum Senden von Nachrichten an Topics.
Mit “Listen to a topic” kannst du Nachrichten in Echtzeit verfolgen.

5. Teilen und Namensgebung von MQTT Geräten

6.1 Teilen von Geräte-Konfiguration

Entities können eine gemeinsame Geräte-Konfiguration teilen.
Andere Entities referenzieren das Gerät nur mit erforderlichen Feldern wie connection oder identifier plus Name.

5.2 Namensgebung von MQTT Entities

Home Assistant erzeugt automatisch eindeutige entity_ids.
Wenn du unique_id definierst, kannst du die entity_id nachträglich ändern.
Falls object_id angegeben ist, wird dieser für die entity_id verwendet.
Entitäten ohne Namen können nach Gerätetyp benannt werden (z.B. „MQTT binary_sensor“).
Attribut has_entity_name wird automatisch auf True gesetzt.

6. MQTT Discovery im Detail

6.1 Aufbau der Discovery Topics

Format:

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

discovery_prefix: Standard homeassistant, kann konfiguriert werden.
component: MQTT-Komponententyp, z.B. binary_sensor, light.
node_id: Optional zur Strukturierung.
object_id: Geräte-ID, zur eindeutigen Identifikation.

6.2 Discovery Payload strukturieren

Payload ist ein JSON-Dictionary mit Geräte- und Komponenteninformationen.
Für Geräte wird der device Abschnitt mit Identifiers, Name, Hersteller etc. angegeben.
Komponenteninformationen kommen als Objekt unter cmps mit jeweils eigenen Eigenschaften.

7.3 Beispiele für Motion Sensor (binary_sensor)

Konfigurations-Topic:

homeassistant/binary_sensor/garden/config

Payload:

{
  "name": null,
  "device_class": "motion",
  "state_topic": "homeassistant/binary_sensor/garden/state",
  "unique_id": "motion01ad",
  "device": {
    "identifiers": ["01ad"],
    "name": "Garden"
  }
}

null für den Namen bedeutet Vererbung des Gerätenamens.
Status-Updates werden an state_topic gesendet.

7.4 Discovery Messages und Availability

Beim Start sendet Home Assistant eine „Birth“-Nachricht (homeassistant/status).
Geräte abonnieren diese, um ihre Discovery-Payload zu senden.
LWT (Last Will and Testament) ermöglicht Erkennung von Offline-Geräten.
Availability Topics helfen Home Assistant zu erkennen, ob ein Gerät erreichbar ist.

8. Manuelle MQTT Items via YAML konfigurieren

8.1 YAML-Stil: Pro Item

mqtt:
  - sensor:
      name: "Temperatur Wohnzimmer"
      state_topic: "homeassistant/sensor/wohnzimmer/temp"
      unit_of_measurement: "°C"
      unique_id: "wohnzimmer_temp"
  - switch:
      name: "Pumpe"
      command_topic: "homeassistant/switch/pumpe/set"
      state_topic: "homeassistant/switch/pumpe/state"
      unique_id: "pumpe_001"

8.2 YAML-Stil: Keyed nach Domain

mqtt:
  sensor:
    - name: "Temperatur Wohnzimmer"
      state_topic: "homeassistant/sensor/wohnzimmer/temp"
      unique_id: "wohnzimmer_temp"
  switch:
    - name: "Pumpe"
      command_topic: "homeassistant/switch/pumpe/set"
      state_topic: "homeassistant/switch/pumpe/state"
      unique_id: "pumpe_001"

8.3 Hinweise

Verwende nie beide Stile gemischt.
Für viele Items empfiehlt sich Split der Konfiguration.

9. MQTT Entity State Updates & Templates

9.1 Zustandsaktualisierungen

MQTT Entities abonnieren Topics für State Updates.
Nur signifikante Änderungen lösen eine Aktualisierung aus.
Last reported State Attribute wird nur bei force_update aktualisiert.

9.2 Verwendung von Templates

Templates helfen, komplexe JSON-Payloads aufzubereiten und Variablen zu extrahieren.
Nutze Jinja2-Syntax in value_template.

Beispiel:

value_template: "{{ value_json.temperature }}"

10. MQTT Automationen und Aktionen

10.1 MQTT Publish Aktion

Du kannst MQTT-Nachrichten via Automationen oder Skripte senden.

Beispiel Skript:

script:
  notify_mqtt:
    sequence:
      - action: mqtt.publish
        data:
          topic: "home/user/notify"
          payload: "Ich bin zu Hause"
          retain: true

Automation, die das Skript auslöst:

automation:
  - alias: "Nachricht bei Heimkommen"
    trigger:
      platform: state
      entity_id: device_tracker.me
      to: "home"
    action:
      - service: script.notify_mqtt
        data:
          target: "me"
          message: "Ich bin zu Hause"

10.2 MQTT Dump Aktion

Du kannst Nachrichten auf MQTT Topics aufzeichnen (Dump), um Fehler zu debuggen:

action:
  - service: mqtt.dump
    data:
      topic: "zigbee2mqtt/#"
      duration: 10

11. Logging & Fehlersuche

11.1 Logging aktivieren

Für detailliertes Debugging kannst du das MQTT Logging aktivieren:

logger:
  default: warning
  logs:
    homeassistant.components.mqtt: debug

11.2 Event: event_mqtt_reloaded

Wird gefeuert, wenn MQTT Entities manuell neu geladen wurden, das kann hilfreich beim Debuggen sein.

12. Die MQTT Integration entfernen

Willst du MQTT entfernen:

Gehe zu Einstellungen > Geräte & Dienste und wähle die MQTT Integration aus.
Klicke auf das Drei-Punkte-Menü und wähle Löschen.
Denke daran, auch die Broker-Daten, MQTT Automationen und configuration.yaml Einträge zu entfernen.
Sichere deine Konfiguration vorher!

13. Fazit

Die MQTT Integration in Home Assistant ist mächtig und flexibel. Mit einem eigenen Broker, z.B. Mosquitto, und der richtigen Konfiguration kannst du nahezu alle smarten Geräte nahtlos an Home Assistant anbinden. MQTT Discovery erleichtert dabei die automatische Integration, aber du hast auch die volle Kontrolle via YAML für individuelle Szenarien. Auch Automatisierungen lassen sich mit MQTT Publishing und Templates perfekt umsetzen. Für den technisch versierten Anwender bietet sich so ein durchgängiges und stabiles System für IoT-Setups.

14. FAQ

14.1 Brauche ich zwingend einen eigenen MQTT Broker?

Nein, es gibt öffentliche Broker, aber für Privatsphäre, Stabilität und volle Kontrolle empfiehlt sich ein eigener Broker, z.B. Mosquitto.

14.2 Wie sicher ist die MQTT Verbindung?

Mit TLS-Zertifikaten, Client-Zertifikaten und sicheren Passwörtern kannst du eine sehr sichere Verbindung gewährleisten.

14.3 Was mache ich, wenn der MQTT Broker TLS Zertifikatsfehler zeigt?

Aktiviere in den Erweiterten Einstellungen die Option zur automatischen Zertifikatsvalidierung oder lade ein eigenes CA-Zertifikat hoch.

14.4 Wie kann ich die MQTT Entities umbenennen?

Falls unique_id gesetzt ist, kannst du in der Home Assistant UI den entity_id ändern, das wird dauerhaft gespeichert.

14.5 Was tun bei vielen MQTT Discovery Nachrichten, die das System belasten?

Verwende keine zu häufigen Discovery Nachrichten, spiele den Birth- und Last Will Mechanismus geschickt aus, und verzichte ggf. auf Retain-Flags bei Statusmeldungen.

Dieses Tutorial basiert auf der folgenden Webseite: https://www.home-assistant.io/integrations/mqtt/

Home » Tutorials » Smart Home » Home Assistant » Integration

MQTT Integration in Home Assistant einrichten: Anleitung zur Integration, Konfiguration & Nutzung