Enelix-EMS/docs/Schnittstelle.md

EMS-Schnittstelle

Vertragsversion: 4.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 4.0
AbsenderID	Ganzzahl	Sendende Symcon-Instanz
EmpfaengerID	Ganzzahl	Empfangende Symcon-Instanz
Zeitpunkt	Ganzzahl	Unixzeit in UTC

Manager an Verbraucher

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

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

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.