Enelix-EMS/Batterie/README.md

# 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
- stufenlose Leistungsbereiche in ganzen Watt innerhalb der dynamischen Grenzen
- 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. NachladenMitMaximalleistung verwendet standardmaessig die
dynamische maximale Ladeleistung. Wird der Schalter deaktiviert, begrenzt
MaximaleNachladeleistung das schutzbedingte Nachladen in W. Der wirksame Wert
wird nie hoeher als die dynamische Ladegrenze der Batterie.

Die bisherigen betriebsartabhaengigen Angebote bleiben erhalten:

- Im PV-Betrieb steht oberhalb der Reserve der durchgaengige Bereich von der
  maximalen Entlade- bis zur maximalen Ladeleistung zur Verfuegung.
- Unterhalb der Reserve wird die wirksame Nachladeleistung als fester Wert
  angeboten.
- Bei vollem Speicher wird der durchgaengige Bereich von der maximalen
  Entladeleistung bis 0 W 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; die positive Grenze ist dabei
  hoechstens die konfigurierte Nachladeleistung.
- Oberhalb der Reserve ohne aktive Hysterese bleibt der normale Ladebereich
  unveraendert und wird nicht durch die Nachladegrenze reduziert.

## 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, Hysterese und Nachladeleistung 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)