feat: Batteriemodul ereignisbasiert integrieren

Batterie/README.md

@@ -0,0 +1,172 @@
+# Batterie
+
+IP-Symcon-Modul fuer Batteriespeicher im Enelix EMS. Das Modul uebernimmt die
+Leistungsangebote und SoC-Logik der bisherigen Enelix-Batterie, arbeitet aber
+ereignisbasiert und schreibt Stellwerte direkt in ausgewaehlte
+IP-Symcon-Registervariablen.
+
+## Funktionen
+
+- positive Leistung bedeutet Laden, negative Leistung bedeutet Entladen
+- 250-W-Grundraster mit 50-W-Feinwerten zwischen -200 W und +200 W
+- unterschiedliche Leistungsangebote fuer PV- und Peakbetrieb
+- Reserve- und Mindestladezustand mit konfigurierbarer Hysterese
+- direkte Registeransteuerung fuer herstellerunabhaengige Batterien, GoodWe,
+  SolarEdge und Sigenergy
+- Umschaltung zwischen Wechselrichter- und Enelix-Steuerung
+- ereignisbasierte Reaktion auf alle ausgewaehlten Messwerte
+- Managerkommunikation ueber den Enelix-Vertrag 4.0
+- Sollwert-Timeout, zeitbasierte Aenderungssperre und periodische Vollmeldung
+- optionale Diagnosevariablen und Debug-Logging
+
+Es gibt keinen zyklischen Regel- oder Berechnungstimer. Timer werden nur fuer
+Vollmeldungen, den Ablauf einer Manager-Vorgabe und das Ende der
+Aenderungssperre verwendet.
+
+## Voraussetzungen
+
+- IP-Symcon ab Version 8.0
+- ein eingerichteter Enelix Manager
+- numerische Variablen fuer Ladezustand, Netzleistung, Batterieleistung sowie
+  maximale Lade- und Entladeleistung
+- numerische Registervariablen mit Standard- oder benutzerdefinierter Aktion
+
+## Vorzeichen und Einheiten
+
+| Wert | Positiv | Negativ | Einheit |
+| --- | --- | --- | --- |
+| Manager-Sollleistung | Laden | Entladen | W |
+| Batterieleistung | Laden | Entladen | W |
+| Netzleistung | Netzbezug | Einspeisung | W |
+| Ladezustand | - | - | % |
+
+Sigenergy-Leistungsregister werden in kW beschrieben. Alle anderen
+Leistungsregister werden in W beschrieben.
+
+## Batterietypen und Register
+
+| Batterietyp | Management | Modus | Leistungsregister |
+| --- | --- | --- | --- |
+| Herstellerunabhaengig | WR 0, Enelix 1 | Laden 0, Entladen 1 | getrennt Laden/Entladen in W |
+| GoodWe | WR 1, Enelix 2 | Laden 11, Entladen 12 | gemeinsam, absoluter Wert in W |
+| SolarEdge | WR 1, Enelix 4 | Laden 3, Entladen 4 | getrennt Laden/Entladen in W |
+| Sigenergy | WR 0, Enelix 1 | Laden 3, Entladen 6 | getrennt Laden/Entladen in kW |
+
+Bei Wechselrichtersteuerung bietet die Batterie dem Manager nur [0] an. Das
+Modul setzt die Leistungsregister auf 0 und schreibt den passenden
+Automatikcode in das Managementregister.
+
+Die Konfigurationsmaske zeigt nach Wahl des Batterietyps nur die benoetigten
+Registerauswahlen:
+
+- GoodWe: Management, Modus und gemeinsames Leistungsregister
+- alle anderen Typen: Management, Modus, Ladeleistung und Entladeleistung
+
+## Messwerte
+
+| Property | Beschreibung |
+| --- | --- |
+| MaxLadeleistungVariableID | Aktuell zulaessige maximale Ladeleistung in W |
+| MaxEntladeleistungVariableID | Aktuell zulaessige maximale Entladeleistung in W |
+| LadezustandVariableID | Ladezustand in % |
+| NetzleistungVariableID | Netzbezug beziehungsweise Einspeisung in W |
+| IstleistungVariableID | Aktuelle Batterieleistung in W |
+| MesswertMaxAlter | Maximales Alter jedes Messwertes in Sekunden |
+
+Alle Messwerte muessen als Integer- oder Floatvariable vorliegen. Fehlt ein
+Messwert, ist er veraltet oder liegt der Ladezustand ausserhalb von 0 bis
+100 %, meldet sich die Batterie als nicht verfuegbar und bietet nur [0] an.
+
+## Ladezustandslogik
+
+ReserveLadezustand entspricht der bisherigen Peakshaving-Reserve.
+MindestLadezustand schuetzt vor weiterer Entladung.
+LadezustandHysterese ersetzt die bisher fest im Code hinterlegte
+2-Prozent-Hysterese.
+
+Die bisherigen betriebsartabhaengigen Angebote bleiben erhalten:
+
+- Im PV-Betrieb steht oberhalb der Reserve das gesamte Raster zur Verfuegung.
+- Unterhalb der Reserve wird die maximale Ladeleistung angeboten.
+- Bei vollem Speicher werden nur Entladung und 0 angeboten.
+- Im Peakbetrieb wird oberhalb der Reserve der aus Netz- und aktueller
+  Batterieleistung berechnete Entladewert angeboten.
+- Innerhalb der Reserve-Hysterese und unterhalb des Mindestladezustands werden
+  Laden und Entladen wie bisher eingeschraenkt.
+
+## Manager und Zeitverhalten
+
+Das Modul verwendet den gemeinsamen Enelix-Nachrichtenvertrag 4.0.
+Betriebsart ist PV oder Peak. Ein Paket mit Sollleistung_W=null
+kuendigt nur die Betriebsart an und loest die Neuberechnung des Angebots aus.
+
+Aenderungssperre ist die ereignisbasierte Entsprechung des frueheren
+Idle-Counters. Nach einer echten Sollwertaenderung meldet das Modul
+AenderungMoeglich=false. Ein einmaliger Timer hebt die Sperre nach Ablauf
+der konfigurierten Sekunden wieder auf.
+
+VorgabeTimeout setzt die Register auf 0, wenn der Manager eine Vorgabe
+nicht rechtzeitig erneuert. Meldeintervall erzeugt nur eine periodische
+Vollmeldung und fuehrt keinen unabhaengigen Regelzyklus aus.
+
+## Sichtbare Variablen
+
+Immer vorhanden:
+
+- Aktiv: lokale EMS-Freigabe
+- Ladestatus: 0 unbekannt, 1 ruhend, 2 laden, 3 entladen
+
+Bei aktivierten Diagnosevariablen werden zusaetzlich unter anderem
+Istleistung, Sollleistung, Ladezustand, Messwertgueltigkeit, Hysterese,
+Leistungsgrenzen, Energie, Leistungsangebot und der letzte Registerbefehl
+angezeigt.
+
+LoggingEin aktiviert zusaetzliche Meldungen im IP-Symcon-Debugprotokoll.
+Die Schaltflaeche **Messwerte und Angebot aktualisieren** loest eine sofortige
+ereignisartige Aktualisierung aus. **Register auf sicheren Zustand setzen**
+verwirft die aktuelle Vorgabe und schreibt eine Leistung von 0.
+
+## Inbetriebnahme
+
+1. Batterietyp und Steuerung auswaehlen.
+2. Alle fuenf Messwertvariablen zuordnen.
+3. Die automatisch eingeblendeten Registervariablen zuordnen.
+4. Reserve, Mindestladezustand und Hysterese pruefen.
+5. Diagnosevariablen und Logging fuer die Erstinbetriebnahme aktivieren.
+6. Die Batterie im Manager zuordnen.
+7. Aktiv einschalten.
+8. Unter Aufsicht je einen Lade-, Entlade- und Nullsollwert senden.
+9. Registercodes, Vorzeichen, Einheiten und reale Wechselrichterreaktion
+   kontrollieren.
+10. Abschliessend die Wechselrichtersteuerung waehlen und pruefen, dass alle
+    Leistungsregister auf 0 sowie das Managementregister auf Automatik gehen.
+
+## Fehlerbilder
+
+- **Konfiguration ungueltig:** Variablentypen, Aktionszuordnung und die fuer
+  den Batterietyp erforderlichen Register pruefen.
+- **Messwerte fehlen oder sind veraltet:** Variablenaktualisierung und
+  MesswertMaxAlter kontrollieren.
+- **Register konnten nicht geschrieben werden:** Standard- oder
+  benutzerdefinierte Aktion der Zielvariablen sowie die Geraetekommunikation
+  pruefen.
+- **Sollwert wird abgewiesen:** Der Wert muss im zuletzt gemeldeten Angebot
+  enthalten und die Aenderungssperre muss abgelaufen sein.
+
+## Tests
+
+~~~bash
+composer test -- --filter 'Batterie(Regler|Modulstruktur)Test'
+composer symcon:single -- Batterie
+composer check
+~~~
+
+Der Symcon-Test prueft die Modulinstanz, direkte GoodWe-Registerbefehle,
+Laden und Entladen, Messwertereignisse sowie die Rueckgabe an die
+Wechselrichtersteuerung.
+
+## Weiterfuehrende Dokumentation
+
+- [Ausfuehrliche Modulbeschreibung](../docs/module/Batterie/README.md)
+- [Manager-Verbraucher-Schnittstelle](../docs/Schnittstelle.md)
+- [Migration von Enelix 1](../docs/migration/Batterie.md)