Ausdrucksengine

Die Ausdrucksengine bildet den Kern der Berechnungsfunktionen von Edge-EMS Builder. Werte von Aggregationsdatenpunkten, Bedingungen von Triggerschemata und der Aufbau von MQTT-Nachrichten entstehen jeweils durch die Ausführung eines Skripts. Die Skriptsprache ist Lua.

1. Regeln für Variablenreferenzen

Vor der Ausführung eines Ausdrucksskripts ersetzt Edge-EMS Builder Platzhalter der Form ${...} durch die tatsächlichen Datenwerte. Anschließend wird das Skript ausgeführt. Folgende Schreibweisen werden unterstützt und lassen sich kombinieren:

Schreibweise	Beschreibung	Beispiel
${dataKey}	Aktuellen Wert eines Datenpunkts referenzieren	${PCS1_有功功率}
${dataKey[-NTimeUnit]}	Historischen Wert von vor N Zeiteinheiten referenzieren	${PCS1_有功功率[-5s]} bezeichnet den Wert vor 5 Sekunden
${dataKey[#N]}	N-ten historischen Messwert vom Ende referenzieren	${PCS1_有功功率[#3]} bezeichnet den drittletzten Wert
${dataKey[raw]}	Unverändert und ohne automatische Typumwandlung einsetzen. Bei schwer unterscheidbaren Darstellungen wie der Zahl 1000 und dem Binärwert 1000 erzwingt raw die unveränderte Übergabe; muss ausschließlich an letzter Stelle stehen	${设备状态[raw]}
${[deviceCode]dataKey}	Aktuellsten Datenpunktwert eines freigebenden Geräts (Share) referenzieren	${[DeviceA]PCS1_有功功率}
Kombination	Die obigen Regeln können frei kombiniert werden	${[DeviceA]PCS1_有功功率[-1s][#3]}

Fehlende Werte: Hat der Zieldatenpunkt aktuell keinen Wert, setzt die Engine die Zeichenfolge __Null__ ein. Prüfen Sie diese ausdrücklich oder verwenden Sie isNull / isNotNull. Nutzen Sie vor numerischen Berechnungen tonumber; verlassen Sie sich bei dieser Zeichenfolge nicht auf or 0.

Unterstützte Einheiten für Zeitverschiebungen:

Einheit	Zulässige Kurzformen
Millisekunde	ms / millisecond
Sekunde	s / sec / second / seconds
Minute	m / min / minute / minutes
Stunde	h / hour / hours
Tag	d / day / days
Woche	w / week / weeks
Monat	M / month

2. Skriptkörper: Standard-Lua-Syntax

Nach dem Ersetzen der Platzhalter wird der verbleibende Skriptkörper gemäß Lua 5.1 ausgeführt. Das Ergebnis wird mit return zurückgegeben. Sie können daher native Lua-Variablen, Bedingungen, Schleifen und Funktionen verwenden:

-- Gesamte Scheinleistung berechnen (vereinfachtes Beispiel)
local ua, ub, uc = tonumber(${Meter1_Ua}), tonumber(${Meter1_Ub}), tonumber(${Meter1_Uc})
local ia, ib, ic = tonumber(${Meter1_Ia}), tonumber(${Meter1_Ib}), tonumber(${Meter1_Ic})
if not (ua and ub and uc and ia and ib and ic) then return "__Null__" end

local s = ua * ia + ub * ib + uc * ic
return s

3. Integrierte Funktionen und Module

Zusätzlich zur Standard-Lua-Syntax einschließlich der nativen Bibliotheken string/table/math stellt Edge-EMS Builder globale Funktionen und über require ladbare Module bereit. Sie decken Datenzugriffe, den Aufbau von Schreibaktionen sowie Zeichenfolgen-, Zeit- und Regex-Verarbeitung ab und ermöglichen komplexe Logik ohne Entwicklung von Basisfunktionen:

Kategorie	Beschreibung	Beispiel
Datenzugriff (globale Funktionen)	getLatestDataValue, getHistoryData, getDeviceShareValue sowie Funktionsfamilien für Sammelabfragen nach Präfix, Suffix oder unscharfer Übereinstimmung	Datenpunkte mit gemeinsamen Namensregeln dynamisch durchsuchen; siehe Beispiel zur dynamischen Geräteerkennung unter Triggerschemata
Aufbau von Schreibaktionen (globale Funktionen)	buildCommonWriteMap, buildCustomizationWriteMap, buildDailyRepeatWriteMap, buildCommonAlarmMap, buildMqttAlarmMap, buildAlarmObservationMap, buildSlaveWriteMap	Zieldatenstrukturen für die einheitliche Ausführung durch Trigger- oder MQTT-Aktionen erstellen
Zeitumrechnung	cp56Time2aToOffsetDateTime, offsetDateTimeToCP56Time2a, mit AB/BA-Unterstützung	IEC-Zeitregister anbinden
Zeitmodule	require("OffsetDateTime"), require("LocalTime")	Aktuelle Zeitstempel für Frequenzbegrenzung abrufen und Zeitintervalle vergleichen
Allgemeine Hilfsmodule	require("Logger"), require("JSON"), require("Regex"), require("String"), require("Math"), require("TableUtils")	Protokollausgabe, tiefe JSON-Operationen, reguläre Ausdrücke sowie Verarbeitung von Zeichenfolgen, Zahlen und Tabellen
JSON-Konvertierung (globale Funktionen)	jsonToMap, jsonToList, toJsonString	Strukturierte Daten mit externen Systemen austauschen, häufig in MQTT-Nachrichten
HTTP	require("http")	HTTP-Anfragen direkt aus Skripten an Drittanbieterschnittstellen senden; Aufruffrequenz und Zeitüberschreitungen müssen selbst gesteuert werden

Vollständige Funktionssignaturen und Modulmethoden: Vollständige Lua-Skriptreferenz. Ausführliche Referenzierungsregeln: Regeln zur Datenvariablenauflösung.

Rückgabekonvention für Aggregationsausdrücke: Geben Sie mit return einen einzelnen Wert zurück, etwa eine Zahl oder Zeichenfolge. Dieser wird zum neuesten Wert des Aggregationsdatenpunkts. Geben Sie hier kein Array von Schreibbeschreibungen wie buildCommonWriteMap zurück; dieses Format ist für Trigger- und MQTT-Aktionen vorgesehen. Siehe Vollständige Lua-Skriptreferenz – Rückgabekonventionen.

4. Konfigurationsbeispiel: verbleibende verfügbare Kapazität

Als Beispiel dient die bei Lastverteilung häufig benötigte „verbleibende verfügbare Leistung“:

-- Nennstrom × Spannung = Obergrenze der Nennleistung (kW)
local rated_kw = tonumber(${Grid_current} or 0) * tonumber(${Grid_voltage} or 0) * 0.001

-- Bereits genutzte Leistung (netzseitig gemessene Gesamtleistung, kW)
local used_kw = tonumber(${Grid_total_power} or 0)

-- 10 % Sicherheitsreserve vorsehen
local avail_kw = (rated_kw - used_kw) * 0.9

return avail_kw

Wird dieses Skript als Ausdruck des Aggregationsdatenpunkts avail_kw konfiguriert, können Triggerschemata und andere Aggregationsdatenpunkte das Ergebnis direkt über ${avail_kw} verwenden. Die Berechnungslogik muss nicht wiederholt werden – so lässt sich Logik wiederverwenden.

5. Testberechnung

Nach dem Erstellen oder Ändern eines Aggregationsausdrucks können Sie vor dem Speichern mit Testberechnung prüfen, ob Syntax und Ergebnis den Erwartungen entsprechen. So werden Skriptfehler vor dem produktiven Einsatz erkannt.

Nächste Schritte

• Vollständige Signaturen integrierter Funktionen, Modulliste und weitere Beispiele: Vollständige Lua-Skriptreferenz
• Berechnungsergebnisse mit Triggerschemata in tatsächliche Aktionen umsetzen: Triggerschemata