Skip to main content

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(timestamp_ms)​

每 100ms 调用一次。timestamp_ms 是当前 Unix 时间戳（毫秒）。

on_stop()​

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

处理流程管道​

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

消息对象 (Message Object)​

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

属性​

属性类型访问权限描述
payload字符串 (字节数组)读/写移除协议帧后的纯数据内容。设置为 nil 会清空内容。
frame字符串 (字节数组)读/写包含所有协议开销的完整线缆格式。设置为 nil 会清空内容。
timestamp整数 (u64)读/写自 UNIX 纪元以来的微秒数。
checksum_valid布尔值只读帧校验和是否有效。如果不存在校验和元数据，则默认为 true。
connection_id整数 (u32)读/写源/目标连接（从 0 开始的配置索引）。
message_type字符串读/写消息类型："rx"、"tx"、"log"、"event"、"request" 或 "response"。
payload_type字符串只读载荷类型："binary"、"text"、"mqtt"、"websocket_binary"、"websocket_text" 等。
highlighted布尔值读/写消息是否在 UI 中高亮显示。
display_hex布尔值读/写消息是否在 UI 中显示十六进制转储视图。
values_json字符串 (JSON)只读以 JSON 格式显示的所有消息值。数组显示为 null（暂不支持）。
  • payload 是您在 on_receive() 中解析以及在 on_send() 中构建的内容。协议头、校验和和分隔符已被剥离。
  • frame 是线路上的原始字节，包括所有协议开销。

方法​

添加值​

方法参数描述
add_int_value(id, value [, timestamp_us])id: 字符串, value: 整数, timestamp_us: 整数（可选，自纪元起的微秒数）添加一个 64 位有符号整数值。若省略 timestamp_us，则使用消息时间戳。
add_float_value(id, value [, timestamp_us])id: 字符串, value: 数值, timestamp_us: 整数（可选，自纪元起的微秒数）添加一个 64 位浮点数值。若省略 timestamp_us，则使用消息时间戳。
add_string_value(id, value [, timestamp_us])id: 字符串, value: 字符串, timestamp_us: 整数（可选，自纪元起的微秒数）添加一个字符串值。若省略 timestamp_us，则使用消息时间戳。
add_bool_value(id, value [, timestamp_us])id: 字符串, value: 布尔值, timestamp_us: 整数（可选，自纪元起的微秒数）添加一个布尔值。遵循 Lua 真值规则：仅 nil 和 false 为假值。

查询值​

方法参数描述
get_value(id)id: 字符串或 nil返回原始类型的值，如果未找到则返回 nil。整数/浮点值可以在 UI 图表中可视化。
get_metadata(id)id: 字符串或 nil按 id 返回元数据值（如 MQTT topic、QoS），如果未找到则返回 nil。
has_value(id)id: 字符串如果存在指定 id 的值则返回 true，否则返回 false。
value_ids()无返回包含所有值 id 字符串的表（数组）。

删除值​

方法参数描述
remove_value(id)id: 字符串删除所有指定 id 的值。如果有值被删除则返回 true。
clear_values()无删除消息中的所有值。

全局函数​

连接查询​

函数参数返回值
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)