跳到主要内容

Lua 脚本

Lua 脚本模块为 CycBox 中的自定义消息处理提供了一个强大的、沙盒化的脚本运行环境。它支持对传入消息进行实时转换、解析和分析，而无需编译插件。

主要特性：

  • 钩子函数：在管道的不同阶段拦截消息
  • 多连接支持：单个 Lua 实例处理来自所有连接的消息
  • 消息路由：在连接之间动态路由消息
  • 丰富的 API：HTTP 客户端、数据库连接、协议助手等

架构​

多连接支持：CycBox 运行一个单一的共享 Lua 任务，处理来自所有连接的消息。这在保持资源效率的同时，实现了强大的跨连接编排。

┌────────────────────────────────────────────────────────────────┐
│           连接 0                      连接 1                    │
│  ┌─────────┐ ┌──────────┐    ┌─────────┐ ┌──────────┐          │
│  │  传输层  │ │  处理器   │    │  传输层  │ │  处理器   │          │
│  └────┬────┘ └────┬─────┘    └────┬────┘ └────┬─────┘          │
│       │           │               │           │                │
│       └─────┬─────┘               └─────┬─────┘                │
│             │                           │                      │
│             └─────────────┬─────────────┘                      │
│                           ▼                                    │
│              ┌─────────────────────────┐                       │
│              │     共享 Lua 任务        │ ← 单个 Lua 实例         │
│              │  - on_receive()         │                       │
│              │  - on_send()            │                       │
│              │  - on_send_confirm()    │                       │
│              │  - on_timer()           │                       │
│              └───────────┬─────────────┘                       │
│                          ▼                                     │
│                        用户界面                                 │
└────────────────────────────────────────────────────────────────┘

接收路径 (RX Path):
传输层 → [编解码器解码] → [转换器] → [格式化] → Lua [on_receive] → 用户界面

发送路径 (TX Path):
用户界面 → Lua [on_send] → [转换器] → [编解码器编码] → 传输层
                                            ↓
                                         [格式化] → Lua [on_send_confirm] → 用户界面

定时器 (Timer):
每 100ms → [on_timer - 全局]

关键特性：

  • 连接 ID 追踪：每条消息都包含一个 connection_id 字段，用于标识其源/目标连接。
  • 全局定时器：on_timer() 每 100ms 全局运行一次（而非每个连接运行一次）。

脚本可以实现钩子函数的任意组合，以在不同阶段拦截和修改消息。全局 message 对象在钩子中可用，用于读取和修改消息数据。

快速入门​

一个最小的 Lua 脚本实现一个或多个可选的钩子函数：

-- 在启动时调用一次 - 初始化状态
function on_start()
    log("info", "脚本已初始化，当前共有 " .. get_connection_count() .. " 个连接")
end

-- 为每条接收到的消息调用 - 解析并提取数据
function on_receive()
    local payload = message.payload
    -- 解析负载并提取数值
    message.add_int_value("temperature", parse_temp(payload))
    return true  -- 如果消息被修改，返回 true
end

-- 为每条发送的消息调用 - 在发送前修改
function on_send()
    -- 修改负载或路由到不同的连接
    return false  -- 如果消息未改变，返回 false
end

-- 每 100ms 调用一次 - 周期性任务
function on_timer(elapsed_ms)
    -- 安排周期性操作
end

-- 在关闭时调用 - 清理资源
function on_stop()
    log("info", "脚本正在关闭")
end

关键点：

  • 所有钩子都是可选的 - 只实现你需要的即可。
  • 消息钩子如果修改了消息必须返回 true，否则返回 false。
  • 全局 message 对象提供对负载、数值和 connection_id 的访问。