190 lines
7.3 KiB
Markdown
190 lines
7.3 KiB
Markdown
# 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.
|
|
|
|
### Verworfene Sollwerte und Anzeige
|
|
|
|
Beim Verwerfen einer gueltigen Vorgabe setzen alle Verbrauchermodule sowohl
|
|
`SollwertGueltig=false` als auch den gespeicherten und gegebenenfalls sichtbaren
|
|
Wert `Sollleistung=0`. An den Manager geht weiterhin `Sollleistung_W=null`;
|
|
die Anzeige 0 W ist keine neue gueltige Manager-Vorgabe und kein Nachweis einer
|
|
physisch ausgeschalteten Last.
|
|
|
|
Lokale Schutzprogramme, Mindestlaufzeiten und bestehende Lade-Uebergaenge
|
|
bleiben unveraendert. Berechnet ein Modul danach eine lokale Sollleistung,
|
|
darf es diese weiterhin anzeigen. Bei Ladestationen bleibt waehrend eines
|
|
Regeluebergangs insbesondere der letzte Geraetebefehl erhalten, auch wenn die
|
|
alte Manager-Vorgabe bereits verworfen und ihre Anzeige auf 0 gesetzt wurde.
|
|
Wiederholte Verwerfungen einer bereits ungueltigen Manager-Vorgabe lassen eine
|
|
inzwischen neu berechnete lokale Schutzleistung unveraendert.
|
|
|
|
Nach einem Modulupdate bereinigt `ApplyChanges` bereits gespeicherte ungueltige
|
|
Altwerte. Gueltige Vorgaben einschliesslich 0 W und negativer Batterieleistung
|
|
bleiben erhalten. Keine neuen Properties, Variablen-IDs oder Vertragsversion;
|
|
es ist keine manuelle Konfigurationsmigration erforderlich. Das Update ist
|
|
kontrolliert anzuwenden, da die regulaere Instanzinitialisierung wie bisher
|
|
Geraeteaktionen ausloesen kann.
|
|
|
|
## 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. Der Manager verteilt Sollleistungen an alle bereits synchronisierten
|
|
Verbraucher.
|
|
6. Fehlende, veraltete oder noch nicht umgeschaltete Verbraucher werden nicht
|
|
angesteuert und als Stoerung ausgewiesen; sie blockieren die aktuellen
|
|
Verbraucher nicht.
|
|
|
|
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.
|
|
- Jeder verfuegbare, synchronisierte Verbraucher mit einem nicht leeren
|
|
`Leistungswerte_W`-Angebot erhaelt einen Sollwert aus genau diesem Angebot.
|
|
- `AenderungMoeglich=false` kennzeichnet ein fixes Angebot und ist kein
|
|
Ausschlussgrund. Ein Angebot `[11000]` fuehrt deshalb zwingend zu `11000 W`.
|
|
- Prioritaeten verteilen nur die ueber den jeweiligen Mindestwert hinaus
|
|
verfuegbare Leistung; sie duerfen keinen angebotenen Mindestwert verdrängen.
|
|
- `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.
|