Enelix-EMS/docs/module/Batterie/README.md

Batterie

Die Referenz gilt für develop und beta; main enthält noch kein installierbares Batteriemodul. Kanalstand und bekannte Grenzen.

Status: implementiert. Zielplattform ist IP-Symcon ab Version 8.0, Nachrichtenvertrag 4.0.

Verantwortung

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.

Positive Leistung bedeutet Laden, negative Leistung Entladen. Die Geraeteanbindung erfolgt ausschliesslich ueber vom Benutzer ausgewaehlte numerische IP-Symcon-Variablen. Schreibziele muessen eine Aktion besitzen.

Ereignismodell

Fachliche Neuberechnungen werden ausgeloest durch:

• 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

Der Meldezyklus verschickt eine Vollmeldung und dient nicht als Regelzyklus. Ein periodischer Berechnungstimer oder Idle-Counter existiert nicht.

Properties

Gemeinsame Verbraucherproperties

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
NachladenMitMaximalleistung	Boolean	true	Verwendet fuer schutzbedingtes Nachladen die dynamische maximale Ladeleistung
MaximaleNachladeleistung	Integer	0	Benutzerdefinierte Nachladegrenze in W; bei deaktivierter Maximalleistung muss der Wert groesser als 0 sein
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

Die Batterie meldet innerhalb der dynamischen Lade- und Entladegrenzen inklusive Leistungsbereiche in ganzen Watt. Der Manager kann dadurch jeden ganzzahligen Sollwert innerhalb des aktuell erlaubten Bereichs vorgeben. Die Grenzen werden abgerundet, damit keine dynamische Maximalleistung ueberschritten wird.

PV und Peak verwenden weiterhin die bisherige SoC-Logik. Feste Schutz- oder Peakvorgaben bleiben Einzelwerte; frei regelbare Angebote werden als Bereiche gemeldet. Bei schutzbedingtem Nachladen innerhalb oder unterhalb der Reserve begrenzt MaximaleNachladeleistung die positive Angebotsgrenze, wenn NachladenMitMaximalleistung deaktiviert ist. Der normale Ladebereich oberhalb der Reserve bleibt unveraendert. 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 beschrieben. Transport und gemeinsame Felder folgen EMS-Schnittstelle.

Tests

• BatterieReglerTest: Leistungsbereiche, 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

Weitere Diagnosevariablen und V4-Kompatibilität

Ident	Typ / Zugriff	Bedeutung
LadezustandGueltig	Boolean / Diagnose	Ladezustandsquelle ist vorhanden, aktuell und im zulässigen Bereich.
HystereseAktiv	Boolean / Diagnose	Die Ladezustandshysterese beschränkt das aktuelle Leistungsangebot.

Der frühere separate V4-Formularbereich ist entfernt; vorhandene Properties, Methoden und Kennungen bleiben kompatibel. Dies entfernt weder Schutzprüfungen noch historische Daten. Die Bedienung liegt im Prognosebereich des Managers.

Property	Typ / Standard	Bedeutung
NetzfahrplanV4RegeltestErlaubt	Boolean / false	Lokale Batteriefreigabe für den begrenzten Regeltest.
NetzfahrplanV4AktivtestErlaubt	Boolean / false	Zusätzliche Freigabe für den ausdrücklich befristeten Aktivtest.
NetzfahrplanV4WatchdogVerzichtErlaubt	Boolean / false	Nur dokumentierte Testanlagen-Ausnahme; keine allgemeine Empfehlung oder Dauerfreigabe.
NetzfahrplanV4GeraeteWatchdogNachweis	String / leer	Nachweiskennung des unabhängigen Geräte-Ausfallschutzes. Ein Symcon-Timer ersetzt diesen Nachweis nicht.
NetzfahrplanV4RueckmeldungKonfiguration	String/JSON / {}	Geprüfte physische Messquellen, Vorzeichen und Rückmeldezuordnung. Anlagenspezifisch, keine universelle Musterkonfiguration.

Bestätigter Geräteabruf, Variablenpublikation und Sammlerzeit sind verschieden. Die Rückmeldung verwendet erfolgreiche Geräte-Lesevorgänge und einen kurzlebigen, quellengebundenen Cache. Ungültige/veraltete Bestätigungen verhindern den Test; ein unveränderter Messwert darf nicht künstlich frisch geschrieben werden.

Bekannte Betriebsgrenze: Am 6. Oktober 2026 wurden nach Modul-Reload erneut blockierte Batterie-Timer beobachtet. Die spätere Nachkontrolle vom 7. Oktober meldet laufende periodische Timer, aber keine geklärte Ursache oder physische V4-Abnahme. Status 102 allein beweist keine laufende Rückmeldung oder Watchdog-Ausführung. Automatischen Timerlauf, physisches Tracking, mehrere Planerneuerungen und bestätigten Null-Stopp gesondert nachweisen. Die frühere Testfreigabe endete am 7. Oktober und wird nicht erneuert. Keine externen Timer-Ersatzaufrufe und kein automatischer Aktivstart aus dieser Anleitung.

Beim Verwerfen einer gültigen Manager-Vorgabe wird seit 5437f3f auch Sollleistung auf 0 W gesetzt. Das ist die Bereinigung der Vorgabe, kein Versprechen, dass lokale Schutz-/Nachladefunktionen und Istleistung sofort null werden. Der bestehende Batteriemanagement- und Gerätepfad bleibt massgeblich.