Verbraucher Warmwassererwaermer implementieren

docs/module/Wassererwaermer/README.md

@@ -1,63 +1,98 @@
-# Wassererwärmer
+# Verbraucher Warmwassererwaermer
 
-> Status: Diskussionsentwurf. Vereinigt Boiler x-Stufig, Boiler mit Fühler,
-> Askoheat und Heizung x-Stufig.
+> Status: implementiert fuer IP-Symcon 8 und den Enelix-2-Vertrag `3.0`.
 
-Anzahl, Leistung und Ausgangsbelegung werden je Stufe konfiguriert. Temperatur-,
-Nachlade-, Legionellen- und Askoheat-Werte sind Properties und können über
-`EinstellungenInVisu` bedienbar gemacht werden.
+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.
 
-## Zusätzliche Variablen
+## Sicherheit und Regelung
 
-| Ident | Typ / Zugriff | Beschreibung |
-| --- | --- | --- |
-| `Wassertemperatur` | Float / Anzeige | Aktueller Wert in °C. |
-| `TemperaturGueltig` | Boolean / Anzeige | Adapter liefert einen gültigen Wert. |
-| `NachladenAktiv` | Boolean / Anzeige | Mindesttemperaturanforderung aktiv. |
-| `LegionellenbetriebAktiv` | Boolean / Anzeige | Legionellenbetrieb läuft. |
-| `AktiveStufe` | Integer / Anzeige | Stufenkennung; `0` bedeutet aus. |
-| `LetzterLegionellenabschluss` | Integer / Anzeige | Unixzeit des letzten erfolgreichen Abschlusses. |
-| `NachladeMindesttemperatur` | Float / lokal bedienbar | Wirksamer Parameter in °C. |
-| `NachladeMaximaltemperatur` | Float / lokal bedienbar | Wirksamer Parameter in °C. |
-| `Maximaltemperatur` | Float / lokal bedienbar | Normale obere Zieltemperatur in °C. |
-| `Hysterese` | Float / lokal bedienbar | Hysterese in K. |
-| `NachladeMindesttemperaturAktiv` | Boolean / lokal bedienbar | Mindesttemperaturnachladung ein/aus. |
-| `NachladeMaximaltemperaturAktiv` | Boolean / lokal bedienbar | Separates Nachlade-Endziel ein/aus. |
-| `LegionellenfunktionAktiv` | Boolean / lokal bedienbar | Funktion ein/aus. |
-| `Legionellentemperatur` | Float / lokal bedienbar | Zieltemperatur in °C. |
-| `AskoheatFunktionAktiv` | Boolean / lokal bedienbar | Ansteuerung ein/aus. |
+- 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.
+- `BoilertemperaturGlaetten` aktiviert eine PT1-Glaettung mit konfigurierbarer
+  Zeitkonstante.
 
-## Zusätzliche Properties
+## Properties
 
-| Ident | Typ | Standard / Beschreibung |
-| --- | --- | --- |
-| `NachladeMindesttemperatur` | Float | `0*` °C; Starttemperatur. |
-| `NachladeMaximaltemperatur` | Float | `0*` °C; Endtemperatur. |
-| `Maximaltemperatur` | Float | `0*` °C; normales oberes Ziel. |
-| `Hysterese` | Float | `1` K; grösser 0. |
-| `NachladeMindesttemperaturAktiv` | Boolean | `false`. |
-| `NachladeMaximaltemperaturAktiv` | Boolean | `false`. |
-| `LegionellenfunktionAktiv` | Boolean | `false`. |
-| `Legionellentemperatur` | Float | `0*` °C. |
-| `AskoheatFunktionAktiv` | Boolean | `false`. |
-| `Betriebsprofil` | Auswahl | `Wassererwaermer` oder `EinfacheTemperaturheizung`. |
-| `Leistungsstufen` | String/JSON | `[]`; Stufenkennung, Leistung in W und vollständige Ausgangsbelegung. |
-| `Volumen` | Float | `0` l; `0` deaktiviert thermische Berechnung. |
-| `Mindestlaufzeit` | Integer | `0` s. |
-| `Mindeststillstand` | Integer | `0` s. |
-| `AskoheatInstanzID` | Integer | `0`; nur bei aktivierter Funktion. |
-| `AskoheatLeistungVariableID` | Integer | `0`; nur wenn der Adapter sie benötigt. |
+Zu den sechs gemeinsamen Verbraucher-Properties aus
+[`Schnittstelle.md`](../../Schnittstelle.md) kommen 17 Modul-Properties hinzu.
 
-Temperatur-Maximalalter, Temperaturgrenze, Temperatur-Variable-ID, Zeitpläne,
-Legionellenhaltezeit, Legionellenmaximaldauer und Zeitzone entfallen.
+| 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. |
+| `Interval` | Integer | `5` | Regelintervall in Sekunden. |
+| `IdleCounterMax` | Integer | `2` | Zyklen bis zum Idle-Status. |
+| `TemperaturMaxAlter` | Integer | `30` | Maximal zulaessiges Messwertalter in Sekunden. |
+| `Hysterese` | Float | `5.0` | Temperaturhysterese in K. |
+| `LegionellenfunktionAktiv` | Boolean | `true` | Periodische Aufheizung aktiv. |
+| `LegionellenIntervallTage` | Integer | `7` | Intervall seit erfolgreichem Abschluss. |
+| `LegionellenHaltezeit` | Integer | `0` | Haltezeit auf Zieltemperatur in Sekunden. |
+| `LegionellenMaximaldauer` | Integer | `86400` | Abbruchzeit in Sekunden. |
+| `NachtstartStunde` | Integer | `22` | Fruehester Programmstart. |
+| `NachtendeStunde` | Integer | `7` | Ende des Nachtfensters. |
+| `DiagnosevariablenAnzeigen` | Boolean | `false` | Blendet zehn Diagnosevariablen ein. |
 
-## Zustand
+`LoggingEin` aktiviert laufende Debug-Ausgaben. Der Formular-Knopf schreibt
+unabhaengig davon genau einen aktuellen Statusdatensatz ins Debug-Log.
 
-`Wassertemperatur_C` als Istwert, `Maximaltemperatur_C` als Sollwert,
-`AktiveStufe`, `NachladenAktiv` und `LegionellenbetriebAktiv` als Status sowie
-`Fuehlerfehler` und `Uebertemperatur` als Störungen.
+## Variablen
 
-## Offene Punkte
+Standardmaessig sichtbar sind nur die acht Betriebsvariablen `Aktiv`,
+`Istleistung`, `Sollleistung`, `Stoerung`, `Stoertext`, `Boilertemperatur`,
+`AktiveStufe` und `BezogeneEnergie`.
 
-- Ablauf für „Wassererwärmer über Wärmepumpe betreiben“ separat festlegen.
-- Konkreten Temperaturadapter und die Fühleranbindung bestätigen.
+Mit `EinstellungenInVisu` werden `Mindesttemperatur`, `Maximaltemperatur` und
+`Legionellentemperatur` sichtbar und geprueft bedienbar. Die Reihenfolge
+`Mindesttemperatur < Maximaltemperatur <= Legionellentemperatur` ist zwingend.
+
+Mit `DiagnosevariablenAnzeigen` werden diese zehn Variablen eingeblendet:
+
+- `Leistungsquelle`
+- `SollwertGueltig`
+- `Verfuegbar`
+- `AenderungMoeglich`
+- `TemperaturGueltig`
+- `NachladenAktiv`
+- `LegionellenbetriebAktiv`
+- `LegioCounter`
+- `Idle`
+- `IdleCounter`
+
+## 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 `VerbraucherZuordnung` seine 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.
+
+## Tests
+
+`WarmwasserReglerTest.php` prueft Leistungsstufen, PT1, Energieberechnung,
+Zeitplan und thermische Prognose. `WarmwassererwaermerModulstrukturTest.php`
+prueft Metadaten, Formular, 23 Properties, Sichtbarkeit, Schnittstellenvertrag
+und Break-before-make-Schaltung.
+
+## Migration
+
+Die Feldzuordnung und die bewusst entfallenen Enelix-1-Kommunikationsvariablen
+sind in [`docs/migration/Boiler-x-Stufig.md`](../../migration/Boiler-x-Stufig.md)
+dokumentiert.