更新记录

0.1.0（2026-08-02）

首次发布：支持 Android 端 Modbus TCP 长连接、FC03 读取保持寄存器、FC06 写单寄存器，以及常用 16/32 位整数和 float32 字节序解码。

平台兼容性

uni-app x(5.15)

Modbus TCP 轻量客户端

面向 uni-app x Android 的 UTS API 插件。当前版本只承诺单连接下的 FC03 和 FC06，不包含 iOS、串口 RTU、自动重连或厂商私有协议。

• 最低 HBuilderX：5.15。
• 最低 Android：5.0（API 21）。
• 系统权限：android.permission.INTERNET，仅用于连接调用方填写的 Modbus TCP 地址。
• 数据声明：插件不采集、上传或保存业务数据，也不接入广告或第三方统计 SDK。

快速使用

import {
  connect,
  disconnect,
  readHoldingRegisters,
  writeSingleRegister
} from '@/uni_modules/wzx-modbustcp'

connect({
  host: '192.168.1.20',
  port: 502,
  success: () => {
    readHoldingRegisters({
      unitId: 1,
      address: 0,
      quantity: 2,
      success: (res) => console.log(res.registers)
    })
  }
})

地址使用 Modbus 报文中的零基地址。设备手册若写 40001，通常应传 0；不同厂商可能另有约定，请以设备文档为准。

当前 API

• connect：建立一个 TCP 长连接，可配置连接和请求超时。
• disconnect：关闭当前连接。
• isConnected：检查本地 Socket 状态；不等同于远端设备健康检查。
• readHoldingRegisters：FC03，单次读取 1–125 个保持寄存器。
• writeSingleRegister：FC06，写一个保持寄存器并校验设备回显。
• decodeUint16 / decodeInt16。
• decodeUint32 / decodeInt32 / decodeFloat32，支持 ABCD、BADC、CDAB、DCBA。

已知边界

• 同一连接一次只执行一个请求；并发调用会返回 1006。
• 网络或协议异常后会关闭连接，调用方需要重新连接。
• 错误码 1001 参数错误、1002 未连接、1003 网络错误、1004 协议校验失败、1005 Modbus 异常响应、1006 忙。
• 本地协议测试和 Android 编译通过不能替代目标 PLC/网关真机测试。

已完成验证

• HBuilderX 5.15 Android class 编译通过。
• Android 15 模拟器连接本地模拟从站，完成 FC03 读取、FC06 写入和再次 FC03 回读。
• 实体 Android 手机和真实 PLC/网关兼容性尚未验证；购买前请先使用试用版连接自己的设备。