# EMS-Schnittstelle

Vertragsversion: `4.0`

Es gibt genau eine fachliche Empfangsmethode je Richtung:

```php
public function ManagerdatenEmpfangen(array $daten): void;
public function VerbraucherdatenEmpfangen(array $daten): void;
```

## Gemeinsamer Kopf

| Feld | Typ | Bedeutung |
| --- | --- | --- |
| `Version` | Text | Vertragsversion `4.0` |
| `AbsenderID` | Ganzzahl | Sendende Symcon-Instanz |
| `EmpfaengerID` | Ganzzahl | Empfangende Symcon-Instanz |
| `Zeitpunkt` | Ganzzahl | Unixzeit in UTC |

## Manager an Verbraucher

```json
{
  "Kopf": {
    "Version": "4.0",
    "AbsenderID": 10001,
    "EmpfaengerID": 20001,
    "Zeitpunkt": 1788825600
  },
  "Betriebsart": "PV",
  "Sollleistung_W": 1501
}
```

`Betriebsart` ist `PV` oder `Peak`. `Sollleistung_W` ist eine Ganzzahl
aus dem fuer diese Betriebsart gemeldeten Leistungsangebot oder `null`.

`null` kuendigt nur die Betriebsart an. Der Verbraucher uebernimmt sie,
berechnet sein Leistungsangebot neu und meldet es zurueck. Eine vorhandene
Sollleistung wird dabei nur verworfen, wenn sie im neuen Angebot nicht mehr
zulaessig ist.

## Verbraucher an Manager

```json
{
  "Kopf": {
    "Version": "4.0",
    "AbsenderID": 20001,
    "EmpfaengerID": 10001,
    "Zeitpunkt": 1788825602
  },
  "Betriebsart": "Peak",
  "PrioritaetPV": 0,
  "PrioritaetPeak": 0,
  "Leistungswerte_W": [0],
  "AenderungMoeglich": false,
  "Verfuegbar": true,
  "Istleistung_W": 0,
  "Leistungsquelle": 1,
  "Zustand": [
    {
      "Kennung": "Sollleistung_W",
      "Art": "Sollwert",
      "Wert": 0,
      "Einheit": "W"
    }
  ]
}
```

## Betriebsart-Synchronisation

1. Der Manager bestimmt `PV` oder `Peak`.
2. Meldungen einer anderen Betriebsart werden nicht zur Verteilung verwendet.
3. Der Manager sendet diesen Verbrauchern eine Betriebsart-Ankuendigung mit
   `Sollleistung_W=null`.
4. Jeder Verbraucher berechnet und meldet seine PowerSteps fuer diese
   Betriebsart.
5. Erst wenn alle aktiven Verbraucher synchronisiert sind, verteilt der Manager
   Sollleistungen.

Damit kann jeder Verbrauchertyp unterschiedliche Angebote fuer PV und Peak
melden, ohne dass der Manager seine interne Geraetelogik kennen muss.

## Feste Regeln

- Prioritaeten beginnen bei 0; eine kleinere Zahl bedeutet hoehere Prioritaet.
- `Leistungsquelle`: 0 nicht vorhanden, 1 berechnet, 2 gemessen.
- Bei Leistungsquelle 0 ist `Istleistung_W` zwingend `null`.
- Leistungsbereiche enthalten jeden ganzen Wattwert von `Von_W` bis `Bis_W`.
- Leistungswerte sind aufsteigend, eindeutig und ueberschneiden sich nicht.
- `Zustand` enthaelt immer `Sollleistung_W`.
- Verbraucher werden ausschliesslich im Manager zugeordnet.
- Der Verbraucher besitzt keine Manager-ID-Property.

## Technische Umsetzung in IP-Symcon

Der Transport erfolgt ueber `IPS_RequestAction` mit JSON. `MessageSink`
erkennt registrierte Aenderungen. Empfang und Neuberechnung sind intern
entkoppelt, damit keine gegenseitige Endlosschleife entsteht.

Das PHP-Interface legt nur die Empfangsmethode fest. Die gemeinsamen
Symcon-Datenpunkte registriert `VerbraucherBasisTrait`.

### Gemeinsame Properties aller Verbraucher

| Ident | Typ | Standard | Beschreibung |
| --- | --- | --- | --- |
| `PrioritaetPV` | Integer | `0` | Prioritaet in der Betriebsart PV |
| `PrioritaetPeak` | Integer | `0` | Prioritaet in der Betriebsart Peak |
| `Meldeintervall` | Integer | `10` | Vollstaendige Rueckmeldung in Sekunden |
| `VorgabeTimeout` | Integer | `120` | Ablaufzeit einer Sollleistung |
| `EinstellungenInVisu` | Boolean | `false` | Lokale Einstellungen in der Visualisierung |
| `LoggingEin` | Boolean | `false` | Laufendes Diagnoseprotokoll |

### Gemeinsame Variablen aller Verbraucher

| Ident | Typ / Zugriff | Beschreibung |
| --- | --- | --- |
| `Aktiv` | Boolean / bedienbar | Lokale EMS-Freigabe; Start `false` |
| `Istleistung` | Float / Anzeige | Aktuelle Leistung in W |
| `Leistungsquelle` | Integer / Anzeige | 0 nicht vorhanden, 1 berechnet, 2 gemessen |
| `Sollleistung` | Integer / Anzeige | Angenommene oder lokal erzwungene Vorgabe |
| `SollwertGueltig` | Boolean / Anzeige | Aktuelle, nicht abgelaufene Vorgabe |
| `Verfuegbar` | Boolean / Anzeige | Verbraucher grundsaetzlich verfuegbar |
| `AenderungMoeglich` | Boolean / Anzeige | Neue Vorgabe darf uebernommen werden |
| `Stoerung` | Boolean / Anzeige | Mindestens eine Stoerung aktiv |
| `Stoertext` | String / Anzeige | Zusammengefasste Stoerbeschreibung |

`Leistungswerte_W`, `Betriebsart` und `Zustand` werden intern gehalten
und direkt in die Nachricht geschrieben.

## Batteriespezifische Erweiterung

Die Batterie verwendet denselben Vertrag 4.0 und ergaenzt Zustandseintraege
fuer Ladezustand, Hysterese, Steuerungsmodus, Messwertfehler und
Registerfehler. Positive Leistung bedeutet Laden, negative Leistung
Entladen. Die vollstaendige Semantik und Registeranbindung beschreibt die
[Schnittstelle Batterie](Schnittstelle-Batterie.md).

## Easee-Gateway-Transport

Der technische JSON-Vertrag zwischen `EaseeGateway` und
`LadestationGateway` ist getrennt vom fachlichen Managervertrag dokumentiert:
[Easee-Gateway-Schnittstelle](Schnittstelle-Easee-Gateway.md). Die
Ladestation uebersetzt Gateway-Ereignisse in den hier beschriebenen
Verbrauchervertrag `4.0`.

## Zeitverhalten

- Rueckmeldung nach Start, relevanten Aenderungen und alle `Meldeintervall`
  Sekunden.
- Laufende Vorgaben werden vom Manager standardmaessig erneuert.
- Nach `VorgabeTimeout` ist eine nicht erneuerte Vorgabe ungueltig.
- Nach einem Neustart wird keine alte Vorgabe ungeprueft aufgenommen.