StateGuard: Home Assistant meldet, wenn Geräte still werden

Ein Akku wird leer. Ein Zigbee-Gerät fällt aus dem Netz. Ein Sensor meldet seit zwei Tagen denselben Wert, weil er in Wahrheit tot ist. Home Assistant zeigt in solchen Fällen gern dauerhaft unavailable an und erwähnt es nicht weiter. StateGuard schließt diese Lücke: Man versieht die Geräte, auf die es ankommt, mit einem Label, und die Integration meldet sich, wenn sie nicht mehr antworten.

Was überwacht wird

Eine Überwachung („Watch“) prüft sechs Bedingungen: nicht verfügbar oder unbekannt, zu lange keine Daten, ein numerischer Schwellwert (etwa Akku unter 25 %, mit separatem Erholungswert, damit der Wert nicht um die Grenze flattert), ein bestimmter Zustand oder dessen Gegenteil, ein zu lange gehaltener Zustand (ein Schloss, das über eine Stunde unlocked ist) und eine Entität, die gar nicht mehr existiert.

Die Prüfung „keine Daten“ misst gegen last_reported, nicht gegen last_changed. Der Unterschied zählt: Ein Homematic-Batteriesensor kann drei Tage bei 75 % stehen und trotzdem alle halbe Stunde zuverlässig melden. Gemessen an last_changed sähe er tot aus. Ausgelöst werden die Prüfungen sofort bei Zustandsänderungen, dazu kommt alle 30 Sekunden ein Durchlauf für alles, was kein eigenes Ereignis hat – eine Entität, die verstummt ist, eine ablaufende Karenzzeit oder eine fällige Eskalation.

Warum nicht einfach eine Automation

Eine einzelne Überwachung lässt sich als Automation bauen. Mühsam ist, was danach kommt: nachts um drei nicht für einen Sensor geweckt zu werden, der um acht Uhr noch genauso kaputt ist, keine fünfzig Nachrichten, wenn ein Zigbee-Koordinator ausfällt, kein Alarm nach jedem Neustart, wenn halb Haus kurz unavailable ist, und ein Protokoll darüber, was wann und wie lange kaputt war. StateGuard ist diese zweite Hälfte, einmal gebaut und im Panel statt in YAML konfiguriert.

Ruhe, wenn sie angebracht ist

Die Unterdrückungskette ist der Kern. Es gibt zwei Arten, eine Meldung zurückzuhalten, und die Unterscheidung ist bewusst:

• Was man selbst verlangt – Überwachung aus, Watch pausiert, Schlummern, Bestätigen –, zieht eine stehende Meldung zurück: Der Sensor geht aus, die Benachrichtigung verschwindet.
• Was das System entscheidet – Karenzzeit nach dem Neustart, kein Internet, ausgefallene Integration, ausgefallenes übergeordnetes Gerät –, hält nur neue Meldungen zurück. Bereits Gemeldetes bleibt gemeldet, ein Neustart benachrichtigt also nicht erneut über bekannte Probleme.

Ruhezeiten sind keines von beidem: Die Nachricht wird zurückgestellt und danach gesendet, aber nur, wenn das Problem noch besteht. Es lassen sich mehrere Zeiträume definieren, weil Wochenenden meist anders sind, etwa 22:00–07:00 von Montag bis Freitag und 23:00–09:00 am Wochenende. Fällt eine Integration oder eine Bridge aus, kommt eine Nachricht statt fünfzig; StateGuard folgt dazu via_device nach oben.

Oberfläche und Einrichtung

Alles passiert in einem eigenen Panel in der Seitenleiste: Übersicht, Watch-Editor, Kanäle, Schweregrade, Störungsverlauf und Einstellungen. Der Editor zeigt vor dem Speichern in einer Live-Vorschau, welche Entitäten die aktuelle Auswahl abdeckt. Labels sind der Hauptselektor; dazu kommen Bereiche, Etagen, Domänen, Integrationen und einzelne Entitäten sowie Ausnahmen über ein Ignorier-Label. Ausgefüllte Kategorien verknüpfen sich mit UND, einzeln aufgeführte Entitäten kommen mit ODER hinzu.

Fünf Vorlagen decken die üblichen Fälle ab: Verfügbarkeit, Akku schwach, Keine Daten, Sicherheitsgeräte und Fehlende Entitäten. Die Akku-Vorlage nutzt 25 % statt 20 %, weil viele Geräte grob gestuft melden – Homematic mit 100 / 75 / 50 / 37,5 / 25 / 0 – und eine Grenze von 20 % dann nur bei null auslösen würde. Schweregrade definiert man frei, jeder mit Priorität, Kanälen, Verhalten in Ruhezeiten, Bündelungsfenster, Wiederholintervall und Eskalationsstufe.

Benachrichtigungen

Als Kanal geht jeder Home-Assistant-Dienst (notify.mobile_app_…, ein Telegram-Bot, die SMTP-Integration, ein Skript) sowie SMTP, Telegram, Pushover und ntfy mit eigenen Zugangsdaten. Jeder Kanal kann einen eigenen Nachrichtentext als Jinja2-Vorlage tragen und hat eine Test-Schaltfläche, damit man ein falsches Token jetzt und nicht beim nächsten Ausfall bemerkt. Die Zugangsdaten liegen im Speicher von Home Assistant und werden nie zurück an den Browser geschickt.

Daneben löst StateGuard das Ereignis stateguard_alert aus, auf das sich Automationen setzen lassen, und bringt Dienste mit: stateguard.snooze, acknowledge, pause_watch, resume_watch, run_check sowie export_config und import_config für Sicherungen. Pro Watch gibt es einen Binärsensor, dazu sensor.stateguard_problems, einen Zähler je Schweregrad und einen Schalter switch.stateguard_monitoring, der alles pausiert. Der Verlauf liegt in stateguard_history.db neben der Konfiguration, bewusst nicht in der Recorder-Datenbank; die Aufbewahrung beträgt standardmäßig 90 Tage.

Die Lovelace-Karte

Die Karte custom:stateguard-card registriert sich selbst und erscheint im Kartenauswahldialog. Sie zeigt aktuelle Probleme, kann sich mit hide_when_healthy komplett ausblenden und lässt sich nach Schweregraden oder Watches filtern. Dashboards im YAML-Modus brauchen einmalig den Ressourceneintrag /stateguard-frontend/stateguard-card.js.

Nachbesserungen von 0.1.1 bis 0.2.1

• 0.1.1: Die Karte blieb für Nicht-Administratoren leer, weil jeder Websocket-Befehl Adminrechte verlangte. Es gibt jetzt einen eigenen Lesebefehl für alle Nutzer, der nur enthält, was zur Anzeige eines Problems nötig ist. Wer StateGuard in der Seitenleiste sieht, ist einstellbar (nur Administratoren oder alle, mit schreibgeschützter Übersicht).
• 0.1.2: Die Karte bekam einen visuellen Editor, vor allem für die beiden Filter, denn Watch-IDs sind Zufallszeichenfolgen. Außerdem blieb die Karte nach dem Platzieren bis zu zehn Sekunden leer.
• 0.1.3: Ein Watch in der Liste lässt sich aufklappen und zeigt jede abgedeckte Entität mit Name, ID, Zustand und in Rot dem Grund eines Problems; Probleme stehen oben. Die Liste wird erst beim Öffnen geladen, weil ein Watch über eine ganze Domäne Tausende Entitäten abdecken kann.
• 0.2.0: Neun weitere Sprachen: Niederländisch, Französisch, Spanisch, Italienisch, Polnisch, Dänisch, Schwedisch, Tschechisch und Portugiesisch, einschließlich der zur Laufzeit zusammengesetzten Benachrichtigungstexte. Die Kataloge werden pro Sprache nachgeladen; das Panel bleibt bei 16 kB gzip, die Karte bei 3 kB, jede Sprache kostet 5 kB, die nur ihre Nutzer laden.
• 0.2.1: Ein zweiter Watch überschrieb den ersten. Das Panel schickt beim Anlegen eine leere ID, der Server füllte nur fehlende Schlüssel auf, eine leere Zeichenfolge zählte als vorhanden. Schweregrade und Kanäle hatten denselben Fehler. Einträge ohne ID bekommen beim Laden eine und eine Warnung im Log; ein früher überschriebener Watch lässt sich nicht wiederherstellen. Wer mit 0.2.0 oder älter mehrere Watches über das Panel angelegt hat, sollte aktualisieren.

Installation und Abgrenzung

In HACS unter „Benutzerdefinierte Repositories“ https://github.com/sphings79/stateguard-home-assistant mit der Kategorie „Integration“ hinzufügen, StateGuard installieren, Home Assistant neu starten und unter Geräte & Dienste die Integration hinzufügen. Dabei ist nichts einzutragen; weiter geht es im Panel mit einer Vorlage. Voraussetzung ist Home Assistant 2026.1 oder neuer.

StateGuard überschneidet sich mit Watchman: Watchman findet fehlende und nicht verfügbare Entitäten auf Abruf, StateGuard ergänzt labelgesteuerte Regeln, Schwellwerte, Erkennung veralteter Daten, Eskalation, Ruhezeiten und einen Verlauf. Beide können nebeneinander laufen. Alles läuft lokal; nur die gewählten Kanäle wie Telegram, Pushover und ntfy sprechen nach außen, und mit einer Konnektivitäts-Entität bleiben sie bei Leitungsausfall still.