138 lines
5.0 KiB
Markdown
138 lines
5.0 KiB
Markdown
# 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 | `30` | 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 Diagnoseprotokoll und zusätzliche Diagnosevariablen. |
|
|
|
|
### 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 10 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.
|