Referência completa de scripts Lua

Esta página é a referência completa dos recursos de script usados no mecanismo de expressões do Edge-EMS Builder: expressões agregadas, condições e ações de gatilho, ações de pós-processamento e conteúdo de publicação/assinatura MQTT. A sintaxe é Lua 5.x, interpretada e executada pelo runtime Lua integrado. Para começar, leia Mecanismo de expressões; esta página complementa os módulos integrados, as assinaturas de funções globais e as convenções de retorno.

⚠️ Se você usou a versão Java inicial do Edge-EMS Builder, com mecanismo QLExpress4 e sintaxe semelhante a Java, observe: a sintaxe de referência a variáveis ${...} permanece essencialmente igual, mas o corpo do script passou a usar Lua padrão, como new ArrayList() → {}, .add(x) → table.insert(t, x), new HashMap() → {} e .put(k, v) → t[k] = v. A maioria dos nomes de funções integradas foi preservada; use esta página como referência de migração.

Visão rápida

Linguagem de script: Lua 5.x; nomes de funções e placeholders diferenciam maiúsculas de minúsculas.
Placeholder de dados: ${dataKey} é substituído pelo valor atual antes da execução; para outro dispositivo, use ${[deviceCode]dataKey}.
Valor sentinela: quando não há dados, o placeholder recebe a string __Null__. Compare-a explicitamente ou use isNull / isNotNull; para cálculos numéricos, use primeiro tonumber.
O retorno depende do cenário, conforme “Convenções de retorno” abaixo. Tipos de retorno incorretos são a causa mais comum de erros de configuração.
Funções de módulos exigem require("nome_do_módulo") antes da chamada; funções globais, como buildCommonWriteMap e jsonToMap, são chamadas diretamente, sem require.
Logs: o nível padrão do módulo Logger é WARN; apenas Logger.warn() / Logger.error() produzem saída. Durante a depuração, não use somente Logger.info()/Logger.debug().

I. Interpretação de dados (referência a variáveis)

Sintaxe	Descrição
`${variable}`	Retorna o valor atual
`${variable[-1s]}`	Retorna o valor do segundo anterior
`${variable[-5s]}`	Retorna o valor de 5 segundos atrás
`${variable[raw]}`	Insere literalmente, sem conversão automática de tipo; para dados difíceis de distinguir, como o valor numérico `1000` e o binário `1000`, use `raw` para controlar a inserção literal. `[raw]` só pode e deve aparecer no final.
`${[deviceA]variable}`	Retorna o valor do dispositivo compartilhado deviceA
`${variable[@timestamp]}`	Retorna o valor no instante absoluto especificado
`${variable[#N]}`	Retorna o N-ésimo valor histórico contando de trás para frente; sem essa regra, retorna o mais recente
`${[deviceA]variable[-5s][#N]}`	Retorna a N-ésima amostra anterior do dispositivo compartilhado deviceA, considerando o instante de 5 segundos atrás

Se não for possível obter o valor do ponto, o mecanismo insere a string sentinela __Null__. Faça a verificação explicitamente no script, por exemplo: if ${some_key} == "__Null__" then ... end.

II. Convenções de retorno por cenário

Os requisitos de retorno variam completamente conforme o local em que o script é configurado; esse é um ponto frequente de erro:

Cenário	Local de configuração	Retorno exigido
Condição de gatilho	Expressão da condição de gatilho	Um único booleano (`true` = condição satisfeita)
Ação de gatilho em perfil do tipo expressão	Conteúdo da ação (Expression)	Tabela Lua em formato de array, com índices consecutivos a partir de 1, cujos elementos são mapas retornados por funções como `buildCommonWriteMap(...)`; a tabela vazia `{}` indica “nenhum item de gravação”
Ação de gatilho em perfil de gravação mista	Ação vinculada individualmente a cada `dataKey`	Um único valor (string/número/booleano), usado como conteúdo a gravar nesse `dataKey`; não retorne um array `buildCommonWriteMap`
Ação de pós-processamento	Script de finalização após a execução da ação de gatilho	Igual à ação do tipo expressão: tabela Lua em formato de array de descrições de gravação; use as variáveis fixas `${trigger_result}` (booleano) e `${trigger_write_result}` (string JSON, interpretada por `jsonToMap`) para avaliar o resultado do fluxo principal
Expressão de ponto agregado	Expressão de cálculo dos dados agregados	Um único valor, como número ou string, usado como valor mais recente do ponto
Conteúdo de publicação MQTT (publishContent)	Configuração de publicação MQTT	Tabela Lua, serializada em JSON como payload da publicação
Ação de assinatura MQTT (actionContent)	Configuração de assinatura MQTT	Igual à ação do tipo expressão: tabela Lua em formato de array de descrições de gravação
Topic de resposta MQTT (responseTopic)	Configuração de assinatura MQTT	Uma única string, usada como Topic da publicação de resposta
Conteúdo de resposta MQTT (response)	Configuração de assinatura MQTT	Strings são enviadas sem alteração; outros valores, como tabelas Lua, são serializados em JSON

Cada chamada de script tem um tempo limite de execução, de 10 segundos por padrão; excedê-lo causa falha da execução. Evite consultas históricas ou solicitações HTTP sem limitação dentro de laços.

III. Módulos integrados

Os módulos abaixo exigem require("nome_do_módulo") antes do uso:

Módulo OffsetDateTime

Módulo completo de data e hora, com suporte a fusos horários, formatação, cálculos e outras operações.

Carregar o módulo

local OffsetDateTime = require("OffsetDateTime")

Construtores

Método	Descrição	Retorno
`new()`	Cria a data e hora atuais	OffsetDateTime
`new(sec, nsec?)`	Cria a partir de um timestamp Unix	OffsetDateTime
`now()`	Obtém a data e hora atuais	OffsetDateTime
`parse(str)`	Interpreta uma string de data e hora	OffsetDateTime \| (nil, err)
`parseInLocation(str, location)`	Interpreta a data e hora no fuso especificado	OffsetDateTime \| (nil, err)
`unix(sec, nsec?)`	Cria a partir de segundos Unix	OffsetDateTime
`unixMilli(msec)`	Cria a partir de um timestamp em milissegundos	OffsetDateTime
`unixMicro(usec)`	Cria a partir de um timestamp em microssegundos	OffsetDateTime

Métodos de instância — componentes de data e hora

Método	Descrição	Retorno
`year()`	Obtém o ano	number
`month()`	Obtém o mês (1-12)	number
`day()`	Obtém o dia do mês (1-31)	number
`hour()`	Obtém a hora (0-23)	number
`minute()`	Obtém o minuto (0-59)	number
`second()`	Obtém o segundo (0-59)	number
`nanosecond()`	Obtém os nanossegundos	number
`yearDay()`	Obtém o dia do ano	number
`weekday()`	Obtém o dia da semana (0=domingo)	number
`isoWeek()`	Obtém as informações da semana ISO	{year, week}
`date()`	Obtém ano, mês e dia	{year, month, day}
`clock()`	Obtém hora, minuto e segundo	{hour, minute, second}

Métodos de instância — cálculos de data e hora

Método	Descrição	Retorno
`add(durationStr)`	Adiciona um intervalo de tempo	OffsetDateTime \| (nil, err)
`addDate(years, months, days)`	Adiciona anos, meses e dias	OffsetDateTime
`sub(other)`	Calcula a diferença temporal em nanossegundos	number
`addYears(n)`	Adiciona anos	OffsetDateTime
`addMonths(n)`	Adiciona meses	OffsetDateTime
`addDays(n)`	Adiciona dias	OffsetDateTime
`addHours(n)`	Adiciona horas	OffsetDateTime
`addMinutes(n)`	Adiciona minutos	OffsetDateTime
`addSeconds(n)`	Adiciona segundos	OffsetDateTime
`addMilliseconds(n)`	Adiciona milissegundos	OffsetDateTime
`addMicroseconds(n)`	Adiciona microssegundos	OffsetDateTime
`addNanoseconds(n)`	Adiciona nanossegundos	OffsetDateTime

Métodos de instância — diferenças de tempo

Método	Descrição	Retorno
`diffYears(other)`	Calcula a diferença em anos	number
`diffMonths(other)`	Calcula a diferença em meses	number
`diffDays(other)`	Calcula a diferença em dias	number
`diffHours(other)`	Calcula a diferença em horas	number
`diffMinutes(other)`	Calcula a diferença em minutos	number
`diffSeconds(other)`	Calcula a diferença em segundos	number

Métodos de instância — comparação de datas e horas

Método	Descrição	Retorno
`equal(other)`	Verifica se é igual	boolean
`before(other)`	Verifica se é anterior	boolean
`after(other)`	Verifica se é posterior	boolean
`isZero()`	Verifica se é o valor zero	boolean

Métodos de instância — verificações de data e hora

Método	Descrição	Retorno
`isToday()`	Verifica se é hoje	boolean
`isYesterday()`	Verifica se é ontem	boolean
`isTomorrow()`	Verifica se é amanhã	boolean
`isThisWeek()`	Verifica se está nesta semana	boolean
`isThisMonth()`	Verifica se está neste mês	boolean
`isThisYear()`	Verifica se está neste ano	boolean
`isBetween(start, end)`	Verifica se está no intervalo	boolean
`isInRange(start, end)`	Verifica se está no intervalo	boolean

Métodos de instância — formatação

Método	Descrição	Retorno
`format(layout)`	Formatação personalizada	string
`toString()`	Converte em string	string
`toDateTimeString()`	Formato de data e hora	string
`toDateString()`	Formato de data	string
`toTimeString()`	Formato de hora	string
`toYearString()`	Ano	string
`toMonthString()`	Mês	string
`toDayString()`	Dia do mês	string
`toHourString()`	Hora	string
`toMinuteString()`	Minuto	string
`toSecondString()`	Segundo	string

Métodos de instância — timestamps Unix

Método	Descrição	Retorno
`unix()`	Timestamp Unix em segundos	number
`unixMilli()`	Timestamp Unix em milissegundos	number
`unixMicro()`	Timestamp Unix em microssegundos	number
`unixNano()`	Timestamp Unix em nanossegundos	number

Métodos de instância — fusos horários

Método	Descrição	Retorno
`utc()`	Converte para UTC	OffsetDateTime
`local()`	Converte para o fuso local	OffsetDateTime
`in(location)`	Converte para o fuso especificado	OffsetDateTime \| (nil, err)

Métodos de instância — outros

Método	Descrição	Retorno
`truncate(durationStr)`	Trunca na precisão especificada	OffsetDateTime \| (nil, err)
`round(durationStr)`	Arredonda na precisão especificada	OffsetDateTime \| (nil, err)
`toTime()`	Converte para time.Time do Go	time.Time

Constantes

local layouts = OffsetDateTime.Layout
-- layouts.DateTime = "2006-01-02 15:04:05"
-- layouts.Date = "2006-01-02"
-- layouts.Time = "15:04:05"

Exemplo de uso

local OffsetDateTime = require("OffsetDateTime")
local Logger = require("Logger")

-- Obtém a data e hora atuais
local now = OffsetDateTime.now()
Logger.warn(now:toString())

-- Interpreta a data e hora
local dt = OffsetDateTime.parse("2024-01-15T10:30:00.000Z")
Logger.warn("年份: " .. dt:year())
Logger.warn("月份: " .. dt:month())

-- Cálculos de data e hora
local tomorrow = now:addDays(1)
local nextWeek = now:addDays(7)
Logger.warn("明天: " .. tomorrow:toDateString())

-- Comparação de datas e horas
if now:isToday() then
    Logger.warn("今天!")
end

-- Diferença temporal
local hours = nextWeek:diffHours(now)
Logger.warn("相差小时: " .. hours)

-- Formatação
Logger.warn(now:format("2006-01-02 15:04:05"))
Logger.warn(now:toDateTimeString())

Módulo LocalTime

Tipo de hora que contém apenas horas, minutos e segundos, sem data nem fuso horário.

Carregar o módulo

local LocalTime = require("LocalTime")

Construtores

Método	Descrição	Retorno
`new(hour, minute, second)`	Cria uma hora	LocalTime \| (nil, err)
`now()`	Obtém a hora atual	LocalTime
`parse(str)`	Interpreta “HH:mm:ss”	LocalTime \| (nil, err)
`fromTime(time.Time)`	Cria a partir de time.Time	LocalTime \| (nil, err)
`fromDuration(durationStr)`	Cria a partir de um intervalo de tempo	LocalTime \| (nil, err)

Métodos de instância

Método	Descrição	Retorno
`hour()`	Obtém a hora	number
`minute()`	Obtém o minuto	number
`second()`	Obtém o segundo	number
`toString()`	Converte para “HH:mm:ss”	string
`toDuration()`	Converte em uma string de intervalo de tempo	string
`equal(other)`	Verifica se é igual	boolean
`before(other)`	Verifica se é anterior	boolean
`after(other)`	Verifica se é posterior	boolean
`beforeOrEqual(other)`	Verifica se é anterior ou igual	boolean
`afterOrEqual(other)`	Verifica se é posterior ou igual	boolean
`isZero()`	Verifica se é 00:00:00	boolean
`diffSeconds(other)`	Diferença em segundos	number
`diffMinutes(other)`	Diferença em minutos	number
`diffHours(other)`	Diferença em horas	number
`addSeconds(n)`	Adiciona segundos	LocalTime
`addMinutes(n)`	Adiciona minutos	LocalTime
`addHours(n)`	Adiciona horas	LocalTime
`subSeconds(n)`	Subtrai segundos	LocalTime
`subMinutes(n)`	Subtrai minutos	LocalTime
`subHours(n)`	Subtrai horas	LocalTime

Exemplo de uso

local LocalTime = require("LocalTime")
local Logger = require("Logger")

-- Cria uma hora
local workStart = LocalTime.new(9, 0, 0)   -- 09:00:00
local workEnd = LocalTime.new(17, 30, 0)   -- 17:30:00

-- Obtém a data e hora atuais
local now = LocalTime.now()
Logger.warn("当前时间: " .. now:toString())

-- Comparação de datas e horas
if now:isBetween(workStart, workEnd) then
    Logger.warn("工作时间")
else
    Logger.warn("非工作时间")
end

-- Cálculos de data e hora
local breakTime = workStart:addHours(3):addMinutes(30)  -- 12:30:00
Logger.warn("午休时间: " .. breakTime:toString())

-- Diferença temporal
local workHours = workEnd:diffHours(workStart)
Logger.warn("工作时长: " .. workHours .. " 小时")

Módulos de utilidades gerais

Módulo Logger

Módulo de saída de logs integrado aos logs do sistema.

Carregar o módulo

local Logger = require("Logger")

API

Método	Descrição	Parâmetros
`info(msg)`	Emite log INFO	string
`warn(msg)`	Emite log WARN	string
`error(msg)`	Emite log ERROR	string
`debug(msg)`	Emite log DEBUG	string
`infof(fmt, ...)`	Formata log INFO	string, …
`warnf(fmt, ...)`	Formata log WARN	string, …
`errorf(fmt, ...)`	Formata log ERROR	string, …
`debugf(fmt, ...)`	Formata log DEBUG	string, …

Exemplo de uso

local Logger = require("Logger")

Logger.info("系统启动")
Logger.warn("磁盘空间不足")
Logger.error("数据库连接失败")
Logger.debug("变量值: x=10")

-- Saída formatada
local user = "admin"
local action = "login"
Logger.infof("用户 %s 执行操作: %s", user, action)
Logger.warnf("重试次数: %s", 3)

Observação: o nível padrão de saída de logs do Edge-EMS Builder é WARN; somente logs WARN e ERROR são emitidos.

Módulo JSON

Módulo de serialização, desserialização e operações JSON, baseado em bytedance/sonic.

Carregar o módulo

local JSON = require("JSON")

API básica

Método	Descrição	Retorno
`encode(value)`	Serializa em JSON	string \| (nil, err)
`decode(text)`	Desserializa	table \| (nil, err)

API estendida

Método	Descrição	Retorno
`toJSONString(value)`	Serializa sem retornar erro	string
`toJSONStringIndent(value, prefix?, indent?)`	Serializa com formatação	string
`toMap(jsonStr)`	Converte em map	table \| (nil, err)
`toStringMap(jsonStr)`	Converte em string map	table \| (nil, err)
`toSlice(jsonStr)`	Converte em array	table \| (nil, err)
`isValid(jsonStr)`	Valida o formato JSON	boolean
`pretty(jsonStr)`	Formata JSON para leitura	string
`merge(json1, json2)`	Mescla dois JSONs	string \| (nil, err)
`get(jsonStr, key)`	Obtém um valor	any \| (nil, err)
`set(jsonStr, key, value)`	Define um valor	string \| (nil, err)
`remove(jsonStr, key)`	Exclui uma chave	string \| (nil, err)
`clone(value)`	Faz uma cópia profunda	any \| (nil, err)

Exemplo de uso

local JSON = require("JSON")
local Logger = require("Logger")

-- Serialização/desserialização básica
local obj = {name = "张三", age = 30, tags = {"developer", "golang"}}
local jsonStr = JSON.encode(obj)
Logger.warn(jsonStr)  -- {"name":"张三","age":30,"tags":["developer","golang"]}

local decoded, err = JSON.decode(jsonStr)
if not decoded then
    Logger.warn("解析失败: " .. err)
else
    Logger.warn("姓名: " .. decoded.name)
end

-- Saída formatada
local pretty = JSON.pretty(jsonStr)
Logger.warn(pretty)

-- Valida JSON
if JSON.isValid(jsonStr) then
    Logger.warn("有效的 JSON")
end

-- Opera sobre JSON
local newJson = JSON.set(jsonStr, "city", "北京")
Logger.warn(newJson)  -- {"name":"张三","age":30,"tags":[...],"city":"北京"}

local age = JSON.get(newJson, "age")
Logger.warn("年龄: " .. age)  -- 30

local removed = JSON.remove(newJson, "age")
Logger.warn(removed)  -- {"name":"张三","tags":[...],"city":"北京"}

-- Mescla JSON
local json1 = '{"a":1}'
local json2 = '{"b":2}'
local merged = JSON.merge(json1, json2)
Logger.warn(merged)  -- {"a":1,"b":2}

-- Cópia profunda
local original = {data = {x = 10}}
local copied = JSON.clone(original)

Módulo Regex

Módulo de expressões regulares com correspondência, busca, substituição, divisão e outras operações.

Carregar o módulo

local Regex = require("Regex")

API

Método	Descrição	Retorno
`match(text, pattern)`	Verifica correspondência	boolean
`findAll(text, pattern, limit?)`	Localiza todas as correspondências, incluindo grupos de captura	{{full, g1, g2, …}, …} \| (nil, err)
`replace(text, pattern, repl)`	Substitui, com suporte a referências de grupos como $1	string \| (nil, err)
`split(text, pattern, limit?)`	Divide por expressão regular	{string, …} \| (nil, err)
`isEmail(text)`	Verifica se é um e-mail	boolean
`isPhone(text)`	Verifica se é um número de celular da China	boolean
`isIP(text)`	Verifica se é um endereço IP	boolean
`isURL(text)`	Verifica se é uma URL	boolean

Exemplo de uso

local Regex = require("Regex")
local Logger = require("Logger")

-- Correspondência
if Regex.match("abc123", "\\d+") then
    Logger.warn("包含数字")
end

-- Localiza todas as correspondências, incluindo grupos de captura
local matches = Regex.findAll("a1 b22 c333", "(\\w)(\\d+)")
-- matches = {{"a1","a","1"}, {"b22","b","22"}, {"c333","c","333"}}
for i, m in ipairs(matches) do
    Logger.warn("匹配 " .. i .. ": " .. m[1] .. ", 字母=" .. m[2] .. ", 数字=" .. m[3])
end

-- Substituição com suporte a referências de grupos
local s = Regex.replace("abc-123-def", "(\\d+)", "[$1]")
Logger.warn(s)  -- "abc-[123]-def"

-- Divisão
local parts = Regex.split("a,b,,c", ",", -1)
-- parts = {"a", "b", "", "c"}
for i, p in ipairs(parts) do
    Logger.warn("部分 " .. i .. ": '" .. p .. "'")
end

-- Validação
Logger.warn(Regex.isEmail("test@example.com"))  -- true
Logger.warn(Regex.isPhone("13812345678"))       -- true
Logger.warn(Regex.isIP("192.168.1.1"))          -- true
Logger.warn(Regex.isURL("https://example.com")) -- true

Módulo String

Utilitários de processamento de strings.

Carregar o módulo

local String = require("String")

API

Método	Descrição	Retorno
`trim(s)`	Remove espaços em branco das extremidades	string
`upper(s)`	Converte para maiúsculas	string
`lower(s)`	Converte para minúsculas	string
`contains(s, sub)`	Verifica se contém uma substring	boolean
`startsWith(s, prefix)`	Verifica se começa com o prefixo especificado	boolean
`endsWith(s, suffix)`	Verifica se termina com o sufixo especificado	boolean

Exemplo de uso

local String = require("String")

local s = "  Hello World  "
Logger.warn(String.trim(s))       -- "Hello World"
Logger.warn(String.upper(s))      -- "  HELLO WORLD  "
Logger.warn(String.lower(s))      -- "  hello world  "

Logger.warn(String.contains("hello", "ll"))      -- true
Logger.warn(String.startsWith("hello", "he"))    -- true
Logger.warn(String.endsWith("hello", "lo"))      -- true

Módulo Math

Utilitários de cálculo matemático.

Carregar o módulo

local Math = require("Math")

API

Método	Descrição	Retorno
`round(n)`	Arredonda para o valor mais próximo	number
`floor(n)`	Arredonda para baixo	number
`ceil(n)`	Arredonda para cima	number
`abs(n)`	Valor absoluto	number
`max(a, b)`	Valor máximo	number
`min(a, b)`	Valor mínimo	number

Exemplo de uso

local Math = require("Math")

Logger.warn(Math.round(3.6))   -- 4
Logger.warn(Math.floor(3.9))   -- 3
Logger.warn(Math.ceil(3.1))    -- 4
Logger.warn(Math.abs(-5))      -- 5
Logger.warn(Math.max(10, 20))  -- 20
Logger.warn(Math.min(10, 20))  -- 10

Módulo TableUtils

Utilitários de operações com tabelas (table), com suporte à iteração sobre arrays e pares chave-valor.

Carregar o módulo

local TableUtils = require("TableUtils")

API

Método	Descrição	Retorno
`keys(tbl)`	Obtém todas as chaves	{string, …}
`values(tbl)`	Obtém todos os valores	{any, …}
`map(tbl, fn)`	Mapeia por fn(value, key)	{any, …}
`filter(tbl, fn)`	Filtra por fn(value, key)	{any, …}
`reduce(tbl, fn, init)`	Reduz por fn(acc, value, key)	any
`sortBy(tblOfMaps, key)`	Ordena por chave, com ordenação estável	{map, …}

Exemplo de uso

local T = require("TableUtils")

-- keys/values
local obj = {a = 1, b = 2, c = 3}
local keys = T.keys(obj)     -- {"a", "b", "c"}
local values = T.values(obj) -- {1, 2, 3}

-- map (array)
local arr = {1, 2, 3}
local doubled = T.map(arr, function(v, i)
    return v * 2
end)
-- doubled = {2, 4, 6}

-- map (pares chave-valor)
local mapped = T.map({a=1, b=2}, function(v, k)
    return k .. ":" .. v
end)
-- mapped = {"a:1", "b:2"}

-- filter
local arr = {1, 2, 3, 4, 5}
local even = T.filter(arr, function(v, i)
    return v % 2 == 0
end)
-- even = {2, 4}

-- reduce
local sum = T.reduce({1, 2, 3}, function(acc, v, i)
    return acc + v
end, 0)
-- sum = 6

-- sortBy
local users = {
    {name="张三", age=30},
    {name="李四", age=25},
    {name="王五", age=35}
}
local sorted = T.sortBy(users, "age")
-- sorted = {{name="李四",age=25}, {name="张三",age=30}, {name="王五",age=35}}

Funções globais

As funções abaixo são registradas diretamente no escopo global e não exigem require.

Conversão de tempo CP56Time2a

Função	Finalidade
`cp56Time2aToOffsetDateTime(hex[, byteOrder])`	Decodifica a data e hora IEC 60870-5 e retorna OffsetDateTime
`offsetDateTimeToCP56Time2a(time[, byteOrder])`	Codifica a data e hora em um payload hexadecimal

byteOrder aceita AB / BA; quando omitido, usa o padrão AB. Quando explicitamente informado, aceita payloads de quatro registradores; se houver ambiguidade na posição do preenchimento com zeros, retorna um erro. Confira a organização dos registradores do dispositivo.

Funções de interpretação de dados

Função	Descrição	Retorno
`jsonToMap(str)`	Converte JSON em map	table \| (nil, err)
`jsonToList(str)`	Converte JSON em list	table \| (nil, err)
`jsonToListMap(str)`	Converte JSON em list of map	table \| (nil, err)
`completeDateTime(str)`	Completa uma string de data e hora	string \| (nil, err)
`quoteJson(str)`	Escapa aspas em JSON	string
`simpleUUID()`	Gera um UUID simples	string
`convertString(str)`	Converte o tipo de uma string	any
`isNull(any)`	Verifica se o valor está vazio	bool
`isNotNull(any)`	Verifica se o valor não está vazio	bool

isNull considera vazios nil, a string vazia, “null” sem diferenciar maiúsculas de minúsculas e o sentinela __Null__. O or 0 de Lua não trata esse sentinela.

Exemplo de uso

local Logger = require("Logger")

-- Interpretação de JSON
local map, err = jsonToMap('{"a":1,"b":2}')
if map then
    Logger.warn(map.a)  -- 1
end

local list = jsonToList('[1,2,3]')
-- list = {1, 2, 3}

-- Complementação de data e hora
local fullTime = completeDateTime("2024-01-15")
-- fullTime = "2024-01-15T00:00:00.000+08:00"

-- Geração de UUID
local id = simpleUUID()
Logger.warn(id)  -- String UUID de 32 caracteres

Funções de acesso ao cache

Função	Descrição	Retorno
`getLatestDataValue(dataKey)`	Obtém o valor mais recente dos dados	any
`getAccountCache(key)`	Obtém o cache de contas	any
`getEMSDataCache(key)`	Obtém o cache de dados EMS	any
`getShareCache(key)`	Obtém o cache de compartilhamento	any
`getMqttCache(key)`	Obtém o cache MQTT	any
`getTriggerCache(key)`	Obtém o cache de gatilhos	any
`getDeviceShareValue(deviceCode, dataKey)`	Obtém o valor mais recente do dado compartilhado de um dispositivo por deviceCode e dataKey	string \| nil
`getDeviceShareValues(deviceCodes, dataKey)`	Obtém o valor mais recente desse dado para cada dispositivo de uma lista, usando dataKey	table
`getAllDeviceShareValues(dataKey)`	Obtém, por dataKey, o valor mais recente desse dado de todos os dispositivos no espaço de compartilhamento	table

Exemplo de uso

local Logger = require("Logger")

-- Obtém os dados mais recentes do dispositivo
local value = getLatestDataValue("device1.temperature")
Logger.warn("当前温度: " .. value)

-- Obtém informações da conta
local account = getAccountCache("user123")
if account then
    Logger.warn("用户名: " .. account.username)
end

-- Obtém dados compartilhados
local sharedData = getShareCache("shared_config")

-- Obtém o valor compartilhado mais recente de um dispositivo
local val = getDeviceShareValue("device1", "temperature")
if val ~= nil then
    Logger.warn("设备 device1 温度: " .. val)
end

-- Obtém os valores compartilhados de cada dispositivo de uma lista
local deviceCodes = {"device1", "device2"}
local shareValues = getDeviceShareValues(deviceCodes, "temperature")
if shareValues then
    for deviceCode, dataValue in pairs(shareValues) do
        Logger.warn("设备 " .. deviceCode .. " 温度: " .. dataValue)
    end
end

-- Obtém os valores compartilhados de todos os dispositivos
local allShareValues = getAllDeviceShareValues("temperature")
if allShareValues then
    for deviceCode, dataValue in pairs(allShareValues) do
        Logger.warn("设备 " .. deviceCode .. " 温度: " .. dataValue)
    end
end

Consultar valores mais recentes em lote por padrão de dataKey

As funções abaixo percorrem o cache local dos valores mais recentes, filtram por prefixo, sufixo ou palavra-chave de dataKey e retornam informações dos pontos correspondentes em uma table {dataKey: FrontDataDTO}.

Campos do retorno: cada valor é um objeto FrontDataDTO, com os seguintes campos comuns:

Campo	Tipo	Descrição
`DataKey`	string	Chave exclusiva dos dados
`DataValue`	string	Valor mais recente
`DataType`	string	Tipo de dado
`DataName`	string	Nome dos dados
`DataUnit`	string	Unidade
`CollectionTime`	OffsetDateTime	Horário da aquisição

Observação: o retorno nil indica que não há correspondências no cache. O parâmetro dataType deve corresponder exatamente a um valor da enumeração: Collection / Customization / Aggregation / Share.

Consulta por suffix

Função	Descrição	Retorno
`getLatestDataValuesBySuffix(dataType, suffix)`	Consulta os valores mais recentes do tipo especificado cujo dataKey termina com suffix	table \| nil
`getAllLatestDataValuesBySuffix(suffix)`	Consulta os valores mais recentes de todos os tipos cujo dataKey termina com suffix	table \| nil

Consulta por prefix

Função	Descrição	Retorno
`getLatestDataValuesByPrefix(dataType, prefix)`	Consulta os valores mais recentes do tipo especificado cujo dataKey começa com prefix	table \| nil
`getAllLatestDataValuesByPrefix(prefix)`	Consulta os valores mais recentes de todos os tipos cujo dataKey começa com prefix	table \| nil

Consulta por prefix + suffix

Função	Descrição	Retorno
`getLatestDataValuesByPrefixAndSuffix(dataType, prefix, suffix)`	Consulta os valores mais recentes do tipo especificado cujo dataKey corresponde simultaneamente a prefix e suffix	table \| nil
`getAllLatestDataValuesByPrefixAndSuffix(prefix, suffix)`	Consulta os valores mais recentes de todos os tipos cujo dataKey corresponde simultaneamente a prefix e suffix	table \| nil

Busca por correspondência parcial (contém palavra-chave)

Função	Descrição	Retorno
`getLatestDataValuesByFuzzy(dataType, keyword)`	Consulta os valores mais recentes do tipo especificado cujo dataKey contém keyword	table \| nil
`getAllLatestDataValuesByFuzzy(keyword)`	Consulta os valores mais recentes de todos os tipos cujo dataKey contém keyword	table \| nil

Exemplo de uso

local Logger = require("Logger")

-- Consulta os valores de aquisição mais recentes cujos nomes terminam com "_power"
local powerValues = getLatestDataValuesBySuffix("Collection", "_power")
if powerValues then
    for dataKey, dto in pairs(powerValues) do
        Logger.warn(dataKey .. " = " .. dto.DataValue)
    end
end

-- Consulta os valores mais recentes de todos os tipos cujos nomes terminam com "_power", sem restrição de tipo de dado
local allPower = getAllLatestDataValuesBySuffix("_power")

-- Consulta todos os dados de aquisição cujos nomes começam com "meter1."
local meterValues = getLatestDataValuesByPrefix("Collection", "meter1.")
if meterValues then
    for dataKey, dto in pairs(meterValues) do
        Logger.warnf("%s = %s (%s)", dataKey, dto.DataValue, dto.DataUnit)
    end
end

-- Consulta dados de todos os tipos cujos nomes começam com "meter1."
local allMeter = getAllLatestDataValuesByPrefix("meter1.")

-- Consulta dados de aquisição cujo dataKey começa com "meter1." e termina com "_voltage"
local voltages = getLatestDataValuesByPrefixAndSuffix("Collection", "meter1.", "_voltage")

-- Consulta dados de todos os tipos que correspondem a prefix e suffix
local allVoltages = getAllLatestDataValuesByPrefixAndSuffix("meter1.", "_voltage")

-- Busca parcial: consulta os valores agregados mais recentes cujo dataKey contém "temp"
local tempValues = getLatestDataValuesByFuzzy("Aggregation", "temp")
if tempValues then
    for dataKey, dto in pairs(tempValues) do
        Logger.warn("温度点位: " .. dataKey .. " = " .. dto.DataValue)
    end
end

-- Busca parcial: consulta os valores mais recentes de todos os tipos cujo dataKey contém "temp"
local allTemp = getAllLatestDataValuesByFuzzy("temp")

Funções de lista de dispositivos

Função	Descrição	Retorno
`getDeviceList(ignoreLocal)`	Obtém a lista de dispositivos, excluindo o local quando ignoreLocal=true	table
`getDeviceCodeList(ignoreLocal)`	Obtém a lista de deviceCode, excluindo o local quando ignoreLocal=true	table

Exemplo de uso

local Logger = require("Logger")

-- Obtém a lista de todos os dispositivos
local allDevices = getDeviceList(false)
if allDevices then
    for i, device in ipairs(allDevices) do
        Logger.warn("设备: " .. device.deviceCode .. " - " .. device.deviceName)
    end
end

-- Obtém a lista de dispositivos, exceto o local
local otherDevices = getDeviceList(true)
if otherDevices then
    for i, device in ipairs(otherDevices) do
        Logger.warn("共享设备: " .. device.deviceCode)
    end
end

-- Obtém a lista de todos os códigos de dispositivo, mais rapidamente que a lista completa
local deviceCodes = getDeviceCodeList(false)
if deviceCodes then
    for i, code in ipairs(deviceCodes) do
        Logger.warn("设备编码: " .. code)
    end
end

-- Obtém a lista de códigos de dispositivo, exceto o local
local otherDeviceCodes = getDeviceCodeList(true)

Funções de consulta de dados históricos

Função	Descrição	Retorno
`getHistoryData(dataType, dataKey, startTime?, endTime?, formatMap?)`	Obtém dados históricos	table
`getShareHistoryData(deviceCode, dataKey, startTime?, endTime?, formatMap?)`	Obtém dados históricos compartilhados do dispositivo especificado	table
`getTimeData(dataKey, time?, interval?)`	Obtém dados do instante especificado	table
`getShareTimeData(deviceCode, dataKey, time?, interval?)`	Obtém dados compartilhados do instante especificado	table
`deleteCustomizationData(dataKey, startTime?, endTime?)`	Exclui dados personalizados	boolean

Descrição dos parâmetros:

startTime/endTime/time: aceita os seguintes formatos:
- Objeto OffsetDateTime (recomendado)
- String de data e hora, como “2024-01-15T10:00:00.000Z”
- String abreviada, como “2024-01-15”, completada automaticamente
formatMap: parâmetro opcional do tipo table para personalizar os nomes dos campos retornados
- dataKey: nome personalizado do campo da chave dos dados; padrão: “dataKey”
- dataValue: nome personalizado do campo do valor dos dados; padrão: “dataValue”
- collectionTime: nome personalizado do campo do horário de aquisição; padrão: “collectionTime”

Campos retornados para o tipo Customization:

Os campos de tempo retornados por getHistoryData / getTimeData para dados Customization dependem do tipo de agendamento:

DailyChange: retorna availableTime (data e hora completas em ISO 8601) e expiredTime.
DailyRepeat: retorna availableTime (string HH:mm:ss) e expiredTime (string HH:mm:ss).

Exemplo de uso

local OffsetDateTime = require("OffsetDateTime")
local Logger = require("Logger")

-- Método 1: usa um objeto OffsetDateTime (recomendado)
local now = OffsetDateTime.now()
local startTime = now:addDays(-7)
local endTime = now
local data = getHistoryData("Collection", "temperature", startTime, endTime)

-- Extensão do método 1: usa formatMap para personalizar os nomes dos campos retornados
local formatMap = {
    dataKey = "key",
    dataValue = "value",
    collectionTime = "time"
}
local data = getHistoryData("Collection", "temperature", startTime, endTime, formatMap)

-- Método 2: usa strings de data e hora
local data = getHistoryData("Collection", "temperature", "2024-01-01T00:00:00.000Z", "2024-01-31T23:59:59.000Z")

-- Método 3: usa strings abreviadas, completadas automaticamente
local data = getHistoryData("Collection", "temperature", "2024-01-01", "2024-01-31")

-- Consulta dados históricos compartilhados
local sharedData = getShareHistoryData("space1", "pressure", startTime, endTime)

-- Consulta dados do instante especificado
local value = getTimeData("temperature", now, "5m")

-- Exclui dados personalizados
local deleted = deleteCustomizationData("data1", startTime, endTime)
Logger.warn("删除成功: " .. tostring(deleted))

Funções auxiliares de construção

Função	Descrição	Retorno
`buildCommonWriteMap(dataType, dataKey, dataValue, availableDate, expiredDate, changeMod)`	Constrói um map de gravação geral	table
`buildGeneralWriteMap(dataType, dataKey, dataValue, changeMod)`	Constrói um map de gravação geral, versão simplificada sem parâmetros de tempo	table
`buildCustomizationWriteMap(dataKey, dataValue, availableDate, expiredDate)`	Constrói um map de gravação de dados por faixa de horário DailyChange, com dataType=Customization implícito	table
`buildDailyRepeatWriteMap(dataKey, dataValue, availableTime, expiredTime)`	Constrói um map de gravação de dados por faixa de horário DailyRepeat, com dataType=Customization implícito e parâmetros de tempo como strings `HH:mm:ss`	table
`updateDailyRepeatSchedule(dataKey, scheduleAvailableDate, scheduleExpiredDate)`	Atualiza o intervalo geral de vigência de uma configuração DailyRepeat; os dois parâmetros de data aceitam `nil`, e `nil` indica ausência de limite, com validade permanente	boolean
`buildAlarmObservationMap(sourceCode, alarmKey, state, alarmType, alarmLevel, alarmContent[, detailKey])`	Constrói uma observação de evento de alarme; state aceita ACTIVE / NORMAL / UNKNOWN	table
`buildCommonAlarmMap(alarmType, alarmContent)`	Constrói um map de alarme geral	table
`buildMqttAlarmMap(alarmType, alarmContent, mqttConnectionConfigId, topic, qos)`	Constrói um map de alarme MQTT	table
`buildSlaveWriteMap(deviceCode, dataType, dataKey, dataValue, availableDate, expiredDate, changeMod)`	Constrói um map de gravação em dispositivo subordinado	table

Observações de alarme usam um sourceCode + alarmKey estável. Envie NORMAL em condições normais e UNKNOWN quando faltarem valores ou o dispositivo estiver offline. Os estados do evento diferem dos estados de observação; consulte o fluxo completo em Ciclo de vida dos alarmes. As funções anteriores de construção de alarmes continuam gerando registros independentes.

A conversão inversa dos coeficientes de gravação na aquisição é tratada pelo CommBridge. O antigo buildCollectionWriteMap foi removido; use as funções gerais de construção de gravações sem repetir a conversão.

Descrição dos parâmetros:

dataType: tipo dos dados operados; valores possíveis: Collection (aquisição), Customization (personalizados/por faixa de horário), Aggregation (agregados), Share (compartilhados) e Alarm (alarmes).
availableDate / expiredDate: necessários apenas para Customization do tipo DailyChange; aceitam strings ISO 8601 ou objetos OffsetDateTime. Para outros tipos, informe nil.
availableTime / expiredTime: necessários apenas para Customization do tipo DailyRepeat, no formato "HH:mm:ss", como "08:00:00"; o intervalo não pode cruzar a meia-noite.
changeMod: booleano; true indica gravação apenas quando o valor muda.

Exemplo de uso

local OffsetDateTime = require("OffsetDateTime")

-- Grava em um ponto de aquisição
local writeCollection = buildCommonWriteMap("Collection", "temperature", 25.5, nil, nil, false)

-- Grava em um ponto personalizado (DailyChange: intervalo completo de data e hora)
local writeCustom = buildCommonWriteMap(
    "Customization", "mode", "1",
    "2024-01-15T07:00:00+08:00",
    "2024-01-15T18:00:00+08:00",
    false
)

-- Grava em um ponto personalizado (DailyChange: função abreviada específica)
local writeCustom2 = buildCustomizationWriteMap(
    "mode", "1",
    "2024-01-15T07:00:00+08:00",
    "2024-01-15T18:00:00+08:00"
)

-- Grava em um ponto personalizado (DailyRepeat: faixa diária repetida, formato HH:mm:ss)
local writeDailyRepeat = buildDailyRepeatWriteMap("charge_mode", "1", "08:00:00", "18:00:00")

-- Atualiza o intervalo geral de vigência da configuração DailyRepeat
local OffsetDateTime = require("OffsetDateTime")
local ok = updateDailyRepeatSchedule("charge_mode",
    OffsetDateTime.parse("2026-01-01T00:00:00+08:00"),
    OffsetDateTime.parse("2026-12-31T23:59:59+08:00"))

-- Define validade permanente, passando nil nas duas datas
local ok2 = updateDailyRepeatSchedule("charge_mode", nil, nil)

-- Define o início sem data final; nil indica que nunca expira
local ok3 = updateDailyRepeatSchedule("charge_mode", "2026-01-01", nil)

-- Grava em um ponto agregado, versão simplificada sem parâmetros de tempo
local writeAgg = buildGeneralWriteMap("Aggregation", "avg_temp", 22.5, false)

-- Constrói um alarme para gravação nos registros locais
local alarm = buildCommonAlarmMap("TEMP_HIGH", "温度超过80°C")

-- Constrói um alarme MQTT, com ID de conexão MQTT vinculado e envio simultâneo ao MQTT Broker
local mqttAlarm = buildMqttAlarmMap("TEMP_HIGH", "温度超过80°C", 1, "alarm/upload", 1)

-- Grava dados compartilhados no dispositivo subordinado
local slaveWrite = buildSlaveWriteMap("DeviceB", "Share", "shared_temp", 25.5, nil, nil, false)

Funções de conversão de base numérica

Função	Descrição	Retorno
`toFixedLengthBinary(value, length)`	Converte para binário de comprimento fixo	string \| (nil, err)
`toDecimal(binaryStr)`	Converte binário em decimal	number \| (nil, err)

Exemplo de uso

-- Converte decimal em binário
local binary = toFixedLengthBinary(10, 8)
Logger.warn(binary)  -- "00001010"

-- Converte binário em decimal
local decimal = toDecimal("00001010")
Logger.warn(decimal)  -- 10

Exemplos completos

Script de monitoramento de dispositivos

local Logger = require("Logger")
local JSON = require("JSON")
local OffsetDateTime = require("OffsetDateTime")
local Math = require("Math")
local Logger = require("Logger")

Logger.info("设备监控脚本启动")

-- Obtém os dados mais recentes do dispositivo
local temperature = getLatestDataValue("device1.temperature")
local humidity = getLatestDataValue("device1.humidity")

Logger.infof("当前温度: %.1f°C, 湿度: %.1f%%", temperature, humidity)

-- Avalia o alarme de temperatura
if temperature > 80 then
    local alarm = buildCommonAlarmMap("TEMP_HIGH", "温度超过80°C")
    Logger.error("温度告警: " .. JSON.toJSONString(alarm))
end

-- Consulta dados históricos
local now = OffsetDateTime.now()
local startTime = now:addHours(-24)
local history = getHistoryData(
    "device1",
    "temperature",
    startTime:toString(),
    now:toString()
)

Logger.infof("获取到 %d 条历史数据", #history)

-- Calcula a média
local sum = 0
for i, record in ipairs(history) do
    sum = sum + record.value
end
local avg = sum / #history
Logger.infof("24小时平均温度: %.2f°C", Math.round(avg * 100) / 100)

Script de processamento de dados

local JSON = require("JSON")
local Regex = require("Regex")
local TableUtils = require("TableUtils")
local String = require("String")
local Logger = require("Logger")

-- Obtém a configuração do cache
local configJson = getShareCache("device_config")
local config = JSON.decode(configJson)

-- Filtra os dispositivos habilitados
local enabledDevices = TableUtils.filter(config.devices, function(device, index)
    return device.enabled == true
end)

-- Extrai os nomes dos dispositivos
local deviceNames = TableUtils.map(enabledDevices, function(device, index)
    return device.name
end)

-- Limpeza de dados
local cleanedNames = TableUtils.map(deviceNames, function(name, index)
    -- Remove espaços em branco e converte para maiúsculas
    return String.upper(String.trim(name))
end)

-- Valida o formato do identificador do dispositivo
for i, device in ipairs(enabledDevices) do
    if not Regex.match(device.id, "^DEV\\d{6}$") then
        Logger.warnf("设备编号格式错误: %s", device.id)
    end
end

-- Exibe o resultado
Logger.info("处理完成: " .. JSON.toJSONString(cleanedNames))

Observações

Tratamento de erros: a maioria das funções retorna no formato (result, error); verifique os erros ao utilizá-las.
Formato de data e hora: strings temporais usam ISO 8601.
Expressões regulares: usam a sintaxe do Go, diferente dos patterns nativos de Lua.
Iteração em tabelas: map/filter/reduce de TableUtils percorrem primeiro a parte de array (1..n) e depois os pares chave-valor.
Nível de log: o nível de saída do Logger é determinado pela configuração do sistema.
Desempenho JSON: o runtime usa processamento JSON de alto desempenho, adequado à serialização de grandes volumes.

Verificar se um ponto tem valor

if isNotNull(${some_key}) then
    return {}
end
return { buildCommonWriteMap("Collection", "target_key", ${some_key}, nil, nil, false) }

Próximos passos

Introdução geral ao mecanismo e exemplos de pontos agregados: Mecanismo de expressões.
Organização de scripts de condições e ações: Perfis de acionamento.
Manual detalhado das ações de gravação em perfis EXPRESSION: Manual de scripts de perfis de acionamento EXPRESSION.
Manual detalhado de publicação/assinatura MQTT: Manual de scripts de publicação/assinatura MQTT.