Mecanismo de expressões

O mecanismo de expressões é o núcleo da capacidade de “cálculo” do Edge-EMS Builder. Os valores dos pontos agregados, as condições de avaliação dos perfis de acionamento e a montagem de mensagens MQTT resultam, essencialmente, da execução de scripts por esse mecanismo. A linguagem dos scripts é Lua.

I. Regras de referência a variáveis

Antes de executar um script de expressão, o Edge-EMS Builder substitui placeholders no formato ${...} pelos valores reais dos dados e, em seguida, executa o corpo do script. Os placeholders aceitam as formas abaixo, que podem ser combinadas:

Sintaxe	Descrição	Exemplo
${dataKey}	Referencia o valor atual de um ponto	${PCS1_有功功率}
${dataKey[-NTimeUnit]}	Referencia o valor histórico de N unidades de tempo atrás	${PCS1_有功功率[-5s]} representa o valor de 5 segundos atrás
${dataKey[#N]}	Referencia a N-ésima amostra histórica contando de trás para frente	${PCS1_有功功率[#3]} representa o terceiro valor mais recente
${dataKey[raw]}	Insere o conteúdo literalmente, sem conversão automática de tipo. Em casos difíceis de distinguir, como o valor numérico 1000 e o binário 1000, use raw para forçar a inserção literal; só pode e deve aparecer no final	${设备状态[raw]}
${[deviceCode]dataKey}	Referencia o valor mais recente de um ponto de dispositivo compartilhado (Share)	${[DeviceA]PCS1_有功功率}
Uso combinado	As regras acima podem ser combinadas livremente	${[DeviceA]PCS1_有功功率[-1s][#3]}

Valores ausentes: quando o ponto de destino ainda não tem valor, o mecanismo insere a string __Null__. Compare-a explicitamente ou use isNull / isNotNull; para cálculos numéricos, use primeiro tonumber e não dependa de or 0 para avaliar essa string.

Unidades aceitas para deslocamento temporal:

Unidade	Abreviações aceitas
Milissegundo	ms / millisecond
Segundo	s / sec / second / seconds
Minuto	m / min / minute / minutes
Hora	h / hour / hours
Dia	d / day / days
Semana	w / week / weeks
Mês	M / month

II. Corpo do script: sintaxe Lua padrão

Após a substituição dos placeholders, o restante do script é executado conforme a sintaxe padrão de Lua 5.1, retornando o resultado do cálculo por return. Isso permite usar variáveis, condições, laços, funções e outros recursos nativos de Lua:

-- Calcula a potência aparente total (exemplo 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

III. Funções e módulos integrados

Além da sintaxe Lua padrão (incluindo as bibliotecas nativas string/table/math), o Edge-EMS Builder disponibiliza no ambiente de scripts funções globais e módulos carregáveis por require. Eles atendem a necessidades comuns de leitura de dados, construção de gravações e processamento de strings, tempo e expressões regulares, permitindo implementar lógicas complexas sem escrever código de baixo nível:

Categoria	Descrição	Exemplo
Leitura de dados (funções globais)	getLatestDataValue, getHistoryData, getDeviceShareValue e famílias de funções de consulta em lote por prefixo/sufixo/correspondência parcial	Varredura dinâmica de pontos com o mesmo padrão de nomenclatura (consulte o exemplo de descoberta dinâmica de dispositivos em Perfis de acionamento)
Construção de gravações (funções globais)	buildCommonWriteMap, buildCustomizationWriteMap, buildDailyRepeatWriteMap, buildCommonAlarmMap, buildMqttAlarmMap, buildAlarmObservationMap, buildSlaveWriteMap	Constrói as estruturas dos dados de destino a gravar, para execução unificada por ações de gatilho/MQTT
Conversão de tempo	cp56Time2aToOffsetDateTime, offsetDateTimeToCP56Time2a, com suporte a AB/BA	Integração com registradores de tempo IEC
Módulo de tempo	require("OffsetDateTime"), require("LocalTime")	Obtém o timestamp atual (para limitação de frequência) e compara intervalos de tempo
Módulos de utilidades gerais	require("Logger"), require("JSON"), require("Regex"), require("String"), require("Math"), require("TableUtils")	Logs, operações profundas em JSON, expressões regulares e processamento de strings/números/tabelas
Conversão JSON (funções globais)	jsonToMap, jsonToList, toJsonString	Troca de dados estruturados com sistemas externos (comum em mensagens MQTT)
HTTP	require("http")	Faz solicitações HTTP diretamente no script para integrar interfaces de terceiros; a frequência e o tempo limite devem ser controlados pelo autor

Para assinaturas completas das funções e listas de métodos dos módulos, consulte a Referência completa de scripts Lua. Para regras detalhadas de referência a variáveis, consulte Regras de interpretação de variáveis de dados.

Convenção de retorno das expressões de pontos agregados: return um único valor (número, string etc.), que se torna o valor mais recente do ponto agregado. Não retorne aqui arrays de descrições de gravação, como buildCommonWriteMap — esse formato é usado em ações de gatilho, ações MQTT e cenários semelhantes. Consulte Referência completa de scripts Lua · Convenções de retorno.

IV. Exemplo de configuração: cálculo da capacidade disponível restante

Considere a “potência disponível restante”, comum em cenários de balanceamento de carga:

-- Corrente nominal × tensão = limite de potência nominal (kW)
local rated_kw = tonumber(${Grid_current} or 0) * tonumber(${Grid_voltage} or 0) * 0.001

-- Potência utilizada (potência total medida no lado da rede, kW)
local used_kw = tonumber(${Grid_total_power} or 0)

-- Reserva uma margem de segurança de 10%
local avail_kw = (rated_kw - used_kw) * 0.9

return avail_kw

Depois de configurar esse script como expressão do ponto agregado avail_kw, qualquer perfil de acionamento ou outro ponto agregado poderá referenciar o resultado diretamente por ${avail_kw}, sem repetir a lógica do cálculo — um exemplo de reutilização de lógica.

V. Simulação de cálculo

Ao adicionar ou alterar uma expressão de ponto agregado, use a simulação de cálculo antes de salvar para verificar se a sintaxe e o resultado atendem ao esperado, evitando descobrir erros de script somente após a entrada em operação.

Próximos passos

• Consulte assinaturas completas das funções integradas, a lista de módulos e mais exemplos na Referência completa de scripts Lua.
• Aprenda a transformar resultados de expressões em ações reais com Perfis de acionamento.