158 lines
5.4 KiB
Markdown
158 lines
5.4 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.
|
|
|
|
## 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. Erst wenn alle aktiven Verbraucher synchronisiert sind, verteilt der Manager
|
|
Sollleistungen.
|
|
|
|
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.
|
|
- `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.
|