F04 V3 - BeGiBue/home-assistant-water-leak-guard GitHub Wiki
Die Implementierung folgt Issue #13 und dem freigegebenen V3-Plan. F02 (statisches High) und F08 (Low-Stabilität) bleiben erhalten. Erstmals in 1.2.0-beta.1, stabil seit 2.0.0 (15. Oktober 2026). Die Betas waren auf hydraulischen Einsatz ohne externe Sensoren oder gespeicherte externe Datensätze beschränkt (historisch); F04-FSR-H01 ist in 2.0.0 behoben, externe Lecksensoren werden unterstützt (Details). Ein erfolgreicher Hydrus-Neustart mit Beta.3 wurde am 14. Oktober 2026 vom Benutzer bestätigt; kein Hardwaretest durch die Entwicklung und keine Abnahme sämtlicher Ausfallszenarien.
Beschädigte Store-Bodies werden nicht als leere Neuinstallation überschrieben.
Alarm und Shutoff bleiben konservativ erhalten; ein HA-Reparaturhinweis fordert
eine geprüfte Backup-Wiederherstellung bei gestopptem HA. Konflikte zwischen
externen Event-IDs oder Source/Generation-Schlüsseln erhalten alle Beiträge, aber
sperren betroffene Quittier-/Reset-Aktionen und bleiben über Neustarts markiert.
Seit dem H01-Fix gilt das auch für die Datensätze der konfigurierten externen Melder
selbst (external_sources): Eine fehlende oder unbekannte Phase, eine fehlende Event-ID
eines ACTIVE-Eintrags oder beschädigte IDs, Zeitstempel oder Flags führen in dieselbe
Recovery-Sperre, statt den Alarm zu verwerfen oder eine Identität zu erfinden. Eine
fehlende Liste ebenfalls, und – bei jeder Installation, auch rein hydraulisch – eine von HA als
water_leak_detection.runtime.<entry_id>.corrupt.<Zeit> beiseitegelegte ungültige JSON-Datei.
Ohne Backup: HA stoppen und die Kopie bewusst verschieben (der gespeicherte Zustand geht verloren).
Echte MQTT-Unterbrechungen setzen eine persistierte Ausschlussgrenze: Gepufferte
Vor-Ausfall-Nullmeldungen dürfen ACTIVE niemals beenden. Interne Ticks liefern
weiterhin keine physische Evidenz. Details stehen in der
Low/ACK/Dauer-Dokumentation.
Für neue bzw. nicht gesetzte Optionen gilt eine Burst-Basis von 3.500 L/h. Explizite Nutzerwerte, auch 2.000 L/h, werden nicht überschrieben. Die Schwelle muss zur Installation passen: zwei starke Verbraucher oder ein 3/4”-Schlauch können normale hohe Verbräuche erzeugen. Rohrdurchmesser und statischer Druck reichen nicht zur sicheren Abgrenzung. Als Kalibrierungsansatz sollte die Basis mindestens 20 % über dem tatsächlich beobachteten normalen Maximum liegen. Auch 3.500 L/h garantiert keine Fehlalarmfreiheit. Eine Leckage und normale Nutzung mit identischer Durchflusskurve sind hydraulisch nicht unterscheidbar.
rolling_candidate = bisheriger sicherer Rolling-/Manuell-Kandidat
long_term_candidate = bestätigtes Langzeitmaximum × 1,20
effective_burst = max(konfigurierte Basis, rolling_candidate, long_term_candidate)
Confidence, P95, kurze/lange Gewichtung, Faktor 1,8 und hydraulisches Ceiling bleiben für den Rolling-/Manuell-Kanal bestehen. Das Langzeitmaximum wirkt nur über 1,20, niemals zusätzlich über 1,8, und wird nicht durch das heuristische Ceiling gekappt. High bleibt exakt statisch: standardmäßig 600 L/h, 45 Minuten ODER 500 Liter, Reset nach fünf bestätigten Minuten strikt unter 100 L/h.
Ein Burst benötigt 30 Sekunden bestätigte Evidenz ab Erreichen der effektiven Burst-Grenze. Rapid Rise beschleunigt ausschließlich darüber: mindestens +1.000 L/h je 10 Sekunden, danach eigene zehn Sekunden bestätigte Evidenz ab dem qualifizierenden Report. Die frühere Frist gewinnt. Keine Rückdatierung und keine Verlängerung einer laufenden normalen Frist. Echte Messlücken und relevante Burst-Optionsänderungen starten unbestätigtes Monitoring frisch. ACTIVE bleibt an seinen physischen Reset gebunden: standardmäßig 60 Sekunden unter 500 L/h. High-Bypass unterdrückt weder Burst/Rapid Rise noch externe Sensoren.
Rolling Learning behält standardmäßig 30 Tage, P95, saisonale Gewichtung und Confidence. High-MONITORING bleibt im normalen Lernpfad suspicious. High-Episoden werden niemals in diesen Sample-Pool aufgenommen.
Long-Term Learning nimmt nur unabhängige, sauber beendete High-MONITORING-Episoden
mit Peak unter der konfigurierten Burst-Basis auf. Eine Episode reicht nicht,
zwei ebenfalls nicht. Drei Peaks bestätigen ein Niveau, wenn inklusive gilt:
max_peak <= min_peak × 1,15. Jede spätere Erhöhung braucht drei neue Episoden
über dem bisherigen Maximum. Frühere bestätigte Episoden liefern keine neuen
Stimmen. Die effektive adaptive Burst-Schwelle ist niemals Aufnahmeanker.
So entsteht keine unbegrenzte automatische Lern-Ratsche.
Pending- und Audit-Historie verfallen nicht mit Zeit. Die Speicherung ist nach vollständiger Validierung, Konfliktprüfung, Deduplizierung und deterministischer chronologischer Auswahl gemeinsam auf die neuesten 4096 Einträge begrenzt. Originalzeitstempel, Episoden-ID, Source-Generation und Learning-Epoch bleiben gebunden. Das separat validierte bestätigte Maximum bleibt auch beim Entfernen alter Audit-Einträge monoton. F15-Berechtigungen gelten exakt pro Fingerprint und Liste. Zukünftige Einträge bestätigen vor UTC-Aufholen nichts; bei Aufholen wird die aktuelle konfigurierte Basis erneut geprüft. Große Clock-Rollbacks können Einzelbelege entfernen, nicht aber einen gültigen bestätigten Summary.
Bypass, irgendein ACTIVE-Alarm, Burst/Rapid Rise, ungültige Werte, unknown,
unavailable, echte Evidenzlücken und Quellenwechsel verwerfen laufende Episoden.
Sie werden nicht persistiert. Nach jedem Neustart ist die volle konfigurierte
High-Ruhe neu zu bestätigen. Interne Ticks liefern keine Evidenz. Die bestehende
absolute 2-µs-Toleranz bleibt unverändert. reset_learning löscht beide Kanäle
und Rollback-Kontext und erzeugt eine neue Learning-Epoch. Ein echter
Messquellenwechsel beginnt eine neue Generation; ein belegtes Registry-Rename
bewahrt sie. Ohne Registry-Provenienz kann ein Neustart keine Lernkontinuität
beweisen.
HA-Store-Version 2 und Learning-Schema 2 quarantänisieren alte samples,
pending_high_candidates und confirmed_high_history, ohne Herkunft zu erraten.
Beide Lernkanäle starten frisch. Nur diagnostischer Marker, ID, Datum und Anzahl
bleiben. Leere Kanäle und Marker werden atomar geschrieben; Wiederholung und
Neustart nach unterbrochener Migration reaktivieren keine alten Peaks.
Konfiguration, Empfänger, ACK, ACTIVE-Lecks, Shutoff-Beiträge, Bypass und
hydraulische Parameter bleiben erhalten. Bis zum erfolgreichen Schreiben bleiben
Lernen und External Reset gesperrt. Tatsächlich migrierte Lerndaten erzeugen
einen einmaligen persistenten HA-Repair-Hinweis mit stabiler ID; eine neue/leere
Installation erzeugt keinen. Eine ausgeblendete Meldung bleibt ausgeblendet.
Die effektive Burst-Schwelle kann durch frisches Lernen sinken: Backup erstellen
und Kalibrierung prüfen. Ein unlesbarer Store erfordert eine gültige Sicherung;
verlorene Sicherheitszustände werden nicht erfunden.
Unter Einstellungen → Geräte & Dienste → Water Leak Guard → Konfigurieren →
Externe Lecksensoren mehrere binary_sensor hinzufügen, benennen, bearbeiten
oder entfernen. Jeder Sensor hat einen Shutoff-Beitrag, standardmäßig true.
Konfigurierte Quellen und Zustände sind sichtbar; Formulare bieten Zurück.
Auch die Ersteinrichtung kann externe Sensoren hinzufügen. Kein YAML-Helfer nötig.
- ARMED + ON: ACTIVE mit neuer Event-ID und ereignisspezifischem Reset-Nonce.
- ACTIVE + ON/unknown/unavailable: ACTIVE bleibt erhalten.
- ACTIVE + OFF: reguläres Ende, ARMED.
- ACTIVE + autorisierter, erfolgreich persistierter External Reset: WAITING.
- WAITING + ON/unknown/unavailable: WAITING bleibt, auch nach Neustart.
- WAITING + echtes OFF: ARMED; erst ein neues ON erzeugt ein neues Ereignis.
ACTIVE blockiert beide Lernkanäle auch ohne Shutoff-Beitrag. Nach erfolgreichem Reset blockiert WAITING allein nicht mehr; andere ACTIVE-Alarme und bereits verdächtige laufende Verbrauchsepisoden bleiben wirksam.
Ein Registry-Rename erhält die Generation. Sensorersatz oder Entfernen/Hinzufügen übernimmt niemals ACTIVE, WAITING, Event-ID oder Nonce. Konfiguriertes Entfernen oder Ersetzen von ACTIVE ist bis OFF oder autorisiertem Reset gesperrt. WAITING kann bewusst entfernt werden. Bei erzwungenem Registry-Ersatz bleibt ein alter ACTIVE-Beitrag als separat gebundener Alarm-Tombstone erhalten; OFF des neuen Sensors beendet den alten Alarm nicht.
Mute ist persönlich, ACK quittiert Benachrichtigungen. Beide beenden weder einen
physischen Alarm noch Shutoff. allow_global_ack und allow_external_reset sind
unabhängig. Reset-Berechtigung ist standardmäßig false und verlangt den aktuellen
Trackerzustand genau home. trusted_stationary ersetzt Home nicht.
Die eigene Aktion „Externen Alarm zurücksetzen“ bindet Entry-ID, Source-ID,
Generation, Event-ID, Recipient-ID, Recipient-Token, Action-Kind und aktuellen
Reset-Nonce. Alte Actions werden abgelehnt; beim Neustart werden ACTIVE-Nonces
rotiert, ACK/Mute bleiben erhalten. Über request_external_reset_action kann ein
berechtigter Home-Empfänger eine frische Action anfordern, ohne ACK aufzuheben.
Bei mehreren aktiven Generationen derselben Quelle zusätzlich Generation und
Event-ID auswählen. Der Reset-Service verlangt weiterhin alle Autorisierungsdaten.
Konkurrierende Sensorupdates, Optionen, Actions und Store-Schreibvorgänge werden serialisiert. Vor endgültiger Prüfung und privater Zustandsänderung liegt keine ungeschützte asynchrone Lücke. Während des Schreibens bleibt öffentlich ACTIVE mit Shutoff sichtbar. Erst erfolgreiches atomisches HA-Schreiben veröffentlicht WAITING. Schreibfehler erzeugen weder positives Ergebnis noch Alarmende oder Freigabe. Andere Beiträge bleiben erhalten. Die Integration betätigt selbst niemals ein physisches Wasserabsperrventil.
Status, Alarm und Shutoff aggregieren alle Quellen unabhängig vom Hauptalarm. Diagnoseattribute zeigen hydraulische Alarme, externe ACTIVE/WAITING-Zustände, Beiträge und Migration; ein Langzeitmaximum-Sensor zeigt den bestätigten Wert. Grenzen bleiben: korrekte Quellen, genaue Home-Tracker, ausreichende Kalibrierung, verlässliche Speicherung und sichere Nutzer-Automationen sind nötig. Reset eines defekten Sensors ist eine bewusste Entfernung seiner Evidenz, kein Nachweis einer trockenen Stelle. Tests garantieren keine Vermeidung von Wasserschäden.
Bei MQTT-Durchflusssensoren können identische Nulltelegramme ohne force_update unterdrückt werden, bevor Home Assistant neue Reports schreibt. Setze force_update: true in der bestehenden MQTT-/Discovery-Konfiguration. Die Integration verändert fremde Discovery nicht automatisch. Ein Repair-Hinweis warnt bei erkennbar fehlendem force_update. Kurzes expire_after oder ein zu kurzer expliziter Source-Timeout unterbricht Ruhe-Evidenz wiederholt. Default der Integration ist source_max_age_seconds=0, ohne automatische Altersgrenze. Fehlende Telegramme, unavailable und interne Ticks bleiben niemals Null-Evidenz.
Status-Attribute zeigen alle Detektorzustände und Event-IDs, letzte gültige Beobachtung mit monotonem Alter, gespeicherten/default/effektiven Timeout sowie den bestätigten Low-Reset-Fortschritt. Der Gesamtzähler ersetzt keine Flow-Evidenz. Unter Konfigurieren → Aktive Meldungen quittieren können Administratoren ein Ereignis und einen aktuellen berechtigten Home-Empfänger wählen. Die neue Aktion acknowledge_event verlangt Event-/Empfänger-ID und aktuellen Empfänger-Token. ACK/Mute beenden weder ACTIVE noch Shutoff und öffnen kein Ventil.
Die technische Dauer bleibt ein numerischer Sekundensensor. DE/EN-Attribute zeigen etwa „1 Stunde 40 Minuten“ für 6043 Sekunden. Die Dauer beginnt bereits mit MONITORING, nicht erst ACTIVE; beide Zeitpunkte und Event-ID werden gezeigt. Angenommener Notify-Versand ist pro Event/Route gegen normale Wiederholung geschützt. Die bestehende Rückkehr-nach-Hause-Meldung bleibt ein absichtlicher zusätzlicher Sicherheitskontext. Eine konkrete Feldzuordnung verlangt echte Discovery-/ConfigEntry-Werte und Event-IDs; diese lagen beim Nachtrag nicht vor.
MQTT-Durchflussquellen benötigen jetzt die originale timezone-aware Radio-/
Empfänger-Messzeit im JSON-Feld timestamp; force_update allein beweist keine
neue Messung. Retained, alte oder ungebundene Nachrichten liefern keine Evidenz.
Fehlende Messherkunft sperrt die Auswertung und erzeugt einen Repair-Hinweis;
bestehende ACTIVE-Alarme bleiben erhalten. Die fremde Discovery wird nicht
überschrieben. Details und Vertrauensgrenzen: Low/ACK/Dauer.
ACK wird erst nach erfolgreicher Persistenz veröffentlicht. Das Configure-ACK ist administrative Delegation anhand des ausgewählten Recipients und dessen Home- Tracker. Status und Dauer wählen dasselbe hydraulische oder externe Ereignis.