第五章 Lua 脚本编程

适用版本：ApusTAI 1.0.27　更新日期：2026-10-09

Lua 脚本用于处理工程业务逻辑，例如读写变量、解析自定义串口报文、定时任务和数据记录。脚本通过系统回调运行；通常不需要自己编写常驻主循环。

从这里开始

文档	主要内容
系统回调函数	初始化、周期运行、触摸、切页、变量更新、控件事件与完整 main.lua 示例
寄存器操作函数	位、数值、字符串、数组、从站选择、预读和自动上传开关
自由协议串口函数	串口参数设置、双串口收发、拆包、粘包与模拟器副屏日志
定时器函数	周期任务、单次延时、有限次数任务、停止与重设
其他接口函数	日期时间、运行计时、音频、设备 UUID、页面查询与 EasyDB
Modbus 脚本读写示例	四区单点与整组、字内位、功能码、批量读写、变量轮询和双从站完整示例

1. 工程脚本的运行方式

将业务脚本保存为工程的 main.lua，随工程一起导出和下载。修改脚本后重新导出工程资源，再在模拟器或屏端加载相同工程。检查运行日志中的脚本加载结果，确保不是在观察旧版本脚本。

系统先注册 Lua 接口并执行脚本顶层代码，再调用 on_init()，随后创建启动页面。初始化变量、预读和定时器可放在 on_init()；页面与控件相关操作要等目标页面已经创建。

所有回调都应使用全局函数名称，例如 function on_timer(timer_id)。只定义需要的回调，同名回调保留一份，并把不同业务合并到各自分支。

2. 最小可运行示例

下面每秒更新一次 LW1014。将数值控件绑定到 LW 地址 0x1014，即可观察计数变化；示例不用控件设置接口。

local LW = 1
local COUNTER_ADDR = 0x1014
local TIMER_COUNTER = 1

function on_init()
    set_uint16(LW, COUNTER_ADDR, 0)
    start_timer(TIMER_COUNTER, 1000, 0, 0)
end

function on_timer(timer_id)
    if timer_id == TIMER_COUNTER then
        local value = get_uint16(LW, COUNTER_ADDR)
        set_uint16(LW, COUNTER_ADDR, (value + 1) % 65536)
    end
end

确认示例地址没有被其他业务使用；发生冲突时更换地址并同步修改绑定。LW 不是预设常量，所以示例首先定义 local LW = 1。

3. 本章示例用到的 Lua 语法

写法	含义
local value = 9	定义局部变量
0x1014	十六进制整数地址；不要省略 0x
if condition then ... end	条件判断，嵌套块使用 4 个空格缩进
for i = 1, 3 do ... end	有限次数循环
{0xA5, 0x5A, 0x00}	Lua 表；原生数组接口通常使用从 1 开始的连续下标
#packet	字符串的字节数或连续表的长度
a == b / a ~= b	相等 / 不相等；赋值使用 =
a .. b	拼接字符串
-- 注释	单行注释

接口名称区分大小写。颜色、地址、数据值与控件 ID 各有不同范围，按各接口表填写；参数不能凭名称推测。当前工程 Lua 使用 32 位整数和单精度浮点数，大整数、64 位数据与双精度读写的实际限制见寄存器页面。

set_* 等多数接口正常调用没有返回值，不能用 == 0 判断成功。uart_send() 和 EasyDB 等有返回结果的接口，按对应文档检查。需要捕获抛出的 Lua 错误时：

local ok, err = pcall(set_uint16, 1, 0x1014, 9)
if not ok then
    print("write failed", err)
end

4. 通信和调度要点

主站寄存器读取来自缓存，get_*() 不同步等待 PLC 应答。按需用 start_read() 登记预读范围，并通过 on_update() 处理有效更新。脚本写入正常返回，也不能替代设备应答确认。

串口接收是字节流，一次 on_uart_recv() 不一定等于一帧。发送二进制使用字节表或 string.char()；字符串 "A5 5A" 发送的是字符，不能当成十六进制字节。

回调运行在界面业务循环中。不要使用无限循环、阻塞等待或长时间计算；延时使用 start_timer()，分阶段工作保存状态后等待下一次回调。get_timestamp() 返回运行毫秒计数，日期时间请使用 RTC 功能。

5. 排查顺序

1. 检查脚本是否随最新工程导出，查看加载或语法错误日志。
2. 检查回调是否全局声明、名称正确、没有同名覆盖。
3. 检查变量类型、十六进制地址、从站索引与实际配置。
4. 检查参数类型、数量、范围和接口返回规则。
5. 涉及串口时核对工程通信参数、完整报文和对端应答。

新版运行库已实现 uart_setup()：通道 0/1 修改组态协议与 Lua 共用的工程通信口，通道 3 配置独立第二串口。工程配置决定初始参数，脚本修改运行参数不会改写工程文件；接收回调通道固定为 0/3。使用前需更新屏端固件或模拟器，详见自由协议串口函数。

set_notify(0/1) 只关闭或恢复 DCBUS/DGUS 自动上传，不停止 PLC 主站轮询、外部寄存器写入、主动 uart_send() 或串口下载。要暂停脚本连续写入，应停止对应定时器或在业务回调中增加开关，详见寄存器操作函数和定时器函数。

模拟器的 Lua print()、脚本加载/运行错误及未捕获的回调异常显示在串口副屏“运行日志”，无需连接 COM，不作为串口数据发送。每篇接口文档列出支持范围与常见错误，使用前先查对应说明。