用 Lua 实现 Modbus 通信协议:cc-mek-scada SCADA 网络数据通信全解析
用 Lua 实现 Modbus 通信协议:cc-mek-scada SCADA 网络数据通信全解析
cc-mek-scada 是一款运行在 ComputerCraft 上的可配置 SCADA 系统,用于集中控制多台 Mekanism 裂变反应堆,提供图形界面、自动安全保护与废液处理控制。它的核心通信层用纯 Lua 实现了一套 Modbus 协议("Modbus TCP 风格"),让多台虚拟计算机像真实的工业网络一样进行数据通信。本文将从数据模型、功能码、异常处理到实际收发流程,带你完整解析这套 Lua 版 Modbus 通信的实现思路。
📡 为什么选 Modbus?
Modbus 是工业界最经典的通信协议之一,它的精华在于用 4 种数据区 描述一切 I/O:
| 数据区 | 含义 | 特性 | 典型用途(本项目) |
|---|---|---|---|
| Discrete Inputs(离散输入) | 单个位只读 | 数字量输入 | 传感器开关量,如红石信号 |
| Coils(线圈) | 单个位可读可写 | 数字量 I/O | 继电器、阀门启停 |
| Input Registers(输入寄存器) | 多字节只读 | 模拟量输入 | 流速、温度、液位等读数 |
| Holding Registers(保持寄存器) | 多字节可读可写 | 模拟量 I/O | 设定值、控制参数 |
理解这 4 个概念,就理解了 SCADA 系统里"读现场、控设备"的全部数据形态。
🏗️ 分层架构:从网段帧到 Modbus 数据包
项目把网络通信拆成清晰的层次,核心定义在 scada-common/comms.lua 中:
有线调制解调器(modem)
└── SCADA Frame:源地址 / 目的地址 / 序列号 / 协议号 / 载荷
└── MODBUS ADU:txn_id / unit_id / func_code / data
- SCADA 帧层:scada_frame() 负责收发原始帧,携带
src_addr、dest_addr、seq_num(序列号)和protocol(协议号),并支持最大传输距离过滤与 HMAC 认证(防重放攻击)。 - 协议路由:协议号由 PROTOCOL 枚举 定义,
MODBUS_TCP = 0表示"类 Modbus TCP"协议,与 RPLC(反应堆 PLC)、SCADA_MGMT(管理)、SCADA_CRDN(协调)等协议共用同一张网络。 - Modbus 容器:modbus_container() 负责组包(
make)与解包(decode),把{txn_id, unit_id, func_code, ...data}扁平化后装进 SCADA 帧载荷,还原时按PROTOCOL.MODBUS_TCP校验。
这种"帧套包"的结构和真实 TCP 之上的 Modbus/TCP 完全同构,只是把 IP 层换成了 ComputerCraft 的调制解调器。
⚙️ 8 个功能码:一次读懂协议能力边界
Modbus 的"动词"是功能码(Function Code),本项目在 scada-common/types.lua#L503-L514 中完整定义:
| 功能码 | 常量 | 操作对象 |
|---|---|---|
| 0x01 | READ_COILS |
读线圈范围 |
| 0x02 | READ_DISCRETE_INPUTS |
读离散输入范围 |
| 0x03 | READ_MUL_HOLD_REGS |
读保持寄存器范围 |
| 0x04 | READ_INPUT_REGS |
读输入寄存器范围 |
| 0x05 | WRITE_SINGLE_COIL |
写单个线圈 |
| 0x06 | WRITE_SINGLE_HOLD_REG |
写单个保持寄存器 |
| 0x0F | WRITE_MUL_COILS |
写多个线圈 |
| 0x10 | WRITE_MUL_HOLD_REGS |
写多个保持寄存器 |
| 0x80 | ERROR_FLAG |
错误标志位(与功能码异或) |
服务端实现集中在 rtu/modbus.lua:modbus.new(rtu_dev, use_parallel_read) 工厂函数为每个 RTU 设备创建处理器,内部实现了 _1_read_coils 到 _16_write_multiple_holding_registers 八个私有函数。值得注意的两个工程细节:
- 范围校验先行:每次读写都先调用
rtu_dev.io_count()检查地址范围,越界直接返回ILLEGAL_DATA_ADDR; - 并行读取优化:
use_parallel_read = true时用parallel.waitForAll并发发起多地址读取,显著加快大范围批量采集。
🚨 异常码与错误应答:协议健壮性的关键
出错时,Modbus 的标准做法是把功能码的最高位置 1(即 bit.bor(func_code, MODBUS_FCODE.ERROR_FLAG)),再附上异常码。异常码定义见 MODBUS_EXCODE:
| 异常码 | 常量 | 场景 |
|---|---|---|
| 0x01 | ILLEGAL_FUNCTION |
未知功能码 |
| 0x02 | ILLEGAL_DATA_ADDR |
地址越界 / 数量非法 |
| 0x04 | SERVER_DEVICE_FAIL |
底层设备访问失败 |
| 0x06 | SERVER_DEVICE_BUSY |
设备事务队列已满 |
| 0x07 | NEG_ACKNOWLEDGE |
报文长度非法 |
| 0x0A | GATEWAY_PATH_UNAVAILABLE |
单元 ID 不存在(网关路径不可用) |
rtu/modbus.lua 还封装了四个便捷应答工厂(reply__srv_device_fail、reply__srv_device_busy 等),让上层在"队列满、设备忙、单元失联"等场景下一行代码就能回出标准错误帧。
🔁 一次请求的完整旅程
以 rtu/rtu.lua 中 RTU 端收包处理为例,整个链路是:
- 收帧解码:parse_packet() 按协议号把帧解成
modbus_adu; - 序列号检查:比对
seq_num,乱序或来源不明的包直接丢弃(见 handle_packet); - 单元路由:
unit_id就是 Modbus 的"从站地址",一台高级计算机可挂载多个 RTU 单元,靠它区分目标设备; - 同步/异步分流:红石 RTU 立即执行
handle_adu;设备类 RTU 先check_request校验合法性,再压入事务队列——若活跃事务超过 3 个,直接回SERVER_DEVICE_BUSY; - 组帧回复:
send_modbus把应答装回 SCADA 帧,序列号自增后发出。
反过来,监控计算机一侧的请求发起逻辑在 supervisor/session/rtu/txnctrl.lua 与各设备会话中。例如 SNA 设备的 supervisor/session/rtu/sna.lua#L86-L104 就分别用 MODBUS_FCODE.READ_INPUT_REGS 读取建造数据、状态与罐体数据,非常直观。
🔌 硬件如何"接"进寄存器?回调绑定模型
真实 Modbus 从站背后是继电器与 A/D 卡,这里用 回调函数引用 模拟:把 turbine.getFlowRate() 这类函数直接传给寄存器。以 rtu/dev/redstone_rtu.lua 为例:
link_di(side, color)/link_do(side, color):把某面红石信号绑定为离散输入/线圈;connect_input_reg(function() return phy.getAnalogInput(side) end):某次读输入寄存器就是执行这个闭包;connect_holding_reg(...):读写保持寄存器同理。
这种"函数即 I/O"的设计让新增一类设备只需实现一套回调,Modbus 处理层完全不用改——这正是"通用 RTU 接口"的精髓。
🧪 动手验证:跑一遍 Modbus 测试
项目自带完整的协议级测试:test/modbustest.lua 配合 testutils.modbus_tester 可以模拟真实报文,覆盖四类场景:
- 请求预检(
check_request):如非法长度返回NEG_ACKNOWLEDGE、未知功能码 99 返回ILLEGAL_FUNCTION; - 坏请求:越界读
read di {1,10}应得ILLEGAL_DATA_ADDR; - 正常读写:批量读回数据、单点/多点写入;
- 错误帧格式:验证功能码确实被加上
ERROR_FLAG后回显。
测试中构造报文的方式值得新手借鉴——先 pkt_set(功能码, 数据),再断言应答,整个交互过程清晰可见。
📌 总结:这套实现教会我们什么
| 知识点 | 对应源码 |
|---|---|
| 4 种 Modbus 数据区 | README 通信章节 + rtu/modbus.lua |
| 帧/包分层封装 | scada-common/comms.lua |
| 功能码与异常码 | scada-common/types.lua#L503-L530 |
| 服务端应答与错误工厂 | rtu/modbus.lua#L402-L437 |
| 收包路由 / 队列 / 忙应答 | rtu/rtu.lua#L459-L549 |
| 寄存器回调绑定 | rtu/dev/redstone_rtu.lua |
哪怕不用 ComputerCraft,这套代码也是学习 Modbus 的优秀范本:功能码分派、错误帧位标志、事务队列限流、单元路由——工业协议的核心机制全都齐了,而且全部用易读的 Lua 写成。读完 rtu/modbus.lua 这 400 多行,你对 Modbus 的理解就会从"协议表"升级为"实现表"。