feat: Wärmepumpenmodul integrieren

docs/module/README.md

@@ -1,8 +1,8 @@
 # EMS-Module und Modulentwürfe
 
-> Manager, Warmwassererwaermer, Batterie, Verbraucher 1-Stufig, Ladestation Stand-Alone,
-> Easee Gateway und Ladestation Gateway sind als installierbare IP-Symcon-Module
-> umgesetzt. Die weiteren Ordner enthalten Besprechungsgrundlagen.
+> Manager, Warmwassererwaermer, Batterie, Verbraucher 1-Stufig, Waermepumpe,
+> Ladestation Stand-Alone, Easee Gateway und Ladestation Gateway sind als
+> installierbare IP-Symcon-Module umgesetzt. Die weiteren Ordner enthalten Besprechungsgrundlagen.
 
 Alle steuerbaren Verbraucher verwenden die gemeinsamen Datenpunkte aus der
 [EMS-Schnittstelle](../Schnittstelle.md). In den Modul-READMEs stehen deshalb

docs/module/Waermepumpe/README.md

@@ -1,47 +1,89 @@
 # Wärmepumpe
 
-> Status: Diskussionsentwurf.
+> Status: Implementiert.
 
-Die Kontaktwirkung ist als Sperrkontakte oder SG Ready konfigurierbar. Die
-elektrische Leistung kann fehlen, berechnet oder gemessen werden.
+Das Modul bindet eine Wärmepumpe über zwei schaltbare Boolean-Ausgänge in den
+Enelix-Manager ein. Die Ausgänge können als getrennte Kontakte für Sperre und
+Erhöhung oder als SG-Ready-Eingänge verwendet werden. Die Regelung arbeitet mit
+dem Nachrichtenvertrag 4.0 und meldet für PV und Peak ein
+zustandsabhängiges Leistungsangebot.
 
-## Zusätzliche Variablen
+## Verhalten
 
-| Ident | Typ / Zugriff | Beschreibung |
+- Im PV-Betrieb kann eine freigegebene Wärmepumpe aus dem Normalzustand in die
+  Erhöhung geschaltet werden.
+- Im Peak-Betrieb kann eine laufende Wärmepumpe gesperrt werden, sofern
+  Mindestlaufzeit und Sperrgrenzen dies erlauben.
+- Schaltvorgänge erfolgen als Break-before-Make: beide Kontakte werden zuerst
+  deaktiviert, danach wird höchstens ein Kontakt aktiviert.
+- Nach einem erfolglosen PV-Anlauf wird die Erhöhung aufgehoben und bis zum
+  Ablauf der Wiederholsperre nicht erneut angeboten.
+- Die maximale Sperrzeit am Stück und innerhalb von 24 Stunden erzwingt eine
+  Erholungsphase im Normalbetrieb.
+- Ohne gültige Manager-Vorgabe fällt die Steuerung in den sicheren
+  Normalzustand zurück.
+
+## Konfiguration
+
+| Property | Standard | Beschreibung |
+| --- | ---: | --- |
+| `Kontaktart` | `0` | `0`: Sperre/Erhöhung, `1`: SG Ready |
+| `Kontakt1VariableID` | `0` | Schaltbarer Ausgang für Sperre beziehungsweise SG Ready 1 |
+| `Kontakt2VariableID` | `0` | Schaltbarer Ausgang für Erhöhung beziehungsweise SG Ready 2 |
+| `Kontakt1Invertiert` | `false` | Logik des ersten Ausgangs invertieren |
+| `Kontakt2Invertiert` | `false` | Logik des zweiten Ausgangs invertieren |
+| `Nennleistung` | `0 W` | Elektrische Nennleistung der Wärmepumpe |
+| `Rueckmeldungsart` | `0` | `0`: gemessene Leistung, `1`: Boolean-Betriebsstatus |
+| `IstleistungVariableID` | `0` | Leistungsmessung oder Betriebsrückmeldung |
+| `Laufschwelle` | `100 W` | Ab dieser Leistung gilt die Wärmepumpe als laufend |
+| `Anlaufwartezeit` | `30 s` | Wartezeit auf bestätigten Anlauf |
+| `Wiederholsperre` | `300 s` | Pause nach einem erfolglosen Anlauf |
+| `Mindestlaufzeit` | `1200 s` | Mindestlaufzeit nach bestätigtem Start |
+| `Mindestsperrzeit` | `1200 s` | Mindestdauer einer begonnenen Sperre |
+| `MaximaleSperrzeit` | `7200 s` | Maximale zusammenhängende Sperre; `0` deaktiviert |
+| `MaximaleSperrzeit24h` | `21600 s` | Maximale Sperrsumme in 24 Stunden; `0` deaktiviert |
+
+Hinzu kommen die gemeinsamen Verbraucher-Properties für Prioritäten,
+Meldeintervall, Vorgabe-Timeout, Visualisierung und Logging.
+
+## Variablen
+
+| Ident | Typ | Beschreibung |
 | --- | --- | --- |
-| `Waermepumpenzustand` | Integer / Anzeige | `0` unbekannt, `1` aus, `2` normal, `3` erhöht, `4` gesperrt. |
-| `SperreAktiv` | Boolean / Anzeige | Aktuelle Sperranforderung. |
-| `ErhoehungAktiv` | Boolean / Anzeige | Aktuelle Erhöhungsanforderung. |
-| `SGReadyZustand` | Integer / Anzeige | Bei SG Ready Zustand 0–3. |
-| `Laufzeit` | Integer / Anzeige | Kumulierte bestätigte Laufzeit in Sekunden. |
+| `Waermepumpenzustand` | Integer | `1` normal/aus, `2` normal/laufend, `3` erhöht, `4` gesperrt |
+| `WaermepumpeLaeuft` | Boolean | Bestätigter Betriebsstatus |
+| `SperreAktiv` | Boolean | Sperrkontakt ist aktiv |
+| `ErhoehungAktiv` | Boolean | Erhöhungskontakt ist aktiv |
+| `SGReadyZustand` | Integer | Bitwert der beiden logischen Kontakte |
+| `Laufzeit` | Integer | Kumulierte bestätigte Laufzeit in Sekunden |
 
-## Zusätzliche Properties
+Optionale Diagnosevariablen zeigen unter anderem Ist- und Sollleistung,
+Verfügbarkeit, Anlaufstatus, Wiederholsperre, Sperrerholung, verbleibende
+Mindestzeiten und die Sperrsumme der letzten 24 Stunden.
 
-| Ident | Typ | Standard / Beschreibung |
-| --- | --- | --- |
-| `Kontaktwirkung` | Auswahl | `Sperrkontakte`; alternativ `SG Ready`. |
-| `Kontakt1VariableID` | Integer | `0`; Sperre oder SG-Ready-Eingang 1. |
-| `Kontakt2VariableID` | Integer | `0`; Erhöhung oder SG-Ready-Eingang 2. |
-| `Kontakt1Invertiert` | Boolean | `false`. |
-| `Kontakt2Invertiert` | Boolean | `false`. |
-| `Leistungsermittlung` | Auswahl | `Nicht vorhanden`, `Berechnet` oder `Gemessen`; entspricht Quelle 0/1/2. |
-| `LeistungsmessungVariableID` | Integer | `0`; nur bei gemessener Leistung. |
-| `Zustandskennlinie` | String/JSON | `[]`; bei berechneter Leistung je Zustand Planleistung und Kontaktbelegung. |
-| `BetriebsrueckmeldungVariableID` | Integer | `0`; optionale echte Betriebsrückmeldung. |
-| `Mindestlaufzeit` | Integer | `0*` s; anlagengerecht festlegen. |
-| `Mindeststillstand` | Integer | `0*` s; anlagengerecht festlegen. |
-| `MaxSperrzeit` | Integer | `0` s; `0` deaktiviert die EMS-Sperrfunktion. |
+## Adaption aus Enelix 1
 
-Zeit- und wetterabhängiges Sperren beziehungsweise Erhöhen aus dem Altmodul
-entfällt.
+| Bereich | Behandlung in Enelix 2 |
+| --- | --- |
+| Grundzustände Normal, Sperre und Erhöhung | angepasst übernommen |
+| Zwei physische Kontakte | angepasst und mit Invertierung sowie Rücklesekontrolle umgesetzt |
+| Leistungsangebot an den Manager | neu nach Nachrichtenvertrag 4.0 implementiert |
+| Mindestlauf- und Sperrzeiten | neu als ereignisbasierte Schutzlogik implementiert |
+| Wetter-, Wolken- und Sonnenaufgangslogik | nicht uebernommen |
+| Warmwasser-Schwellwert im Wärmepumpenmodul | nicht uebernommen |
+| Fester zyklischer Fünf-Sekunden-Regler | nicht uebernommen; Ereignisse und Einmal-Timer |
 
-## Zustand
+## Lizenzierung und Manager
 
-`Waermepumpenzustand`, `SperreAktiv`, `ErhoehungAktiv` beziehungsweise
-`SGReadyZustand` als Status, `Laufzeit_s` als Istwert und
-`Kommunikationsfehler` als Störung.
+Der Manager erkennt das Modul über die Modul-ID
+`{A31C9274-54F7-4BD2-9804-7AF23E86C4D1}`. Es verwendet das bestehende
+Lizenzkontingent `consumer_single`, das im Portal als einstufiger Verbraucher
+mit Wärmepumpe als Beispiel angeboten wird.
 
-## Offene Punkte
+## Sicherheitshinweise
 
-- Der Formularbutton „Wassererwärmer über Wärmepumpe betreiben“ bleibt ohne
-  Regelwirkung, bis Anschluss und Verriegelung gemeinsam definiert sind.
+Die beiden Ausgänge müssen unterschiedliche, schaltbare Boolean-Variablen sein.
+Die Rückmeldung ist verpflichtend: entweder eine numerische Leistungsmessung
+oder ein Boolean-Betriebsstatus. Bei ungültiger Konfiguration, fehlgeschlagenem
+Schalten oder widersprüchlicher Rücklesung setzt das Modul seinen Status auf
+Fehler und meldet sich dem Manager als nicht verfügbar.