Eine MQTT-Nachricht kann wie JSON aussehen und trotzdem keine sichere Eingabe für eine Automatisierung sein. Vielleicht ist sie fehlerhaft aufgebaut, kommt auf dem falschen Topic an oder wurde bei einem früheren Test als Retained-Nachricht gespeichert. Selbst gültiges JSON kann ein Feld enthalten, dessen Bedeutung sich geändert hat. Eine Regel kann auf jede dieser Nachrichten reagieren, obwohl das Ereignis, für das sie gedacht ist, gar nicht eingetreten ist.
Fang mit einer kleineren, konkreteren Frage an als „Funktioniert MQTT?“: Kann eine Home-Assistant-Regel eine gezielt gesendete JSON-Nachricht empfangen, den vorgesehenen Wert auslesen und eine harmlose, sichtbare Änderung ausführen? Diese Anleitung führt dich durch diesen Test auf einem Broker und einer Home-Assistant-Installation, die du selbst verwaltest. Der Test sagt nichts darüber aus, ob ein echtes Gerät online ist, ein Sensorwert stimmt oder eine Aktion im Produktivbetrieb ausgeführt werden sollte.
Ein klarer Testzweck
Lege fest, was die Automatisierung aus der Payload braucht, bevor du einen Trigger anlegst. Mit einer kleinen Testnachricht wie {"event":"check","sequence":1} prüfst du, ob sich die Nachricht als JSON parsen lässt und ob das erwartete Feld event den erwarteten Wert enthält. Mehr weist der Test nicht nach. Er zeigt nicht, ob ein Gerät einen aktuellen Messwert geliefert hat. Lass Zugangsdaten, vollständige Netzwerkinventare, MAC-Adressen, private IP-Adressen und Personennamen aus der Test-Payload weg.
Wähle ein temporäres Topic, das kein vorhandener Publisher und keine bestehende Regel nutzt, zum Beispiel lab/json-payload-check-2026-10-29/event. Vermeide Wildcards und Topics für Befehle. Notiere den Broker, das genaue Topic, die erwartete JSON-Struktur, den eingestellten QoS, die Retain-Einstellung und die Entität oder Automatisierung, die die Nachricht auswerten soll. Damit kannst du einen Topic-Fehler von einem Template-Fehler unterscheiden, ohne mehrere Einstellungen gleichzeitig zu ändern.
Die MQTT-Spezifikation definiert die Payload einer Nachricht als Anwendungsdaten. Publisher und Empfänger entscheiden, JSON zu verwenden; der Broker fügt diese Eigenschaft nicht hinzu. Die MQTT-Spezifikation Version 5.0 liefert Hintergrundwissen zu Topics und zur Zustellung von Nachrichten. Sie legt aber nicht fest, was ein Feld namens event oder status bedeutet.
Topic-Prüfung vor der Template-Prüfung
Prüfe zuerst den genauen Topic-Pfad mit einem Publisher, den du kontrollierst, und einem Subscriber zur Diagnose in der Testumgebung. Veröffentliche eine klar als Test erkennbare Nachricht mit erfundenen Daten. Kommt sie nicht an, prüfe die Schreibweise des Topics, die Verbindung, die Authentifizierung und die ACLs, bevor du ein JSON-Template hinzufügst. Auch ein korrektes Template hilft nicht, wenn der Subscriber auf einem anderen Pfad lauscht.
Veröffentliche anschließend eine Nachricht mit der vorgesehenen Struktur und eine weitere mit einem bewusst anderen, aber weiterhin gültigen Wert, etwa {"event":"check","sequence":2}. Vergleiche sequence in der vollständigen Payload beim Diagnose-Subscriber, um die beiden Nachrichten zu unterscheiden. Ein Sensor, der nur event ausliest, zeigt bei beiden check. Verwende für beide Nachrichten dasselbe Retain-Flag. Teste das Retain-Verhalten bei Bedarf in einem separaten Durchlauf und halte es als eigene Variable fest.
Home Assistant dokumentiert die MQTT-Verbindung und Einrichtung getrennt von MQTT-Sensoren und Automatisierungen. Eine verbundene Integration zeigt dir, dass Home Assistant mit dem Broker kommunizieren kann. Sie zeigt nicht, ob ein bestimmtes konfiguriertes Topic, eine Entität oder eine Automatisierung die vorgesehenen Daten empfängt. Die Dokumentation zur MQTT-Integration von Home Assistant beschreibt die Konfiguration der Integration.
Ein gezielter MQTT-Sensor oder Trigger
Wenn du einen Zustand prüfen möchtest, kann ein MQTT-Sensor ein State-Topic auswerten und ein Value-Template darauf anwenden. Soll ein Ereignis eine Regel starten, kann ein MQTT-Trigger auf einem Topic lauschen und die empfangene Payload filtern oder mit einem Template auswerten. Wähle für den Test einen dieser Wege. Wenn du gleichzeitig einen Sensor, eine Discovery-Konfiguration und eine Automatisierung für den Produktivbetrieb aufbaust, lässt sich schwer erkennen, welche Ebene die Nachricht angenommen hat.
Lies nur die JSON-Eigenschaft aus, die du für den Test brauchst. Soll die Regel nur fortfahren, wenn event den Wert check hat, vergleiche genau diesen Wert. Erfolgreiches Parsen reicht nicht aus, um eine Payload zu akzeptieren. Wenn du den Vergleich lockerst, nur damit der Test auslöst, verfehlt er seinen Zweck. Groß- und Kleinschreibung zählt. Auch Leerzeichen innerhalb eines Strings, ein fehlendes Feld oder ein geänderter Datentyp können entscheidend sein.
Die Dokumentation zum MQTT-Sensor beschreibt die Konfiguration von Zustand und Value-Template. Halte dich an die dokumentierte Syntax für die Home-Assistant-Version deiner Testinstanz, statt einen Ausschnitt aus einer anderen Integration zu kopieren. Gibt ein Template einen leeren oder unerwarteten Wert zurück, geh der Ursache nach. Immer mehr unterschiedliche Testdaten zu veröffentlichen hilft dir nicht, die Ursache zu verstehen.
Drei kontrollierte Testnachrichten
Verwende nur einen Broker und Topics, die du selbst verwaltest. Mit dieser Reihenfolge bleiben die Ergebnisse nachvollziehbar:
- Veröffentliche eine gültige Nachricht mit klar erkennbar erfundenen Daten sowie dem erwarteten Feld und Wert, etwa
{"event":"check","sequence":1}. - Veröffentliche eine gültige JSON-Nachricht mit einem bewusst anderen Wert für
event, etwa{"event":"ignore","sequence":2}. - Veröffentliche einen syntaktisch fehlerhaften Teststring nur, wenn er sich über den Diagnoseweg gefahrlos anzeigen lässt. Andernfalls beende den Test nach den ersten beiden Nachrichten und halte fest, dass der Umgang mit ungültigen Eingaben nicht getestet wurde.
Notiere nach jeder Nachricht den Veröffentlichungszeitpunkt, das Topic, die Retain-Einstellung, den Empfang beim Subscriber, den ausgelesenen Wert und ob die Regel ausgelöst wurde. Achte besonders auf die zweite Nachricht. Läuft die Regel bei beiden Werten, prüft sie noch nicht auf das vorgesehene Ereignis. Der Test mit fehlerhaften Daten ist optional, weil seine Wirkung von deiner Home-Assistant-Konfiguration abhängt. Teste eine fehlerhafte Payload niemals mit einer Automatisierung, die die Stromversorgung, Netzwerkkonfiguration, Schlösser, Alarmanlagen oder andere Aktionen mit realen Auswirkungen steuert.
Eine Retained-Nachricht ist nicht aktuell, nur weil ihr Zustand nach dem Abonnieren sichtbar wird. Lösche nach dem Test den gespeicherten Retained-Testwert und prüfe, dass das temporäre Topic keine dauerhafte Regel mit Daten versorgen kann.
Eine rückgängig zu machende erste Aktion
Lass die Automatisierung beim ersten erfolgreichen Treffer eine dauerhafte Benachrichtigung, einen Logbucheintrag oder eine Änderung an einem eigens dafür angelegten Helfer erzeugen. Starte kein NAS neu, veröffentliche keinen Befehl, ändere keine Netzwerkeinstellung und benachrichtige keine Dritten. Die Trigger-Referenz für Automatisierungen von Home Assistant erklärt MQTT-Trigger. Die Anleitung zur Fehlersuche bei Automatisierungen hilft dir zu unterscheiden, ob ein Trigger nicht ausgelöst hat oder eine Bedingung beziehungsweise Aktion das erwartete Ergebnis verhindert hat.
Sieh dir nach jeder Testnachricht den Trace der Automatisierung an. Ein Trace für die erwartete Nachricht zeigt dir etwas Konkretes: Diese Konfiguration hat für diese Testeingabe den konfigurierten Ablauf gestartet. Das beweist weder, dass ein Publisher im Produktivbetrieb vergleichbare Daten sendet, noch, dass ein Gerät einwandfrei funktioniert. Es beweist auch nicht, dass eine spätere Benachrichtigung einen Menschen erreicht.
Kein Trace vorhanden? Prüfe zuerst das notierte Topic und die Payload, bevor du die Aktion bearbeitest. Gibt es einen Trace, aber kein sichtbares, harmloses Ergebnis, prüfe die Bedingungen und die ausgewählte Aktion. Ändere ein Element und wiederhole eine Eingabe mit erfundenen Daten. Lass auch diesen Durchlauf in der Testumgebung. So bleiben die Ergebnisse nachvollziehbar, was bei mehreren gleichzeitigen Änderungen und einem erneuten Versuch verloren ginge.
JSON und weitere Netzwerkbeobachtungen
JSON kann eine Kennung oder eine Adresse enthalten. Beides beweist nicht die Identität eines Geräts. Hostnamen können sich ändern, private WLAN-Adressen können wechseln und Publisher können alte Zustände melden. Bezieht sich eine MQTT-Nachricht auf ein Netzwerkgerät, vergleiche sie mit geeigneten unabhängigen Aufzeichnungen: dem Broker-Log, dem Publisher-Log, der Ansicht aktiver Clients im Router oder einer kontrollierten lokalen Beobachtung. Der Artikel Alle Geräte in deinem Netzwerk und ihre IP-Adressen hilft dir, eine aktuelle Netzwerkbeobachtung von einer Bezeichnung in einer Nachricht zu unterscheiden.
DeviceShelf Server kann Netzwerkbeobachtungen über MQTT Discovery an eine Home-Assistant-Installation liefern, die du selbst verwaltest. Du kannst ihn als eine Quelle zum Abgleich mit dem Nachrichtenweg nutzen. Er validiert kein beliebiges JSON, beweist weder die Identität noch die Verfügbarkeit eines Geräts und bestätigt auch nicht, dass eine Automatisierung erfolgreich abgeschlossen wurde.
Aufräumen nach dem Test und begrenzte Aussagekraft
Deaktiviere oder entferne nach dem Durchlauf die temporäre Automatisierung und lösche alle verwendeten Retained-Testdaten. Bewahre nur eine Aufzeichnung ohne sensible Daten auf: Topic, Beispielstruktur, Beobachtungszeitpunkte und Trace-Ergebnis. Halte genau fest, was funktioniert hat: Auf dem notierten Test-Topic wurde der erwartete erfundene JSON-Wert ausgelesen und eine harmlose Regel einmal ausgeführt; der abweichende Wert hat den vorgesehenen Filter nicht passiert. Falls das nicht so lief, finde zuerst die Ebene, die sich anders als erwartet verhalten hat, bevor du eine Aktion mit größeren Auswirkungen in Betracht ziehst.
Damit hast du eine Grundlage, um eine spätere Änderung im Produktivbetrieb zu beurteilen. Eine MQTT-Payload wird dadurch weder zur Garantie für einen fehlerfreien Betrieb noch zu einem Sicherheitsbefund oder einem Nachweis, dass jedes Netzwerkgerät korrekt abgebildet ist.