# 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
Einzelwert oder Leistungsbereich enthalten sein. Waehrend 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": "PV",
  "PrioritaetPV": 0,
  "PrioritaetPeak": 0,
  "Leistungswerte_W": [{"Von_W": -5000, "Bis_W": 5000}],
  "AenderungMoeglich": true,
  "Verfuegbar": true,
  "Istleistung_W": -250.0,
  "Leistungsquelle": 2,
  "Zustand": [
    {
      "Kennung": "Sollleistung_W",
      "Art": "Sollwert",
      "Wert": -537,
      "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. Frei regelbare Lade- und Entladeangebote werden als
inklusive Bereiche in ganzen Watt gemeldet. Feste Schutz- und Peakvorgaben
bleiben einzelne Leistungswerte.

## 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).