Enelix-EMS/docs/Schnittstelle.md

EMS-Schnittstelle

Vertragsversion: 3.0

Es gibt genau eine fachliche Empfangsmethode je Richtung:

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

{
  "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

{
  "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	120	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 das laufende Diagnoseprotokoll. Module können zusätzliche Diagnosevariablen getrennt einblenden.

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. Während einer Lastwechselsperre meldet ein Verbraucher AenderungMoeglich als false und beschränkt Leistungswerte_W auf die aktuell gehaltene Leistung. Separate Felder wie Idle oder IdleCounter sind nicht Bestandteil des Vertrags.

Zeitverhalten

• Rückmeldung nach dem Start, bei relevanten Änderungen und zusätzlich alle Meldeintervall Sekunden.
• Laufende Vorgaben werden vom Manager standardmässig alle 60 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 beschrieben.