Wassererwaermer umfassend dokumentieren

docs/module/Wassererwaermer/README.md

@@ -1,109 +1,405 @@
 # Verbraucher Warmwassererwaermer
 
-> Status: implementiert fuer IP-Symcon 8 und den Enelix-2-Vertrag `3.0`.
+> Status: implementiert fuer IP-Symcon 8.0+ und den Enelix-2-Vertrag `3.0`.
 
-Das Modul adaptiert ausschliesslich das fruehere Modul `Boiler_x_Stufig`.
-Mehrere elektrische Leistungsstufen werden exklusiv geschaltet. Der Manager
-waehlt eine der aktuell angebotenen Leistungen; Mindesttemperatur, Zeitplan und
-Legionellenprogramm koennen die lokale Warmwassersicherheit priorisieren.
+Das Modul bindet einen elektrischen Warmwasserspeicher mit einer oder mehreren
+exklusiven Leistungsstufen an den Enelix-Manager an. Der Manager kann nur eine
+der aktuell angebotenen Leistungen vorgeben. Lokale Schutz- und Komfortregeln
+fuer Mindesttemperatur, Maximaltemperatur, Zeitplan und Legionellenfunktion
+haben Vorrang vor einer Manager-Vorgabe.
 
-## Sicherheit und Regelung
+Das Modul ist eine gezielte Adaption des Enelix-1-Moduls
+`Boiler_x_Stufig`. Zyklische Altlogik und alte Kommunikationsvariablen wurden
+nicht uebernommen. Die Regelung arbeitet ereignisbasiert und verwendet
+ausschliesslich den Enelix-2-Nachrichtenvertrag.
 
-- Die Schaltkontakte werden mit Break-before-make geschaltet: zuerst alle aus,
-  danach hoechstens eine Stufe ein.
-- Fehlende, veraltete oder nicht numerische Temperaturwerte schalten die
-  EMS-Verfuegbarkeit aus und fuehren zu einer Stoerung.
-- Manager-Vorgaben werden nur angenommen, wenn sie im zuletzt gemeldeten
-  `Leistungswerte_W`-Angebot enthalten sind.
-- Nach `VorgabeTimeout` wird eine nicht erneuerte Manager-Vorgabe ungueltig.
-- Mindesttemperatur, vorausberechneter Zeitplan und Legionellenprogramm koennen
-  die maximale Stufe lokal erzwingen. Diese Phase wird mit
-  `AenderungMoeglich=false` gemeldet.
-- Lastwechsel werden fuer `LastwechselSperrzeit` Sekunden gesperrt. Danach
-  erfolgt genau eine ereignisgesteuerte Neuberechnung; sicherheitsbedingtes
-  Ausschalten bleibt sofort moeglich.
-- `BoilertemperaturGlaetten` aktiviert eine PT1-Glaettung mit konfigurierbarer
-  Zeitkonstante und der tatsaechlich verstrichenen Zeit.
+| Technisches Merkmal | Wert |
+| --- | --- |
+| Modulname | `VerbraucherWarmwassererwaermer` |
+| Alias | `Wassererwärmer` |
+| Modul-ID | `{B7C54AF4-AD7D-4FE4-B75D-203693906251}` |
+| Modultyp | Geraeteinstanz (`3`) |
+| Funktionspraefix | `ENELIX` |
+| Enelix-Vertrag | `3.0` |
 
-## Properties
+## Funktionsumfang
 
-Zu den sechs gemeinsamen Verbraucher-Properties aus
-[`Schnittstelle.md`](../../Schnittstelle.md) kommen 13 Modul-Properties hinzu.
+- beliebig viele, eindeutig konfigurierte Leistungsstufen inklusive `0 W`,
+- exklusive Break-before-make-Schaltung der Stufenkontakte,
+- lokale Mindest- und Maximaltemperatur mit Hysterese,
+- optionale PT1-Glaettung des Temperaturmesswerts,
+- thermische Vorhersage fuer taegliche Solltemperatur-Zeitpunkte,
+- zweistufige Legionellenfunktion mit Fruehest- und Spaetestintervall,
+- berechnete Istleistung, aktive Stufe und bezogene Energie,
+- ereignisbasierte Regelung mit einstellbarer Lastwechselsperre,
+- Kommunikation mit manuell oder automatisch zugeordneten Enelix-Managern,
+- optionale Diagnosevariablen und Debug-Logging.
+
+## Voraussetzungen
+
+- IP-Symcon ab Version 8.0,
+- installierte Bibliothek `Enelix-EMS` vom Branch `develop`,
+- eine Integer- oder Floatvariable als Temperaturfuehler,
+- mindestens eine positive Leistungsstufe,
+- je Leistungsstufe eine eigene Booleanvariable mit funktionsfaehiger Aktion,
+- ein Enelix-Manager, dem die Verbraucherinstanz aktiv zugeordnet wird.
+
+Die Schaltkontakte duerfen nicht mehrfach verwendet werden. Der Anlagenaufbau
+muss sicherstellen, dass die konfigurierten Leistungsstufen elektrisch
+zulaessig sind. Die Software ersetzt keine hardwareseitigen Verriegelungen,
+Temperaturbegrenzer oder Schutzorgane.
+
+## Regelungsablauf
+
+Eine Neuberechnung wird insbesondere ausgeloest durch:
+
+- einen neuen oder aktualisierten Temperaturmesswert,
+- das Ein- oder Ausschalten von `Aktiv`,
+- eine neue Manager-Vorgabe,
+- eine Aenderung der bedienbaren Temperatursollwerte,
+- das Ende der Lastwechselsperre,
+- das Uebernehmen einer neuen Instanzkonfiguration,
+- eine periodische Vollmeldung an den Manager.
+
+`Meldeintervall` ist kein Regelintervall. Es stellt die regelmaessige
+vollstaendige Rueckmeldung sicher. Die Lastwechselsperre verwendet einen
+einmaligen Timer und loest nach ihrem Ablauf genau eine Neuberechnung aus.
+
+Die Zielentscheidung folgt dieser Prioritaet:
+
+1. Bei deaktivierter Instanz oder ungueltiger Temperatur ist der Verbraucher
+   nicht verfuegbar und wird ausgeschaltet. Eine ungueltige Konfiguration wird
+   bereits beim Uebernehmen mit Status `202` abgewiesen.
+2. Unterschreitet die Temperatur die wirksame Mindesttemperatur oder reicht die
+   verbleibende Zeit bis zum naechsten Zeitplanziel rechnerisch nicht aus, wird
+   die hoechste Leistungsstufe lokal erzwungen.
+3. Ab der wirksamen Maximaltemperatur wird ausgeschaltet.
+4. Im Bereich unmittelbar unter der Maximaltemperatur wird eine bereits aktive
+   Stufe bis zum Erreichen der Abschaltgrenze gehalten.
+5. In allen anderen Zustaenden darf der Manager zwischen `0 W` und allen
+   konfigurierten Leistungsstufen waehlen.
+
+Lokale Zwangsvorgaben werden mit `AenderungMoeglich=false` und einem
+entsprechend eingeschraenkten `Leistungswerte_W` gemeldet.
+
+## Konfiguration
+
+Das Modul besitzt 19 Properties: sechs gemeinsame Verbraucher-Properties und
+13 modulspezifische Properties.
+
+### Manager und Zeitverhalten
 
 | Ident | Typ | Standard | Beschreibung |
 | --- | --- | ---: | --- |
-| `LeistungsStufen` | JSON-Liste | `[]` | Stufe, positive Leistung in W und Boolean-Schaltkontakt. |
-| `ZeitKonstante` | Integer | `120` | PT1-Zeitkonstante in Sekunden. |
-| `Boilerfuehler_PT1` | Integer | `0` | Temperaturvariable. |
-| `BoilertemperaturGlaetten` | Boolean | `false` | PT1-Glaettung aktiv. |
-| `Boilervolumen` | Integer | `300` | Volumen in Litern fuer die Zeitplanprognose. |
-| `Zeitplan` | JSON-Liste | `[]` | Uhrzeit und Solltemperatur. |
+| `PrioritaetPV` | Integer | `0` | Prioritaet im PV-Betrieb; kleinere Werte werden zuerst beruecksichtigt. |
+| `PrioritaetPeak` | Integer | `0` | Prioritaet im Peak-Betrieb; kleinere Werte werden zuerst beruecksichtigt. |
+| `Meldeintervall` | Integer | `10` | Abstand der vollstaendigen Verbraucherrueckmeldungen in Sekunden. |
+| `VorgabeTimeout` | Integer | `120` | Zeit in Sekunden, nach der eine nicht erneuerte Manager-Vorgabe ungueltig wird. |
 | `LastwechselSperrzeit` | Integer | `5` | Mindestzeit zwischen zwei Lastwechseln in Sekunden. |
-| `TemperaturMaxAlter` | Integer | `30` | Maximal zulaessiges Messwertalter in Sekunden. |
-| `Hysterese` | Float | `5.0` | Temperaturhysterese in K. |
-| `LegionellenfunktionAktiv` | Boolean | `true` | Zweistufige periodische Aufheizung aktiv. |
-| `LegionellenMinimalintervallTage` | Integer | `4` | Ab diesem Intervall wird die Legionellentemperatur als Maximaltemperatur angeboten. |
-| `LegionellenMaximalintervallTage` | Integer | `7` | Ab diesem Intervall wird die Legionellentemperatur zwingend nachgeladen. |
-| `DiagnosevariablenAnzeigen` | Boolean | `false` | Legt 16 Diagnosevariablen bei Bedarf an. |
 
-`LoggingEin` aktiviert laufende Debug-Ausgaben.
+### Speichereinstellungen
+
+| Ident | Typ | Standard | Beschreibung |
+| --- | --- | ---: | --- |
+| `LeistungsStufen` | JSON-Liste | `[]` | Positive Leistung, Stufennummer und Boolean-Schaltkontakt jeder Stufe. |
+| `Boilerfuehler_PT1` | Integer | `0` | Objekt-ID der Integer- oder Floatvariable fuer die Speichertemperatur. |
+| `LegionellenfunktionAktiv` | Boolean | `true` | Aktiviert die periodische Anhebung auf Legionellentemperatur. |
+| `LegionellenMinimalintervallTage` | Integer | `4` | Fruehestens: Legionellentemperatur wird zur Maximaltemperatur. |
+| `LegionellenMaximalintervallTage` | Integer | `7` | Spaetestens: Legionellentemperatur wird zur Mindesttemperatur. |
+
+Jeder Eintrag in `LeistungsStufen` besteht aus:
+
+| Feld | Anforderung |
+| --- | --- |
+| `Stufe` | Positive Ganzzahl. |
+| `Leistung` | Eindeutige positive Ganzzahl in Watt. |
+| `Schaltkontakt_Stufe` | Eindeutige Objekt-ID einer Booleanvariable. |
+
+Die Eintraege werden intern nach Leistung sortiert. `0 W` wird automatisch als
+Aus-Zustand in das Leistungsangebot aufgenommen und darf nicht als eigene
+Stufe konfiguriert werden.
+
+### Erweiterte Speichereinstellungen
+
+| Ident | Typ | Standard | Beschreibung |
+| --- | --- | ---: | --- |
+| `Boilervolumen` | Integer | `300` | Speichervolumen in Litern fuer die thermische Zeitplanprognose. |
+| `Hysterese` | Float | `5.0` | Temperaturhysterese in Kelvin. |
+| `Zeitplan` | JSON-Liste | `[]` | Taegliche Zielwerte mit `Uhrzeit` im Format `HH:MM` und `Solltemperatur`. |
+
+Der jeweils naechste Zeitplaneintrag wird fuer heute oder den folgenden Tag
+ermittelt. Reicht die verbleibende Zeit bei maximaler elektrischer Leistung
+rechnerisch nicht mehr aus, wird sofort die hoechste Stufe angefordert. Die
+Berechnung verwendet Wasser mit `4186 J/(kg K)` und beruecksichtigt keine
+Speicher- oder Leitungsverluste. Fuer Datum und Uhrzeit gilt die in IP-Symcon
+eingestellte lokale Zeitzone.
+
+### Erweiterte sonstige Einstellungen
+
+| Ident | Typ | Standard | Beschreibung |
+| --- | --- | ---: | --- |
+| `TemperaturMaxAlter` | Integer | `30` | Maximal zulaessiges Alter des Temperaturmesswerts in Sekunden. |
+| `BoilertemperaturGlaetten` | Boolean | `false` | Aktiviert die PT1-Glaettung. |
+| `ZeitKonstante` | Integer | `120` | PT1-Zeitkonstante in Sekunden. |
+| `EinstellungenInVisu` | Boolean | `false` | Zeigt Temperatursollwerte an und gibt ihre Bedienung frei. |
+| `DiagnosevariablenAnzeigen` | Boolean | `false` | Legt die 14 Diagnosevariablen an. |
+| `LoggingEin` | Boolean | `false` | Aktiviert laufende Debug-Ausgaben des Moduls. |
+
+Alle Zeitwerte und Intervalle muessen groesser als `0` sein. Die beiden
+Prioritaeten muessen mindestens `0` betragen. Das Legionellen-Minimalintervall
+darf nicht groesser als das Maximalintervall sein.
+
+## Temperaturverarbeitung
+
+Der Rohwert des konfigurierten Fuehlers muss numerisch und juenger als
+`TemperaturMaxAlter` sein. Andernfalls werden `TemperaturGueltig=false`,
+`Verfuegbar=false` und eine Stoerung gemeldet; eine aktive Stufe wird
+ausgeschaltet.
+
+Ohne Glaettung entspricht `Boilertemperatur` dem letzten gueltigen Rohwert.
+Mit aktivierter Glaettung verwendet das Modul ein PT1-Glied. Der erste Wert
+initialisiert den Filter; danach wird die tatsaechlich seit der letzten
+Temperaturberechnung vergangene Zeit verwendet.
+
+Die Solltemperaturen werden bei der ersten Initialisierung auf folgende Werte
+gesetzt:
+
+| Variable | Initialwert |
+| --- | ---: |
+| `Mindesttemperatur` | `45.0 Grad C` |
+| `Maximaltemperatur` | `60.0 Grad C` |
+| `Legionellentemperatur` | `65.0 Grad C` |
+
+Es gilt immer:
+
+`Mindesttemperatur < Maximaltemperatur <= Legionellentemperatur`
+
+Temperaturwerte muessen zwischen `0` und `100 Grad C` liegen. Bedienaktionen sind
+nur erlaubt, wenn `EinstellungenInVisu=true` gesetzt ist.
+
+## Hysterese und lokales Nachladen
+
+Sinkt die Temperatur unter die wirksame Mindesttemperatur, beginnt das lokale
+Nachladen mit der hoechsten Leistungsstufe. Es endet, sobald mindestens
+`Mindesttemperatur + Hysterese` erreicht ist. Oberhalb der wirksamen
+Maximaltemperatur wird ausgeschaltet.
+
+Ist bereits eine Stufe aktiv und liegt die Temperatur bei mindestens
+`Maximaltemperatur - Hysterese`, wird diese Stufe bis zur Abschaltgrenze
+gehalten. Dadurch werden unnoetige Stufenwechsel kurz vor dem Ziel vermieden.
+
+## Legionellenfunktion
+
+Die Legionellenfunktion arbeitet zweistufig:
+
+1. Ab `LegionellenMinimalintervallTage` wird die Legionellentemperatur zur
+   wirksamen Maximaltemperatur. Der Manager kann die Aufheizung innerhalb des
+   verbleibenden Zeitfensters ermoeglichen.
+2. Ab `LegionellenMaximalintervallTage` wird die Legionellentemperatur auch zur
+   wirksamen Mindesttemperatur. Die hoechste Stufe wird dadurch lokal
+   erzwungen, bis das Ziel erreicht ist.
+
+Erreicht die gueltige Speichertemperatur die Legionellentemperatur, wird der
+Zeitpunkt als erfolgreicher Abschluss gespeichert und das Intervall beginnt
+neu. `LegioCounter` zeigt die Sekunden seit diesem Abschluss.
+
+`Legionellentemperatur` wird nur als Symcon-Variable angelegt, wenn
+`LegionellenfunktionAktiv=true` ist. Beim Ausschalten der Funktion wird die
+Variable geloescht; der letzte Wert bleibt intern erhalten und steht bei einem
+spaeteren Wiedereinschalten wieder zur Verfuegung.
+
+## Lastwechselsperre und Schaltsicherheit
+
+Nach jedem tatsaechlichen Lastwechsel wird fuer
+`LastwechselSperrzeit` Sekunden kein weiterer regulaerer Wechsel zugelassen.
+In dieser Zeit gilt:
+
+- `AenderungMoeglich=false`,
+- `Leistungswerte_W` enthaelt nur die aktuell gehaltene Leistung,
+- eine abweichende Manager-Vorgabe wird abgewiesen,
+- ein einmaliger Timer plant die Freigabe.
+
+Ein sicherheitsbedingtes Ausschalten, beispielsweise bei ungueltiger
+Temperatur oder erreichter Maximaltemperatur, darf die Sperre uebergehen.
+Separate Variablen `Idle` oder `IdleCounter` existieren nicht.
+
+Beim Schalten werden zuerst alle konfigurierten Kontakte ausgeschaltet und
+anschliessend hoechstens der Kontakt der Zielstufe eingeschaltet. Schlaegt ein
+Schaltvorgang fehl, versucht das Modul alle Kontakte auszuschalten, setzt die
+berechnete Istleistung auf `0 W` und meldet einen Schaltfehler.
 
 ## Variablen
 
-Standardmaessig sichtbar sind nur `Aktiv` und `Boilertemperatur`.
+### Betriebs- und Einstellvariablen
 
-Mit `EinstellungenInVisu` werden `Mindesttemperatur` und `Maximaltemperatur`
-sichtbar und geprueft bedienbar. `Legionellentemperatur` wird nur angelegt,
-wenn `LegionellenfunktionAktiv` eingeschaltet ist, und ist ebenfalls nur mit
-`EinstellungenInVisu` sichtbar. Beim Abschalten der Legionellenfunktion wird
-die Variable geloescht; ihr letzter Wert bleibt intern fuer ein spaeteres
-Wiedereinschalten erhalten. Die Reihenfolge
-`Mindesttemperatur < Maximaltemperatur <= Legionellentemperatur` ist zwingend.
+| Ident | Typ / Zugriff | Sichtbarkeit | Beschreibung |
+| --- | --- | --- | --- |
+| `Aktiv` | Boolean / bedienbar | immer | Lokale EMS-Freigabe; Startwert `false`. |
+| `Boilertemperatur` | Float / Anzeige | immer | Letzter gueltiger, gegebenenfalls geglaetteter Temperaturwert. |
+| `Mindesttemperatur` | Float / bedienbar | bei `EinstellungenInVisu` | Untere Grenze fuer lokales Nachladen. |
+| `Maximaltemperatur` | Float / bedienbar | bei `EinstellungenInVisu` | Abschaltgrenze im Normalbetrieb. |
+| `Legionellentemperatur` | Float / bedienbar | Funktion aktiv; Anzeige freigegeben | Ziel des Legionellenprogramms. |
 
-Mit `DiagnosevariablenAnzeigen` werden diese 14 Variablen angelegt:
+### Diagnosevariablen
 
-- `Istleistung`
-- `Leistungsquelle`
-- `Sollleistung`
-- `SollwertGueltig`
-- `Verfuegbar`
-- `AenderungMoeglich`
-- `Stoerung`
-- `Stoertext`
-- `AktiveStufe`
-- `BezogeneEnergie`
-- `TemperaturGueltig`
-- `NachladenAktiv`
-- `LegionellenbetriebAktiv`
-- `LegioCounter`
+Mit `DiagnosevariablenAnzeigen=true` werden diese 14 Variablen angelegt. Beim
+Abschalten der Property werden sie wieder geloescht. Die Regellogik verwendet
+persistente interne Zustaende und funktioniert unabhaengig von diesen
+Anzeigevariablen.
 
-Die Regelung und Managerkommunikation verwenden fuer diese Werte eine interne
-Zustandsablage und funktionieren auch ohne angelegte Diagnosevariablen weiter.
-Die Lastwechselsperre wird ausschliesslich ueber die Schnittstellenfelder
-`AenderungMoeglich` und `Leistungswerte_W` abgebildet.
+| Ident | Typ | Bedeutung |
+| --- | --- | --- |
+| `Istleistung` | Float | Berechnete aktuelle Leistung in Watt. |
+| `Leistungsquelle` | Integer | Immer `1` fuer berechnete Leistung. |
+| `Sollleistung` | Integer | Aktuell angenommene oder lokal erzwungene Zielvorgabe in Watt. |
+| `SollwertGueltig` | Boolean | Eine Manager-Vorgabe ist vorhanden und noch nicht abgelaufen. |
+| `Verfuegbar` | Boolean | Das Modul kann grundsaetzlich durch das EMS gesteuert werden. |
+| `AenderungMoeglich` | Boolean | Der Manager darf momentan eine neue Leistung vorgeben. |
+| `Stoerung` | Boolean | Mindestens eine Stoerbedingung ist aktiv. |
+| `Stoertext` | String | Zusammengefasste lesbare Stoerbeschreibung. |
+| `AktiveStufe` | Integer | Stufennummer der berechneten aktuellen Leistung; `0` bedeutet aus. |
+| `BezogeneEnergie` | Float | Aus Istleistung und verstrichener Zeit berechnete Energie in kWh. |
+| `TemperaturGueltig` | Boolean | Temperaturfuehler vorhanden, numerisch und nicht veraltet. |
+| `NachladenAktiv` | Boolean | Lokales Nachladen aufgrund der Mindesttemperatur ist aktiv. |
+| `LegionellenbetriebAktiv` | Boolean | Das Fruehestintervall der Legionellenfunktion ist erreicht. |
+| `LegioCounter` | Integer | Sekunden seit dem letzten erfolgreichen Legionellenabschluss. |
 
 ## Managerkommunikation
 
-Das Modul implementiert `VerbraucherSchnittstelle::ManagerdatenEmpfangen()`.
-Der Transport erfolgt wie beim Manager ueber `IPS_RequestAction` mit JSON. Der
-Verbraucher besitzt keine Manager-ID-Property. Er ermittelt nur Manager, in
-deren manueller oder automatischer Verbraucherzuordnung seine Instanz aktiv
-eingetragen ist.
+Das Modul implementiert
+`VerbraucherSchnittstelle::ManagerdatenEmpfangen()` und verwendet den
+Enelix-2-Vertrag `3.0`. Es besitzt keine Manager-ID-Property. Zugelassen sind
+nur Manager, in deren manueller oder automatischer Verbraucherzuordnung die
+Instanz aktiv eingetragen ist.
 
-Die Rueckmeldung erfolgt ereignisbasiert und zusaetzlich alle
-`Meldeintervall` Sekunden. Eine Rueckmeldung nach empfangener Vorgabe wird kurz
-verzoegert, damit keine synchrone Manager-Verbraucher-Endlosschleife entsteht.
+Eine Manager-Vorgabe wird nur angenommen, wenn:
+
+- Vertragsversion, Absender, Empfaenger und Datentypen gueltig sind,
+- der Manager die Instanz aktiv zugeordnet hat,
+- `Sollleistung_W` im zuletzt berechneten `Leistungswerte_W` enthalten ist.
+
+Rueckmeldungen erfolgen bei relevanten Ereignissen, kurz verzoegert nach einer
+Manager-Vorgabe und zusaetzlich alle `Meldeintervall` Sekunden. Die kurze
+Verzoegerung verhindert eine synchrone Manager-Verbraucher-Endlosschleife.
+
+Die Verbraucherrueckmeldung enthaelt insbesondere:
+
+- Prioritaeten fuer PV- und Peak-Betrieb,
+- `Leistungswerte_W`, `AenderungMoeglich` und `Verfuegbar`,
+- `Istleistung_W` mit `Leistungsquelle=1`,
+- Zustandseintraege fuer Sollleistung, Wassertemperatur, Maximaltemperatur,
+  aktive Stufe, Nachladen, Legionellenbetrieb und Stoerungen.
+
+Nach `VorgabeTimeout` Sekunden ohne Erneuerung wird eine Manager-Vorgabe
+bei der naechsten Neuberechnung, spaetestens bei der folgenden Vollmeldung,
+ungueltig. Beim Neustart wird keine alte Manager-Vorgabe ungeprueft wieder
+aufgenommen.
+
+## Abgrenzung des aktuellen Stands
+
+- `Istleistung`, `AktiveStufe` und `BezogeneEnergie` sind berechnete Werte; das
+  Modul besitzt keinen Anschluss fuer einen elektrischen Leistungsmesser.
+- Die Stufenkontakte sind Aktoren, keine separate physische Rueckmeldung. Ihr
+  Booleanzustand wird bei einer Regelberechnung auf Plausibilitaet geprueft.
+- Externe Aenderungen an den Stufenkontakten loesen selbst keine
+  Neuberechnung aus. Der Temperaturfuehler ist die abonnierte Messvariable.
+- Der Zeitplan beschreibt taeglich wiederkehrende Zielzeitpunkte und keine
+  einmaligen Kalendertermine.
+
+## Status- und Fehlerzustaende
+
+| Status | Bedeutung | Typische Ursache |
+| ---: | --- | --- |
+| `102` | Aktiv | Konfiguration und Temperaturmessung sind gueltig. |
+| `201` | Temperaturmessung ungueltig | Fuehler fehlt, ist nicht numerisch oder zu alt. |
+| `202` | Konfiguration ungueltig | Unzulaessige Intervalle, Temperaturen, Stufen, Kontakte oder Zeitplaneintraege. |
+| `203` | Schaltfehler | Eine Aktion eines Stufenkontakts ist fehlgeschlagen. |
+
+Eine Uebertemperatur liegt vor, wenn `Boilertemperatur` die hoehere Grenze aus
+Maximal- und Legionellentemperatur um mehr als `Hysterese` ueberschreitet. Sie
+wird ueber `Stoerung` und `Stoertext` gemeldet; der Modulstatus bleibt ohne
+zusaetzlichen Schalt- oder Fuehlerfehler `102`.
+
+## Installation und Inbetriebnahme
+
+1. Im IP-Symcon Module Control den Branch `develop` der Bibliothek
+   `https://git.belevo.ch/ENELIX/Enelix-EMS.git` installieren oder
+   aktualisieren.
+2. Unter **Instanz hinzufuegen** nach dem Alias **Wassererwärmer** oder dem
+   Modulnamen `VerbraucherWarmwassererwaermer` suchen und eine Instanz anlegen.
+3. Den Temperaturfuehler auswaehlen und `TemperaturMaxAlter` passend zum
+   Aktualisierungsintervall des Fuehlers einstellen.
+4. Alle Leistungsstufen mit positiver Leistung und jeweils eigenem
+   Boolean-Schaltkontakt konfigurieren.
+5. Normal-, Legionellen- und Zeitplanwerte pruefen. Danach die Konfiguration
+   uebernehmen.
+6. Die Instanz im Enelix-Manager manuell aktiv zuordnen oder bei automatischer
+   Suche in der gefundenen Liste aktivieren.
+7. Fuer die Erstpruefung `DiagnosevariablenAnzeigen` und bei Bedarf
+   `LoggingEin` einschalten.
+8. Unter Aufsicht `Aktiv` einschalten und jede Stufe einzeln pruefen. Dabei
+   kontrollieren, dass nie zwei Stufenkontakte gleichzeitig aktiv sind.
+9. Eine Manager-Vorgabe fuer `0 W` und fuer jede konfigurierte Stufe pruefen.
+10. Diagnosevariablen nach der Abnahme bei Bedarf wieder ausschalten.
+
+## Abnahmecheckliste
+
+- Die Instanz erreicht Status `102`.
+- `Aktiv=false` schaltet alle Stufenkontakte aus.
+- Der Fuehlerwert erscheint unverfaelscht oder erwartungsgemaess geglaettet in
+  `Boilertemperatur`.
+- Unterhalb der Mindesttemperatur wird die hoechste Stufe lokal erzwungen.
+- Oberhalb der Maximaltemperatur werden alle Stufen ausgeschaltet.
+- Jede Manager-Vorgabe schaltet genau den zugeordneten Kontakt.
+- Direkt nach einem Wechsel ist `AenderungMoeglich=false`; nach der
+  konfigurierten Sperrzeit wird ein regulaerer Wechsel wieder freigegeben.
+- Eine Gegenanforderung waehrend der Sperre liegt nicht im gemeldeten
+  Leistungsangebot.
+- Ein veralteter oder ungueltiger Fuehlerwert fuehrt zu Status `201`, einer
+  Stoerung und sicherem Ausschalten.
+- Bei aktiver Legionellenfunktion wird `Legionellentemperatur` angelegt; nach
+  dem Abschalten der Funktion wird die Variable geloescht.
+- Mit ausgeschalteten Diagnosevariablen bleiben Regelung und Kommunikation
+  funktionsfaehig.
+
+## Diagnosehinweise
+
+- Status `202`: zuerst Fuehler-ID, Leistungsstufen, eindeutige Kontakte,
+  Temperaturreihenfolge, Intervalle und Zeitplanformat pruefen.
+- Status `201`: `VariableUpdated`, Datentyp des Fuehlers und
+  `TemperaturMaxAlter` kontrollieren.
+- Status `203`: Aktionen der Boolean-Schaltkontakte einzeln in IP-Symcon
+  testen; das Modul versucht bei einem Fehler alle Kontakte auszuschalten.
+- Manager-Vorgabe wird abgewiesen: Zuordnung im Manager,
+  `AenderungMoeglich` und das aktuelle `Leistungswerte_W` pruefen.
+- Unerwartetes Nachladen: Mindesttemperatur, Hysterese, naechstes Zeitplanziel
+  und Alter des letzten Legionellenabschlusses kontrollieren.
 
 ## Tests
 
-`WarmwasserReglerTest.php` prueft Leistungsstufen, PT1, Energieberechnung,
-Zeitplan, thermische Prognose und die zweistufigen Legionellengrenzen.
-`WarmwassererwaermerModulstrukturTest.php` prueft Metadaten, Formular,
-19 Properties, bedarfsgesteuerte Diagnosevariablen, Schnittstellenvertrag und
+`WarmwasserReglerTest.php` prueft die reine Regellogik fuer Leistungsstufen,
+PT1, Lastwechselsperre, Energieberechnung, thermische Prognose, Zeitplan und
+Legionellengrenzen.
+
+`WarmwassererwaermerModulstrukturTest.php` prueft Metadaten, Formular, alle 19
+Properties, ereignisbasierte Lastwechselsperre, Vertrag `3.0`, bedarfsgesteuerte
+Diagnosevariablen, Legionellentemperatur, Temperatursollwerte und
 Break-before-make-Schaltung.
 
-## Migration
+## Migration von Enelix 1
 
-Die Feldzuordnung und die bewusst entfallenen Enelix-1-Kommunikationsvariablen
-sind in [`docs/migration/Boiler-x-Stufig.md`](../../migration/Boiler-x-Stufig.md)
+Die Zuordnung der uebernommenen, angepassten und entfallenen Felder des alten
+Moduls `Boiler_x_Stufig` ist in
+[`docs/migration/Boiler-x-Stufig.md`](../../migration/Boiler-x-Stufig.md)
 dokumentiert.
+
+Wesentliche Unterschiede:
+
+- `Interval` entfaellt; die Regelung ist ereignisbasiert.
+- `IdleCounterMax` wird durch `LastwechselSperrzeit` in Sekunden ersetzt.
+- `Idle` und `IdleCounter` entfallen vollstaendig.
+- `PowerSteps` wird durch das Vertragsfeld `Leistungswerte_W` ersetzt.
+- Prioritaeten sind Properties; Betriebsart und Leistungsverteilung liegen im
+  Manager.
+- Die neue Modul-ID erfordert eine neue Instanz; eine automatische Umwandlung
+  des Enelix-1-Objekts findet nicht statt.