dh_Agent: docs/Schnittstelle.md anlegen

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.
+