Moteur d’expressions

Le moteur d’expressions est au cœur du calcul d’Edge-EMS Builder. Valeurs agrégées, conditions de déclenchement et messages MQTT résultent tous de l’exécution d’un script. La syntaxe est Lua.

1. Règles de référence des variables

Avant l’exécution, Edge-EMS Builder remplace les espaces réservés ${...} par les valeurs réelles, puis exécute le corps du script. Les syntaxes suivantes peuvent être combinées :

Syntaxe	Description	Exemple
${dataKey}	Valeur courante d’un point	${PCS1_有功功率}
${dataKey[-NTimeUnit]}	Valeur historique N unités de temps auparavant	${PCS1_有功功率[-5s]} : valeur 5 secondes auparavant
${dataKey[#N]}	Nième échantillon historique en remontant depuis le plus récent	${PCS1_有功功率[#3]} : troisième valeur précédente
${dataKey[raw]}	Injection telle quelle sans conversion automatique de type. Utilisez raw pour les cas ambigus, tels que le nombre 1000 et le binaire 1000. raw ne peut être placé qu’en dernière position et doit l’être.	${设备状态[raw]}
${[deviceCode]dataKey}	Dernière valeur d’un point d’équipement partagé (Share)	${[DeviceA]PCS1_有功功率}
Combinaison	Les règles précédentes peuvent être combinées librement	${[DeviceA]PCS1_有功功率[-1s][#3]}

Valeur manquante : si le point n’a pas de valeur disponible, le moteur injecte la chaîne __Null__. Comparez-la explicitement ou utilisez isNull / isNotNull. Avant un calcul numérique, utilisez tonumber ; ne vous fiez pas à or 0 pour détecter cette chaîne.

Unités de décalage temporel :

Unité	Abréviations acceptées
Milliseconde	ms / millisecond
Seconde	s / sec / second / seconds
Minute	m / min / minute / minutes
Heure	h / hour / hours
Jour	d / day / days
Semaine	w / week / weeks
Mois	M / month

2. Corps du script : syntaxe Lua standard

Après remplacement des espaces réservés, le corps du script suit la syntaxe Lua 5.1 standard et retourne le résultat par return. Variables, conditions, boucles et fonctions natives Lua sont donc utilisables :

-- Calculer la puissance apparente totale, exemple simplifié
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. Fonctions et modules intégrés

Outre Lua standard et ses bibliothèques string/table/math, Edge-EMS Builder fournit des fonctions globales et modules chargeables par require pour lire les données, construire des écritures et traiter chaînes, temps et expressions régulières. Ils permettent une logique complexe sans code bas niveau :

Catégorie	Description	Exemple
Lecture de données, fonctions globales	getLatestDataValue, getHistoryData, getDeviceShareValue et familles de requêtes par préfixe/suffixe/correspondance partielle	Recherche dynamique de points partageant une règle de nommage ; voir Plans de déclenchement
Construction d’écritures, fonctions globales	buildCommonWriteMap, buildCustomizationWriteMap, buildDailyRepeatWriteMap, buildCommonAlarmMap, buildMqttAlarmMap, buildAlarmObservationMap, buildSlaveWriteMap	Construire les structures cibles exécutées uniformément par les actions de déclenchement/MQTT
Conversion temporelle	cp56Time2aToOffsetDateTime, offsetDateTimeToCP56Time2a, avec AB/BA	Intégration aux registres temporels IEC
Modules temporels	require("OffsetDateTime"), require("LocalTime")	Horodatage courant pour limiter la fréquence et comparaison d’intervalles
Modules utilitaires	require("Logger"), require("JSON"), require("Regex"), require("String"), require("Math"), require("TableUtils")	Journalisation, opérations JSON profondes, expressions régulières, chaînes, nombres et tables
Conversion JSON, fonctions globales	jsonToMap, jsonToList, toJsonString	Échange de données structurées, notamment dans les messages MQTT
HTTP	require("http")	Requêtes HTTP directes depuis les scripts vers des interfaces tierces, avec maîtrise de la fréquence et des délais

Consultez la référence complète Lua pour signatures et méthodes de modules, et les règles de résolution des variables pour les références de données.

Une expression de point agrégé doit renvoyer une seule valeur par return, numérique, textuelle, etc., qui devient la dernière valeur du point. Ne renvoyez pas ici un tableau de descriptions d’écriture tel que buildCommonWriteMap : ce format concerne les actions de déclenchement ou MQTT. Voir les conventions de retour dans la référence complète Lua.

4. Exemple : calcul de capacité restante

Exemple de puissance encore disponible, fréquent dans l’équilibrage de charge :

-- Courant nominal × tension = plafond de puissance nominale (kW)
local rated_kw = tonumber(${Grid_current} or 0) * tonumber(${Grid_voltage} or 0) * 0.001

-- Puissance utilisée, total mesuré côté réseau en kW
local used_kw = tonumber(${Grid_total_power} or 0)

-- Conserver une marge de sécurité de 10%
local avail_kw = (rated_kw - used_kw) * 0.9

return avail_kw

Après affectation de ce script à l’expression du point agrégé avail_kw, tout plan de déclenchement ou autre point agrégé peut référencer ${avail_kw} sans répéter le calcul : c’est la réutilisation de la logique.

5. Test de calcul

Après création ou modification d’une expression agrégée, utilisez le test de calcul avant enregistrement pour vérifier syntaxe et résultat, et détecter les erreurs avant la mise en service.

Étapes suivantes

• Signatures complètes, modules et autres exemples : Référence complète Lua.
• Transformer les résultats des expressions en actions : Plans de déclenchement.