Test eines MQTT-Payload-Filters in Home Assistant vor dem Einsatz für einen Alarm

Trotz korrektem MQTT-Topic kann eine Automatisierung falsch reagieren: Der Payload-Filter akzeptiert zu viel, ein Template vergleicht das falsche Feld oder ein Retain-Wert erscheint als neues Ereignis. Umgekehrt kann der Filter eine im Listener korrekt aussehende Nachricht ablehnen.

Prüfe, ob die Regel die gewünschte erfundene Nachricht akzeptiert und eine ähnliche ablehnt. MQTT-Abonnements allein belegen das nicht. Ein isolierter Test prüft die Regel ohne Netzwerkbeobachtungen, NAS-Status oder echte Alarme als Testdaten.

Wenn du wissen musst, welche Clients tatsächlich im Netzwerk sind, kläre das separat, bevor du einen Alarm einrichtest. Alle Geräte im Netzwerk und ihre IP-Adressen finden erklärt, wie du einen Scan mit den Angaben des Routers abgleichst, ohne einen Namen, eine Adresse oder ein einzelnes Automatisierungsergebnis als Identitätsnachweis zu werten.

Die Regel in einfachen Worten

Schreib die gewünschte Regel als Satz auf, bevor du den Automatisierungseditor öffnest. Zum Beispiel: „Akzeptiere eine Nachricht auf lab/filter-check/2026-11-07/event nur dann, wenn ihr JSON-Feld kind exakt den Wert fictional_device_seen hat; erstelle dann eine einzelne Testbenachrichtigung.“ Damit stehen Topic, Feld, akzeptierter Wert und ein harmloses Ergebnis fest.

Der Abgleich des MQTT-Topics und die Prüfung der Payload beantworten unterschiedliche Fragen. Ein exaktes Topic legt fest, wo Home Assistant lauscht. Eine Payload-Bedingung legt fest, welche Nachrichten auf diesem Topic für die Automatisierung relevant sind. Eine Nachricht kann eine Prüfung bestehen und an der anderen scheitern. Schreib beide getrennt auf. Sonst änderst du schnell beides gleichzeitig und weißt anschließend nicht mehr, warum das Testergebnis anders ausfällt.

Verwende ein Test-Topic, das kein echter Exporter, kein Gerät und kein Dienst nutzt. Ein Testpfad mit Datum wie lab/filter-check/2026-11-07/event verringert das Risiko einer versehentlichen Überschneidung. Außerdem findest du den Test später leichter in einem Trace oder im Broker-Log wieder. Verwende im Topic und in den Testdaten keine echten Hostnamen, MAC-Adressen, privaten IP-Adressen, Kundennamen, Passwörter oder Tokens.

Wähle ein Ergebnis ohne Auswirkungen nach außen. Eine dauerhafte Benachrichtigung mit einer neuen Kennung kann zeigen, dass die akzeptierte Nachricht eine Aktion erreicht hat. Ein eigens angelegter Helfer oder ein Logbucheintrag erfüllt denselben Zweck. Fang nicht mit einem Schalter, einem Schloss, einem Neustart, einer externen Nachricht oder einer Benachrichtigung an, auf die jemand reagieren soll. Auch ein erfolgreicher Filtertest ist kein Grund, schon die erste Aktion mit echten Folgen zu verbinden.

Akzeptierte Testnachricht und Kontrollnachricht

Verwende JSON nur, wenn die eigentliche Regel JSON auswerten soll. Für diesen erfundenen Test reicht diese kleine Nachricht als akzeptierter Testfall:

~~~json { "kind": "fictional_device_seen", "label": "Tutorial sensor", "test_id": "filter-check-2026-11-07" } ~~~

Die Bezeichnung und die Kennung sind erfundene Beispiele, keine Beobachtungen echter Geräte. Der Filter wertet kind aus. Die anderen Felder sind vorhanden, spielen aber keine Rolle. So verwechselt später niemand eine Bezeichnung, einen vermeintlichen Gerätenamen oder eine Kennung mit dem Feld, das tatsächlich zum Treffer geführt hat.

Bereite eine Kontrollnachricht für dasselbe Topic vor. Ändere dabei nur das Feld, das über den Treffer entscheidet:

~~~json { "kind": "fictional_device_ignored", "label": "Tutorial sensor", "test_id": "filter-check-2026-11-07" } ~~~

Lass die Kontrollnachricht nicht weg. Eine Benachrichtigung nach der akzeptierten Nachricht zeigt, dass möglicherweise ein Ablauf ausgeführt wurde. Sie sagt aber nicht, ob der Filter gezielt ausgewählt hat. Wenn beide Testnachrichten dasselbe Ergebnis auslösen, lässt die Regel mehr durch, als dein aufgeschriebener Regelsatz erlaubt. Wenn keine der beiden ein Ergebnis erzeugt, prüfe zuerst das Abonnement, die Schreibweise des Topics, den Aktivierungsstatus der Automatisierung und die Auswertung der Payload, bevor du den getesteten Wert änderst.

Gib jedem Testergebnis eine eindeutige Kennung. Eine Benachrichtigungs-ID wie lab_filter_check_2026_11_07_accept lässt sich leichter von einem alten Test unterscheiden als ein allgemeiner Titel wie „MQTT-Alarm“. Entferne vor dem Test ein älteres Ergebnis mit dieser ID oder verwende eine neue ID. Eine alte Benachrichtigung, die noch angezeigt wird, beweist nur, dass sie irgendwann zuvor erstellt wurde.

Der Filtermechanismus

MQTT-Trigger in Home Assistant können die Payload direkt auf einen bestimmten Wert einschränken. Templates können detailliertere Daten aus der Payload auswerten. Wähle den einfachsten Mechanismus, der die tatsächliche Regel abbildet: Für eine einfache Nachricht reicht vielleicht ein exakter Textvergleich, während ein JSON-Template ein bestimmtes Feld prüfen kann. Mehrere Felder in einer Testnachricht sind noch kein Grund für ein komplexes Template. Dieser Ablauf prüft die Filterung innerhalb des MQTT-Triggers mit payload und bei JSON mit value_template. Er prüft keine Filterung in einer Automatisierungsbedingung, die eine Nachricht nach Beginn eines Durchlaufs korrekt ablehnen und dabei einen an dieser Bedingung endenden Trace hinterlassen kann.

Prüfe beim erfundenen JSON-Beispiel oben den Wert von kind. Prüfe nicht nur, ob fictional_device_seen irgendwo in der rohen Payload vorkommt. Eine Teilzeichenfolge kann auch in einem völlig anderen Feld stehen. Eine spätere Nachricht würde dann scheinbar aus dem richtigen Grund akzeptiert, obwohl das gar nicht stimmt. Auch Änderungen an der Formatierung können eine solche Prüfung unzuverlässig machen. Wenn du ein bestimmtes Feld vergleichst, bleibt die beabsichtigte Bedingung leicht nachvollziehbar.

Datentypen sind wichtig. In JSON sind 1, "1", true und "true" unterschiedliche Werte. Wenn ein echter Publisher manchmal eine Zahl und manchmal einen String sendet, dokumentiere diese Abweichung und lege fest, welche Form gültig ist. Akzeptiere nicht stillschweigend beide, nur damit der Test durchläuft. Achte bei Textvergleichen genauso auf Groß- und Kleinschreibung sowie Leerzeichen.

Ein Template, das sich fehlerfrei auswerten lässt, hat noch keinen Automatisierungstest bestanden. Die Auswertung prüft die Syntax und eine vorgegebene Eingabe. Sie zeigt nicht, ob die MQTT-Integration eine tatsächlich gesendete Nachricht empfangen hat oder ob das Topic gepasst hat. Ebenso wenig zeigt sie, ob die Automatisierung aktiviert war oder eine Aktion ausgeführt wurde. Wenn du diese Prüfung nutzt, halte sie als reine Template-Prüfung fest.

Ein klar begrenzter Testablauf

Notiere vor dem Senden der beiden Testnachrichten die aktuelle Uhrzeit, den Namen der Automatisierung, das isolierte Topic, den exakt akzeptierten Wert, den gewählten Modus und die Kennung des harmlosen Ergebnisses. Prüfe, ob die Automatisierung aktiviert ist. Bereits vorhandene Traces oder Benachrichtigungen gehören zu einem früheren Durchlauf, nicht zu diesem Test. Starte einen unabhängigen MQTT-Listener, der das exakte Test-Topic auf demselben Broker abonniert, und lass ihn während des gesamten Tests laufen. Beobachte und protokolliere dort beide exakten Testnachrichten und ihre Empfangszeiten, bevor du ihre Automatisierungsergebnisse bewertest.

Sende die nicht passende Kontrollnachricht genau einmal, ohne Retain. Bestätige zuerst, dass der unabhängige Listener genau diese Nachricht auf dem Test-Topic empfangen hat. Falls nicht, ist der Kontrolltest nicht aussagekräftig; eine später erfolgreich akzeptierte Testnachricht kann die Zustellung der Kontrollnachricht nicht belegen. Prüfe erst nach bestätigtem Empfang, ob die Kontrollnachricht keinen neuen Durchlauf und kein harmloses Ergebnis erzeugt hat. „Es ist nichts passiert“ reicht allein nicht aus: Suche nach einem unerwarteten Automatisierungs-Trace oder einer Benachrichtigung mit der Testkennung. Falls die Automatisierung bei der Filterung innerhalb des MQTT-Triggers gelaufen ist, halte an und prüfe den Filter, bevor du weitere Nachrichten sendest.

Sende anschließend die akzeptierte Testnachricht genau einmal, ebenfalls ohne Retain, und notiere den Sendezeitpunkt. Bestätige auch hier, dass der unabhängige Listener genau diese Nachricht auf dem Test-Topic empfangen hat; andernfalls ist ihr Automatisierungsergebnis nicht aussagekräftig. Eine per Retain gespeicherte Nachricht kann nach einem erneuten Abonnieren oder einer erneuten Verbindung zum Broker nochmals zugestellt werden. Dieses Verhalten solltest du separat testen. Bei dieser Prüfung des Ereignisablaufs macht es das Ergebnis jedoch uneindeutig. Dasselbe gilt, wenn du die Testnachricht so lange wiederholst, bis eine Benachrichtigung erscheint. Das sichtbare Ergebnis könnte zu einem früheren oder späteren Versuch gehören.

Prüfe nach bestätigtem Empfang der akzeptierten Testnachricht den Automatisierungs-Trace oder eine andere Aufzeichnung des Durchlaufs. Die Trigger-Daten sollten exakt das Test-Topic und die erfundene Payload zeigen. Falls die Automatisierung Bedingungen enthält, prüfe, ob der Durchlauf sie erfüllt hat, bevor er die harmlose Aktion erreicht hat. Gleiche anschließend die Aktionsdaten und den Zeitpunkt mit der neuen Benachrichtigung oder dem Zustand des Helfers ab.

Halte diese Ergebnisse auseinander:

• Der unabhängige Listener hat die exakte Kontrollnachricht auf dem Test-Topic empfangen, und die Kontrollnachricht hat keinen passenden Durchlauf und kein Ergebnis erzeugt: Das belegt, dass dieser Test genau diesen einen nicht passenden Wert am MQTT-Trigger abgelehnt hat. Ohne bestätigten Empfang ist das Kontrollergebnis nicht aussagekräftig.
• Der unabhängige Listener hat die exakte akzeptierte Testnachricht auf dem Test-Topic empfangen, und sie hat einen Durchlauf erzeugt, dessen Trigger-Daten zum Topic und zur Testnachricht passen: Das belegt, dass der Trigger und sein Payload-Filter genau diese eine Nachricht akzeptiert haben.
• Der Durchlauf enthält die festgelegte harmlose Aktion, und ein neues, passendes Ergebnis ist sichtbar: Das belegt, dass dieser Durchlauf die Aktion erreicht hat.
• Ein Publish-Dienst hat die Anfrage angenommen: Das belegt nur, dass Home Assistant eine Anfrage zum Veröffentlichen angenommen hat. Es belegt nicht, dass der Abonnent die Verarbeitung oder die Aktion abgeschlossen hat.

Diese Beobachtungen beweisen nicht, dass ein echtes Gerät online oder offline ist, einer bestimmten Person gehört oder korrekt identifiziert wurde. Sie garantieren auch keine künftige Zustellung durch den Broker. Sie belegen einen eng begrenzten Ablauf zu einem bestimmten Zeitpunkt.

Fehlerprüfung an den einzelnen Übergängen

Wenn die Kontrollnachricht die Automatisierung auslöst, prüfe die Payload-Regel, bevor du das MQTT-Topic änderst. Kläre, ob die Automatisierung ein bestimmtes JSON-Feld, die rohe Payload als String oder ein Template-Ergebnis vergleicht. Prüfe, ob ein anderer Trigger in derselben Automatisierung den Durchlauf gestartet haben könnte. Eine vorübergehende Automatisierung mit einem Trigger und einer Aktion lässt sich leichter nachvollziehen als eine produktive Regel mit mehreren Einstiegspunkten.

Wenn die akzeptierte Testnachricht keinen Durchlauf erzeugt, prüfe zuerst das exakte Topic, den ausgewählten Broker, den Aktivierungsstatus der Automatisierung und das Nachrichtenformat. MQTT-Topics unterscheiden Groß- und Kleinschreibung: Lab/filter-check ist etwas anderes als lab/filter-check. Wenn ein Listener die Nachricht sieht, die Automatisierung aber nicht läuft, solltest du bei ihrem Trigger, Filter, ihren Bedingungen oder ihrem Ausführungsmodus weitersuchen. Das beweist noch nicht, dass die Aktion fehlerhaft ist.

Wenn der Trace den akzeptierten Trigger zeigt, aber keine Benachrichtigung erscheint und der Helfer kein Update erhält, prüfe Bedingungen und Aktion getrennt. Eine Bedingung kann den Durchlauf absichtlich stoppen. Die Aktion verwendet möglicherweise die falsche Benachrichtigungs-ID oder falsche Dienstdaten. Ändere Filter, Bedingung und Aktion nicht gleichzeitig. Ändere einen Übergang und starte dann einen neuen Test mit Datum und neuer Kennung.

Der Automatisierungsmodus spielt eine Rolle, wenn Nachrichten kurz hintereinander eintreffen. Im Modus single kann ein zweiter Trigger ignoriert werden, solange ein früherer Durchlauf noch aktiv ist. Die Modi für Warteschlangen und parallele Ausführung haben jeweils andere Vor- und Nachteile. Ändere den Modus nicht nur, um ein scheinbar erfolgreiches Ergebnis zu bekommen. Kläre zuerst, ob es einen Durchlauf gab und ob er den Filter und die Aktion erreicht hat, die du untersuchen wolltest.

Ein kurzes, brauchbares Testprotokoll

Speichere außerhalb der Automatisierung ein kompaktes Protokoll: den Regelsatz, den Namen der Automatisierung, das isolierte Topic, die akzeptierte Testnachricht, die Kontrollnachricht, die Retain-Einstellung, Sendezeiten, Aufzeichnungen des unabhängigen Listeners zu beiden exakten Testnachrichten und ihren Empfangszeiten, Ausführungszeiten, Ergebnis-IDs und beobachtete Ergebnisse. Lass Tokens, Passwörter, private Hostnamen, echte Gerätenamen und Kundendaten weg. Mit diesem Protokoll lässt sich bei einer späteren Prüfung unterscheiden, ob sich die Regel, der Broker oder die übrige Einrichtung geändert hat.

Entferne nach dem Test die vorübergehende Benachrichtigung. Setze den eigens angelegten Helfer zurück oder entferne ihn, falls du einen verwendet hast. Deaktiviere oder lösche bei Bedarf eine Automatisierung, die nur für diesen Test angelegt wurde. Falls du für einen separaten Test Nachrichten per Retain im Broker gespeichert hast, entferne auch diese. So sieht ein erfundenes Testergebnis mit altem Datum später nicht wie ein aktueller Alarm aus dem laufenden Betrieb aus.

DeviceShelf Server kann Netzwerkbeobachtungen über MQTT Discovery in einer Home-Assistant-Installation veröffentlichen, die du verwaltest. Ein Payload-Filter ist ein Schritt bei der Überprüfung dieser Beobachtungen. Prüfe zuerst mit kontrollierten Testdaten, welche Nachrichten der Filter akzeptiert. Gleiche anschließend Zeitstempel und unabhängige Netzwerk- oder Dienstprotokolle ab, bevor du eine Aussage über ein echtes Gerät triffst.