Référence complète des scripts Lua

Cette page est la référence complète des scripts du moteur d’expressions Edge-EMS Builder : expressions agrégées, conditions et actions de déclenchement, post-traitement, publication et abonnement MQTT. La syntaxe Lua 5.x est interprétée par le runtime intégré. Pour commencer, consultez le moteur d’expressions ; cette page détaille modules, signatures globales et conventions de retour.

⚠️ Si vous avez utilisé l’ancienne version Java d’Edge-EMS Builder, fondée sur QLExpress4 et une syntaxe proche de Java, la notation ${...} reste globalement identique, mais le corps du script utilise désormais Lua standard : new ArrayList() → {}, .add(x) → table.insert(t, x), new HashMap() → {}, .put(k, v) → t[k] = v. La plupart des noms de fonctions sont conservés ; utilisez cette page pour migrer.

Aperçu

Langage : Lua 5.x ; noms de fonctions et espaces réservés sensibles à la casse.
Espaces réservés de données : ${dataKey} est remplacé par la valeur courante avant exécution ; utilisez ${[deviceCode]dataKey} entre équipements.
Sentinelle : sans donnée, la chaîne __Null__ est injectée. Comparez-la explicitement ou utilisez isNull / isNotNull. Pour les nombres, appliquez d’abord tonumber.
Le retour dépend du contexte, comme expliqué ci-dessous. Un type de retour incorrect est l’erreur de configuration la plus fréquente.
Les fonctions de module nécessitent require("nom-du-module") ; les fonctions globales, telles que buildCommonWriteMap et jsonToMap, s’appellent directement sans require.
Journaux : le niveau par défaut de Logger est WARN. Seuls Logger.warn() et Logger.error() produisent réellement une sortie ; ne vous limitez pas à Logger.info()/Logger.debug() pour déboguer.

1. Résolution des données et références de variables

Syntaxe	Description
`${variable}`	Valeur courante
`${variable[-1s]}`	Valeur de la seconde précédente
`${variable[-5s]}`	Valeur 5 secondes auparavant
`${variable[raw]}`	Injection telle quelle sans conversion automatique de type, notamment pour distinguer le nombre `1000` du binaire `1000`. `[raw]` ne peut être placé qu’en dernière position et doit l’être.
`${[deviceA]variable}`	Valeur de l’équipement partagé deviceA
`${variable[@timestamp]}`	Valeur à l’instant absolu spécifié
`${variable[#N]}`	Nième valeur historique en remontant depuis la plus récente ; sans cette règle, la dernière valeur est retournée
`${[deviceA]variable[-5s][#N]}`	Nième échantillon précédent de l’équipement partagé deviceA à l’instant situé 5 secondes auparavant

Si un point n’a pas de valeur disponible, le moteur injecte toujours __Null__. Testez-le explicitement, par exemple if ${some_key} == "__Null__" then ... end.

2. Conventions de retour selon le contexte

Les exigences de retour diffèrent complètement selon l’emplacement du script, source fréquente d’erreurs :

Contexte	Emplacement	Retour requis
Condition de déclenchement	Expression de condition	Un booléen unique ; `true` signifie que la condition est satisfaite
Action d’un plan de type expression	Contenu de l’action (Expression)	Tableau indexé continûment à partir de 1, contenant des maps retournées par `buildCommonWriteMap(...)` ou équivalent ; `{}` signifie aucune écriture
Action d’un plan d’écritures mixtes	Action liée séparément à chaque `dataKey`	Valeur unique, chaîne, nombre ou booléen, à écrire dans ce `dataKey` ; ne pas retourner un tableau `buildCommonWriteMap`
Post-traitement	Script après exécution de l’action	Tableau de descriptions d’écriture, comme pour une action expression. `${trigger_result}` est booléen ; `${trigger_write_result}` est une chaîne JSON à analyser avec `jsonToMap` pour vérifier le résultat principal.
Expression d’un point agrégé	Expression de calcul des données agrégées	Valeur unique, numérique, textuelle, etc., devenant la dernière valeur du point
Contenu de publication MQTT, publishContent	Configuration de publication MQTT	Table Lua, sérialisée en JSON comme charge utile
Action d’abonnement MQTT, actionContent	Configuration d’abonnement MQTT	Tableau de descriptions d’écriture, comme une action expression
Topic de réponse MQTT, responseTopic	Configuration d’abonnement MQTT	Chaîne unique, utilisée comme topic de publication de réponse
Contenu de réponse MQTT, response	Configuration d’abonnement MQTT	Chaîne envoyée telle quelle ; les autres valeurs, telles que tables Lua, sont sérialisées en JSON

Chaque appel de script a un délai maximal d’exécution, 10 secondes par défaut ; le dépassement fait échouer l’appel. Évitez les requêtes historiques ou HTTP sans limitation dans les boucles.

3. Modules intégrés

Chargez les modules suivants avec require("nom-du-module") avant utilisation :

Module OffsetDateTime

Module complet de date et heure avec fuseaux horaires, formatage et calculs.

Chargement du module

local OffsetDateTime = require("OffsetDateTime")

Constructeurs

Méthode	Description	Retour
`new()`	Créer la date et l’heure courantes	OffsetDateTime
`new(sec, nsec?)`	Créer depuis un horodatage Unix	OffsetDateTime
`now()`	Obtenir la date et l’heure courantes	OffsetDateTime
`parse(str)`	Analyser une chaîne temporelle	OffsetDateTime \| (nil, err)
`parseInLocation(str, location)`	Analyser une date/heure dans le fuseau indiqué	OffsetDateTime \| (nil, err)
`unix(sec, nsec?)`	Créer depuis des secondes Unix	OffsetDateTime
`unixMilli(msec)`	Créer depuis un horodatage en millisecondes	OffsetDateTime
`unixMicro(usec)`	Créer depuis un horodatage en microsecondes	OffsetDateTime

Méthodes d’instance : composants temporels

Méthode	Description	Retour
`year()`	Obtenir l’année	number
`month()`	Obtenir le mois (1-12)	number
`day()`	Obtenir le jour du mois (1-31)	number
`hour()`	Obtenir l’heure (0-23)	number
`minute()`	Obtenir la minute (0-59)	number
`second()`	Obtenir la seconde (0-59)	number
`nanosecond()`	Obtenir les nanosecondes	number
`yearDay()`	Obtenir le jour de l’année	number
`weekday()`	Obtenir le jour de la semaine (0=dimanche)	number
`isoWeek()`	Obtenir l’année et la semaine ISO	{year, week}
`date()`	Obtenir année, mois et jour	{year, month, day}
`clock()`	Obtenir heure, minute et seconde	{hour, minute, second}

Méthodes d’instance : calculs temporels

Méthode	Description	Retour
`add(durationStr)`	Ajouter une durée	OffsetDateTime \| (nil, err)
`addDate(years, months, days)`	Ajouter années, mois et jours	OffsetDateTime
`sub(other)`	Calculer l’écart temporel en nanosecondes	number
`addYears(n)`	Ajouter des années	OffsetDateTime
`addMonths(n)`	Ajouter des mois	OffsetDateTime
`addDays(n)`	Ajouter des jours	OffsetDateTime
`addHours(n)`	Ajouter des heures	OffsetDateTime
`addMinutes(n)`	Ajouter des minutes	OffsetDateTime
`addSeconds(n)`	Ajouter des secondes	OffsetDateTime
`addMilliseconds(n)`	Ajouter des millisecondes	OffsetDateTime
`addMicroseconds(n)`	Ajouter des microsecondes	OffsetDateTime
`addNanoseconds(n)`	Ajouter des nanosecondes	OffsetDateTime

Méthodes d’instance : différences temporelles

Méthode	Description	Retour
`diffYears(other)`	Écart en années	number
`diffMonths(other)`	Écart en mois	number
`diffDays(other)`	Écart en jours	number
`diffHours(other)`	Écart en heures	number
`diffMinutes(other)`	Écart en minutes	number
`diffSeconds(other)`	Écart en secondes	number

Méthodes d’instance : comparaisons temporelles

Méthode	Description	Retour
`equal(other)`	Tester l’égalité	boolean
`before(other)`	Tester l’antériorité	boolean
`after(other)`	Tester la postériorité	boolean
`isZero()`	Tester la valeur zéro	boolean

Méthodes d’instance : tests temporels

Méthode	Description	Retour
`isToday()`	Est-ce aujourd’hui ?	boolean
`isYesterday()`	Est-ce hier ?	boolean
`isTomorrow()`	Est-ce demain ?	boolean
`isThisWeek()`	Est-ce cette semaine ?	boolean
`isThisMonth()`	Est-ce ce mois-ci ?	boolean
`isThisYear()`	Est-ce cette année ?	boolean
`isBetween(start, end)`	L’instant est-il dans l’intervalle ?	boolean
`isInRange(start, end)`	L’instant est-il dans l’intervalle ?	boolean

Méthodes d’instance : formatage

Méthode	Description	Retour
`format(layout)`	Formatage personnalisé	string
`toString()`	Convertir en chaîne	string
`toDateTimeString()`	Format date et heure	string
`toDateString()`	Format date	string
`toTimeString()`	Format heure	string
`toYearString()`	Année	string
`toMonthString()`	Mois	string
`toDayString()`	Jour	string
`toHourString()`	Heure	string
`toMinuteString()`	Minute	string
`toSecondString()`	Seconde	string

Méthodes d’instance : horodatages Unix

Méthode	Description	Retour
`unix()`	Horodatage Unix en secondes	number
`unixMilli()`	Horodatage Unix en millisecondes	number
`unixMicro()`	Horodatage Unix en microsecondes	number
`unixNano()`	Horodatage Unix en nanosecondes	number

Méthodes d’instance : fuseaux horaires

Méthode	Description	Retour
`utc()`	Convertir en UTC	OffsetDateTime
`local()`	Convertir dans le fuseau local	OffsetDateTime
`in(location)`	Convertir dans le fuseau indiqué	OffsetDateTime \| (nil, err)

Autres méthodes d’instance

Méthode	Description	Retour
`truncate(durationStr)`	Tronquer à la précision indiquée	OffsetDateTime \| (nil, err)
`round(durationStr)`	Arrondir à la précision indiquée	OffsetDateTime \| (nil, err)
`toTime()`	Convertir en time.Time 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"

Exemple d’utilisation

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

-- Obtenir la date et l’heure courantes
local now = OffsetDateTime.now()
Logger.warn(now:toString())

-- Analyser la date et l’heure
local dt = OffsetDateTime.parse("2024-01-15T10:30:00.000Z")
Logger.warn("年份: " .. dt:year())
Logger.warn("月份: " .. dt:month())

-- Calculs temporels
local tomorrow = now:addDays(1)
local nextWeek = now:addDays(7)
Logger.warn("明天: " .. tomorrow:toDateString())

-- Comparaisons temporelles
if now:isToday() then
    Logger.warn("今天!")
end

-- Différence temporelle
local hours = nextWeek:diffHours(now)
Logger.warn("相差小时: " .. hours)

-- Formatage
Logger.warn(now:format("2006-01-02 15:04:05"))
Logger.warn(now:toDateTimeString())

Module LocalTime

Type temporel contenant uniquement heure, minute et seconde, sans date ni fuseau horaire.

Chargement du module

local LocalTime = require("LocalTime")

Constructeurs

Méthode	Description	Retour
`new(hour, minute, second)`	Créer une heure	LocalTime \| (nil, err)
`now()`	Obtenir l’heure courante	LocalTime
`parse(str)`	Analyser “HH:mm:ss”	LocalTime \| (nil, err)
`fromTime(time.Time)`	Créer depuis time.Time	LocalTime \| (nil, err)
`fromDuration(durationStr)`	Créer depuis une durée	LocalTime \| (nil, err)

Méthodes d’instance

Méthode	Description	Retour
`hour()`	Obtenir l’heure	number
`minute()`	Obtenir la minute	number
`second()`	Obtenir la seconde	number
`toString()`	Convertir en “HH:mm:ss”	string
`toDuration()`	Convertir en chaîne de durée	string
`equal(other)`	Tester l’égalité	boolean
`before(other)`	Tester l’antériorité	boolean
`after(other)`	Tester la postériorité	boolean
`beforeOrEqual(other)`	Tester antériorité ou égalité	boolean
`afterOrEqual(other)`	Tester postériorité ou égalité	boolean
`isZero()`	Tester 00:00:00	boolean
`diffSeconds(other)`	Écart en secondes	number
`diffMinutes(other)`	Écart en minutes	number
`diffHours(other)`	Écart en heures	number
`addSeconds(n)`	Ajouter des secondes	LocalTime
`addMinutes(n)`	Ajouter des minutes	LocalTime
`addHours(n)`	Ajouter des heures	LocalTime
`subSeconds(n)`	Soustraire des secondes	LocalTime
`subMinutes(n)`	Soustraire des minutes	LocalTime
`subHours(n)`	Soustraire des heures	LocalTime

Exemple d’utilisation

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

-- Créer une heure
local workStart = LocalTime.new(9, 0, 0)   -- 09:00:00
local workEnd = LocalTime.new(17, 30, 0)   -- 17:30:00

-- Obtenir la date et l’heure courantes
local now = LocalTime.now()
Logger.warn("当前时间: " .. now:toString())

-- Comparaisons temporelles
if now:isBetween(workStart, workEnd) then
    Logger.warn("工作时间")
else
    Logger.warn("非工作时间")
end

-- Calculs temporels
local breakTime = workStart:addHours(3):addMinutes(30)  -- 12:30:00
Logger.warn("午休时间: " .. breakTime:toString())

-- Différence temporelle
local workHours = workEnd:diffHours(workStart)
Logger.warn("工作时长: " .. workHours .. " 小时")

Modules utilitaires

Module Logger

Module de journalisation relié aux journaux système.

Chargement du module

local Logger = require("Logger")

API

Méthode	Description	Paramètres
`info(msg)`	Émettre un journal INFO	string
`warn(msg)`	Émettre un journal WARN	string
`error(msg)`	Émettre un journal ERROR	string
`debug(msg)`	Émettre un journal DEBUG	string
`infof(fmt, ...)`	Émettre un journal INFO formaté	string, …
`warnf(fmt, ...)`	Émettre un journal WARN formaté	string, …
`errorf(fmt, ...)`	Émettre un journal ERROR formaté	string, …
`debugf(fmt, ...)`	Émettre un journal DEBUG formaté	string, …

Exemple d’utilisation

local Logger = require("Logger")

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

-- Sortie formatée
local user = "admin"
local action = "login"
Logger.infof("用户 %s 执行操作: %s", user, action)
Logger.warnf("重试次数: %s", 3)

Remarque : le niveau de journalisation par défaut d’Edge-EMS Builder est WARN ; seuls les journaux WARN et ERROR sont émis.

Module JSON

Module de sérialisation, désérialisation et manipulation JSON, fondé sur bytedance/sonic.

Chargement du module

local JSON = require("JSON")

API de base

Méthode	Description	Retour
`encode(value)`	Sérialiser en JSON	string \| (nil, err)
`decode(text)`	Désérialiser	table \| (nil, err)

API étendue

Méthode	Description	Retour
`toJSONString(value)`	Sérialiser sans retour d’erreur	string
`toJSONStringIndent(value, prefix?, indent?)`	Sérialiser avec mise en forme	string
`toMap(jsonStr)`	Convertir en map	table \| (nil, err)
`toStringMap(jsonStr)`	Convertir en map de chaînes	table \| (nil, err)
`toSlice(jsonStr)`	Convertir en tableau	table \| (nil, err)
`isValid(jsonStr)`	Valider le format JSON	boolean
`pretty(jsonStr)`	Mettre en forme le JSON	string
`merge(json1, json2)`	Fusionner deux JSON	string \| (nil, err)
`get(jsonStr, key)`	Obtenir une valeur	any \| (nil, err)
`set(jsonStr, key, value)`	Définir une valeur	string \| (nil, err)
`remove(jsonStr, key)`	Supprimer une clé	string \| (nil, err)
`clone(value)`	Copie profonde	any \| (nil, err)

Exemple d’utilisation

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

-- Sérialisation/désérialisation de base
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

-- Sortie formatée
local pretty = JSON.pretty(jsonStr)
Logger.warn(pretty)

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

-- Manipuler le 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":"北京"}

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

-- Copie profonde
local original = {data = {x = 10}}
local copied = JSON.clone(original)

Module Regex

Module d’expressions régulières pour correspondance, recherche, remplacement et découpage.

Chargement du module

local Regex = require("Regex")

API

Méthode	Description	Retour
`match(text, pattern)`	Tester une correspondance	boolean
`findAll(text, pattern, limit?)`	Trouver toutes les correspondances, groupes capturés compris	{{full, g1, g2, …}, …} \| (nil, err)
`replace(text, pattern, repl)`	Remplacer, avec références de groupes telles que $1	string \| (nil, err)
`split(text, pattern, limit?)`	Découper par expression régulière	{string, …} \| (nil, err)
`isEmail(text)`	Tester une adresse e-mail	boolean
`isPhone(text)`	Tester un numéro de téléphone mobile chinois	boolean
`isIP(text)`	Tester une adresse IP	boolean
`isURL(text)`	Tester une URL	boolean

Exemple d’utilisation

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

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

-- Trouver toutes les correspondances, groupes capturés compris
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

-- Remplacer, avec références de groupes
local s = Regex.replace("abc-123-def", "(\\d+)", "[$1]")
Logger.warn(s)  -- "abc-[123]-def"

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

-- Valider
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

Module String

Outils de traitement des chaînes.

Chargement du module

local String = require("String")

API

Méthode	Description	Retour
`trim(s)`	Supprimer les espaces aux extrémités	string
`upper(s)`	Convertir en majuscules	string
`lower(s)`	Convertir en minuscules	string
`contains(s, sub)`	Tester la présence d’une sous-chaîne	boolean
`startsWith(s, prefix)`	Tester le préfixe indiqué	boolean
`endsWith(s, suffix)`	Tester le suffixe indiqué	boolean

Exemple d’utilisation

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

Module Math

Outils de calcul mathématique.

Chargement du module

local Math = require("Math")

API

Méthode	Description	Retour
`round(n)`	Arrondir à l’entier le plus proche	number
`floor(n)`	Arrondir à l’entier inférieur	number
`ceil(n)`	Arrondir à l’entier supérieur	number
`abs(n)`	Valeur absolue	number
`max(a, b)`	Maximum	number
`min(a, b)`	Minimum	number

Exemple d’utilisation

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

Module TableUtils

Outils de manipulation des tables, avec parcours des tableaux et paires clé-valeur.

Chargement du module

local TableUtils = require("TableUtils")

API

Méthode	Description	Retour
`keys(tbl)`	Obtenir toutes les clés	{string, …}
`values(tbl)`	Obtenir toutes les valeurs	{any, …}
`map(tbl, fn)`	Transformer avec fn(value, key)	{any, …}
`filter(tbl, fn)`	Filtrer avec fn(value, key)	{any, …}
`reduce(tbl, fn, init)`	Réduire avec fn(acc, value, key)	any
`sortBy(tblOfMaps, key)`	Trier par clé, de façon stable	{map, …}

Exemple d’utilisation

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 sur un tableau
local arr = {1, 2, 3}
local doubled = T.map(arr, function(v, i)
    return v * 2
end)
-- doubled = {2, 4, 6}

-- map sur des paires clé-valeur
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}}

Fonctions globales

Ces fonctions sont enregistrées directement dans la portée globale, sans require.

Conversion temporelle CP56Time2a

Fonction	Usage
`cp56Time2aToOffsetDateTime(hex[, byteOrder])`	Décoder l’heure IEC 60870-5 et renvoyer un OffsetDateTime
`offsetDateTimeToCP56Time2a(time[, byteOrder])`	Encoder l’heure en charge utile hexadécimale

byteOrder accepte AB / BA ; AB standard est utilisé par défaut. Une valeur explicite permet les charges utiles de quatre registres. Une ambiguïté de placement du zéro de remplissage provoque une erreur ; vérifiez la disposition des registres de l’équipement.

Fonctions d’analyse des données

Fonction	Description	Retour
`jsonToMap(str)`	Convertir JSON en map	table \| (nil, err)
`jsonToList(str)`	Convertir JSON en list	table \| (nil, err)
`jsonToListMap(str)`	Convertir JSON en list of map	table \| (nil, err)
`completeDateTime(str)`	Compléter une chaîne de date et heure	string \| (nil, err)
`quoteJson(str)`	Échapper les guillemets du JSON	string
`simpleUUID()`	Générer un UUID simple	string
`convertString(str)`	Convertir le type d’une chaîne	any
`isNull(any)`	Tester si la valeur est nulle	bool
`isNotNull(any)`	Tester si la valeur n’est pas nulle	bool

isNull considère comme nuls nil, la chaîne vide, “null” sans distinction de casse et la sentinelle __Null__. Le or 0 de Lua ne traite pas cette sentinelle.

Exemple d’utilisation

local Logger = require("Logger")

-- Analyser le 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}

-- Compléter la date et l’heure
local fullTime = completeDateTime("2024-01-15")
-- fullTime = "2024-01-15T00:00:00.000+08:00"

-- Générer un UUID
local id = simpleUUID()
Logger.warn(id)  -- Chaîne UUID de 32 caractères

Fonctions d’accès au cache

Fonction	Description	Retour
`getLatestDataValue(dataKey)`	Obtenir la dernière valeur des données	any
`getAccountCache(key)`	Obtenir le cache des comptes	any
`getEMSDataCache(key)`	Obtenir le cache des données EMS	any
`getShareCache(key)`	Obtenir le cache des données partagées	any
`getMqttCache(key)`	Obtenir le cache MQTT	any
`getTriggerCache(key)`	Obtenir le cache des déclencheurs	any
`getDeviceShareValue(deviceCode, dataKey)`	Obtenir la dernière valeur partagée d’un équipement via un deviceCode et un dataKey	string \| nil
`getDeviceShareValues(deviceCodes, dataKey)`	Obtenir la dernière valeur de chaque équipement via une liste d’équipements et un dataKey	table
`getAllDeviceShareValues(dataKey)`	Obtenir la dernière valeur de tous les équipements de l’espace de partage via dataKey	table

Exemple d’utilisation

local Logger = require("Logger")

-- Obtenir les dernières données de l’équipement
local value = getLatestDataValue("device1.temperature")
Logger.warn("当前温度: " .. value)

-- Obtenir les informations du compte
local account = getAccountCache("user123")
if account then
    Logger.warn("用户名: " .. account.username)
end

-- Obtenir les données partagées
local sharedData = getShareCache("shared_config")

-- Obtenir la dernière valeur partagée d’un équipement
local val = getDeviceShareValue("device1", "temperature")
if val ~= nil then
    Logger.warn("设备 device1 温度: " .. val)
end

-- Obtenir les valeurs partagées des équipements d’une liste
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

-- Obtenir les valeurs partagées de tous les équipements
local allShareValues = getAllDeviceShareValues("temperature")
if allShareValues then
    for deviceCode, dataValue in pairs(allShareValues) do
        Logger.warn("设备 " .. deviceCode .. " 温度: " .. dataValue)
    end
end

Requêtes par lot des dernières valeurs selon un motif dataKey

Ces fonctions parcourent le cache local des dernières valeurs et filtrent par préfixe, suffixe ou mot-clé de dataKey. Elles retournent les informations des points correspondants sous forme de table {dataKey: FrontDataDTO}.

Champs de retour : chaque valeur est un objet FrontDataDTO contenant notamment :

Champ	Type	Description
`DataKey`	string	Clé unique des données
`DataValue`	string	Dernière valeur
`DataType`	string	Type de données
`DataName`	string	Nom des données
`DataUnit`	string	Unité
`CollectionTime`	OffsetDateTime	Heure d’acquisition

Remarque : nil signifie qu’aucune entrée du cache ne correspond. dataType doit être exactement une valeur d’énumération : Collection / Customization / Aggregation / Share.

Recherche par suffix

Fonction	Description	Retour
`getLatestDataValuesBySuffix(dataType, suffix)`	Dernières valeurs du type indiqué dont le dataKey se termine par suffix	table \| nil
`getAllLatestDataValuesBySuffix(suffix)`	Dernières valeurs de tous les types dont le dataKey se termine par suffix	table \| nil

Recherche par prefix

Fonction	Description	Retour
`getLatestDataValuesByPrefix(dataType, prefix)`	Dernières valeurs du type indiqué dont le dataKey commence par prefix	table \| nil
`getAllLatestDataValuesByPrefix(prefix)`	Dernières valeurs de tous les types dont le dataKey commence par prefix	table \| nil

Recherche par prefix + suffix

Fonction	Description	Retour
`getLatestDataValuesByPrefixAndSuffix(dataType, prefix, suffix)`	Dernières valeurs du type indiqué dont le dataKey correspond à prefix et suffix	table \| nil
`getAllLatestDataValuesByPrefixAndSuffix(prefix, suffix)`	Dernières valeurs de tous les types dont le dataKey correspond à prefix et suffix	table \| nil

Recherche partielle par mot-clé

Fonction	Description	Retour
`getLatestDataValuesByFuzzy(dataType, keyword)`	Dernières valeurs du type indiqué dont le dataKey contient keyword	table \| nil
`getAllLatestDataValuesByFuzzy(keyword)`	Dernières valeurs de tous les types dont le dataKey contient keyword	table \| nil

Exemple d’utilisation

local Logger = require("Logger")

-- Dernières données acquises dont la clé se termine par "_power"
local powerValues = getLatestDataValuesBySuffix("Collection", "_power")
if powerValues then
    for dataKey, dto in pairs(powerValues) do
        Logger.warn(dataKey .. " = " .. dto.DataValue)
    end
end

-- Dernières valeurs de tous les types se terminant par "_power", sans restriction de type
local allPower = getAllLatestDataValuesBySuffix("_power")

-- Toutes les données acquises commençant par "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

-- Données de tous les types commençant par "meter1."
local allMeter = getAllLatestDataValuesByPrefix("meter1.")

-- Données acquises dont dataKey commence par "meter1." et se termine par "_voltage"
local voltages = getLatestDataValuesByPrefixAndSuffix("Collection", "meter1.", "_voltage")

-- Données de tous les types correspondant à prefix et suffix
local allVoltages = getAllLatestDataValuesByPrefixAndSuffix("meter1.", "_voltage")

-- Recherche partielle : dernières données agrégées dont dataKey contient "temp"
local tempValues = getLatestDataValuesByFuzzy("Aggregation", "temp")
if tempValues then
    for dataKey, dto in pairs(tempValues) do
        Logger.warn("温度点位: " .. dataKey .. " = " .. dto.DataValue)
    end
end

-- Recherche partielle : dernières valeurs de tous les types dont dataKey contient "temp"
local allTemp = getAllLatestDataValuesByFuzzy("temp")

Fonctions de liste des équipements

Fonction	Description	Retour
`getDeviceList(ignoreLocal)`	Liste des équipements ; ignoreLocal=true exclut l’équipement local	table
`getDeviceCodeList(ignoreLocal)`	Liste des deviceCode ; ignoreLocal=true exclut l’équipement local	table

Exemple d’utilisation

local Logger = require("Logger")

-- Obtenir la liste de tous les équipements
local allDevices = getDeviceList(false)
if allDevices then
    for i, device in ipairs(allDevices) do
        Logger.warn("设备: " .. device.deviceCode .. " - " .. device.deviceName)
    end
end

-- Obtenir la liste sans l’équipement local
local otherDevices = getDeviceList(true)
if otherDevices then
    for i, device in ipairs(otherDevices) do
        Logger.warn("共享设备: " .. device.deviceCode)
    end
end

-- Obtenir tous les codes d’équipement, plus rapide que la liste complète
local deviceCodes = getDeviceCodeList(false)
if deviceCodes then
    for i, code in ipairs(deviceCodes) do
        Logger.warn("设备编码: " .. code)
    end
end

-- Obtenir les codes sans l’équipement local
local otherDeviceCodes = getDeviceCodeList(true)

Fonctions de consultation de l’historique

Fonction	Description	Retour
`getHistoryData(dataType, dataKey, startTime?, endTime?, formatMap?)`	Obtenir les données historiques	table
`getShareHistoryData(deviceCode, dataKey, startTime?, endTime?, formatMap?)`	Obtenir l’historique partagé de l’équipement indiqué	table
`getTimeData(dataKey, time?, interval?)`	Obtenir les données à un instant indiqué	table
`getShareTimeData(deviceCode, dataKey, time?, interval?)`	Obtenir les données partagées à un instant indiqué	table
`deleteCustomizationData(dataKey, startTime?, endTime?)`	Supprimer des données personnalisées	boolean

Paramètres :

startTime/endTime/time accepte les formats suivants :
- Objet OffsetDateTime, recommandé.
- Chaîne temporelle, par exemple “2024-01-15T10:00:00.000Z”.
- Chaîne abrégée, par exemple “2024-01-15”, complétée automatiquement.
formatMap : table facultative personnalisant les noms des champs de la réponse.
- dataKey : nom du champ de clé, “dataKey” par défaut.
- dataValue : nom du champ de valeur, “dataValue” par défaut.
- collectionTime : nom du champ d’heure d’acquisition, “collectionTime” par défaut.

Champs renvoyés pour Customization :

Les champs temporels retournés par getHistoryData / getTimeData pour Customization dépendent du type de programme :

DailyChange : availableTime, date et heure complètes ISO 8601, et expiredTime.
DailyRepeat : availableTime et expiredTime, chaînes HH:mm:ss.

Exemple d’utilisation

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

-- Méthode 1 : objets OffsetDateTime, recommandés
local now = OffsetDateTime.now()
local startTime = now:addDays(-7)
local endTime = now
local data = getHistoryData("Collection", "temperature", startTime, endTime)

-- Extension de la méthode 1 : personnaliser les champs de retour avec formatMap
local formatMap = {
    dataKey = "key",
    dataValue = "value",
    collectionTime = "time"
}
local data = getHistoryData("Collection", "temperature", startTime, endTime, formatMap)

-- Méthode 2 : chaînes temporelles
local data = getHistoryData("Collection", "temperature", "2024-01-01T00:00:00.000Z", "2024-01-31T23:59:59.000Z")

-- Méthode 3 : chaînes abrégées, complétées automatiquement
local data = getHistoryData("Collection", "temperature", "2024-01-01", "2024-01-31")

-- Consulter l’historique partagé
local sharedData = getShareHistoryData("space1", "pressure", startTime, endTime)

-- Consulter les données à un instant donné
local value = getTimeData("temperature", now, "5m")

-- Supprimer des données personnalisées
local deleted = deleteCustomizationData("data1", startTime, endTime)
Logger.warn("删除成功: " .. tostring(deleted))

Fonctions auxiliaires de construction

Fonction	Description	Retour
`buildCommonWriteMap(dataType, dataKey, dataValue, availableDate, expiredDate, changeMod)`	Construire une map d’écriture générique	table
`buildGeneralWriteMap(dataType, dataKey, dataValue, changeMod)`	Construire une map d’écriture générique simplifiée, sans paramètres temporels	table
`buildCustomizationWriteMap(dataKey, dataValue, availableDate, expiredDate)`	Construire une map d’écriture horaire DailyChange, avec dataType=Customization implicite	table
`buildDailyRepeatWriteMap(dataKey, dataValue, availableTime, expiredTime)`	Construire une map d’écriture horaire DailyRepeat, avec dataType=Customization implicite et heures au format `HH:mm:ss`	table
`updateDailyRepeatSchedule(dataKey, scheduleAvailableDate, scheduleExpiredDate)`	Actualiser la période globale de validité de DailyRepeat ; les deux dates acceptent `nil`, qui signifie sans limite, donc validité permanente	boolean
`buildAlarmObservationMap(sourceCode, alarmKey, state, alarmType, alarmLevel, alarmContent[, detailKey])`	Construire une observation d’événement d’alarme ; state vaut ACTIVE / NORMAL / UNKNOWN	table
`buildCommonAlarmMap(alarmType, alarmContent)`	Construire une map d’alarme générique	table
`buildMqttAlarmMap(alarmType, alarmContent, mqttConnectionConfigId, topic, qos)`	Construire une map d’alarme MQTT	table
`buildSlaveWriteMap(deviceCode, dataType, dataKey, dataValue, availableDate, expiredDate, changeMod)`	Construire une map d’écriture sur un esclave	table

Les observations d’alarme utilisent un sourceCode + alarmKey stable. Envoyez NORMAL en situation normale et UNKNOWN pour une donnée manquante ou un équipement hors ligne. L’état de l’événement diffère de l’observation ; consultez le cycle de vie des alarmes. Les anciens constructeurs d’alarme génèrent toujours des enregistrements indépendants.

CommBridge effectue la conversion inverse des coefficients d’écriture d’acquisition. L’ancienne fonction buildCollectionWriteMap a été supprimée ; utilisez les constructeurs génériques sans répéter la conversion.

Paramètres :

dataType : type manipulé, parmi Collection (acquisition), Customization (personnalisé/horaire), Aggregation (agrégé), Share (partagé) et Alarm (alarme).
availableDate / expiredDate : uniquement pour Customization DailyChange ; chaîne ISO 8601 ou objet OffsetDateTime. Transmettez nil pour les autres types.
availableTime / expiredTime : uniquement pour Customization DailyRepeat, au format "HH:mm:ss", par exemple "08:00:00", sans traverser minuit.
changeMod : booléen ; true écrit uniquement lorsque la valeur change.

Exemple d’utilisation

local OffsetDateTime = require("OffsetDateTime")

-- Écrire un point acquis
local writeCollection = buildCommonWriteMap("Collection", "temperature", 25.5, nil, nil, false)

-- Écrire un point personnalisé DailyChange, avec intervalle complet de date et heure
local writeCustom = buildCommonWriteMap(
    "Customization", "mode", "1",
    "2024-01-15T07:00:00+08:00",
    "2024-01-15T18:00:00+08:00",
    false
)

-- Écrire un point personnalisé DailyChange avec la fonction abrégée dédiée
local writeCustom2 = buildCustomizationWriteMap(
    "mode", "1",
    "2024-01-15T07:00:00+08:00",
    "2024-01-15T18:00:00+08:00"
)

-- Écrire un point personnalisé DailyRepeat, plages quotidiennes au format HH:mm:ss
local writeDailyRepeat = buildDailyRepeatWriteMap("charge_mode", "1", "08:00:00", "18:00:00")

-- Actualiser la période globale de validité de 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"))

-- Rendre la validité permanente en transmettant nil pour les deux dates
local ok2 = updateDailyRepeatSchedule("charge_mode", nil, nil)

-- Définir le début sans échéance ; nil signifie sans expiration
local ok3 = updateDailyRepeatSchedule("charge_mode", "2026-01-01", nil)

-- Écrire un point agrégé, version simplifiée sans paramètres temporels
local writeAgg = buildGeneralWriteMap("Aggregation", "avg_temp", 22.5, false)

-- Construire une alarme, enregistrée localement
local alarm = buildCommonAlarmMap("TEMP_HIGH", "温度超过80°C")

-- Construire une alarme MQTT avec ID de connexion associé, également envoyée au broker
local mqttAlarm = buildMqttAlarmMap("TEMP_HIGH", "温度超过80°C", 1, "alarm/upload", 1)

-- Écrire des données partagées sur un esclave
local slaveWrite = buildSlaveWriteMap("DeviceB", "Share", "shared_temp", 25.5, nil, nil, false)

Fonctions de conversion de base numérique

Fonction	Description	Retour
`toFixedLengthBinary(value, length)`	Convertir en binaire de longueur fixe	string \| (nil, err)
`toDecimal(binaryStr)`	Convertir du binaire en décimal	number \| (nil, err)

Exemple d’utilisation

-- Convertir du décimal en binaire
local binary = toFixedLengthBinary(10, 8)
Logger.warn(binary)  -- "00001010"

-- Convertir du binaire en décimal
local decimal = toDecimal("00001010")
Logger.warn(decimal)  -- 10

Exemples complets

Script de surveillance d’équipements

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

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

-- Obtenir les dernières données de l’équipement
local temperature = getLatestDataValue("device1.temperature")
local humidity = getLatestDataValue("device1.humidity")

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

-- Évaluer l’alarme de température
if temperature > 80 then
    local alarm = buildCommonAlarmMap("TEMP_HIGH", "温度超过80°C")
    Logger.error("温度告警: " .. JSON.toJSONString(alarm))
end

-- Consulter l’historique
local now = OffsetDateTime.now()
local startTime = now:addHours(-24)
local history = getHistoryData(
    "device1",
    "temperature",
    startTime:toString(),
    now:toString()
)

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

-- Calculer la moyenne
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 traitement des données

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

-- Lire la configuration depuis le cache
local configJson = getShareCache("device_config")
local config = JSON.decode(configJson)

-- Filtrer les équipements activés
local enabledDevices = TableUtils.filter(config.devices, function(device, index)
    return device.enabled == true
end)

-- Extraire les noms des équipements
local deviceNames = TableUtils.map(enabledDevices, function(device, index)
    return device.name
end)

-- Nettoyer les données
local cleanedNames = TableUtils.map(deviceNames, function(name, index)
    -- Supprimer les espaces et convertir en majuscules
    return String.upper(String.trim(name))
end)

-- Valider le format du numéro d’équipement
for i, device in ipairs(enabledDevices) do
    if not Regex.match(device.id, "^DEV\\d{6}$") then
        Logger.warnf("设备编号格式错误: %s", device.id)
    end
end

-- Afficher le résultat
Logger.info("处理完成: " .. JSON.toJSONString(cleanedNames))

Points d’attention

Gestion des erreurs : la plupart des fonctions retournent (result, error) ; vérifiez les erreurs.
Format temporel : les chaînes utilisent ISO 8601.
Expressions régulières : la syntaxe est celle de Go, différente des patterns natifs Lua.
Parcours des tables : map/filter/reduce de TableUtils parcourent d’abord la partie tableau, 1..n, puis les paires clé-valeur.
Niveau des journaux : la configuration système détermine le niveau de Logger.
Performances JSON : le runtime utilise un traitement JSON performant, adapté à la sérialisation en masse.

Vérifier si un point possède une valeur

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

Étapes suivantes

Présentation du moteur et exemples de points agrégés : Moteur d’expressions.
Organisation des scripts de conditions et d’actions : Plans de déclenchement.
Manuel détaillé des actions d’écriture EXPRESSION : Scripts de plans EXPRESSION.
Manuel détaillé des scripts MQTT : Publication et abonnement MQTT.