feat: Batteriemodul ereignisbasiert integrieren

docs/module/Batterie/README.md

@@ -1,59 +1,121 @@
 # Batterie
 
-> Status: Diskussionsentwurf. Positiv bedeutet Laden, negativ Entladen.
+> Status: implementiert. Zielplattform ist IP-Symcon ab Version 8.0,
+> Nachrichtenvertrag 4.0.
 
-Die Auswahl des Batterietyps bestimmt den Adapter und die sichtbaren
-Anschlussfelder. Ohne Logging bleibt von den zusätzlichen Variablen nur
-`Ladestatus` sichtbar.
+## Verantwortung
 
-## Zusätzliche Variablen
+Das Modul bildet einen Batteriespeicher als bidirektionalen Enelix-Verbraucher
+ab. Es berechnet das betriebsart- und ladezustandsabhaengige
+Leistungsangebot, empfaengt Sollleistungen vom Manager und uebersetzt sie in
+herstellerspezifische Registerwerte.
 
-| Ident | Typ / Zugriff | Beschreibung |
-| --- | --- | --- |
-| `Ladestatus` | Integer / Anzeige | `0` unbekannt, `1` ruhend, `2` laden, `3` entladen. |
-| `Ladezustand` | Float / Logging | Physischer Ladezustand in %. |
-| `LadezustandGueltig` | Boolean / Logging | Gültigkeit unabhängig von der Leistungsmessung. |
-| `Steuerungsmodus` | Integer / lokal bedienbar | `0` Batterie, `1` Manager, `2` Virtuelle Batterie führt. |
-| `NotnachladungAktiv` | Boolean / Logging | Aus Ladezustand ermittelter lokaler Bedarf. |
-| `LadeleistungVerfuegbar` | Float / Logging | Aktuell nutzbare Ladeleistung in W. |
-| `EntladeleistungVerfuegbar` | Float / Logging | Aktuell nutzbare Entladeleistung als positiver Betrag in W. |
-| `MaxLadeleistung` | Float / lokal bedienbar | Wirksamer Parameter in W. |
-| `MaxEntladeleistung` | Float / lokal bedienbar | Wirksamer Parameter in W. |
-| `Mindestladezustand` | Float / lokal bedienbar | Wirksamer Parameter in %. |
-| `Maximalladezustand` | Float / lokal bedienbar | Wirksamer Parameter in %. |
-| `Nachladeschwelle` | Float / lokal bedienbar | Wirksamer Parameter in %. |
-| `Nachladehysterese` | Float / lokal bedienbar | Wirksamer Parameter in %. |
-| `Notnachladeleistung` | Float / lokal bedienbar | `0` deaktiviert; sonst Leistung in W. |
+Positive Leistung bedeutet Laden, negative Leistung Entladen. Die
+Geraeteanbindung erfolgt ausschliesslich ueber vom Benutzer ausgewaehlte
+numerische IP-Symcon-Variablen. Schreibziele muessen eine Aktion besitzen.
 
-## Zusätzliche Properties
+## Ereignismodell
 
-| Ident | Typ | Standard / Beschreibung |
-| --- | --- | --- |
-| `MaxLadeleistung` | Float | `0*` W; einzige einstellbare obere Ladegrenze. |
-| `MaxEntladeleistung` | Float | `0` W; einzige einstellbare obere Entladegrenze. |
-| `Mindestladezustand` | Float | `0*` %; Bereich 0–100. |
-| `Maximalladezustand` | Float | `100` %; grösser als Mindestladezustand. |
-| `Nachladeschwelle` | Float | `0*` %; zwischen Mindest- und Maximalladezustand. |
-| `Nachladehysterese` | Float | `2` %; Schwelle plus Hysterese höchstens Maximalladezustand. |
-| `Notnachladeleistung` | Float | `0` W; sonst höchstens MaxLadeleistung. |
-| `Batterietyp` | Auswahl | `Unkonfiguriert`, `Herstellerunabhaengig`, `Goodwe`, `SolarEdge`, `SigEnergy`. |
-| `BatterieInstanzID` | Integer | `0`; für kompatible Herstelleradapter. |
-| `LadezustandVariableID` | Integer | `0`; nur herstellerunabhängig. |
-| `IstleistungVariableID` | Integer | `0`; nur herstellerunabhängig. |
-| `SollleistungVariableID` | Integer | `0`; nur herstellerunabhängig, vorzeichenbehaftet in W. |
-| `LadezustandMaxAlter` | Integer | `60` s; Aktualität des Ladezustands. |
-| `VirtuelleBatterieID` | Integer | `0`; Pflicht bei Steuerungsmodus 2. |
+Fachliche Neuberechnungen werden ausgeloest durch:
 
-Anschlussart, Batteriespannung, Gerätezuordnung, Leistungsschritt,
-Sollwertquelle und externe Sollwerte entfallen.
+- Aktualisierung eines der fuenf Messwerte
+- Managerdaten mit Betriebsart oder Sollleistung
+- lokale Aenderung der Variablen Aktiv
+- Ablauf von Vorgabe-Timeout oder Aenderungssperre
+- manuelle Aktualisierung in der Konfigurationsmaske
 
-## Zustand
+Der Meldezyklus verschickt eine Vollmeldung und dient nicht als Regelzyklus.
+Ein periodischer Berechnungstimer oder Idle-Counter existiert nicht.
 
-`Ladezustand_Prozent` als Istwert; `Steuerungsmodus` und
-`NotnachladungAktiv` als Status; `LadezustandFehlt` und `Geraetefehler` als
-Störungen.
+## Properties
 
-## Offene Punkte
+### Gemeinsame Verbraucherproperties
 
-- Michis konkrete Fehlerliste nachliefern und gegen den Entwurf prüfen.
-- Datenpunkte und Leistungsgrenzen der drei Herstelleradapter verifizieren.
+PrioritaetPV, PrioritaetPeak, Meldeintervall, VorgabeTimeout,
+EinstellungenInVisu und LoggingEin stammen aus VerbraucherBasisTrait.
+
+### Batteriespezifische Properties
+
+| Property | Typ | Standard | Bedeutung |
+| --- | --- | ---: | --- |
+| Batterietyp | Integer | 0 | 0 unkonfiguriert, 1 generisch, 2 GoodWe, 3 SolarEdge, 4 Sigenergy |
+| Batteriemanagement | Integer | 1 | 1 Wechselrichter, 2 Enelix |
+| MaxLadeleistungVariableID | Integer | 0 | Dynamische Ladegrenze in W |
+| MaxEntladeleistungVariableID | Integer | 0 | Dynamische Entladegrenze in W |
+| LadezustandVariableID | Integer | 0 | SoC in Prozent |
+| NetzleistungVariableID | Integer | 0 | Positiv Netzbezug, negativ Einspeisung |
+| IstleistungVariableID | Integer | 0 | Positiv Laden, negativ Entladen |
+| ManagementRegisterVariableID | Integer | 0 | Steuerungsquelle des Wechselrichters |
+| ModusRegisterVariableID | Integer | 0 | Laden-/Entladen-Code |
+| LeistungsRegisterVariableID | Integer | 0 | GoodWe-Leistungsregister in W |
+| LadeleistungRegisterVariableID | Integer | 0 | Ladeleistung in W beziehungsweise kW |
+| EntladeleistungRegisterVariableID | Integer | 0 | Entladeleistung in W beziehungsweise kW |
+| ReserveLadezustand | Float | 20 | Peakshaving-Reserve in Prozent |
+| MindestLadezustand | Float | 10 | Untere Entladegrenze in Prozent |
+| LadezustandHysterese | Float | 2 | Hysterese oberhalb der Reserve |
+| MesswertMaxAlter | Integer | 60 | Maximales Messwertalter in Sekunden |
+| Aenderungssperre | Integer | 4 | Sperrzeit nach Sollwertaenderung |
+| DiagnosevariablenAnzeigen | Boolean | false | Technische Variablen einblenden |
+
+## Registeradapter
+
+| Typ | WR-Management | Enelix-Management | Laden | Entladen |
+| --- | ---: | ---: | --- | --- |
+| Generisch | 0 | 1 | Modus 0, Ladeleistung W | Modus 1, Entladeleistung W |
+| GoodWe | 1 | 2 | Modus 11, Betrag W | Modus 12, Betrag W |
+| SolarEdge | 1 | 4 | Modus 3, Ladeleistung W | Modus 4, Entladeleistung W |
+| Sigenergy | 0 | 1 | Modus 3, Ladeleistung kW | Modus 6, Entladeleistung kW |
+
+Beim Wechsel in die Wechselrichtersteuerung werden zuerst die zum Typ
+gehoerenden Leistungsregister auf 0 gesetzt und danach der Automatikcode
+geschrieben. Im Enelix-Modus werden zuerst die Leistungswerte, dann Modus und
+zuletzt Management geschrieben.
+
+## Leistungsangebot
+
+Das Raster besteht wie in Enelix 1 aus 250-W-Grundschritten. Um 0 werden
+zusaetzlich -200, -150, -100, -50, 0, 50, 100, 150 und 200 W angeboten,
+soweit diese Werte innerhalb der dynamischen Leistungsgrenzen liegen.
+
+PV und Peak verwenden die bisherige SoC-Logik. Die Hysterese wird als
+persistenter Modulzustand gefuehrt. Bei Wechselrichtersteuerung, lokaler
+Deaktivierung oder ungueltigen Messwerten lautet das Angebot [0].
+
+## Variablen
+
+Immer sichtbar sind Aktiv und Ladestatus. Ladestatus verwendet:
+
+| Wert | Bedeutung |
+| ---: | --- |
+| 0 | Messwert ungueltig oder unbekannt |
+| 1 | Ruhezustand |
+| 2 | Laden |
+| 3 | Entladen |
+
+Die Diagnoseoption ergaenzt die gemeinsamen Verbraucherdiagnosen sowie
+Ladezustand, Netzleistung, Leistungsgrenzen, Hysterese, Steuerungsmodus,
+BezogeneEnergie, LeistungsangebotDiagnose und LetzterRegisterbefehl.
+
+## Fehlerbehandlung
+
+- Status 201: Konfiguration oder Variablentyp ungueltig
+- Status 202: Messwert fehlt, ist veraltet oder fachlich ungueltig
+- Status 203: RequestAction auf mindestens ein Register ist fehlgeschlagen
+
+Ein ungueltiger oder abgelaufener Sollwert wird verworfen und durch 0 ersetzt.
+Die konkrete Stoerung wird im Vertrag und bei aktivierter Diagnose in
+Stoerung und Stoertext gemeldet.
+
+## Managerkommunikation
+
+Die fachliche Schnittstelle ist in
+[Schnittstelle Batterie](../../Schnittstelle-Batterie.md) beschrieben.
+Transport und gemeinsame Felder folgen
+[EMS-Schnittstelle](../../Schnittstelle.md).
+
+## Tests
+
+- BatterieReglerTest: Raster, Hysterese, PV/Peak und Herstellerabbildung
+- BatterieModulstrukturTest: Metadaten, Formular, Ereignismodell und Manager-ID
+- Symcon/modules/Batterie.php: reale Modulinstanz und Registeraktionen unter
+  IP-Symcon 8.0

docs/module/README.md

@@ -1,6 +1,6 @@
 # EMS-Module und Modulentwürfe
 
-> Manager, Warmwassererwaermer, Verbraucher 1-Stufig, Ladestation Stand-Alone,
+> 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.
 
@@ -11,7 +11,7 @@ nur zusätzliche Properties, Variablen, Zustände und offene Punkte.
 | Modul | Rolle |
 | --- | --- |
 | [Manager](Manager/README.md) | Leistungsverteilung und Anschlüsse (implementiert) |
-| [Batterie](Batterie/README.md) | Laden und Entladen eines Speichers |
+| [Batterie](Batterie/README.md) | Laden und Entladen eines Speichers (implementiert) |
 | [Wassererwärmer](Wassererwaermer/README.md) | Mehrstufige elektrische Erwärmung (implementiert) |
 | [Pufferspeicher](Pufferspeicher/README.md) | Heizstufen nach Heizkurve |
 | [Verbraucher 1-Stufig](Verbraucher-1-Stufig/README.md) | Ein-/Aus-Verbraucher (implementiert) |