Verbrauchermodule und betriebsartabhängige Angebote ergänzen

docs/module/Pufferspeicher/README.md

@@ -1,54 +1,144 @@
-# Pufferspeicher
+# Verbraucher Pufferspeicher
 
-> Status: Diskussionsentwurf.
+> Status: implementiert fuer IP-Symcon 8.0+ und den Enelix-2-Vertrag `4.0`.
 
-Regelt elektrische Heizstufen nach Pufferbedarf. Die Heizkurve verwendet einen
-Fusspunkt bei 20 °C Aussentemperatur und eine Steigung:
+Das Modul bindet elektrische Heizstufen eines Pufferspeichers an den
+Enelix-Manager an. Die Freigabe wird aus Puffer- und Aussentemperatur,
+Heizkurve, Hysterese, lokaler Aktivierung und aktueller Betriebsart berechnet.
 
-`Solltemperatur = FusspunktVorlauftemperatur + HeizkurvenSteigung × (20 - Aussentemperatur)`
+Es ist eine gezielte Adaption des Enelix-1-Moduls `Puffer_Speicher`.
+Leistungsstufen, Temperaturquellen, optionale PT1-Glaettung und Heizkurve
+wurden uebernommen und ueberarbeitet. Zyklische Altlogik, alte
+Kommunikationsvariablen, `Idle` und `PowerSteps` als Symcon-Variable wurden
+verworfen.
 
-Anschliessend wird auf Mindest- und Maximaltemperatur begrenzt.
+| Technisches Merkmal | Wert |
+| --- | --- |
+| Modulname | `VerbraucherPufferspeicher` |
+| Alias | `Pufferspeicher` |
+| Modul-ID | `{C92D5EEF-9632-47A5-9659-4B02BF40FBE9}` |
+| Enelix-Vertrag | `4.0` |
 
-## Zusätzliche Variablen
+## Regelverhalten
 
-| Ident | Typ / Zugriff | Beschreibung |
+Die Solltemperatur wird berechnet als:
+
+`FusspunktVorlauftemperatur + HeizkurvenSteigung * (20 - Aussentemperatur)`
+
+Anschliessend wird sie auf `HeizkurveMinimaltemperatur` und
+`HeizkurveMaximaltemperatur` begrenzt.
+
+Die Einschaltschwelle wird je nach `MindesttemperaturModus` bestimmt:
+
+- `Aus`: Solltemperatur minus Hysterese,
+- `Statisch`: konfigurierte absolute Mindesttemperatur,
+- `Differenz`: Solltemperatur minus konfigurierte Differenz.
+
+Es gilt:
+
+- im PV-Betrieb unter der Einschaltschwelle: `[0, ...Leistungsstufen]`,
+- im PV-Betrieb an oder oberhalb der Einschaltschwelle: `[0]`,
+- im Peakbetrieb unabhaengig von der Temperatur: `[0]`,
+- bei `Aktiv=false`: immer `[0]`,
+- bei ungueltigen Temperaturen: `[0]` und nicht verfuegbar.
+
+Der Pufferspeicher ist im Peakbetrieb damit pauschal gesperrt. Beim Wechsel in
+Peak wird eine aktive Stufe sicher ausgeschaltet.
+
+## Properties
+
+Die Properties erscheinen im Formular in dieser Reihenfolge.
+
+### Manager und Zeitverhalten
+
+| Ident | Standard | Beschreibung |
+| --- | ---: | --- |
+| `PrioritaetPV` | `0` | Prioritaet im PV-Betrieb |
+| `PrioritaetPeak` | `0` | Prioritaet im Peakbetrieb |
+| `Meldeintervall` | `10 s` | Vollstaendige Rueckmeldung |
+| `VorgabeTimeout` | `120 s` | Gueltigkeit einer Vorgabe |
+| `LastwechselSperrzeit` | `5 s` | Mindestzeit zwischen Lastwechseln |
+
+### Pufferspeicher
+
+| Ident | Standard | Beschreibung |
+| --- | ---: | --- |
+| `LeistungsStufen` | `[]` | Stufe, Leistung und Boolean-Schaltkontakt |
+| `PufferfuehlerVariableID` | `0` | Integer- oder Floatvariable |
+| `AussentemperaturVariableID` | `0` | Integer- oder Floatvariable |
+
+### Heizkurve
+
+| Ident | Standard | Beschreibung |
+| --- | ---: | --- |
+| `FusspunktVorlauftemperatur` | `35.0 C` | Vorlauf bei 20 C aussen |
+| `HeizkurvenSteigung` | `1.0` | Anhebung je Kelvin fallender Aussentemperatur |
+| `HeizkurveMinimaltemperatur` | `20.0 C` | Untere Sollwertbegrenzung |
+| `HeizkurveMaximaltemperatur` | `80.0 C` | Obere Sollwertbegrenzung |
+| `Hysterese` | `5.0 K` | Abstand zur Einschaltschwelle |
+| `MindesttemperaturModus` | `Aus` | Aus, statisch oder Differenz |
+| `Mindesttemperatur` | `20.0 C` | Wert im statischen Modus |
+| `MindesttemperaturDifferenz` | `5.0 K` | Wert im Differenzmodus |
+| `WaermepumpenSolltemperaturVariableID` | `0` | Optionale Quelle fuer die WP-Uebernahme |
+
+Der Button **Wert von Waermepumpe uebernehmen** berechnet den Fusspunkt so,
+dass die lokale Heizkurve beim aktuellen Aussenwert durch den aktuellen
+WP-Sollwert verlaeuft. Es entsteht keine dauerhafte Laufzeitkopplung.
+
+### Erweiterte Einstellungen
+
+| Ident | Standard | Beschreibung |
+| --- | ---: | --- |
+| `TemperaturMaxAlter` | `120 s` | Maximal zulaessiges Alter beider Messwerte |
+| `PuffertemperaturGlaetten` | `false` | Aktiviert PT1-Glaettung |
+| `ZeitKonstante` | `120 s` | PT1-Zeitkonstante |
+| `EinstellungenInVisu` | `false` | Gemeinsame Verbraucheroption |
+| `DiagnosevariablenAnzeigen` | `false` | Diagnosevariablen einblenden |
+| `LoggingEin` | `false` | Debug-Protokoll aktivieren |
+
+## Variablen
+
+Immer vorhanden:
+
+| Ident | Typ | Beschreibung |
 | --- | --- | --- |
-| `Puffertemperatur` | Float / Anzeige | Aktuelle Temperatur in °C. |
-| `Aussentemperatur` | Float / Anzeige | Heizkurveneingang in °C. |
-| `TemperaturenGueltig` | Boolean / Anzeige | Beide Quellen sind gültig. |
-| `Solltemperatur` | Float / Anzeige | Berechneter und begrenzter Sollwert in °C. |
-| `Heizbedarf` | Boolean / Anzeige | Bedarf unter Berücksichtigung der Hysterese. |
-| `AktiveStufe` | Integer / Anzeige | Stufenkennung; `0` bedeutet aus. |
-| `FusspunktVorlauftemperatur` | Float / lokal bedienbar | Wirksamer Parameter in °C. |
-| `HeizkurvenSteigung` | Float / lokal bedienbar | Anhebung pro K fallender Aussentemperatur. |
-| `Mindesttemperatur` | Float / lokal bedienbar | Untere Begrenzung in °C. |
-| `Maximaltemperatur` | Float / lokal bedienbar | Obere Begrenzung in °C. |
-| `Hysterese` | Float / lokal bedienbar | Ein unter Soll minus Hysterese, aus bei Soll. |
+| `Aktiv` | Boolean / bedienbar | Lokale Ein-/Aus-Freigabe |
+| `Puffertemperatur` | Float | Aktueller, gegebenenfalls geglaetteter Wert |
+| `Aussentemperatur` | Float | Heizkurveneingang |
+| `Solltemperatur` | Float | Berechneter und begrenzter Sollwert |
+| `Heizbedarf` | Boolean | Temperatur liegt unter der Einschaltschwelle |
 
-## Zusätzliche Properties
+Optional sichtbar sind die gemeinsamen Verbraucher-Diagnosevariablen sowie
+`AktiveStufe`, `BezogeneEnergie` und `TemperaturenGueltig`.
 
-| Ident | Typ | Standard / Beschreibung |
-| --- | --- | --- |
-| `FusspunktVorlauftemperatur` | Float | `0*` °C; Vorlauf bei 20 °C aussen. |
-| `HeizkurvenSteigung` | Float | `0*`; mindestens 0. |
-| `Mindesttemperatur` | Float | `0*` °C. |
-| `Maximaltemperatur` | Float | `0*` °C. |
-| `Hysterese` | Float | `1` K; grösser 0. |
-| `Leistungsstufen` | String/JSON | `[]`; Stufenkennung, Leistung in W und Ausgangsbelegung. |
-| `PuffertemperaturVariableID` | Integer | `0`; Temperaturquelle. |
-| `AussentemperaturVariableID` | Integer | `0`; Aussentemperaturquelle. |
-| `Mindestlaufzeit` | Integer | `0` s. |
-| `Mindeststillstand` | Integer | `0` s. |
+## Managerkommunikation
 
-Vier bisherige Heizkurventemperaturen, beide Heizkurvenquellen, Übernahmeaktion,
-Zeitplan und Zeitzone entfallen.
+Das Modul implementiert `VerbraucherSchnittstelle` und Vertrag `4.0`.
+Es uebernimmt zuerst die vom Manager angekuendigte Betriebsart, berechnet das
+passende Leistungsangebot und meldet es mit derselben Betriebsart zurueck.
+Erst danach wird eine Sollleistung angenommen.
 
-## Zustand
+Die Rueckmeldung enthaelt zusaetzlich:
 
-`Puffertemperatur_C` und `Aussentemperatur_C` als Istwerte,
-`Solltemperatur_C` als Sollwert, `Heizbedarf` als Status und `Fuehlerfehler` als
-Störung.
+- `Puffertemperatur_C`,
+- `Aussentemperatur_C`,
+- `Solltemperatur_C`,
+- `Heizbedarf`,
+- `AktiveStufe`,
+- `Fuehlerfehler` und `Schaltfehler`.
 
-## Offene Punkte
+## Sicherheit und Schaltung
 
-- Optionale Einbindung der Wärmepumpe beim Pufferheizen ausarbeiten.
+Die Kontakte werden Break-before-make geschaltet: zuerst alle aus, danach
+hoechstens eine Stufe ein. Ein Schaltfehler fuehrt zu einem Ausschaltversuch
+aller Kontakte und einer Stoerungsmeldung. Hardwareseitige Verriegelungen,
+Temperaturbegrenzer und Schutzorgane bleiben erforderlich.
+
+## Tests
+
+- `PufferspeicherReglerTest` prueft Heizkurve, Hysterese, Ein/Aus, Peak und
+  alle Mindesttemperatur-Modi.
+- `PufferspeicherModulstrukturTest` prueft Metadaten, Properties, Formular,
+  Vertrag und Schaltfolge.
+- Der standardisierte Symcon-Test prueft die reale Modulinstanz und ist im
+  gemeinsamen Manifest sowie in der Manager-Matrix registriert.