更新记录

1.0.0（2026-07-19）

新增 RTU-over-TCP 传输 + 多从站巡检 + 断开语义更名。

• RTU-over-TCP 传输：connectModbusRtuOverTcp({ host, port?, unitId?, timeoutMs? }) —— 以 Modbus RTU 帧（含 CRC16 校验）经 TCP 传输建立连接，面向串口服务器 / 协议网关（区别于 Modbus TCP 的 MBAP 帧）。CRC16 自动编解码，坏帧 / 半包按异常返回、不崩宿主；返回与 Modbus TCP 相同的 ModbusClient 对象，建连后所有读写方法一致工作。
• 多从站切换：ModbusClient.setSlave(unitId) —— 不重连即切换后续请求的目标从站，支撑一条连接轮询多个从站。
• 多从站批量读：ModbusClient.readHoldingRegistersMulti(unitIds[], address, quantity) —— 一次调用对多个从站读同一寄存器区块，逐从站返回结果（{ unitId, ok, values, error }）；单个从站超时 / 异常不拖垮整批，失败项带错误标记、其余正常返回（SCADA 定时巡检刚需）。
• 断开语义更名：`ModbusClient.cl

平台兼容性

uni-app x(5.14)

nex-modbus

自研高性能 Modbus 工业协议主站核心（Modbus TCP + RTU-over-TCP 两种传输），提供 uni-app 可调的异步 JS API。面向工厂安卓平板控制屏：连 PLC / 传感器 / 串口服务器，读写寄存器 / 线圈，多从站巡检，并按寄存器表做字序 / 类型解码 → 干净 JSON。

仅 App 端（Android / iOS）：依赖原生库，H5 / 小程序加载不了（浏览器无原生 TCP，无法直连设备）。Android 需 android.permission.INTERNET。 连接是有状态对象 ModbusClient（TCP 与 RTU-over-TCP 共用同一对象）；全部读写 API 均为异步 Promise，后台执行、不卡 UI。

API

• connectModbusTcp({ host, port?, unitId?, timeoutMs? }): Promise<ModbusClient> —— 建 Modbus TCP 连接（默认 port 502 / unitId 1 / timeout 3000ms）
• connectModbusRtuOverTcp({ host, port?, unitId?, timeoutMs? }): Promise<ModbusClient> —— 建 RTU-over-TCP 连接（RTU 帧含 CRC16 经 TCP，面向串口服务器 / 协议网关；入参同上）
• ModbusClient：
  • 读：readHoldingRegisters(addr, qty) / readInputRegisters → number[]；readCoils / readDiscreteInputs → boolean[]
  • 写：writeSingleRegister(addr, value) / writeMultipleRegisters(addr, values[]) / writeSingleCoil(addr, on) / writeMultipleCoils(addr, on[])
  • 多从站：setSlave(unitId)（切从站不重连）/ readHoldingRegistersMulti(unitIds[], addr, qty)（一次巡检多从站，单从站异常不拖垮整批）
  • 转换：readMap(fields) → 按寄存器表解码的 JSON 对象
  • 生命周期：isConnected() / disconnect()

寄存器表解码（readMap 护城河）

fields 每项 { name, address, type, wordOrder?, length?, scale?, offset?, source? }：

• type：int16/uint16/int32/uint32/int64/uint64/float32/float64/string
• wordOrder：ABCD(大端,默认) / CDAB(字交换) / BADC(字节交换) / DCBA(全反序)
• scale/offset：输出 raw*scale+offset（工程量纲）；source：holding(默认) / input

最小用例

import { connectModbusTcp } from '@/uni_modules/nex-modbus';

const client = await connectModbusTcp({ host: '192.168.1.10', port: 502, unitId: 1 });
const data = await client.readMap([
  { name: 'temp', address: 0, type: 'int16', scale: 0.1 },
  { name: 'power', address: 10, type: 'uint32', wordOrder: 'CDAB' },
]);
console.log(data); // { temp: 25.0, power: 123456 }
client.disconnect();

多从站巡检（一条连接轮询多个从站，单从站离线不影响其余）：

import { connectModbusRtuOverTcp } from '@/uni_modules/nex-modbus';

// RTU-over-TCP 网关，一条连接读 1/2/3 号从站的 0..2 保持寄存器
const gw = await connectModbusRtuOverTcp({ host: '192.168.1.20', port: 502 });
const results = await gw.readHoldingRegistersMulti([1, 2, 3], 0, 2);
results.forEach(r => {
  if (r.ok) console.log(`从站 ${r.unitId}:`, r.values);
  else console.warn(`从站 ${r.unitId} 失败:`, r.error);
});
gw.disconnect();

错误（reject 的 Error）

ConnectFailed / Timeout / ConnectionLost / ModbusException(从站异常码) / InvalidParam(越界) / Decode。

当前状态：协议核心已通过模拟从站集成测试全量验证；App 真机端到端验证持续完善中。