MQTT für Home Assistant

Für beide Varianten benötigst du Administratorzugriff auf Home Assistant sowie Zugriff auf dein lokales Netzwerk. Entscheide dich anschließend für eine der beiden Broker-Installationen – zwei MQTT-Broker sind für ein einzelnes Smart Home normalerweise nicht nötig.

• Methode 1: Home Assistant OS oder Home Assistant Supervised mit Zugriff auf den Add-on-Shop.
• Methode 2: ein Docker-Host, zum Beispiel ein Unraid-Server, mit dauerhaftem Speicherplatz für die Mosquitto-Daten.
• Eine feste IP-Adresse oder DHCP-Reservierung für den Server, auf dem Mosquitto läuft.
• Ein langes, eigenes Kennwort für MQTT.

Diese Methode eignet sich für Home Assistant OS. Mosquitto läuft dabei als verwaltete Home-Assistant-App auf demselben System.

Mosquitto Broker installieren

1. Öffne Einstellungen → Apps → App Installieren.
2. Suche nach Mosquitto broker und öffne die offizielle App.
3. Klicke auf Installieren.
4. Aktiviere bei Bedarf Beim Start starten und Watchdog.
5. Starte die App.

Wenn du die MQTT-Integration noch nicht eingerichtet hast, kannst du auch über Einstellungen → Geräte & Dienste → Integration hinzufügen → MQTT beginnen. Home Assistant kann den offiziellen Mosquitto Broker dabei direkt einrichten und die internen Zugangsdaten selbst verwalten.

Home Assistant selbst verbindet sich automatisch mit dem offiziellen Broker. Für externe Geräte und Dienste wie Node-RED, Tasmota, Zigbee2MQTT oder eigene ESP32-Projekte legst du einen eigenen MQTT-Benutzer an.

Öffne in der Mosquitto-App den Reiter Konfiguration und trage zum Beispiel Folgendes ein:

logins:
  - username: mqtt
    password: "HIER_EIN_LANGES_EIGENES_PASSWORT_EINTRAGEN"
anonymous: false
customize:
  active: false

Speichere die Konfiguration und starte die Mosquitto-App neu. Für Geräte im Heimnetz verwendest du anschließend die IP-Adresse oder den Hostnamen deines Home-Assistant-Systems, Port 1883 und die gerade angelegten Zugangsdaten.

Ein eigener Mosquitto-Container ist unabhängig von Home Assistant. Dadurch kann derselbe Broker gleichzeitig von Home Assistant, Node-RED, Zigbee2MQTT, Tasmota und eigenen ESP32-Projekten verwendet werden. Ein Neustart von Home Assistant unterbricht den Broker dabei nicht.

Dauerhafte Ordner anlegen

Öffne auf deinem Unraid-Server ein Terminal und lege die drei benötigten Ordner an:

mkdir -p /mnt/user/appdata/mosquitto/config
mkdir -p /mnt/user/appdata/mosquitto/data
mkdir -p /mnt/user/appdata/mosquitto/log

In diesen Ordnern speichert Mosquitto seine Konfiguration, gespeicherte Nachrichten und Log-Dateien dauerhaft. Bei einem Container-Update bleiben sie erhalten.

Erstelle die Datei /mnt/user/appdata/mosquitto/config/mosquitto.conf und füge diesen vollständigen Inhalt ein:

persistence true
persistence_location /mosquitto/data/

log_dest file /mosquitto/log/mosquitto.log

listener 1883
allow_anonymous false
password_file /mosquitto/config/passwordfile

Die Konfiguration aktiviert die dauerhafte Speicherung und erlaubt ausschließlich Benutzer mit Kennwort. Als Nächstes erzeugst du die Passwortdatei für den MQTT-Benutzer mqtt:

docker run --rm -it \
  -v /mnt/user/appdata/mosquitto/config:/mosquitto/config \
  eclipse-mosquitto:2 \
  mosquitto_passwd -c /mosquitto/config/passwordfile mqtt

Du wirst danach zweimal nach einem Kennwort gefragt. Dieses wird nur als sicherer Hash in der Datei passwordfile gespeichert.

persistence true
persistence_location /mosquitto/data/

log_dest file /mosquitto/log/mosquitto.log

listener 1883
allow_anonymous true

Erstelle in Unraid einen neuen Docker-Container mit dem Image eclipse-mosquitto:2. Lege folgende Pfad- und Portzuordnungen an:

Als Netzwerkmodus ist Bridge mit der Portfreigabe 1883:1883 für die meisten Unraid-Installationen ausreichend. Aktiviere außerdem die automatische Neustart-Option des Containers.

Wenn du Docker Compose verwendest, kannst du alternativ diese Konfiguration einsetzen:

services:
  mosquitto:
    image: eclipse-mosquitto:2
    container_name: mosquitto
    restart: unless-stopped
    ports:
      - "1883:1883"
    volumes:
      - /mnt/user/appdata/mosquitto/config:/mosquitto/config
      - /mnt/user/appdata/mosquitto/data:/mosquitto/data
      - /mnt/user/appdata/mosquitto/log:/mosquitto/log

Starte den Container. Im Log sollte Mosquitto anschließend ohne Fehler starten und auf Port 1883 lauschen.

1. Öffne in Home Assistant Einstellungen → Geräte & Dienste.
2. Klicke auf Integration hinzufügen und suche nach MQTT.
3. Als Broker trägst du die IP-Adresse deines Unraid-Servers ein, zum Beispiel 192.168.1.10.
4. Verwende den Port 1883 sowie den Benutzer mqtt und dein selbst vergebenes Kennwort.
5. Schließe die Einrichtung ab.

Wenn Home Assistant und Mosquitto im selben Docker-Netzwerk liegen, kann auch der Container-Name verwendet werden. Für eine klare und wartungsarme Heimnetz-Konfiguration ist die feste IP-Adresse des Unraid-Servers jedoch meist die einfachere Wahl.

Nach der Einrichtung kannst du direkt in Home Assistant prüfen, ob Nachrichten am Broker ankommen:

1. Öffne Einstellungen → Geräte & Dienste → MQTT.
2. Klicke auf Konfigurieren.
3. Trage unter Auf ein Topic hören ein # ein.
4. Klicke auf Lauschen starten.

Das Zeichen # steht für alle Topics. Sobald ein MQTT-Gerät eine Nachricht sendet, sollte sie hier sichtbar werden.

Alternativ kannst du mit den Mosquitto-Clients aus einem Linux-Terminal testen. Zuerst hörst du auf alle Nachrichten:

mosquitto_sub -h 192.168.1.10 -p 1883 -u mqtt -P "DEIN_PASSWORT" -v -t "#"

In einem zweiten Terminal veröffentlichst du eine Testnachricht:

mosquitto_pub -h 192.168.1.10 -p 1883 -u mqtt -P "DEIN_PASSWORT" \
  -t "test/hello" -m "MQTT funktioniert"

Erscheint die Nachricht im ersten Terminal oder in Home Assistant, ist dein MQTT-Broker korrekt eingerichtet.