内容目录
本文目录
- 1. 一、核心通信 API
- 2. 1.1 start_read —— 后台自动轮询（最常用）
- 3. 1.2 其它管理函数
- 4. 1.3 select_slave —— 切换从站（关键）
- 5. 二、LUA 读寄存器（带在线判断）
- 6. 三、LUA 写寄存器
- 7. 四、批量写线圈（0x0F 封装）
前面讲了屏在工程里配 Modbus 主从，但碰到”一主多从 + 复杂逻辑”（比如读两个从机的电量求和、按条件写寄存器、批量写线圈），光靠画面绑变量不够，得用 LUA 脚本接管通信。这篇把 Modbus 相关的 LUA API 讲透，代码都是大彩文档里的真实例程，我加了工程师视角的注解和踩坑提示。
⚠️ 适用范围： HMI&M&Dx 系列。示例是 Modbus 两个从站，站号 10 和 20，逻辑对 FX2N/FX3U 主从同样适用。
一、核心通信 API
1.1 start_read —— 后台自动轮询（最常用）
主机模式下周期性读从机寄存器的调度函数。调用后系统把它加进通信队列，每个周期自动发请求，返回数据写进 HMI 内存镜像，你用 get_uint16/get_float 直接读缓存，没有通信延迟。
start_read(index, vtype, addr, quantity, cycle, cycle_run, mode)| 参数 | 类型 | 说明 |
|---|---|---|
| index | number | 任务索引 0~127，stop_read 时用 |
| vtype | number | 数据类型 VT_3x / VT_4x 等 |
| addr | number | 寄存器地址 |
| quantity | number | 读取数量 1~120 |
| cycle | number | 轮询周期倍数，0=每周期都读 |
| cycle_run | number | 周期内第几次执行（0-based，需 < cycle） |
| mode | number | 0=持续读(默认) / 1=仅读一次 |
💡 调度精髓： cycle/cycle_run 用来分高低频。高频变量（速度、温度）cycle=0 每周期读；低频变量（累计量、状态字）cycle=5, cycle_run=4 每 5 周期读一次，降总线负载。例：
start_read(0, VT_4x, 0x1000, 10) → 每周期读 4×1000~1009start_read(1, VT_4x, 0x2000, 10, 3, 2) → 每 3 周期、第 3 个周期读 4×2000~2009
1.2 其它管理函数
stop_read(index)：停单个轮询任务，缓存保留最后一次值stop_all_read()：一键停全部，适合复位/急停set_auto_read(en)：1=启用画面绑定变量自动读（默认），0=只靠脚本start_read接管，适合高带宽场景去冗余
1.3 select_slave —— 切换从站（关键）
多从机下，select_slave(slave_id) 临时指定后续 get_xxx/set_xxx 访问哪个从机。注意 slave_id 是从机列表下标，不是 Modbus 站号！
| 术语 | 含义 | 示例 |
|---|---|---|
| 从机索引 slave_id | HMI 内部列表下标 0,1,2 | 0 = 第一个从机 |
| Modbus 站号 | 设备物理地址 | 10, 33 |
⚠️ 最容易错的点： slave_id=0 对应站号 10，slave_id=1 对应站号 33，这个映射在工程配置里定。脚本里填错下标就读到别的从机去了，查半天以为是协议问题。
二、LUA 读寄存器（带在线判断）
读之前两件事不能省：判断从机在线 + 选对从站。在线状态存在系统变量 VT_LW 0x01A3 的对应位。
-- 读保持寄存器 4x
function mb_read_reg_03(slave, addr)
local onlineState = get_uint16(VT_LW, 0x01A3) -- 从机在线状态字
if ((onlineState >> slave) & 0x01) == 0x01 then -- 该从机在线
select_slave(slave) -- 切到这个从机
return get_uint16(VT_4x, addr) -- 读缓存
else
return false
end
end
-- 读两个从机电量求和，写回 LW 区
function on_run(screen)
local Energy1 = mb_read_reg_03(0, 0x0000)
local Energy2 = mb_read_reg_03(1, 0x0000)
if Energy1 ~= false and Energy2 ~= false then
set_uint16(VT_LW, 0x1000, Energy1 + Energy2)
end
end三、LUA 写寄存器
-- 写单个保持寄存器 0x06
function mb_write_reg_06(slave, addr, value)
local onlineState = get_uint16(VT_LW, 0x01A3)
if ((onlineState >> slave) & 0x01) == 0x01 then
feed_dog() -- 喂狗，防脚本卡死看门狗复位
select_slave(slave)
set_uint16(VT_4x, addr, value)
return true
else
return false
end
end
⚠️ 重点：写之前务必 feed_dog()。 LUA 脚本跑在屏的实时任务里，长时间不喂狗会被看门狗当死循环干掉，屏重启。凡是循环或耗时逻辑，间隔里加 feed_dog。
一个称重校准的实例（三种校准模式），展示 on_update 回调里根据 LW 变量做分支写：
function on_update(slave, vtype, addr)
if vtype == VT_LW and addr == 0x1004 then
local mode = get_uint16(VT_LW, 0x1003)
if mode == 0 then
mb_write_reg_06(0, 0x1002, 57) -- 零点校准
elseif mode == 1 then
local w = get_uint16(VT_LW, 0x1005) -- 砝码校准
mb_write_reg_06(0, 0x1002, w)
elseif mode == 2 then
local c = get_uint16(VT_LW, 0x1006) -- 实物校准
local s = get_uint16(VT_LW, 0x1007)
if c > 0 and s > 0 then
mb_write_reg_06(0, 0x1002, (s*w)//c)
end
end
end
end四、批量写线圈（0x0F 封装）
VisualHMI 批量写线圈最小单位是 16 位对齐。下面这个函数是大彩封装的（非系统 API，自己写的），演示如何把 14 个线圈值合并写入：
mb_write_coil_15(slave_id, addr, coilsTb)
-- slave_id: 从站索引; addr: 起始地址; coilsTb: 线圈值表
调试提示： 联机验证用 Modbus Slave 软件 + 虚拟串口对，让屏当主机、电脑当从机，实时看总电压/总电量变化。比直接上真机快得多。
本文整理自 广州大彩科技 VisualHMI 开发文档 LUA 教程「Modbus 应用」章节，代码与 API 均按原文保真，版权归大彩科技所有，此处加工程师注解与重点标注，仅供学习参考。
发表回复