Modbus TCP 驱动功能设计

Modbus TCP 驱动是 EasyPro 智慧楼宇管控平台用于接入 Modbus 协议设备的协议驱动。Modbus 是工业自动化领域应用最广泛的通信协议之一，几乎所有主流 PLC、变频器、仪表、网关都支持它。

平台作为 Modbus 主站（Master），主动轮询一个或多个 从站（Slave）设备，读取传感器数据、下发控制指令。一个驱动实例对应一台从站设备（由 IP + 端口 + 从站号三元组唯一确定）。

Modbus 是单主多从架构。主站逐一向每个从站发起请求，从站被动应答。同一时刻主站只与一个从站通信。

Modbus 设备的数据按 寄存器类型 组织，每种类型有不同的读写权限和对应的功能码。这是理解点位配置的基础：

每个寄存器在设备内有唯一 地址（address）。平台从 0 起按寄存器偏移寻址（PLC-zero 寻址）。例如保持寄存器地址 10 对应设备手册上常见的 40011（40001 + 10）。

对于 32 位整数、浮点数等跨多寄存器的数据类型（占 2 个 16 位寄存器），还需指定 字节序（dataOffSet） 说明高低字节的排列顺序，否则不同厂商设备会解析出错误数值。

Modbus 是纯请求-响应协议，设备不会主动上报。因此驱动必须 周期性轮询 每个点位。这与 MQTT/KNX 等「事件驱动」驱动形成鲜明对比：

驱动为每个实例维护独立的 ModbusMaster 连接。建连由专门的 initThread 完成，连接失败按 retryInterval 间隔持续重试，直到成功。建连前会做一次端口可达性预检（isPortOpen），避免长时间阻塞。

ModbusAliveTask 每 5 秒触发一次 checkDriverInstanceAlive()，这是驱动的「主 reconciler」循环。它会：

• 遍历所有「已打开」的驱动实例
• 为每个实例创建或复用 ModbusTcpServer
• 离线的实例触发重连；配置变更的实例重建连接
• 调用 server.startRead() 拉起（每实例一个）虚拟线程读循环

读循环会先把一个实例下的所有点位按寄存器类型分组，组内按地址排序，再把地址连续或接近的点位打包成一次读请求（一个 packet），从而最小化网络往返。拆包规则由两个参数控制：

读回的原始字节按点位的 dataType 解析为平台类型。跨寄存器类型（int32/float 占 2 个寄存器）的字节序由 dataOffSet 决定：

写保持寄存器有两种功能码可选：

由 writeRegisterWithFallback 实现，区分两种失败场景，仅在 writeCodeSwitchMode=auto 时触发降级：

线圈点位（1 位开关量）的写不经过回退逻辑，直接用 0x0F（写多个线圈）批量下发。

每个 Modbus 驱动实例由以下属性配置，存储于 iot_driver_attribute。来源：ModbusTcpDriverInstance 实体 + BuildBean.buildDriverInstance 字段映射。

每个 Modbus 点位由以下属性定义，存储于 iot_driver_point_attribute。其中数据类型、偏移、位长度的可选项随上一级联动：

选择上一级后，下一级的可选值会动态收窄。这保证了点位配置在协议层面的合法性。

点位在实例内的唯一标识由以下公式生成（BuildBean.getPointUniqueCode）：

# 基础四元组
registerType && address && dataType && dataOffSet

# 若 bitLength 非空，追加
registerType && address && dataType && dataOffSet && bitLength

例如：保持寄存器&&10&&float&&3210。批量校验时按此五元组去重。

Modbus 驱动不对外暴露任何 HTTP 接口：getHttpApiCallBackList() 返回 List.of()。所有数据采集与控制都通过定时任务和平台的点位下发机制完成。

多字节值（int32/float）的字节排列顺序由 dataOffSet/databits 决定，覆盖四种常见端序：