MQTT-Nachrichten und Zustände nachvollziehbar organisieren

Auf dem Dashboard steht eine Temperatur, obwohl das zugehörige Gerät längst ausgeschaltet ist. Technisch kann diese Anzeige korrekt aus einer zuletzt empfangenen Nachricht entstanden sein. Inhaltlich fehlt ihr jedoch eine entscheidende Information: Ist der Messwert noch aktuell? MQTT transportiert Nachrichten zuverlässig nach seinen jeweiligen Regeln, erklärt aber nicht von selbst, wie lange eine Temperatur gelten soll oder ob ein angeschlossenes Gerät gerade funktioniert.

Eine verständliche Integration braucht deshalb einen kleinen Vertrag zwischen Sender und Empfänger. Er beschreibt Namen, Inhalte und erwartetes Verhalten bei Unterbrechungen. Als Beispiel dient ein vollständig erfundener Werkstattsensor. Seine Nachrichten enthalten künstliche Werte und verwenden einen eigenen Beispielsnamensraum. Die gezeigte Konfiguration beschreibt einen Entwurf zum Prüfen, keine aktive Installation und keine realen Geräte eines Haushalts.

Die Beteiligten und ihre Aufgaben benennen

Im Entwurf veröffentlicht das Gerät Nachrichten. Ein Broker nimmt sie entgegen und verteilt sie an passende Abonnenten. Home Assistant liest die vorgesehenen Topics und bildet daraus Entitäten. Diese Trennung ist praktisch: Wenn eine Anzeige fehlt, lässt sich nacheinander prüfen, ob das Gerät gesendet hat, ob die Nachricht beim Broker sichtbar ist und ob die Integration sie richtig verarbeitet hat.

Für jede Stufe sollte ein eigener Nachweis existieren. Eine Verbindung zum Broker beweist noch nicht, dass eine gültige Messung vorliegt. Eine sichtbare Nachricht beweist noch nicht, dass ihre Felder zum konfigurierten Template passen. Und eine erstellte Entität beweist noch nicht, dass sie nach dem nächsten Neustart wieder sinnvoll versorgt wird. Diese Unterscheidungen machen die spätere Fehlersuche wesentlich kürzer.

Die MQTT-Integration von Home Assistant beschreibt die Anbindung und vorgesehene Mechanismen wie Discovery und Verfügbarkeitsmeldungen. Für einen eigenen Sender lohnt sich trotzdem eine zusätzliche, kleine Schnittstellenbeschreibung. Sie enthält die projektspezifische Bedeutung der Nachrichten, die eine allgemeine Integrationsdokumentation naturgemäß nicht kennen kann.

Topics nach Bedeutung gliedern

Ein Topic sollte erkennen lassen, zu welchem Gerät und zu welcher Art von Information eine Nachricht gehört. Im Beispiel gibt es für das Gerät sensor-a getrennte Bereiche für Messwerte und Verfügbarkeit. Falls später ein steuerbares Gerät hinzukommt, erhält es außerdem einen ausdrücklich benannten Befehlskanal. Dadurch wird eine gemeldete Tatsache nicht mit einer gewünschten Änderung verwechselt.

beispiel/werkstatt/sensor-a/state
beispiel/werkstatt/sensor-a/availability
beispiel/werkstatt/leuchte-a/set
beispiel/werkstatt/leuchte-a/state

Die Namen sind absichtlich unspektakulär. Sie sollen keine private Raumstruktur veröffentlichen und keine wechselnde Anzeigenbeschriftung enthalten. Ein sichtbarer Gerätename kann später geändert werden, ohne die technische Schnittstelle umzubenennen. Im Inventar steht, welches physische Beispielgerät dem stabilen Namen zugeordnet ist. Diese Zuordnung ist besonders nützlich, wenn ein Sensor versetzt oder ein Gerät ersetzt wird.

Für größere Projekte wird außerdem festgelegt, welche Namensebene gemeinsam abonniert werden darf. Ein Diagnosewerkzeug muss nicht automatisch sämtliche Nachrichten erhalten. Eine enge Auswahl erleichtert das Lesen und begrenzt unbeabsichtigte Datenweitergabe. Die Topic-Struktur sollte deshalb zur vorgesehenen Zuständigkeit passen, statt erst nachträglich aus zufällig entstandenen Namen zusammengesetzt zu werden.

Ein kleines Nachrichtenformat festlegen

Der fiktive Sensor sendet ein JSON-Objekt mit einer Temperatur und einer Formatversion. Die Temperatur steht als Zahl im vereinbarten Maßstab; die Einheit wird in der Schnittstellenbeschreibung festgehalten. Eine Versionsangabe erleichtert spätere Änderungen. Sie ersetzt keine sorgfältige Migration, macht aber sichtbar, ob Sender und Empfänger über dasselbe Format sprechen.

{
  "schema": 1,
  "temperature_c": 21.4
}

Zur Beschreibung gehören auch Fehlerfälle. Fehlt die Temperatur, darf der Empfänger daraus nicht unbemerkt null Grad machen. Enthält das Feld plötzlich eine Zeichenfolge mit zusätzlicher Einheit, ist das eine Formatänderung und kein gewöhnlicher Messwert. Für solche Nachrichten wird eine eindeutige Behandlung vereinbart: ablehnen, kenntlich machen und die letzte gültige Messung nicht als frisch bestätigt ausgeben.

Die erste Version enthält nur Felder, die tatsächlich benötigt werden. Beliebige Diagnosedaten in derselben Nachricht machen zwar alles leicht erreichbar, koppeln aber unterschiedliche Aufgaben aneinander. Ein ständig wechselnder Zeitstempel kann beispielsweise eine andere Aufzeichnungslast erzeugen als ein ruhig bleibender Messwert. Diagnoseinformationen erhalten daher bei Bedarf einen eigenen, bewusst genutzten Weg.

Einen Sensor verständlich konfigurieren

Das folgende illustrative Fragment verbindet das vereinbarte Zustandsformat mit einer Home-Assistant-Entität. Es setzt eine bereits eingerichtete MQTT-Anbindung voraus. Vor einer Verwendung muss es in eine vorhandene Konfiguration eingepasst werden; ein zweiter gleichnamiger Hauptblock wäre keine saubere Zusammenführung. Die Verfügbarkeitsnachrichten sollen hier ausschließlich online oder offline enthalten.

mqtt:
  sensor:
    - name: "Beispiel Werkstatt Temperatur"
      unique_id: beispiel_werkstatt_sensor_a_temperatur
      state_topic: "beispiel/werkstatt/sensor-a/state"
      value_template: "{{ value_json.temperature_c }}"
      unit_of_measurement: "°C"
      device_class: temperature
      state_class: measurement
      availability_topic: "beispiel/werkstatt/sensor-a/availability"
      payload_available: "online"
      payload_not_available: "offline"
      expire_after: 180

Die MQTT-Sensor-Dokumentation beschreibt diese Felder. expire_after lässt den Zustand nach ausbleibenden Aktualisierungen unverfügbar werden. Im Beispiel beträgt die Frist drei Minuten, weil als Entwurfsannahme mindestens einmal pro Minute eine gültige Messung gesendet wird. Ohne diese Sendervereinbarung wäre die Zahl willkürlich und könnte einen korrekt arbeitenden, selten sendenden Sensor fälschlich als ausgefallen erscheinen lassen.

Das kurze Template validiert noch nicht den gesamten Nachrichtenvertrag. Insbesondere prüft es weder die Formatversion noch fachliche Plausibilität. Für einen produktiven eigenen Sender gehören solche Prüfungen an eine bewusst gewählte Stelle. Das Beispiel zeigt die Zuordnung, nicht eine vollständige Datenbereinigung. Diese Grenze muss bekannt sein, bevor aus der angezeigten Temperatur eine automatische Entscheidung abgeleitet wird.

Verfügbarkeit und Frische getrennt prüfen

Eine Verfügbarkeitsmeldung beantwortet zunächst eine andere Frage als eine aktuelle Messung. Das Gerät kann mit dem Broker verbunden sein und trotzdem keine brauchbaren Sensordaten mehr erzeugen. Deshalb betrachtet der Entwurf beide Ebenen. online bedeutet hier, dass der Sender seinen Kommunikationszustand so meldet. Die Messwertfrist verlangt zusätzlich regelmäßige Aktualisierungen des dafür vorgesehenen Topics.

Für einen unerwarteten Verbindungsverlust kann eine beim Broker hinterlegte Will-Nachricht helfen, den Ausfall sichtbar zu machen. Die Funktionsweise ist Teil des MQTT-Standards. Im Beispiel wird die Zuordnung auf Senderseite eingerichtet und anschließend gezielt getestet. Sie entsteht nicht allein dadurch, dass Home Assistant ein Availability-Topic abonniert.

Auch ein sauberer Neustart braucht eine Vereinbarung. Wann veröffentlicht der Sender online? Schon nach erfolgreicher Verbindung oder erst nach einer gültigen Messung? Beide Bedeutungen sind denkbar, führen aber zu unterschiedlichen Anzeigen. Der Entwurf schreibt seine Wahl ausdrücklich auf. So bleibt verständlich, warum ein Gerät erreichbar sein kann, während seine Temperatur noch nicht als verfügbar gilt.

Retained-Nachrichten bewusst einsetzen

Eine retained veröffentlichte Nachricht kann neuen Abonnenten den zuletzt gespeicherten Inhalt eines Topics liefern. Das ist nützlich für einen bekannten letzten Zustand, macht diesen Inhalt aber nicht automatisch aktuell. Der MQTT-Standard beschreibt den Mechanismus; die fachliche Gültigkeit bleibt eine Entscheidung der Anwendung. Für einen Messwert sind Empfang beim neuen Abonnenten und ursprünglicher Messzeitpunkt unterschiedliche Ereignisse.

Gerade zusammen mit einer Ablaufzeit ist das wichtig. Die MQTT-Sensor-Dokumentation weist darauf hin, dass retained Messwerte beim Neustart erneut zugestellt werden können. Für das Beispiel wird deshalb ausdrücklich geprüft, was bei ausgeschaltetem Sensor und neu gestarteter Integration sichtbar wird. Eine wieder eingespielte alte Zahl darf nicht unbemerkt als Beweis einer neuen Messung interpretiert werden.

Bei Befehlen wird noch sorgfältiger entschieden. Ein alter Schaltwunsch, der einem später verbundenen Empfänger erneut begegnet, kann eine unerwartete Wirkung haben. Der Entwurf verwendet daher keine retained Befehle für die beispielhafte Leuchte. Falls ein anderes System dauerhaft gewünschte Sollzustände speichern soll, braucht es dafür eine eigene klar benannte Semantik und eine Prüfung der Wiederanlaufreihenfolge.

Bestätigung ist mehr als Transport

MQTT bietet verschiedene Zustellqualitäten. Deren Garantien betreffen den Nachrichtentransport nach den Regeln des Protokolls. Sie beweisen nicht, dass eine Leuchte tatsächlich eingeschaltet wurde oder eine Messung fachlich richtig ist. Für die Anwendungslogik wird deshalb eine tatsächliche Rückmeldung getrennt von einem gesendeten Befehl behandelt. Diese Unterscheidung bleibt auch bei einer höher gewählten Zustellqualität notwendig.

Für wiederholbare Befehle ist eine eindeutige Zielangabe oft einfacher zu beherrschen als ein relativer Umschaltbefehl. „Einschalten“ kann erneut verarbeitet werden, ohne dadurch unmittelbar das Gegenteil zu bewirken. „Umschalten“ benötigt dagegen eine besonders sorgfältige Behandlung möglicher Wiederholungen. Im Beispieldesign wird diese Entscheidung vor der Implementierung getroffen, damit Transportverhalten und Gerätewirkung zusammenpassen.

Ein eigener Befehlskanal erhält außerdem eine Rückmeldung über den beobachteten Zustand. Die Oberfläche kann dadurch zwischen angefordert und bestätigt unterscheiden. Bleibt die Bestätigung aus, ist das eine offene Frage. Ein optimistisch sofort geändertes Symbol mag bequem aussehen, sollte aber nicht als bestätigte physische Wirkung ausgegeben werden, wenn diese Information noch fehlt.

Discovery und Identität stabil halten

Für mehrere Geräte kann Discovery die Zuordnung vereinfachen. Die offizielle MQTT-Dokumentation beschreibt, wie Konfigurationsnachrichten bereitgestellt werden und nach einem Neustart wieder verfügbar sein müssen. Im Entwurf bleiben die eindeutigen Kennungen stabil, während sichtbare Namen geändert werden dürfen. Dadurch wird aus einer einfachen Umbenennung nicht versehentlich ein vermeintlich neues Gerät mit parallelen Altentitäten.

Ein Austausch wird als geplanter Übergang behandelt. Vorher steht fest, ob das Ersatzgerät dieselbe fachliche Aufgabe übernimmt und wie alte Konfigurationsnachrichten entfernt oder ersetzt werden. Sonst tauchen nach einem Neustart möglicherweise längst vergessene Definitionen erneut auf. Die Untersuchung betrachtet deshalb sowohl die aktuelle Entitätenliste als auch die Nachrichten, aus denen sie aufgebaut wird.

Zum Test gehört ein vollständiger Wiederanlauf in unterschiedlicher Reihenfolge. Zuerst startet Home Assistant, während der Sender noch fehlt. Danach wird die Reihenfolge umgekehrt. In beiden Fällen soll am Ende dieselbe sinnvolle Zuordnung entstehen. Dieser Test deckt Abhängigkeiten auf, die bei einer Einrichtung im bereits laufenden Gesamtsystem leicht verborgen bleiben.

Zuständigkeiten am Nachrichtenweg begrenzen

Für den Beispielsensor genügt es, seine eigenen Messungen und Verfügbarkeitsinformationen zu veröffentlichen. Er benötigt keinen fachlichen Grund, Befehle für die Leuchte zu senden. Diese Trennung wird bei der Einrichtung der Brokerberechtigungen berücksichtigt. Die genaue Umsetzung hängt vom eingesetzten Broker ab; geprüft wird am Ende das Verhalten: Ein erlaubter Messwert kommt an, ein unzulässiger Schreibversuch auf einen fremden Befehlskanal wird abgewiesen.

Auch ein Diagnosezugang erhält nur den vorgesehenen Lesebereich. Damit bleibt ein Test auf die untersuchte Komponente begrenzt. Zugangsdaten gehören weder in Beispielnachrichten noch in gemeinsam genutzte Fehlerberichte. Für die nachvollziehbare Dokumentation reichen der betroffene Topicbereich, die Art des Versuchs und das beobachtete Ergebnis. Der technische Nachweis benötigt keine Veröffentlichung tatsächlicher Kennwörter oder privater Brokeradressen.

Mit einer kurzen Nachrichtenfolge abnehmen

Die Abnahme beginnt mit einer gültigen künstlichen Messung und einer passenden Verfügbarkeitsmeldung. Danach folgt eine neue Zahl, anschließend eine absichtlich fehlerhafte Nachricht. Für jeden Schritt wird vorher festgelegt, welche Anzeige erwartet wird. Besonders beim Fehlerfall wird geprüft, ob ein alter Wert stehen bleibt und ob Menschen ihn noch irrtümlich für frisch halten könnten.

Anschließend wird der Sender unerwartet getrennt. Die Will- beziehungsweise Verfügbarkeitsbehandlung und die Messwertfrist werden beobachtet. Danach startet nur Home Assistant neu, während der Sender weiterhin fehlt. Dieser kombinierte Fall prüft, ob gespeicherte Nachrichten eine falsche Rückkehr vortäuschen. Erst dann wird das Gerät wieder verbunden und eine neue gültige Messung gesendet.

Die fertige Schnittstellenbeschreibung enthält Topics, Nachrichtenformat, Einheiten, Fristen und Verhalten beim Wiederanlauf. Dazu kommt das Ergebnis der Abnahme mit offenen Einschränkungen. Sie bleibt kurz genug, um bei einer Änderung tatsächlich gelesen zu werden. So ist MQTT mehr als ein Weg, Zahlen auf eine Karte zu bringen: Die Verbindung liefert Zustände, deren Herkunft und Bedeutung sich nachvollziehen lassen.