Echtzeitübertragung und direkte Steuerung für Frontends

Der Schritt „Ausführung“ in der Architekturübersicht umfasst neben Datenpunktschreiben, Alarmen und MQTT auch die direkte Anbindung von Frontends. Edge-EMS Builder bietet zwei WebSocket-Kanäle, über die individuelle Frontends Echtzeitdaten empfangen und Steuerbefehle direkt an Geräte senden können. Eine zusätzliche Zwischenschicht muss nicht entwickelt werden.

1. Zwei WebSocket-Kanäle

Kanal	Pfad	Authentifizierung	Zweck
Frontend-Push-Kanal	ws://<host>:<port>/front	Anmelde-Token nach Anmeldung mit Benutzername und Passwort	Individuelle Frontends; rollenbasierte Berechtigungsprüfung, Abonnements und direktes Schreiben
Daten-Lese-/Schreibkanal	ws://<host>:<port>/data/rw	Statisches data-rw-token aus ems.yaml	Backend-Integrationen; ohne Anmeldung, Lese-/Schreibzugriffe mit geringer Latenz, für System-zu-System-Integration

Beide Kanäle verwenden identische Nachrichtenformate. Sie unterscheiden sich nur in Authentifizierung und Granularität der Berechtigungsprüfung. Diese Seite erläutert hauptsächlich /front; /data/rw wird entsprechend verwendet.

Übergeben Sie beim Verbindungsaufbau folgende Query-Parameter:

ws://<host>:<port>/front?socketId=<benutzerdefinierte-Verbindungs-ID>&token=<Anmelde-Token>
ws://<host>:<port>/data/rw?socketId=<benutzerdefinierte-Verbindungs-ID>&token=<data-rw-token>

2. Nachrichtenformat

Einheitlicher Aufbau einer Anfrage (Frontend → Edge-EMS Builder):

{
  "topic": "read | write | clear",
  "messageId": "Benutzerdefinierte eindeutige ID zur Zuordnung der Antwort",
  "keep": true,
  "content": [
    { "dataKey": "pcsActivePower" }
  ]
}

Antworten (Edge-EMS Builder → Frontend) werden über messageId eindeutig der jeweiligen Anfrage zugeordnet:

{
  "code": "200",
  "message": "Processed successfully",
  "topic": "read",
  "messageId": "...",
  "time": "2026-07-23T10:00:00+08:00",
  "data": { "...": "..." }
}

3. Echtzeitdaten empfangen: Abonnement = read + keep

Das Push-Modell von Edge-EMS Builder ist kein Publish/Subscribe auf einem Topic. Stattdessen legt jede Verbindung ihre eigene Push-Konfiguration fest:

1. Das Frontend sendet topic: "read", führt in content die gewünschten dataKey-Kennungen auf oder wählt mit groupCode eine ganze Datengruppe aus und setzt keep auf true.
2. Edge-EMS Builder speichert content als Push-Konfiguration dieser Verbindung (socketId) und antwortet sofort einmal mit den aktuellen Werten.
3. Eine Hintergrundaufgabe durchläuft anschließend jede Sekunde alle noch verbundenen Frontend-Sockets und überträgt die aktuellen Werte ihrer jeweiligen Konfiguration aktiv. Wiederholte Polling-Anfragen des Frontends sind nicht erforderlich.
4. Wenn keine dauerhafte Übertragung benötigt wird, setzen Sie keep auf false oder lassen es weg. Edge-EMS Builder sendet dann nur 30 Sekunden lang Daten.
5. Senden Sie topic: "clear", um die Push-Konfiguration einer Verbindung zu entfernen.

// Abonnement: Neueste Werte von pcsActivePower und bmsSOC fortlaufend verfolgen
{
  "topic": "read",
  "messageId": "sub-001",
  "keep": true,
  "content": [
    { "dataKey": "pcsActivePower" },
    { "dataKey": "bmsSOC" }
  ]
}

// Alternativ nach Gruppe abonnieren: alle Datenpunkte der Gruppe einschließlich Untergruppen
{
  "topic": "read",
  "messageId": "sub-002",
  "keep": true,
  "content": [
    { "groupCode": "pcs-group-01" }
  ]
}

Dieselbe Verbindung kann mehrmals read mit keep:true senden, um die Push-Konfiguration zu ergänzen oder zu aktualisieren. Mindestens eines der Felder dataKey und groupCode muss angegeben sein.

4. Geräte direkt steuern: write

Das Frontend sendet topic: "write" und übergibt in content die zu schreibenden dataKey und dataValue. Eine Datentypangabe ist nicht erforderlich. Edge-EMS Builder erkennt anhand von dataKey, ob es sich um Rohdaten (Collection), Aggregationsdaten (Aggregation) oder Zeitplandaten (Customization) handelt, und leitet an die entsprechende Schreiblogik weiter:

{
  "topic": "write",
  "messageId": "ctrl-001",
  "content": [
    { "dataKey": "pcsActivePower", "dataValue": "300" }
  ]
}

Beim Schreiben von Zeitplandaten (Customization) kann ein Gültigkeitsintervall mitgegeben werden:

{
  "topic": "write",
  "messageId": "ctrl-002",
  "resetCustomValue": true,
  "content": [
    {
      "dataKey": "import_price",
      "dataValue": "0.85",
      "availableDate": "2026-06-25T00:00:00+08:00",
      "expiredDate": "2026-06-25T08:00:00+08:00"
    }
  ]
}

• resetCustomValue: true löscht zuerst die vorhandenen Werte dieses Zeitplandatenpunkts und schreibt anschließend die neuen Inhalte. Dies dient zum vollständigen Ersetzen eines Plans und vermeidet Überschneidungen alter und neuer Zeitfenster.
• Zum Schreiben eines Datenpunkts auf einem anderen freigebenden Gerät ergänzen Sie im jeweiligen content-Element das Feld deviceCode. Edge-EMS Builder erkennt den Schreibzugriff auf freigegebene Daten und leitet ihn zum Zielgerät weiter.

Berechtigungsregeln

• Verbindung über /data/rw mit statischem data-rw-token: Direkte Freigabe ohne Rollenprüfung, geeignet für Backend-Systemintegration.
• Verbindung über /front mit Anmelde-Token: Das Konto muss Superadministrator, Administrator oder Bediener sein. Beobachter dürfen nicht schreiben. Dies entspricht den Berechtigungen der Oberfläche; es gibt keinen Schreibweg zur Umgehung dieser Frontend-Berechtigungen.

Täglich wiederkehrende Pläne

DAILY_REPEAT verwendet availableTime / expiredTime, beispielsweise 08:00:00 bis 12:00:00. Der Gesamtgültigkeitszeitraum wird am Zeitplandatenpunkt konfiguriert. Nur DAILY_CHANGE verwendet vollständige Datums- und Zeitintervalle. Beide Parametertypen dürfen nicht vermischt werden; Zeitfenster über Mitternacht sind aufzuteilen.

Verbindung und Ausführungsergebnisse

/front prüft die Verbindung über Ping/Pong-Heartbeats. Clients müssen code/message beim Schließen verarbeiten und nach einer Wiederverbindung ihre Abonnements neu aufbauen. Schreibanfragen dürfen dabei nicht automatisch zusammen mit den Abonnements erneut gesendet werden.

Maßgeblich für Geräteschreibzugriffe sind die CommBridge-Antwort oder das Zeitüberschreitungsergebnis. Erfolgreiches Senden allein bestätigt keine Geräteausführung. Gerätesteuerungsprotokolle zeigen In Bearbeitung, Erfolgreich und Fehlgeschlagen. Die Faktor-Rückrechnung beim Schreiben übernimmt CommBridge; Aufrufer dürfen nicht erneut umrechnen.

Während einer Wartungssperre liefern geschützte Steuer-Schreibzugriffe 200162. Die Sperre darf nicht automatisch verlassen werden, um den Zugriff erneut zu versuchen.

5. Vollständiges Frontend-Integrationsbeispiel

const ws = new WebSocket(`ws://<host>:<port>/front?socketId=web-ui-01&token=${loginToken}`);

ws.onopen = () => {
  // Echtzeitdaten abonnieren: PCS-Wirkleistung und SOC verfolgen
  ws.send(JSON.stringify({
    topic: 'read',
    messageId: 'sub-' + Date.now(),
    keep: true,
    content: [
      { dataKey: 'pcsActivePower' },
      { dataKey: 'bmsSOC' }
    ]
  }));
};

ws.onmessage = (event) => {
  const resp = JSON.parse(event.data);
  if (resp.topic === 'read') {
    // Jede Sekunde werden die neuesten Werte empfangen; Dashboard und Diagramme aktualisieren
    renderDashboard(resp.data);
  }
  if (resp.topic === 'write') {
    // Rückmeldung zum Schreibvorgang: resp.successContent / resp.errorContent
    showWriteResult(resp);
  }
};

// Wenn der Benutzer in der Oberfläche auf „Leistung auf 300 kW setzen“ klickt:
function setPower(value) {
  ws.send(JSON.stringify({
    topic: 'write',
    messageId: 'ctrl-' + Date.now(),
    content: [{ dataKey: 'pcsActivePower', dataValue: String(value) }]
  }));
}

Dieser Code deckt den typischen vollständigen Frontend-Ablauf ab: beim Laden der Seite Echtzeitdaten abonnieren → Oberfläche sekündlich aktualisieren → bei Benutzeraktionen Steuerbefehle direkt senden → Rückmeldung zum Schreibergebnis erhalten. Ein zusätzlicher Backend-Vermittlungsdienst ist nicht erforderlich.

6. Zusammenspiel mit anderen Funktionen

• Über /front oder /data/rw geschriebene Daten sind dieselben Daten, die Triggerschemata und Ausdrucksengine lesen. Nach dem Zurücklesen vom Gerät können die endgültigen Ergebnisse einer Frontend-Steueraktion wieder in Aggregationsausdrücke und Triggerbedingungen einfließen. Siehe Datenmodell.
• Für die zusätzliche Darstellung auf einem Cloud-Dashboard können beide Wege parallel genutzt werden: /front versorgt das eigene Frontend, während Cloud-Edge-Koordination mit MQTT dieselben Daten an die Cloud meldet.
• Der KI-Konfigurations-Skill aems-write-data kapselt Aufrufe von /data/rw und /front. Damit kann ein KI-Agent anhand natürlichsprachlicher Anweisungen beim Prüfen von Schreibbefehlen helfen.

Nächste Schritte

• Vollständige HTTP-/WebSocket-Schnittstellenliste: Fordern Sie die „HTTP-Schnittstellendokumentation von Edge-EMS Builder“ beim technischen Support an.
• Verwendung geschriebener Daten in Ausdrücken und Regeln: Ausdrucksengine, Triggerschemata
• Für geräteübergreifende Schreibzugriffe: Gerätekoordination und Freigabeziele