diff --git a/docs/Schnittstelle.md b/docs/Schnittstelle.md new file mode 100644 index 0000000..60a83d6 --- /dev/null +++ b/docs/Schnittstelle.md @@ -0,0 +1,83 @@ +# 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. +