Eine MQTT-Automation beginnt oft mit einer vernünftigen Idee: Ein Gerät veröffentlicht ein Ereignis, und Home Assistant reagiert darauf. Schwieriger ist die Frage, was dieses Ereignis genau bedeuten muss. Würde ein verpasstes Update nur dazu führen, dass ein Dashboard nicht ganz aktuell ist? Könnte ein wiederholtes Ereignis zwei Benachrichtigungen auslösen? Würde die Aktion ein Schloss, eine Heizung oder ein anderes Gerät steuern, bei dem du vorsichtiger planen musst?
Quality of Service, meist kurz QoS, gehört zu dieser Entscheidung. QoS beschreibt, welches Bestätigungsverfahren für die Zustellung zwischen einem MQTT-Client und einem Broker angefordert wird. Es beweist weder, dass ein Sensor korrekt gemessen hat, noch, dass ein Gerät gerade erreichbar ist. Auch dass Home Assistant eine Automation abgeschlossen hat, lässt sich daraus nicht ableiten. Lege zuerst fest, welche Folgen die Zustellung hat, und wähle dann die QoS-Stufe. So kannst du gezielter testen, als wenn du erst eine Zahl änderst, nachdem sich eine Benachrichtigung seltsam verhält.
Das Ereignis und seine Folgen
Bevor du eine QoS-Einstellung änderst, notiere das genaue Topic, die Payload, den Publisher und den Empfänger. Bei einem Temperaturbericht können andere Fehler auftreten als bei einem Druck auf einen Button oder einer Verfügbarkeitsmeldung. Den regelmäßig gesendeten Temperaturbericht kann der nächste Messwert ersetzen. Ein Druck auf einen Button kann einmal wichtig sein, aber Probleme verursachen, wenn er zweimal als Befehl verarbeitet wird. Ein Verfügbarkeits-Topic beschreibt möglicherweise die Verbindung einer Anwendung zum Broker und nicht den Zustand eines Dienstes auf dem Gerät.
Mit der MQTT-Integration von Home Assistant können Entitäten und Automationen MQTT-Topics abonnieren. Dadurch wird eine Nachricht aber noch nicht zu einer vollständigen Zustandsprüfung. Die Konfigurationssyntax und die unterstützten MQTT-Funktionen findest du in der Dokumentation. Home Assistant: MQTT Wenn eine Aktion vom tatsächlichen Dienst abhängt, musst du diesen weiterhin separat prüfen.
Halte genau fest, was du nachgewiesen hast. „Der Broker hat eine Veröffentlichung mit dieser QoS-Stufe angenommen“ bedeutet etwas anderes als „Die Automation ist gelaufen“ und wiederum etwas anderes als „Das physische Gerät hat ausgeführt, was in der Payload stand“. Wenn du diese Unterschiede sauber auseinanderhältst, lassen sich Störungen später leichter untersuchen.
Zustellverhalten bei QoS 0, 1 und 2
Die MQTT-Spezifikation definiert drei QoS-Stufen für Anwendungsnachrichten. OASIS MQTT Version 5.0 Sie beschreiben die zugesicherte Zustellung zwischen den beteiligten MQTT-Clients und dem Broker. Sie bewerten nicht die Qualität der Daten.
Bei QoS 0 sieht der Sender keine Wiederholung aufgrund einer fehlenden Bestätigung vor. Das wird üblicherweise als „höchstens einmal“ bezeichnet. Das kann für häufige Meldungen passen, die das nächste Update ersetzen kann, etwa für regelmäßige Messungen, bei denen ein neuer Wert nützlicher ist als ein alter. Lücken können dabei allerdings schwerer zu erkennen sein. Eine fehlende Nachricht allein verrät dir nicht, an welcher Stelle im Netzwerk oder im Client der Fehler aufgetreten ist.
Bei QoS 1 bestätigt der Empfänger die Veröffentlichung. Das wird üblicherweise als „mindestens einmal“ bezeichnet. Bei MQTT 5 werden unbestätigte QoS-1-Veröffentlichungen erneut übertragen, wenn eine Verbindung eine bestehende Sitzung fortsetzt. Beim Empfänger können deshalb Duplikate ankommen. Wenn eine Automation jede Kopie als neuen Befehl behandelt, kann sie eine Benachrichtigung doppelt senden oder eine Aktion wiederholen. Gestalte Payload und Automation so, dass dasselbe Ereignis gefahrlos erneut verarbeitet werden kann, oder erfasse eine Sequenznummer beziehungsweise einen Zeitstempel, den der Publisher selbst verwaltet.
QoS 2 nutzt einen längeren Nachrichtenaustausch, der innerhalb des MQTT-Protokollablaufs eine Zustellung „genau einmal“ sicherstellen soll. Das ist keine allgemeine Zusage für alles, was außerhalb dieses Ablaufs passiert. Es bedeutet weder, dass das reale Ereignis genau einmal stattgefunden hat, noch, dass ein nachgelagerter HTTP-Aufruf genau einmal ausgeführt wurde. Eine Automation könnte nach einem Neustart oder durch eine andere Nachricht erneut ausgelöst werden. QoS 2 verursacht zusätzlichen Protokollaufwand. Nutze es deshalb erst, wenn du begründen kannst, warum die Anwendung dieses Zustellverhalten braucht.
QoS beim Abonnieren
Veröffentlichen und Abonnieren sind getrennte Entscheidungen. Wenn ein Client ein Topic abonniert, fordert er eine maximale QoS-Stufe für die Nachrichten dieses Abonnements an. Der Broker verwendet für die Zustellung die jeweils geltende Stufe. Ein hoher Wert an einer Stelle hebt nicht automatisch die QoS-Stufe aller Nachrichten auf dem gesamten Weg an. Die Spezifikation beschreibt diese Aushandlung. Die Dokumentation oder die Logs deines Brokers können zeigen, was in deiner Installation tatsächlich akzeptiert wurde.
Mit den Mosquitto-Kommandozeilenclients kannst du für einen kleinen, kontrollierten Test Nachrichten mit einer gewählten QoS-Stufe veröffentlichen und abonnieren. Die Optionen sind im Handbuch zu mosquitto_pub und im Handbuch zu mosquitto_sub dokumentiert. Halte das Test-Topic von echten Gerätebefehlen getrennt und verwende in der Test-Payload niemals Passwörter, Adressen oder persönliche Daten.
Mit diesem Ablauf bleiben die Testschritte rückgängig zu machen:
- Lege auf einem Broker und in einem Netzwerk, die du verwaltest, ein eindeutig benanntes Test-Topic an, etwa
lab/qos-check-2026-10-21. - Starte einen Subscriber, der die gewählte QoS-Stufe anzeigt, und notiere den Zeitpunkt seiner Verbindung. Halte seine Client-ID, die QoS-Stufe des Abonnements, die Clean-Session-/Clean-Start-Einstellung und die Sitzungsablaufzeit (Session Expiry) fest.
- Veröffentliche eine klar erkennbare Test-Payload mit QoS 0 und wiederhole den Test anschließend mit QoS 1. Veröffentliche nichts auf einem Befehls-Topic.
- Trenne zu einem kontrollierten Zeitpunkt nur den Test-Subscriber, verbinde ihn erneut und halte fest, was angekommen ist. Um die Zustellung über eine Verbindungsunterbrechung hinweg zu testen, brauchst du eine persistente Sitzung, die mit derselben Client-ID fortgesetzt wird; QoS allein erhält kein Abonnement. Leite aus diesem Ergebnis nicht ab, wie sich andere Geräte verhalten.
- Wenn du eine Automation testest, verwende als erste Aktion einen rückgängig zu machenden Logbucheintrag oder eine dauerhafte Benachrichtigung. Prüfe den Automation-Trace getrennt von der Broker-Ausgabe.
Ergänze denselben Test nur dann um QoS 2, wenn du einen konkreten Grund für den Vergleich hast. Eine erfolgreiche Client-Verbindung beweist nur, dass sich der Client verbinden kann. Sie belegt nicht, dass ein produktiv genutzter Sensor oder eine Automation dieselben Einstellungen verwendet.
Doppelte Nachrichten und wiederholte Folgeaktionen
Wenn eine Automation etwas auslöst oder verändert, plane Wiederholungen und Duplikate ein, bevor du dich auf QoS 1 verlässt. Eine Ereignis-ID in der Payload gibt dem Empfänger einen konkreten Vergleichswert. Ein monoton steigender Zähler oder ein Zeitstempel kann denselben Zweck erfüllen. Verwende aber nur ein Feld, das der Publisher tatsächlich selbst verwaltet und dokumentiert. Eine von einem anderen System angezeigte Zeit lässt sich möglicherweise nicht vergleichen, wenn die Uhren falsch gehen oder sich die Formate unterscheiden.
Wähle eine Aktion, die sich gefahrlos wiederholen lässt, oder baue vor der Ausführung eine gezielte Prüfung ein. Eine Benachrichtigung kann beispielsweise die Ereignis-ID enthalten. Bevor ein Befehl ein Gerät verändert, sollte der gewünschte Zustand mit dem aktuellen Zustand verglichen werden, der über einen autorisierten Zugriff erfasst wurde. Bei einer Warnmeldung kann eine kurze, protokollierte Sperrzeit helfen. Lege das aber als ausdrückliche Regel fest, statt damit unbemerkt Duplikate zu verwerfen, deren Ursache du noch nicht geklärt hast.
Prüfe Retained-Nachrichten separat. Ein Client kann beim späteren Abonnieren eine gespeicherte Zustandsmeldung erhalten. Das bedeutet nicht unbedingt, dass ein aktives Gerät sie gerade erst veröffentlicht hat. Teste Topics für gespeicherte Zustände, Verfügbarkeit und Ereignisse getrennt. Verwende ein Ereignis-Topic nicht zugleich für gespeicherte Zustandsmeldungen, sofern der Publisher das nicht ausdrücklich unterstützt.
QoS bei der Fehlersuche
Wenn eine Nachricht zu fehlen scheint, prüfe die kleinste relevante Kette: Verbindung des Publishers, Broker-Log, Schreibweise des Topics, Abonnement, Home-Assistant-Konfiguration und Automation-Trace. Wenn sie zweimal erscheint, sichere Topic und Payload zusammen mit QoS-Stufe, Zeitpunkt und Client-Logs, bevor du Einstellungen änderst. Diese Aufzeichnung kann helfen, eine Wiederholung durch den Publisher von zwei unabhängigen Veröffentlichungen oder zwei Abonnements zu unterscheiden.
Ein Tool zur Inventarisierung oder Netzwerkbeobachtung kann dir einen weiteren lokalen Hinweis auf Geräte in einem Netzwerk geben, das du verwaltest. Mit DeviceShelf kannst du beispielsweise eine beobachtete Adresse samt Zeitpunkt zusammen mit den MQTT-Nachweisen festhalten. Das beweist weder die MQTT-Zustellung noch die Identität oder Verfügbarkeit eines Geräts oder den Erfolg einer Automation.
QoS hilft dir am meisten, wenn du es auf dokumentierte Folgen abgestimmt hast. Wähle QoS 0, wenn neuere Daten einen früheren Wert ersetzen dürfen. Sorge bei QoS 1 dafür, dass Empfänger mit Duplikaten umgehen können. Nutze QoS 2 nur bei einem nachgewiesenen Bedarf auf Protokollebene und teste anschließend den gesamten relevanten Weg. Eine Garantie hast du damit weiterhin nicht. Du hast aber eine genaue, wiederholt prüfbare Erwartung an das nächste Ereignis.