Motor de expresiones

El motor de expresiones es el núcleo de las capacidades de cálculo de Edge-EMS Builder. Los valores de puntos agregados, las condiciones de esquemas de disparadores y la construcción de mensajes MQTT son resultados de scripts ejecutados por este motor. La sintaxis es Lua.

1. Reglas de referencia a variables

Antes de ejecutar un script, Edge-EMS Builder sustituye los marcadores ${...} por valores reales y después ejecuta el cuerpo. Se admiten las siguientes formas, que pueden combinarse:

Sintaxis	Descripción	Ejemplo
${dataKey}	Valor actual de un punto	${PCS1_有功功率}
${dataKey[-NTimeUnit]}	Valor histórico de hace N unidades de tiempo	${PCS1_有功功率[-5s]}: valor de hace 5 segundos
${dataKey[#N]}	Enésima muestra histórica contando desde la más reciente	${PCS1_有功功率[#3]}: tercera muestra más reciente
${dataKey[raw]}	Inserción sin conversión automática de tipo. En casos ambiguos, como el número 1000 y el binario 1000, raw fuerza la inserción literal; solo puede y debe situarse al final	${设备状态[raw]}
${[deviceCode]dataKey}	Valor más reciente de un punto compartido (Share)	${[DeviceA]PCS1_有功功率}
Combinación	Las reglas anteriores pueden combinarse libremente	${[DeviceA]PCS1_有功功率[-1s][#3]}

Valores ausentes: si el punto no tiene valor, el motor inserta la cadena __Null__. Compárala explícitamente o utiliza isNull / isNotNull. Para cálculos numéricos, utiliza primero tonumber; no confíes en or 0 para detectar esa cadena.

Unidades admitidas para desplazamientos temporales:

Unidad	Abreviaturas admitidas
Milisegundos	ms / millisecond
Segundos	s / sec / second / seconds
Minutos	m / min / minute / minutes
Horas	h / hour / hours
Días	d / day / days
Semanas	w / week / weeks
Meses	M / month

2. Cuerpo del script: sintaxis estándar de Lua

Tras sustituir los marcadores, el cuerpo se ejecuta con sintaxis estándar Lua 5.1 y devuelve el resultado mediante return. Puedes utilizar variables, condiciones, bucles y funciones nativos de Lua:

-- Calcular la potencia aparente total: ejemplo simplificado
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. Funciones y módulos incorporados

Además de la sintaxis estándar y de las bibliotecas nativas string, table y math, Edge-EMS Builder incorpora funciones globales y módulos accesibles mediante require. Cubren lectura de datos, construcción de escrituras y procesamiento de cadenas, tiempo y expresiones regulares, permitiendo lógica compleja sin programar funciones de bajo nivel:

Categoría	Descripción	Ejemplo
Lectura de datos (funciones globales)	getLatestDataValue, getHistoryData, getDeviceShareValue y familias de consultas por lotes mediante prefijo, sufijo o coincidencia parcial	Exploración dinámica de puntos con reglas de nomenclatura comunes; consulta el ejemplo de descubrimiento dinámico en Esquemas de disparadores
Construcción de escrituras (funciones globales)	buildCommonWriteMap, buildCustomizationWriteMap, buildDailyRepeatWriteMap, buildCommonAlarmMap, buildMqttAlarmMap, buildAlarmObservationMap, buildSlaveWriteMap	Construyen estructuras de destino para que las acciones de disparadores o MQTT las ejecuten de forma uniforme
Conversión de tiempo	cp56Time2aToOffsetDateTime, offsetDateTimeToCP56Time2a; admiten AB/BA	Integración con registros temporales IEC
Módulos de tiempo	require("OffsetDateTime"), require("LocalTime")	Obtener marcas de tiempo actuales para limitar frecuencia y comparar intervalos
Módulos de utilidades	require("Logger"), require("JSON"), require("Regex"), require("String"), require("Math"), require("TableUtils")	Registros, operaciones profundas sobre JSON, expresiones regulares y procesamiento de cadenas, números y tablas
Conversión JSON (funciones globales)	jsonToMap, jsonToList, toJsonString	Intercambio de datos estructurados con sistemas externos, habitual en mensajes MQTT
HTTP	require("http")	Solicitudes HTTP directas desde scripts para integrar interfaces de terceros; controla su frecuencia y tiempo de espera

Consulta las firmas completas y los métodos en Referencia completa de scripts Lua, y las reglas detalladas de variables en Reglas de análisis de variables de datos.

Retorno de expresiones de puntos agregados: return debe devolver un valor único, como un número o una cadena, que se convierte en el valor más reciente del punto. No devuelvas arrays de descriptores de escritura como buildCommonWriteMap; ese formato corresponde a acciones de disparadores o MQTT. Consulta Referencia completa de Lua: convenciones de retorno.

4. Ejemplo: cálculo de capacidad disponible restante

Ejemplo de potencia disponible restante, habitual en equilibrado de cargas:

-- Corriente nominal × tensión = límite de potencia nominal (kW)
local rated_kw = tonumber(${Grid_current} or 0) * tonumber(${Grid_voltage} or 0) * 0.001

-- Potencia utilizada: potencia total medida del lado de red, en kW
local used_kw = tonumber(${Grid_total_power} or 0)

-- Reservar un margen de seguridad del 10%
local avail_kw = (rated_kw - used_kw) * 0.9

return avail_kw

Si configuras este script como expresión del punto agregado avail_kw, cualquier esquema de disparadores u otro punto agregado puede referenciar el resultado mediante ${avail_kw} sin repetir el cálculo. Así se reutiliza la lógica.

5. Evaluación de expresiones

Al crear o modificar una expresión de agregación, utiliza Evaluar antes de guardar para comprobar la sintaxis y el resultado esperado y detectar errores antes de la puesta en servicio.

Siguientes pasos

• Consulta firmas de funciones, módulos y más ejemplos en Referencia completa de scripts Lua.
• Aprende a convertir resultados de expresiones en acciones reales mediante Esquemas de disparadores.