Templates mit fehlenden und unbekannten Werten robust machen

Eine Zahl auf dem Dashboard wirkt eindeutig. Doch hinter der Anzeige können ein aktueller Messwert, ein alter Zustand oder ein still eingesetzter Ersatzwert stecken. Für eine hübsche Karte mag dieser Unterschied zunächst unsichtbar bleiben. Sobald dieselbe Zahl eine Automation beeinflusst, bekommt er praktische Bedeutung. Ein fehlender Sensor darf nicht versehentlich eine günstige Situation vortäuschen. Gute Templates beginnen deshalb mit der Frage, welche Aussage die vorhandenen Daten tatsächlich erlauben, bevor sie diese Aussage passend formatieren.

Als Beispiel dient ein erfundener Feuchtigkeitssensor in einem Abstellraum. Er liefert Prozentwerte, aus denen eine reine Hinweiszeile entstehen soll. Die Zeile steuert keine Heizung und trifft keine gesundheitliche Bewertung. Ihre Schwellenwerte sind frei gewählte Demonstrationswerte. Das begrenzte Beispiel macht die Datenbehandlung sichtbar, ohne einen konkreten privaten Raum oder eine reale Gerätekonfiguration zu beschreiben. Erst nach dem Test der Anzeige könnte eine weitere Funktion auf den sauber unterschiedenen Zuständen aufbauen.

Rohwert, Bedeutung und Darstellung trennen

Ein Template übernimmt häufig drei Aufgaben gleichzeitig: Es liest einen Zustand, bewertet ihn und baut einen Text. Für die Entwicklung werden diese Aufgaben zunächst getrennt betrachtet. Der Rohwert ist die tatsächlich gelieferte Information. Die Bewertung entscheidet, ob diese Information für den Zweck brauchbar ist. Die Darstellung erklärt das Ergebnis für eine Person. Wenn alle drei Schritte in einer einzigen schwer lesbaren Zeile verschwinden, lässt sich ein unerwarteter Hinweis kaum noch einer konkreten Ursache zuordnen.

Home Assistant stellt Entitätszustände in Templates als Text bereit. Für numerische Vergleiche ist daher eine passende Umwandlung nötig. Die offizielle Dokumentation zu Datentypen und Umwandlung erläutert diese Unterscheidung und die Ersatzwerte bei fehlgeschlagener Konvertierung. Für unser Beispiel ist die eigentliche Entwurfsfrage jedoch nicht nur, wie Text zur Zahl wird. Entscheidend ist, welche Bedeutung der gewählte Ersatz anschließend bekommt und ob die Anzeige sie wahrheitsgemäß wiedergibt.

Eine intern eingesetzte Null ist beispielsweise keine gemessene Luftfeuchtigkeit. Würde die Anzeige daraus „sehr trocken“ machen, hätte sie eine fachliche Aussage erfunden. Deshalb soll der Fehlerweg einen eigenen Text erhalten. Eine beliebige Zahl ist kein geeigneter universeller Ausweg aus einem Datenproblem. Der Zweck des Templates bestimmt, ob fehlende Informationen die Anzeige aussetzen, eine unvollständige Zusammenfassung erzeugen oder einen ausdrücklich gekennzeichneten Ersatz erlauben. Diese Entscheidung gehört in die Beschreibung der Funktion.

Die erwarteten Eingaben zuerst aufschreiben

Vor dem eigentlichen Template entsteht eine kleine Fallliste. Für das Beispiel gibt es einen gültigen niedrigen Wert, einen gültigen höheren Wert, die echte Null, den Grenzwert, einen nicht numerischen Text und einen Wert außerhalb des für Prozentangaben vorgesehenen Bereichs. Diese Fälle werden künstlich vorbereitet. Sie hängen nicht davon ab, ob der reale Sensor zufällig gerade einen passenden Wert liefert. So lässt sich jede gewünschte Entscheidung überprüfen, ohne im Raum eine bestimmte Umgebung herstellen zu müssen.

Die echte Null ist ein besonders wichtiger Fall. Sie darf nicht mit einem fehlenden Wert verwechselt werden, auch wenn eine solche Messung im konkreten Einsatz ungewöhnlich wäre. Ebenso wird ein numerisch lesbarer negativer Wert nicht allein wegen seiner erfolgreichen Umwandlung als brauchbare Prozentangabe behandelt. Syntaktische Lesbarkeit und fachliche Plausibilität sind zwei verschiedene Prüfungen. Für andere Messgrößen gelten andere plausible Bereiche; eine Temperatur kann zum Beispiel durchaus negativ sein. Das Beispiel wird daher nicht als allgemeiner Sensorfilter ausgegeben.

Auch der genaue Grenzwert wird bewusst aufgenommen. Soll ein Hinweis ab sechzig Prozent erscheinen oder erst oberhalb davon? Ohne diese Festlegung kann ein späterer Wechsel zwischen > und >= unbemerkt die Bedienregel ändern. Hier wird der höhere Hinweis bereits bei sechzig verwendet. Die Zahl dient ausschließlich dem Vergleich im Entwurf. Wer eine tatsächliche Raumfunktion plant, muss deren Bedeutung separat begründen und sollte die Anzeige nicht mit einer fachlichen Beratung verwechseln.

Eine kurze Hinweiszeile entwerfen

Der folgende Ausschnitt ist ein Template für eine Textausgabe, etwa im Template-Editor. Er ist keine vollständige YAML-Konfiguration für einen numerischen Sensor. Der erfundene Entitätsname muss beim Übertragen angepasst werden. Zunächst wird der Rohwert gelesen. Ist er nicht numerisch verwertbar, entsteht eine klare Fehlanzeige. Bei einer Zahl wird zusätzlich der Bereich geprüft. Erst danach folgt die Einordnung für die Demonstration. Diese Reihenfolge verhindert, dass eine Formatierung bereits unbrauchbare Eingangsdaten überzeugend aussehen lässt.

{% set raw = states('sensor.beispiel_abstellraum_feuchtigkeit') %}
{% if not is_number(raw) %}
  Kein auswertbarer Messwert
{% else %}
  {% set value = raw | float(none) %}
  {% if value < 0 or value > 100 %}
    Messwert außerhalb des erwarteten Bereichs
  {% elif value >= 60 %}
    Beispielhinweis: {{ value | round(0) }} Prozent
  {% else %}
    Beispielbereich: {{ value | round(0) }} Prozent
  {% endif %}
{% endif %}

Die Ausgabe ist absichtlich nüchtern. Sie behauptet weder einen Geräteschaden noch eine bestimmte Ursache für das fehlende Ergebnis. Ein unlesbarer Zustand kann unterschiedliche Gründe haben, und das Template hat nicht automatisch die nötigen Informationen zur Diagnose. Der Ausdruck „kein auswertbarer Messwert“ beschreibt seine eigene Grenze. Eine separate Geräteansicht kann weitere Hinweise liefern. So bleibt der Text auch dann korrekt, wenn sich die technische Ursache eines Ausfalls von einem Fall zum nächsten unterscheidet.

Einen Fehler nicht unsichtbar normalisieren

Ersatzwerte können in manchen Berechnungen sinnvoll sein. Wenn ein bewusst optionaler Summand fehlen darf, kann ein klar dokumentierter Ersatz Teil des Modells sein. Bei einer Raumfeuchtigkeit wäre ein stiller Ersatz durch Null dagegen eine falsche Beobachtung. Die entscheidende Frage lautet deshalb nicht, ob ein Ausdruck ohne Fehlermeldung auswertet. Sie lautet, ob sein Ergebnis noch dieselbe fachliche Aussage trägt. Ein technisch erfolgreiches Template kann inhaltlich irreführend sein.

Für eine Oberfläche lohnt sich eine eigene Gestaltung des fehlenden Zustands. Ein kurzer Text und eine zurückhaltende Kennzeichnung reichen häufig aus. Eine leere Fläche lässt die Person dagegen raten, ob kein Sensor vorhanden ist oder nur die Darstellung nicht geladen wurde. Ebenso kann ein unverändert stehen gelassener Wert wie eine aktuelle Messung wirken. Falls ein letzter bekannter Wert gezeigt werden soll, muss sein Alter oder sein ausdrücklich historischer Charakter sichtbar werden. Der Entwurf darf Aktualität nicht allein durch eine ordentlich formatierte Zahl suggerieren.

Der Fehlerweg wird genauso sorgfältig formuliert wie der Normalweg. Er enthält einen sinnvollen nächsten Schritt, soweit dieser aus den vorhandenen Informationen folgt. Im Beispiel könnte das Öffnen der Sensoransicht helfen. Ein pauschaler Aufruf zum Neustart wäre weniger passend, weil das Template die Ursache gar nicht kennt. Präzise begrenzte Aussagen sparen dadurch nicht nur Text, sondern verhindern auch, dass harmlose Darstellungslücken unnötige Eingriffe in die gesamte Installation auslösen.

Die Anzeige von einer numerischen Entität unterscheiden

Eine Textkarte darf einen Satz als Ergebnis liefern. Ein numerischer Sensor verfolgt einen anderen Zweck und sollte nicht zwischen Prozentzahl und beliebigem Fehlertext wechseln. Wenn aus dem Beispiel eine eigene numerische Template-Entität entsteht, werden Zustand und Verfügbarkeit entsprechend dem vorgesehenen Entitätstyp gestaltet. Die Template-Integration dokumentiert die dafür verfügbaren Konfigurationsmöglichkeiten. Der oben gezeigte Textausschnitt wird also nicht unverändert in jedes Feld kopiert, nur weil beide Stellen Templates unterstützen.

Diese Trennung erleichtert auch spätere Erweiterungen. Eine einzige sauber beschriebene numerische Größe kann von mehreren Darstellungen verwendet werden, während die Hinweiszeile ihre eigene Sprache und Rundung besitzt. Umgekehrt sollte ein bereits gerundeter Anzeigeausdruck nicht unbemerkt die Grundlage einer feineren Berechnung werden. Im Beispiel ist die gerundete Prozentangabe eine Entscheidung für die Lesbarkeit. Die Bewertung des Grenzwerts verwendet weiterhin den vorher eingelesenen Zahlenwert.

Für die Pflege wird festgehalten, welche Ebene andere Automationen verwenden dürfen. Ein menschenlesbarer Satz ist keine stabile Schnittstelle für eine weitere Regel. Schon eine sprachliche Verbesserung könnte sonst deren Verhalten verändern. Ein definierter Zustand oder eine passende numerische Entität ist dafür besser geeignet. Die Oberfläche darf dann verständlicher werden, ohne dass eine andere Automation plötzlich ein bestimmtes Wort nicht mehr erkennt.

Die Fälle unabhängig vom aktuellen Raumzustand testen

Für den ersten Test kann die Zeile zum Lesen des Sensors vorübergehend durch einen festen Beispieltext ersetzt werden. Nacheinander werden etwa '45', '60', '0', 'unknown', 'unavailable', 'abc' und '130' eingesetzt. Die erwartete Ausgabe wird vor dem Ausführen notiert. Dadurch entsteht eine einfache Tabelle aus Eingabe und Entscheidung. Nach dem Versuch wird die ursprüngliche Lesezeile wiederhergestellt. Die Testwerte dürfen nicht versehentlich als dauerhafte Datenquelle stehen bleiben.

Anschließend folgt der Test mit der tatsächlichen Testentität. Er prüft eine andere Ebene: ob der richtige Name verwendet wird und der reale Zustand dieselbe Form besitzt wie die vorbereiteten Werte. Eine Verwechslung der Entität kann selbst ein logisch korrektes Template unbrauchbar machen. Deshalb werden künstliche Fallprüfung und tatsächliche Anbindung getrennt dokumentiert. Die erste prüft die Entscheidung, die zweite die Verbindung zu ihrer vorgesehenen Eingabe.

Ein weiterer Durchlauf betrachtet die Darstellung auf einem kleinen Bildschirm. Längere Fehltexte dürfen nicht wichtige Bedienelemente verdrängen. Gleichzeitig sollen sie nicht so stark gekürzt werden, dass die Unterscheidung zwischen fehlender und ungewöhnlicher Messung verschwindet. Das Beispiel verwendet zwei verschiedene Aussagen, weil beide Situationen unterschiedliche Untersuchungen nahelegen. Die mobile Ansicht wird daher ausdrücklich auch im Fehlerfall geprüft, nicht nur mit einer kurzen zweistelligen Prozentzahl.

Mehrere Messwerte nicht vorschnell zusammenziehen

Wird später ein zweiter Sensor ergänzt, entstehen neue fachliche Fragen. Soll eine gemeinsame Anzeige nur bei zwei gültigen Werten erscheinen? Darf sie mit einem Wert fortfahren und muss sie dann als unvollständig gekennzeichnet werden? Ein Durchschnitt kann mathematisch korrekt berechnet und trotzdem missverständlich sein, wenn die Person zwei Räume erwartet, tatsächlich aber nur einer einfließt. Die Zahl gültiger Beiträge ist dann Teil der Aussage und gehört in die Darstellung oder ihre Erläuterung.

Für jede Ergänzung wird deshalb dieselbe kleine Fallliste erweitert. Neben zwei normalen Werten gibt es einen fehlenden, zwei fehlende und widersprüchlich wirkende Werte. Die ursprünglichen Einzeltests bleiben erhalten. Damit wird sichtbar, ob eine bequemere gemeinsame Formel die bisher sorgfältig getrennten Zustände wieder vermischt. Eine kurze, erklärte Berechnung ist langfristig hilfreicher als eine elegante Filterkette, deren Umgang mit fehlenden Eingaben niemand mehr benennen kann.

Verständlichkeit als Wartungshilfe behalten

Ein gutes Template macht seine Annahmen lesbar: erwartete Eingabe, verwendete Einheit, Fehlerweg und Bedeutung der Ausgabe. Für das Beispiel genügen wenige klar getrennte Schritte. Eine spätere Person kann den Grenzwert ändern, ohne die Behandlung eines Ausfalls neu erfinden zu müssen. Sie kann auch die Formulierung verbessern, ohne eine numerische Schnittstelle anzutasten. Diese Trennung ist der eigentliche Gewinn der zusätzlichen Sorgfalt.

Der fertig geprüfte Ausdruck wird zusammen mit seiner Fallliste abgelegt. Bei einer Änderung der Integration oder des Sensornamens wird nicht nur nach einer sichtbaren Zahl gesucht, sondern die gesamte kleine Prüfung wiederholt. So bleibt ein fehlender Messwert auch in einer späteren Fassung ein fehlender Messwert. Die Anzeige zeigt dann nicht bloß irgendein berechenbares Ergebnis, sondern eine Aussage, deren Bedeutung für die vorhandenen Daten bewusst festgelegt wurde.