# Verbraucher Warmwassererwaermer

> Status: implementiert fuer IP-Symcon 8 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.

## Sicherheit und Regelung

- 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.

## Properties

Zu den sechs gemeinsamen Verbraucher-Properties aus
[`Schnittstelle.md`](../../Schnittstelle.md) kommen 13 Modul-Properties hinzu.

| 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. |
| `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.

## Variablen

Standardmaessig sichtbar sind nur `Aktiv` und `Boilertemperatur`.

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.

Mit `DiagnosevariablenAnzeigen` werden diese 16 Variablen angelegt:

- `Istleistung`
- `Leistungsquelle`
- `Sollleistung`
- `SollwertGueltig`
- `Verfuegbar`
- `AenderungMoeglich`
- `Stoerung`
- `Stoertext`
- `AktiveStufe`
- `BezogeneEnergie`
- `TemperaturGueltig`
- `NachladenAktiv`
- `LegionellenbetriebAktiv`
- `LegioCounter`
- `Idle` (Lastwechsel freigegeben)
- `IdleCounter` (verbleibende Sperrzeit in Sekunden)

Die Regelung und Managerkommunikation verwenden fuer diese Werte eine interne
Zustandsablage und funktionieren auch ohne angelegte Diagnosevariablen weiter.

## 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.

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, thermische Prognose und die zweistufigen Legionellengrenzen.
`WarmwassererwaermerModulstrukturTest.php` prueft Metadaten, Formular,
19 Properties, bedarfsgesteuerte Diagnosevariablen, 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.