feat: Batteriemodul ereignisbasiert integrieren

2026-09-22 09:27:49 +00:00
parent d03a7fd8fb
commit d7308663da
18 changed files with 2670 additions and 51 deletions
@@ -0,0 +1,110 @@
+# Schnittstelle Batterie
+
+Diese Beschreibung ergaenzt den allgemeinen
+[Manager-Verbraucher-Vertrag](Schnittstelle.md) fuer das Batteriemodul.
+Vertragsversion ist 4.0.
+
+## Manager an Batterie
+
+Die Batterie empfaengt den unveraenderten gemeinsamen Datensatz:
+
+~~~json
+{
+  "Kopf": {
+    "Version": "4.0",
+    "AbsenderID": 10001,
+    "EmpfaengerID": 20001,
+    "Zeitpunkt": 1788825600
+  },
+  "Betriebsart": "PV",
+  "Sollleistung_W": -1500
+}
+~~~
+
+Sollleistung_W verwendet folgende Semantik:
+
+- positiver Wert: Batterie laden
+- negativer Wert: Batterie entladen
+- 0: Leistungsregister auf 0 setzen
+- null: nur Betriebsart synchronisieren und neues Angebot anfordern
+
+Ein konkreter Wert muss im zuletzt fuer dieselbe Betriebsart gemeldeten
+Leistungsangebot enthalten sein. Waehren der Aenderungssperre wird nur die
+Wiederholung des aktuellen Sollwerts akzeptiert.
+
+## Batterie an Manager
+
+Die Batterie verwendet alle Pflichtfelder des gemeinsamen Vertrags und
+ergaenzt folgende Zustandseintraege:
+
+| Kennung | Art | Typ | Einheit | Bedeutung |
+| --- | --- | --- | --- | --- |
+| Sollleistung_W | Sollwert | Integer oder null | W | Aktuell gueltige Manager-Vorgabe |
+| Ladezustand_Prozent | Istwert | Float oder null | % | Physischer SoC |
+| HystereseAktiv | Status | Boolean | - | Reserve-Hysterese ist aktiv |
+| Batteriesteuerung | Status | Integer | - | 1 Wechselrichter, 2 Enelix |
+| Messwertfehler | Stoerung | Boolean | - | Pflichtmesswert fehlt oder ist ungueltig |
+| Registerfehler | Stoerung | Boolean | - | Mindestens ein Schreibbefehl ist fehlgeschlagen |
+
+Beispiel:
+
+~~~json
+{
+  "Kopf": {
+    "Version": "4.0",
+    "AbsenderID": 20001,
+    "EmpfaengerID": 10001,
+    "Zeitpunkt": 1788825602
+  },
+  "Betriebsart": "Peak",
+  "PrioritaetPV": 0,
+  "PrioritaetPeak": 0,
+  "Leistungswerte_W": [-1500],
+  "AenderungMoeglich": true,
+  "Verfuegbar": true,
+  "Istleistung_W": -250.0,
+  "Leistungsquelle": 2,
+  "Zustand": [
+    {
+      "Kennung": "Sollleistung_W",
+      "Art": "Sollwert",
+      "Wert": -1500,
+      "Einheit": "W"
+    },
+    {
+      "Kennung": "Ladezustand_Prozent",
+      "Art": "Istwert",
+      "Wert": 54.2,
+      "Einheit": "%"
+    }
+  ]
+}
+~~~
+
+Ist die Leistungsmessung ungueltig, wird Istleistung_W als null und
+Leistungsquelle als 0 gemeldet. Bei einem gueltigen Messwert ist
+Leistungsquelle 2.
+
+## Ereignisse
+
+Das Modul registriert VM_UPDATE fuer:
+
+- maximale Ladeleistung
+- maximale Entladeleistung
+- Ladezustand
+- Netzleistung
+- aktuelle Batterieleistung
+
+Jede Aktualisierung berechnet Zustand und Angebot neu und plant eine
+gebuendelte Rueckmeldung. Registerwerte werden nur geschrieben, wenn sich der
+resultierende Befehl geaendert hat.
+
+## Registerausgang
+
+Der technische Ausgang besteht aus ausgewaehlten numerischen
+IP-Symcon-Variablen. Das Modul verwendet RequestAction und setzt diese
+Variablen nicht mit SetValue. Damit bleibt der jeweilige Modbus-, Skript- oder
+Geraeteadapter fuer die konkrete Registerkommunikation verantwortlich.
+
+Die genaue Herstellerabbildung steht in der
+[Moduldokumentation](module/Batterie/README.md).