# EMS-Schnittstelle

Vertragsversion: `3.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 `3.0` |
| `AbsenderID` | Ganzzahl | Sendende Symcon-Instanz |
| `EmpfaengerID` | Ganzzahl | Empfangende Symcon-Instanz |
| `Zeitpunkt` | Ganzzahl | Unixzeit in UTC |

## Manager an Verbraucher

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

`Sollleistung_W` ist immer eine Ganzzahl und muss im aktuell gemeldeten Leistungsangebot liegen.

## Verbraucher an Manager

```json
{
  "Kopf": {
    "Version": "3.0",
    "AbsenderID": 20001,
    "EmpfaengerID": 10001,
    "Zeitpunkt": 1788825602
  },
  "PrioritaetPV": 0,
  "PrioritaetPeak": 0,
  "Leistungswerte_W": [
    -3000,
    -2000,
    {"Von_W": -1000, "Bis_W": -500},
    0,
    100,
    {"Von_W": 1000, "Bis_W": 2000},
    3000
  ],
  "AenderungMoeglich": true,
  "Verfuegbar": true,
  "Istleistung_W": 1498.5,
  "Leistungsquelle": 2,
  "Zustand": [
    {
      "Kennung": "Sollleistung_W",
      "Art": "Sollwert",
      "Wert": 1501,
      "Einheit": "W"
    }
  ]
}
```

### Feste Regeln

- Prioritaeten beginnen bei 0; eine kleinere Zahl bedeutet eine 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` einschliesslich.
- Die Leistungswerte sind aufsteigend, eindeutig und ueberschneiden sich nicht.
- `Zustand` enthaelt immer den gemeinsamen Eintrag `Sollleistung_W` und daneben nur benoetigte geraetespezifische Eintraege.
- Eine aktive Stoerung wird mit `Art=Stoerung` und `Wert=true` gemeldet; eine behobene mit `false`.
- Verbraucher werden ausschliesslich im Manager zugeordnet. Der Verbraucher besitzt keine Manager-ID-Property.

## Technische Umsetzung in IP-Symcon

Der Transport erfolgt über `IPS_RequestAction` mit JSON. `MessageSink` erkennt
registrierte Änderungen; der empfangende Action-Handler prüft das Paket und
ruft danach genau eine fachliche Empfangsmethode auf. Empfang und Neuberechnung
werden intern entkoppelt, damit keine gegenseitige Endlosschleife entsteht.

Das PHP-Interface legt nur die Methode fest. Die folgenden gemeinsamen
Symcon-Datenpunkte werden durch `VerbraucherBasisTrait` registriert.

### Gemeinsame Properties aller Verbraucher

| Ident | Typ | Standard | Beschreibung |
| --- | --- | --- | --- |
| `PrioritaetPV` | Integer | `0` | Priorität ab 0; kleinere Zahl bedeutet höhere Priorität. |
| `PrioritaetPeak` | Integer | `0` | Wie PV-Priorität, ohne fachliche Obergrenze. |
| `Meldeintervall` | Integer | `10` | Vollständige Rückmeldung in Sekunden; muss grösser als 0 sein. |
| `VorgabeTimeout` | Integer | `120` | Sollwert wird nach dieser Zeit ohne Erneuerung ungültig. |
| `EinstellungenInVisu` | Boolean | `false` | Blendet lokale Einstellvariablen ein und macht sie geprüft bedienbar. |
| `LoggingEin` | Boolean | `false` | Aktiviert das laufende Diagnoseprotokoll. Module können zusätzliche Diagnosevariablen getrennt einblenden. |

### Gemeinsame Variablen aller Verbraucher

| Ident | Typ / Zugriff | Beschreibung |
| --- | --- | --- |
| `Aktiv` | Boolean / bedienbar | Lokale EMS-Freigabe; Start `false`. |
| `Istleistung` | Float / Anzeige | Aktuelle Leistung in W; nur zusammen mit `Leistungsquelle` gültig. |
| `Leistungsquelle` | Integer / Anzeige | `0` nicht vorhanden, `1` berechnet, `2` gemessen. |
| `Sollleistung` | Integer / Anzeige | Tatsächlich angenommene Vorgabe in W. |
| `SollwertGueltig` | Boolean / Anzeige | Kennzeichnet eine aktuell gültige Vorgabe. |
| `Verfuegbar` | Boolean / Anzeige | Verbraucher grundsätzlich für EMS-Steuerung verfügbar. |
| `AenderungMoeglich` | Boolean / Anzeige | Neue Vorgabe darf momentan übernommen werden. |
| `Stoerung` | Boolean / Anzeige | Mindestens ein Zustandseintrag der Art `Stoerung` ist aktiv. |
| `Stoertext` | String / Anzeige | Zusammengefasste lesbare Störbeschreibung. |

`Leistungswerte_W` und `Zustand` werden intern gehalten und direkt in die
Nachricht geschrieben. Dafür werden keine zusätzlichen Symcon-Variablen
angelegt. Der gemeinsame Zustandseintrag `Sollleistung_W` wird durch die Basis
ergänzt.

## Zeitverhalten

- Rückmeldung nach dem Start, bei relevanten Änderungen und zusätzlich alle
  `Meldeintervall` Sekunden.
- Laufende Vorgaben werden vom Manager standardmässig alle 60 Sekunden erneuert.
- Nach `VorgabeTimeout` Sekunden ist eine nicht erneuerte Vorgabe ungültig.
- Nach einem Neustart wird zuerst der Gerätezustand erfasst; eine alte Vorgabe
  wird nicht ungeprüft wieder aufgenommen.

## Obere Anschlüsse des Managers

SDL/VGT, Prognose, Lizenzierung und Störüberwachung verändern den
Manager-Verbraucher-Vertrag nicht. Ihr aktueller Diskussionsstand ist in
[Obere-Anschluesse.md](Obere-Anschluesse.md) beschrieben.