Home-Assistant-Energieübersicht: device_class, Einheit und state_class in der Discovery-Nachricht

Der Sensor kommt an. Er zeigt eine Zahl, die Zahl ändert sich, der Verlauf zeichnet eine Linie. Dann wird die Energieübersicht geöffnet, die Liste möglicher Quellen ist kurz, und der Sensor steht nicht darin – ohne Fehlermeldung irgendwo, denn aus Sicht des Systems ist nichts schiefgegangen.

Was fehlt, ist die Übereinstimmung dreier Felder der Entdeckungsnutzlast. Jedes davon ist freiwillig, jedes wird für sich angenommen, und erst die Kombination entscheidet, ob eine Entität eine Zahl in einem Diagramm ist oder eine Größe, die sich aufsummieren lässt.

Wohin die Nutzlast geht und warum sie dort bleibt

Entdeckung ist eine Nachricht auf einem Topic, das der Broker behält: homeassistant/<Komponente>/<Knoten>/<Objekt>/config, veröffentlicht mit gesetztem Retain-Merker. Behalten heißt, dass der Broker sie Home Assistant nach jedem Neustart erneut zustellt – deshalb übersteht ein MQTT-Gerät einen Neustart, ohne dass das Gerät etwas senden müsste.

# anlegen, behalten
mosquitto_pub -h broker -r -t "homeassistant/sensor/zaehler01/energie/config" -m "$(cat sensor.json)"

# entfernen: leere Nutzlast auf dasselbe Topic, wieder behalten
mosquitto_pub -h broker -r -t "homeassistant/sensor/zaehler01/energie/config" -m ""

Der zweite Befehl ist der, der meist fehlt. Die Entität in der Oberfläche zu löschen, entfernt sie bis zum nächsten Neustart; dann spielt der Broker die behaltene Konfiguration wieder ein, und das Gerät ist zurück. Eine MQTT-Entität ist erst weg, wenn das Topic leer ist, das sie erzeugt hat.

Die drei Felder, die alles entscheiden

device_class erklärt, um welche Art Größe es sich handelt, und legt damit fest, welche Einheiten dazu erlaubt sind. Für energy sind das Wh, kWh und MWh. Für power sind es W und kW, und ein Leistungssensor kommt als Energiequelle nicht in Frage, gleich was sonst in der Nutzlast steht – Watt ist eine Rate, und eine Übersicht, die Raten aufaddiert, wäre falsch.

unit_of_measurement wird buchstäblich verglichen. kWh geht durch, kwh und KWH nicht, und das Ergebnis ist keine abgelehnte Nutzlast, sondern eine Entität, deren Einheit nicht zur Klasse passt und die sich deshalb nicht auswählen lässt. Das ist die mit Abstand häufigste Ursache, und sie ist auf jedem Bildschirm unsichtbar außer auf dem, auf dem die Entität nicht erscheint.

state_class entscheidet, ob überhaupt Langzeitstatistik entsteht. Ohne dieses Feld bleibt der Wert im kurzen Verlauf und sonst nirgends; mit dem falschen ebenso. Nur total und total_increasing erzeugen die Stundensummen, aus denen eine Energieübersicht liest.

total_increasing, total, measurement

total_increasing ist für Zähler gedacht, die nur aufwärts zählen. Ein Rückgang wird als Zählerwechsel gelesen – ein getauschtes Gerät, eine Firmware, die bei null beginnt – und der neue Wert zählt ab dort, statt als negativer Verbrauch. Es braucht kein last_reset und ist für nahezu jeden Energiezähler die richtige Wahl.

total ist für Werte, die auch fallen können, etwa eine Bilanz, und erwartet einen last_reset-Zeitpunkt, um zu wissen, wann eine Periode begann. measurement ist für alles, was ein Zustand ist und keine Summe: Temperatur, Leistung, Feuchte. Es ist die Angabe, zu der alle greifen, weil sie neutral klingt, und es ist der Grund, warum ein tadelloser Zählerstand einen schönen Verlauf ergibt und nie eine einzige Kilowattstunde.

Eine Feinheit von total_increasing sollte bekannt sein, bevor sie eintritt: Ein Wert, der nach unten springt, wird bei genügend großem Sprung als Zählerwechsel gelesen, und der gesamte neue Stand wird in dieser Stunde als Verbrauch verbucht. Ein Zähler, der gelegentlich einen alten, niedrigeren Wert meldet, erzeugt also keinen kleinen Fehler, sondern eine Spitze in Höhe des ganzen Zählerstands.

Welches Symptom aus welcher Zeile kommt

Fünf der sechs zeigen sich als etwas anderes als ein Fehler. Das ist die Gestalt des ganzen Problems: Eine Entdeckungsnutzlast wird Feld für Feld angenommen oder übergangen, und ein übergangenes Feld hinterlässt keine Spur außer der Fähigkeit, die es lautlos vorenthalten hat.

Der Sensor, der seinen letzten Wert für immer behält

Ein MQTT-Sensor ohne Verfügbarkeitsbehandlung kennt kein Offline. Der letzte eingetroffene Wert bleibt stehen, und bei einem Zählerstand ist das schlimmer als eine Lücke: Die Zahl wirkt plausibel, der Verlauf ist flach, und die Energieübersicht meldet einen Haushalt, der seit Dienstag nichts verbraucht hat.

availability_topic mit einem letzten Willen auf der Geräteseite ist die saubere Lösung, expire_after die grobe – eine Sekundenzahl, nach der der Zustand als nicht verfügbar gilt, wenn nichts Neues eintrifft. Für einen Zähler, der alle zehn Sekunden sendet, sind dreihundert großzügig und fangen ein totes Gerät trotzdem binnen fünf Minuten ab.

Statistik schaut nicht zurück

Langzeitstatistiken entstehen einmal je Stunde aus den Zuständen, die in dieser Stunde aufgezeichnet wurden. Eine am Freitag berichtigte Nutzlast erzeugt keine Statistik für Montag bis Donnerstag, weil es nichts gab, woraus sie hätte entstehen können – die Zustände waren da, nur hatte niemand angeordnet, sie zu summieren.

Das Loch lässt sich im Statistikeditor unter den Entwicklerwerkzeugen von Hand schließen, der einzelne Summen ändern kann, und bei einem Zähler, auf dessen Stände es ankommt, lohnt sich das. Es ist zugleich der Grund, die drei Felder am Tag der Einrichtung zu prüfen statt am Monatsende: Alles andere in einer Entdeckungsnutzlast lässt sich später berichtigen, ohne dass etwas verloren geht.