更新记录

1.3.13（2026-09-07）

• 修复 Android：init 等成功回调 ClassCast（InitOption 不可强转为 BaseOption；按具体 Option 取 success/fail）
• 须重打自定义基座并云端传统打包；.vue 直接传对象，.uvue 仍须 as XxxOption

1.3.12（2026-09-07）

• 修复 Android：.vue 调用带数字字段与 success/fail 时 ClassCast（对外形参改回 XxxOption，由 JS 桥接正确映射回调）
• uni-app x 调用请对入参使用 as XxxOption；须重打自定义基座并云端传统打包
• 不传参行为与上一版兼容

1.3.11（2026-09-07）

• 修复 Android：带数字参数（如 port/unitId/maxQueue）与 success/fail 同时传入时 ClassCast 崩溃
• 入口透传对象字面量，按键名读取字段与回调；uni-app / uni-app x 均可直接传对象
• 使用须制作自定义基座，并走云端传统打包（不支持离线打包、安心打包）

平台兼容性

uni-app(4.11)

uni-app x(4.11)

breao-modbustcp 使用说明

轻量 Modbus TCP 客户端，适用于工控采集、网关读写下发、多从站巡检，以及经串口服务器的 RTU-over-TCP 场景。

当前版本：1.3.13

• Android / iOS / 鸿蒙：TCP 长连接；FC01～06、FC15、FC16；uni-app 与 uni-app x（含鸿蒙）
• 能力：标准 MBAP 与可选 RTU-over-TCP；忙碌时请求队列与 maxQueue；pollUnits 支持多从站与同一从站多地址批量读写；clearQueue / cancelPending；ABCD/BADC/CDAB/DCBA 四字序数值辅助；异常码中文 errMsg
• 不做微信小程序（无原始 TCP）、不做真串口 / USB-RS485、不做 MQTT 云平台

建议调用顺序：init → connect → 读/写 / pollUnits（可夹数值辅助）→ disconnect / destroy。各异步方法均支持 success / fail / complete；fail 含 errCode / errMsg。插件为单例连接语义：再次 init 会重置配置并断开旧连接。

调用入参：uni-app（.vue）直接传对象；uni-app x（.uvue）须 as XxxOption（见 §5.2、§8）。须 1.3.13+ 自定义基座。

1. 环境要求

• HBuilderX 4.11 及以上
• uni-app Vue3（App-vue / App-nvue）或 uni-app x（App-Android / App-iOS / App-鸿蒙）
• 支持：App-Android、App-iOS、App-鸿蒙（uni-app 与 uni-app x）
• 不支持：H5、微信及其它小程序
• Android 最低 API：21；iOS 最低 12；鸿蒙最低 API：12
• App 真机调试须制作自定义基座；正式发版须购买授权后走云端传统打包
• 授权绑定唯一 appid + 包名

2. 安装与引入

将插件目录放入工程的 uni_modules/breao-modbustcp，或从插件市场导入后同步。

import {
  init,
  connect,
  disconnect,
  destroy,
  getConnectionState,
  clearQueue,
  cancelPending,
  pollUnits,
  readCoils,
  readDiscreteInputs,
  readHoldingRegisters,
  readInputRegisters,
  writeSingleCoil,
  writeSingleRegister,
  writeMultipleCoils,
  writeMultipleRegisters,
  registerToI16,
  i16ToRegister,
  registersToU32BE,
  u32BEToRegisters,
  registersToFloat32BE,
  float32BEToRegisters,
  registersToU32,
  u32ToRegisters,
  registersToFloat32,
  float32ToRegisters,
  setDefaultByteOrder,
  getDefaultByteOrder,
  // 可选：异常码中文与字序规范化
  // exceptionCodeLabel,
  // exceptionErrMsg,
  // normalizeByteOrder,
} from '@/uni_modules/breao-modbustcp'

3. API

3.1 init / connect / destroy

init({
  host: '192.168.1.10',
  port: 502,
  unitId: 1,
  // transport: 'rtu-over-tcp', // 串口服务器时开启；默认 tcp
  // maxQueue: 32, // 忙碌时排队上限；不传=不限制；满队 9050002
  // defaultByteOrder: 'ABCD', // 或 BADC / CDAB / DCBA；BE/LE 为别名
  onConnectionLost(res) { console.log('lost', res) },
  success() {},
  fail(err) { console.error(err.errCode, err.errMsg) },
})

connect({ timeout: 10000, success() {}, fail(err) { console.error(err.errCode, err.errMsg) } })
disconnect({ success() {} })
destroy({ success() {} })

全量 init 参数见 §4。destroy 会取消排队中的请求（fail：插件已销毁）、关闭连接并复位默认字序。

3.2 读（FC01～04）

readCoils({ address: 0, quantity: 8, success(res) { /* res.bits */ } })
readHoldingRegisters({ address: 0, quantity: 4, success(res) { /* res.registers */ } })

3.3 写（FC05 / 06 / 15 / 16）

writeSingleCoil({ address: 0, value: true })
writeSingleRegister({ address: 0, value: 1234 })
writeMultipleCoils({ address: 0, values: [true, false, true] })
writeMultipleRegisters({ address: 0, values: [1, 2, 3] })

读写均可单次覆盖 unitId / timeout。忙碌时自动入队；可用 maxQueue 限制长度。

3.4 多从站 / 同从站多地址巡检 · 清空队列

pollUnits 完整支持在一次调用里按 items 顺序串行调度多条读写：

• 多从站：不同 unitId 混排（经网关访问多台设备）
• 同一从站多地址：相同 unitId、不同 address / op / quantity（本机批量采多段点位）
• 可读写混排；单项失败默认继续（continueOnError: true）

地址连续时，优先用一条更大的 quantity 一次读完；地址不连续或需分段处理时，拆成多条 item 即可。

// 多从站
pollUnits({
  items: [
    { unitId: 1, op: 'readHoldingRegisters', address: 0, quantity: 2 },
    { unitId: 2, op: 'readHoldingRegisters', address: 0, quantity: 2 },
    { unitId: 3, op: 'writeSingleRegister', address: 10, value: 1 },
  ],
  continueOnError: true, // 默认 true；false 时遇错提前结束（仍 success，aborted=true）
  success(res) {
    // res.results: [{ index, unitId, op, ok, address, registers?/bits?/value?/quantity?/errMsg? }, ...]
  },
})

// 同一 Modbus 设备、多地址批量读（unitId 相同，address 不同）
pollUnits({
  items: [
    { unitId: 1, op: 'readHoldingRegisters', address: 0, quantity: 2 },
    { unitId: 1, op: 'readHoldingRegisters', address: 10, quantity: 4 },
    { unitId: 1, op: 'readCoils', address: 100, quantity: 8 },
  ],
  success(res) {
    ;(res.results || []).forEach((row) => {
      if (row.ok) console.log(row.address, row.registers || row.bits)
    })
  },
})

clearQueue({ success(res) { /* res.cleared */ } })
cancelPending({ success(res) { /* 与 clearQueue 相同 */ } })

pollUnits success 字段：

clearQueue / cancelPending success 字段：

clearQueue / cancelPending 只清空等待队列，不影响进行中的请求；被取消项 fail：9050002「队列已清空」。

3.5 状态

getConnectionState({
  success(res) {
    // res.state: idle | connecting | connected | disconnected
  },
})

3.6 辅助函数（同步）

const i16 = registerToI16(regs[0])
const f = registersToFloat32(regs[0], regs[1], 'CDAB') // 四字序
const u = registersToU32(regs[0], regs[1], 'ABCD')
setDefaultByteOrder('BADC')

// 异常码与字序（由 index 导出，无需连接）
const label = exceptionCodeLabel(2) // 如「非法数据地址」
const msg = exceptionErrMsg(2) // 如「从站异常响应：非法数据地址（02）」
const order = normalizeByteOrder('LE') // 规范为 CDAB；BE→ABCD

数值辅助为纯函数，无需连接。defaultByteOrder / setDefaultByteOrder 只影响通用辅助默认字序，不改变原始 registers 回传。历史 registersToFloat32BE / registersToU32BE 仍可用（固定大端）。

4. 可配置项

不传参即用默认值。

4.1 串口服务器（RTU-over-TCP）

当设备侧为 Modbus RTU，中间经以太网串口服务器 / 协议网关透传时：

init({
  host: '192.168.1.50',
  port: 4001, // 串口服务器映射端口，按设备说明填写
  unitId: 1,
  transport: 'rtu-over-tcp',
})

链路仍为 TCP；报文为 [unitId][PDU][CRC16_lo][CRC16_hi]。功能码 API 与 tcp 模式相同。CRC 失败返回 9050012；半包未齐在超时内返回 9050006。不传 transport 或传 tcp 时使用标准 Modbus TCP（MBAP），与 1.0.0 一致。

5. 完整示例

5.1 uni-app（.vue）

直接传对象即可（JS 桥接按 XxxOption 映射回调与数字字段）。

import {
  init,
  connect,
  pollUnits,
  registersToFloat32,
  disconnect,
  destroy,
} from '@/uni_modules/breao-modbustcp'

init({
  host: '192.168.1.10',
  port: 502,
  unitId: 1,
  maxQueue: 64,
  defaultByteOrder: 'ABCD',
  success() {
    connect({
      success() {
        pollUnits({
          items: [
            // 同一从站多地址
            { unitId: 1, op: 'readHoldingRegisters', address: 0, quantity: 2 },
            { unitId: 1, op: 'readHoldingRegisters', address: 10, quantity: 2 },
            // 也可换 unitId 做多从站
            { unitId: 2, op: 'readHoldingRegisters', address: 0, quantity: 2 },
          ],
          success(res) {
            const rows = res.results || []
            rows.forEach((row) => {
              if (row.ok && row.registers && row.registers.length >= 2) {
                console.log(row.unitId, row.address, registersToFloat32(row.registers[0], row.registers[1]))
              }
            })
            disconnect({ success() { destroy({}) } })
          },
        })
      },
    })
  },
  fail(err) { console.error(err.errCode, err.errMsg) },
})

5.2 uni-app x（.uvue）

对象字面量默认为 UTSJSONObject，须在调用处 as XxxOption，否则编译报 error17。嵌套的 connect / pollUnits 同样要断言。

import {
  init,
  connect,
  pollUnits,
  registersToFloat32,
  disconnect,
  destroy,
  ModbusTcpInitOption,
  ModbusTcpConnectOption,
  ModbusTcpPollUnitsOption,
  ModbusTcpDisconnectOption,
  ModbusTcpDestroyOption,
} from '@/uni_modules/breao-modbustcp'

init({
  host: '192.168.1.10',
  port: 502,
  unitId: 1,
  maxQueue: 64,
  defaultByteOrder: 'ABCD',
  success() {
    connect({
      success() {
        pollUnits({
          items: [
            { unitId: 1, op: 'readHoldingRegisters', address: 0, quantity: 2 },
            { unitId: 1, op: 'readHoldingRegisters', address: 10, quantity: 2 },
          ],
          success(res) {
            const rows = res.results || []
            rows.forEach((row) => {
              if (row.ok && row.registers != null && row.registers.length >= 2) {
                console.log(row.unitId, row.address, registersToFloat32(row.registers[0], row.registers[1]))
              }
            })
            disconnect({
              success() {
                destroy({} as ModbusTcpDestroyOption)
              },
            } as ModbusTcpDisconnectOption)
          },
        } as ModbusTcpPollUnitsOption)
      },
    } as ModbusTcpConnectOption)
  },
  fail(err) { console.error(err.errCode, err.errMsg) },
} as ModbusTcpInitOption)

若希望页面少写 as，可在业务层收口（参数类型已是 Option，调用处传对象即可）：

import { init, ModbusTcpInitOption } from '@/uni_modules/breao-modbustcp'

export function initModbus(opt : ModbusTcpInitOption) {
  init(opt)
}

// 页面：initModbus({ host: '...', port: 502, success() {} })

6. 权限

请在应用 manifest / 隐私弹窗中按需声明，并说明用于连接局域网 Modbus TCP 从站读写寄存器。

7. 错误码（905）

从站异常码映射（写入 9050008 的 errMsg）：01 非法功能码；02 非法数据地址；03 非法数据值；04 从站设备故障；05 已确认；06 从站设备忙；07 否定确认；08 存储器奇偶校验错误。

8. 平台注意

• 入参与端： uni-app（.vue）直接传对象；uni-app x（.uvue）每个 API 对象字面量须 as XxxOption（完整示例见 §5.2）。勿把对外形参改成 any 或自行 coerce 重建 Option，Android 易 Integer cannot be cast to Function1。须 1.3.13+ 并重打自定义基座
• 手机与从站须网络可达；经网关时注意 Unit ID 与地址映射
• iOS 须允许本地网络访问，并在 Info.plist 填写用途说明
• 同一 TCP 连接可连续发起读写：忙碌时自动入队；maxQueue>0 时满队返回 9050002；可用 clearQueue / cancelPending 清空等待项
• pollUnits 按 items 串行调度：支持多从站，也支持同一 unitId 下多 address 批量读写；可与其它读写共用同一队列；地址连续时优先单次大 quantity
• addressBase: 1 时传入地址会减 1 后下发，适配部分组态软件习惯
• transport: 'rtu-over-tcp' 仅改组帧方式，不提供真串口；端口以串口服务器配置为准（常见非 502）
• 默认字序仍为大端（ABCD）；勿把历史 BE/LE 业务数据无说明地改为其它四字序
• 从站异常响应 9050008 的 errMsg 已由 exceptionErrMsg 输出中文说明；亦可单独用 exceptionCodeLabel / exceptionErrMsg 解析异常码