Message API
Message 对象是 CycBox Lua 脚本系统中的中心数据结构。它代表流经系统的通信消息，包含原始数据、解析值、显示格式和元数据。
概述
CycBox 消息处理流程：
接收: 传输层 → 编解码器 → 转换器 → Lua 脚本 → UI
发送: UI → Lua 脚本 → 转换器 → 编解码器 → 传输层
在 Lua 脚本中，你可以：
- 读取和修改消息的数据载荷与数据帧
- 根据消息结构提取类型化数据
- 访问消息元数据（时间戳、连接 ID）
- 转换消息体提取自定义值用于数据可视化
属性
payload
local data = message.payload -- 获取payload（Lua 字符串）
message.payload = "\\x01\\x02\\x03" -- 设置payload
message.payload = nil -- 设置为空字节
消息 payload - 移除协议帧后的实际数据内容。
- 类型: Lua 字符串（字节数组）
- 访问: 读/写
- Nil 安全: 设置为
nil清空负载（空字节）
frame
local full_frame = message.frame -- 获取完整帧
message.frame = "[STX]data[ETX]" -- 设置帧
message.frame = nil -- 设置为空字节
完整的协议帧，包括前缀、payload、后缀和校验和。
- 类型: Lua 字符串（字节数组）
- 访问: 读/写
- Nil 安全: 设置为
nil清空帧（空字节）
timestamp
local ts = message.timestamp -- 获取时间戳（微秒）
消息时间戳，单位为微秒（自 UNIX 纪元起）。
- 类型: 整数 (u64)
- 访问: 只读
connection_id
local conn_id = message.connection_id -- 获取连接 ID
message.connection_id = 1 -- 设置连接 ID
标识源/目标连接（配置索引）。
- 类型: 整数 (u32)
- 访问: 读/写
values_json
local json_str = message.values_json -- 获取所有值的 JSON 字符串
-- 示例: '{\"temperature\":25.5,\"humidity\":60,\"status\":\"ok\"}'
返回消息的所有值作为 JSON 字符串，方便检查或日志记录。
- 类型: 字符串（JSON 格式）
- 访问: 只读
- 注意: 数组类型暂不支持，将显示为
null
方法
add_int_value()
message:add_int_value(id, value)
添加整数值到消息。以 64 位有符号整数 (Int64) 存储，将通过数值界面展示。
参数:
id(字符串，必需): 值的唯一标识符（例如"temperature"、"counter"）value(整数，必需): 要存储的整数值
示例:
message:add_int_value("device_id", 1001)
message:add_int_value("counter", 42)
add_float_value()
message:add_float_value(id, value)
添加浮点值到消息。以 64 位浮点数 (Float64) 存储。
参数:
id(字符串，必需): 值的唯一标识符value(数字，必需): 要存储的浮点值
示例:
message:add_float_value("temperature", 25.5)
message:add_float_value("voltage", 3.3)
message:add_float_value("humidity", 60.2)
add_string_value()
message:add_string_value(id, value)
添加字符串值到消息。
参数:
id(字符串，必需): 值的唯一标识符value(字符串，必需): 要存储的字符串值
示例:
message:add_string_value("status", "OK")
message:add_string_value("device_name", "Sensor-01")
add_bool_value()
message:add_bool_value(id, value)
添加布尔值到消息。
参数:
id(字符串，必需): 值的唯一标识符value(布尔值，必需): 要存储的布尔值
示例:
message:add_bool_value("is_active", true)
message:add_bool_value("alarm", false)
get_value()
local value = message:get_value(id)
按 ID 检索值。返回原始类型的值或 nil（若未找到）。
参数:
id(字符串或 nil): 值的标识符
返回:
- 整数: 对于 Int8、Int16、Int32、Int64、UInt8、UInt16、UInt32
- 数字: 对于 UInt64（如果 > Int64 最大值）、Float32、Float64
- 布尔值: 对于布尔值
- 字符串: 对于字符串值
- nil: 如果 ID 为 nil、未找到值或数组类型（暂不支持）
值的存储和可视化
添加到消息的值具有以下特性：
- 有时间戳: 每个值都包含消息时间戳
- 有类型: 保持原始数据类型（整数、浮点、字符串、布尔）
- 可视化: 整数和浮点值可以在 UI 中的图表上绘制
- 缓冲: 最近的值保存在内存中用于实时监控
注意事项
- Nil 安全:
payload、frame和get_value()能够优雅地处理nil - ID 格式: 值 ID 应该是描述性的（例如"temperature"、"device:sensor1"）
- 类型一致性: 在消息中为同一值 ID 使用一致的类型
- 性能: 每条消息添加多个值是高效的；值的存储是紧凑的
- 数组类型: 数组值类型（Int8Array、Float32Array 等）在 Lua API 中暂不支持