跳到主要内容

Lua API 手册

CycBox 运行 Lua 脚本来处理跨连接（串口、TCP、WebSocket、MQTT、UDP）的消息。脚本通过钩子函数（hook functions）和全局 API 与引擎进行交互。

钩子函数 (Hook Functions)​

所有钩子都是可选的。只需实现您需要的部分。

on_start()​

在 Lua 任务启动或重新加载时调用一次，处理任何消息之前执行。

on_receive() → boolean​

针对每条接收到的消息调用（RX 路径）。全局 message 对象包含接收到的数据，connection_id 用于标识来源。

如果消息被修改则返回 true，否则返回 false。

on_send() → boolean​

针对来自 UI 的每条发送消息调用（TX 路径，在编码器之前）。全局 message 对象包含待发送的数据，connection_id 用于控制目的地。

如果消息被修改则返回 true，否则返回 false。

on_send_confirm() → boolean​

在成功发送后调用（TX 确认）。全局 message 对象包含已确认的消息。

如果消息被修改则返回 true，否则返回 false。

on_timer(elapsed_ms)​

每 100ms 调用一次。elapsed_ms 是自 Lua 任务启动以来的毫秒数。

on_stop()​

在引擎停止或脚本热重载之前调用。在热重载时，on_stop() 在旧脚本上运行，然后在新脚本上运行 on_start()。

处理流程管道​

启动:      on_start() → [就绪]
接收 (RX): 传输层 → 解码器 → 转换器 → on_receive() → UI
发送 (TX): UI → on_send() → 转换器 → 编码器 → 传输层 → on_send_confirm() → UI
定时器:    [每 100ms] → on_timer(elapsed_ms)
关闭:      on_stop() → [完成]

消息对象 (Message Object)​

全局 message 对象在 on_receive()、on_send() 和 on_send_confirm() 中可用。

属性​

属性类型访问权限描述
payload字符串 (字节数组)读/写移除协议帧后的纯数据内容。设置为 nil 会清空内容。
frame字符串 (字节数组)读/写包含所有协议开销的完整线缆格式。设置为 nil 会清空内容。
timestamp整数 (u64)只读自 UNIX 纪元以来的微秒数。
connection_id整数 (u32)读/写源/目标连接（从 0 开始的配置索引）。
values_json字符串 (JSON)只读以 JSON 格式显示的所有消息值。数组显示为 null（暂不支持）。
  • payload 是您在 on_receive() 中解析以及在 on_send() 中构建的内容。协议头、校验和和分隔符已被剥离。
  • frame 是线路上的原始字节，包括所有协议开销。

方法​

方法参数描述
add_int_value(id, value)id: 字符串, value: 整数添加一个 64 位有符号整数值。
add_float_value(id, value)id: 字符串, value: 数值添加一个 64 位浮点数值。
add_string_value(id, value)id: 字符串, value: 字符串添加一个字符串值。
add_bool_value(id, value)id: 字符串, value: 布尔值添加一个布尔值。
get_value(id)id: 字符串或 nil返回原始类型的值，如果未找到则返回 nil。整数/浮点值可以在 UI 图表中可视化。

全局函数​

连接查询​

函数参数返回值
get_connection_count()无number — 总活动连接数
get_transport(connection_id)connection_id: 从 0 开始索引string — "serial", "tcp_client", "websocket_client", "mqtt", "udp"
get_codec(connection_id)connection_id: 从 0 开始索引string — "modbus_rtu", "modbus_tcp", "line", "frame", "passthrough"

实用工具​

函数参数返回值
log(level, message)level: "debug"/"info"/"warn"/"error" (默认 "info"); message: 字符串无
get_env(var_name)var_name: 字符串字符串值，如果未设置则为 nil
send_after(payload, delay_ms, connection_id)payload: 二进制字符串 (必填); delay_ms: 数值; connection_id: 从 0 开始索引 (默认 0)成功返回 true，失败返回 false

二进制数据读取函数​

所有读取函数都接受 (payload, offset)，其中 payload 是二进制字符串，offset 是 从 1 开始 的偏移量（Lua 惯例）。

整数读取器​

函数返回值
read_u8(payload, offset)无符号 8 位 (0–255)
read_i8(payload, offset)有符号 8 位 (-128–127)
read_u16_be(payload, offset)无符号 16 位 大端 (Big-endian)
read_u16_le(payload, offset)无符号 16 位 小端 (Little-endian)
read_i16_be(payload, offset)有符号 16 位 大端
read_i16_le(payload, offset)有符号 16 位 小端
read_u32_be(payload, offset)无符号 32 位 大端
read_u32_le(payload, offset)无符号 32 位 小端
read_i32_be(payload, offset)有符号 32 位 大端
read_i32_le(payload, offset)有符号 32 位 小端

浮点数读取器​

函数返回值
read_float_be(payload, offset)32 位浮点数 大端 (IEEE 754)
read_float_le(payload, offset)32 位浮点数 小端 (IEEE 754)
read_double_be(payload, offset)64 位双精度浮点数 大端 (IEEE 754)
read_double_le(payload, offset)64 位双精度浮点数 小端 (IEEE 754)

可用模块辅助函数​

以下模块辅助函数可供使用。

模块描述
modbusModbus RTU/TCP 读写辅助函数和编解码器自动解析值
mqttMQTT 发布辅助函数
udpUDP 数据报发送辅助函数
httpHTTP POST 请求辅助函数
discordDiscord Webhook 消息辅助函数
smtpSMTP 邮件发送辅助函数
ntfyntfy 推送通知辅助函数
influxdbInfluxDB v2/v3 行协议写入辅助函数
redisRedis 连接、get/set/del/exists 辅助函数
timescaledbTimescaleDB/PostgreSQL 连接、execute/insert 辅助函数