更新记录

1.3.3（2026-09-05）

v1.3.3 修复 Android 端云打包编译错误：补齐 Modbus TCP/RTU 的 Promise 链类型标注，修复 USB 串口相关 Number/Int 转换及 okio 依赖配置，确保 TCP、WebSocket、Modbus TCP/RTU、USB 串口硬件通信在 Android 平台正常编译运行。

1.3.2（2026-09-05）

修复 iot-hardware UTS 插件 Android 端编译错误：补齐 Modbus TCP/RTU Promise 链类型标注，修复 USB 串口 Number/Int 转换与 okio 依赖配置，确保 TCP、WebSocket、Modbus、USB 串口硬件通信功能正常编译打包。

1.3.1（2026-09-04）

修复（Android 原生层，对照三方库源码逐项核验）

• 修复 USB 串口流控：UsbSerialPort.FLOWCONTROL_NONE 在 usb-serial-for-android 3.7.3 中不存在，改为占位 0（3.7.3 的 setParameters 无流控参数，需流控请用 setDTR()/setRTS()）
• 修复 USB 串口连接：移除不存在的 UsbSerialDriver.attach(connection) 调用（3.7.3 的 getPorts() 返回端口已绑定连接）
• 修复串口关闭：移除不存在的 driver.close()（usbPort.close() 已一并关闭 UsbDeviceConnection），并置空引用避免悬挂
• 修复 WebSocket 心跳：移除 okhttp 4.12 不存在的 WebSocket.ping() 协议手动 ping，改为 OkHttpClient.Builder.pingInterval() 自动保活（heartbeatInterval > 0 时启用，0 仍表示禁用），读超时兜底检测保留
• 以上修复均不改变 UTS 层 API 签名，现有调用方无需改动

平台兼容性

uni-app(3.8.3)

uni-app x(3.8.4)

iot-hardware

UniApp 硬件通信 UTS 原生插件。提供 TCP 长连接、WebSocket、Modbus TCP / Modbus RTU、USB 转串口 能力，专为工控平板、PDA、物联网设备设计，Android + iOS 双端支持。

特性

• TCP 二进制长连接（子线程非阻塞读写），支持 TLS/SSL 加密
• WebSocket 客户端：文本帧 + 二进制帧收发、okhttp pingInterval 自动保活、断线自动重连（Android 基于 okhttp / iOS 基于 URLSessionWebSocketTask）
• 断线自动重连（指数退避，可设最大次数）
• 心跳保活 + 超时检测 + 读超时（半开连接兜底检测）
• 可配置粘包分包处理器：帧头 / 长度域偏移 / 长度字节数 / 字节序 / 帧格式 / CRC16 校验 均在构造时配置，无需改源码
• Modbus TCP（Promise API）+ Modbus RTU（Android，CRC16 + 静默分帧）
• Modbus 大段自动分片：readHoldingRegisters 等 count > 125 时自动分片串行读取并合并，无需手动拆分
• Modbus 不连续地址读取：readHoldingRegistersAt(addresses) / readInputRegistersAt(addresses) 一次批量读取任意地址组合，返回 [{ address, value }]
• 寄存器转换工具：int16 / uint16 / int32 / uint32 / float32 / int64 / uint64 / float64 ↔ 寄存器数组
• USB 转串口 RS232/RS485/TTL（via usb-serial-for-android），支持流控、DTR/RTS 控制、热插拔监听
• 多连接管理器：统一注册/销毁全部实例，页面卸载 destroyAll() 防线程泄漏
• 多回调监听、状态主动查询、sendAsync() Promise 发送
• 统一错误码（见 错误码表）

环境要求

说明：iOS 原生实现（utssdk/app-ios/SocketClient.swift、WebSocketClient.swift）需在 Mac + HBuilderX 环境下编译验证；Android WebSocket 依赖三方库 okhttp，本地真机运行需在 HBuilderX 配置离线运行环境（含 mavenCentral 依赖缓存），或提交云端打自定义基座。

快速开始

1. 安装

将 iot-hardware 复制到项目 uni_modules/ 目录。

2. 基础 TCP 通信

import { HardwareTcpClient } from '@/uni_modules/iot-hardware'

const client = new HardwareTcpClient({
    host: "192.168.1.100",
    port: 8899,
    reconnect: true,
    reconnectInterval: 3000,
    heartbeatInterval: 5000,
    heartbeatData: HardwareTcpClient.hex2buf("AA BB 00 00")
})

client.onStatus((status) => {
    console.log("连接状态:", status)
})

client.onData((buffer) => {
    const hex = HardwareTcpClient.buf2hex(buffer)
    console.log("收到:", hex)
})

client.onError((msg, code) => {
    console.error("错误:", code, msg)
})

client.connect()

// 发送报文
const buf = HardwareTcpClient.hex2buf("AA BB 00 02 01 02 00 00")
client.send(buf)

// 异步发送（Promise）
await client.sendAsync(buf)

// 页面销毁时
// client.destroy()

3. 对接自定义协议（粘包分包 + CRC 配置）

无需改插件源码，构造时配置帧格式即可：

const client = new HardwareTcpClient({
    host: "192.168.1.100",
    port: 8899,
    packet: {
        enabled: true,            // 启用分包
        header: [0xAA, 0xBB],     // 帧头
        lengthOffset: 2,          // 长度域偏移（帧头后第 0 字节）
        lengthBytes: 2,           // 长度域 2 字节
        lengthEndian: "big",      // 大端
        lengthIncludesHeader: false,
        tailLength: 2,            // 帧尾 2 字节 CRC
        crc: "crc16-modbus",      // CRC16-Modbus 校验
        crcByteOrder: "little"    // CRC 低字节在前
    }
})

固定帧长协议（无长度域）：

packet: {
    frameType: "fixed",
    header: [0x50, 0xFF],     // 三菱 MC 协议示例
    bodyLength: 8,            // 固定数据体长度
    tailLength: 0
}

设 packet: { enabled: false }（或旧参数 disablePacketHandler: true）可关闭分包，直出原始 TCP/UART 流。

4. Modbus TCP

import { ModbusTcpClient } from '@/uni_modules/iot-hardware'

const modbus = new ModbusTcpClient({
    host: "192.168.1.50",
    port: 502,
    unitId: 1,
    responseTimeout: 5000
})

modbus.onStatus((s) => console.log(s))
modbus.connect()

// 读取保持寄存器（Promise API，count > 125 时自动分片串行读取并合并）
const values = await modbus.readHoldingRegisters(0, 10)
console.log("寄存器值:", values)

// 写单个寄存器
await modbus.writeSingleRegister(0, 1234)

// 不连续地址批量读取（自动合并连续段 + 分片），返回 [{ address, value }]
const readings = await modbus.readHoldingRegistersAt([0, 1, 5, 100, 101, 102])
for (const r of readings) {
    console.log("地址", r.address, "=", r.value)
}

// 动态修改从站地址
modbus.setUnitId(2)

// 多连接串行化：serialRequests=true 时同一实例请求严格串行（默认 false 并发）
const modbusSerial = new ModbusTcpClient({
    host: "192.168.1.50", port: 502, unitId: 1, serialRequests: true
})
modbusSerial.connect()

5. Modbus RTU（Android，经 USB 串口）

import { ModbusRtuClient } from '@/uni_modules/iot-hardware'

const rtu = new ModbusRtuClient({
    baudRate: 9600,
    dataBits: 8,
    stopBits: 0,          // 0=1位
    parity: 0,            // 0=无
    unitId: 1,
    responseTimeout: 1000,
    readIdleTime: 30      // 字符间静默间隔 (ms)，默认 30（9600 波特约 3.5 字符时间 ≈ 4ms）
})

rtu.onStatus((s) => console.log("RTU 状态:", s))
rtu.onError((msg, code) => console.error("RTU 错误:", code, msg))
rtu.requestPermission()   // 首次使用需授权
rtu.connect()             // 授权后自动连接，或直接 connect()

const vals = await rtu.readHoldingRegisters(0, 5)
await rtu.writeSingleRegister(0, 100)

6. USB 转串口（Android）

import { HardwareSerialClient } from '@/uni_modules/iot-hardware'

const serial = new HardwareSerialClient({
    baudRate: 9600,
    dataBits: 8,
    vendorId: 0x1A86,  // CH340 示例
    productId: 0x7523
})

const devices = serial.listDevices()
console.log("检测到设备:", devices)

serial.onStatus((s) => console.log("串口状态:", s))
serial.onData((buf) => {
    console.log("串口收到:", HardwareTcpClient.buf2hex(buf))
})
serial.onDeviceChange((attached, vid, pid) => {
    console.log("设备", attached ? "插入" : "拔出", vid, pid)
})

// 首次使用需申请 USB 权限（授权后自动连接）
serial.requestPermission()
serial.connect()
serial.send(new Uint8Array([0xAA, 0xBB, 0x00, 0x01]).buffer as ArrayBuffer)

7. 寄存器转换工具

import { registersToInt16, registersToInt32, registersToFloat32, floatToRegisters, registersToUint64, uint64ToRegisters } from '@/uni_modules/iot-hardware'
const regs = await modbus.readHoldingRegisters(0, 4)
// 前 2 个寄存器为有符号 32 位整数，后 2 个为浮点
const i32 = registersToInt32(regs.slice(0, 2))       // [int32]
const f32 = registersToFloat32(regs.slice(2, 4))     // [float32]

// 写入：把浮点数组转成寄存器再写
const toWrite = floatToRegisters([3.14, -1.5])
await modbus.writeMultipleRegisters(10, toWrite)

// 64 位数值需 4 个寄存器；为避免 BigInt 兼容性问题，以十进制字符串返回/接收
const big = registersToUint64(await modbus.readHoldingRegisters(0, 4))   // ["12345678901234"]
await modbus.writeMultipleRegisters(0, uint64ToRegisters(["12345678901234"]))

8. 多连接管理

import { hardwareManager } from '@/uni_modules/iot-hardware'

const id = hardwareManager.register("plc1", client)  // 注册（id 重复时先销毁旧实例）
// hardwareManager.destroy("plc1")   // 注销并销毁
// hardwareManager.destroyAll()      // 页面卸载：一次性释放全部连接

9. WebSocket 通信

import { HardwareWebSocketClient } from '@/uni_modules/iot-hardware'

const ws = new HardwareWebSocketClient({
    url: "ws://192.168.1.100:8080/ws",
    protocols: ["binary"],                       // 可选：子协议
    headers: new Map([["Authorization", "token"]]), // 可选：握手请求头
    reconnect: true,
    heartbeatInterval: 30000,                    // okhttp pingInterval 自动保活（>0 启用）
    readTimeout: 0                               // 无数据兜底断线（ms），0=禁用
})

ws.onStatus((status) => { console.log("WS 状态:", status) })
ws.onData((data: ArrayBuffer) => { console.log("WS 二进制消息:", HardwareWebSocketClient.buf2hex(data)) })
ws.onText((text: string) => { console.log("WS 文本消息:", text) })
ws.onError((msg, code) => { console.error("WS 错误:", code, msg) })

ws.connect()
ws.sendText("hello")                     // 文本帧
ws.send(HardwareWebSocketClient.hex2buf("AA 01 02 BB"))  // 二进制帧
ws.disconnect()

API 参考

HardwareWebSocketClient

构造参数

方法

HardwareTcpClient

构造参数

方法

onStatus / onData / onError 支持注册多个回调（每次调用追加）；传 null 可清空该类回调。

ModbusTcpClient

构造参数（继承 HardwareTcpClient 参数 +）

方法

Modbus 请求参数有边界校验：位操作 count 范围 1-2000（>2000 抛参错），寄存器单帧 count 范围 1-125，批量写 1-123 个。大段读取（count>125）由 readHoldingRegisters/readInputRegisters 自动分片处理；不连续地址读取自动合并连续地址段并做合法性/去重/升序处理。

ModbusError

Modbus 方法的 Promise 拒绝时抛出 ModbusError：

本地错误码（负数，与 MODBUS_LOCAL_ERR_* 常量等价）：

ModbusRtuClient（Android）

构造参数（继承 HardwareSerialClient 参数 +）

方法

与 ModbusTcpClient 相同（readCoils / readDiscreteInputs / readHoldingRegisters / readInputRegisters / readHoldingRegistersAt / readInputRegistersAt / writeSingleCoil / writeSingleRegister / writeMultipleRegisters / setUnitId），另含串口能力：listDevices() / requestPermission() / connect(index?)。异常同样抛 ModbusError。RTU 请求天然串行（RS485 半双工），大段读取同样自动分片。

HardwareSerialClient（Android）

构造参数

方法

协议工具（跨平台，均可直接 import）

64 位转换避免使用 BigInt 以保证多端兼容：registersToInt64/registersToUint64 返回十进制 string[]，int64ToRegisters/uint64ToRegisters 接收 (string|number)[]；float64 仍为 JS number。

错误码

错误码由 onError(msg, code) 的 code 参数返回，常量定义见 utssdk/unierror.uts。

注意事项

1. 页面卸载（onUnload/onHide）必须调用 client.destroy()，或将实例交给 hardwareManager 统一管理并在卸载时调用 destroyAll()，否则线程泄漏、后台持续连接
2. 对接自定义硬件协议时，优先使用 packet 运行时配置（帧头/长度域/CRC），无需修改插件源码
3. USB 串口需要 Android USB Host 支持，且需用户授权（调用 requestPermission()）
4. iOS 串口与 Modbus RTU 不支持（无 USB Host 能力），构造即抛错；iOS 的 TCP/Modbus TCP 原生实现需在 Mac 环境编译验证
5. 模拟器网络行为与真机有差异，建议使用真实 Android 工控平板/PDA 调试
6. 原生层发送（含心跳）统一经单线程写执行器串行化，确保不会因并发写导致报文字节交错
7. hex2buf() 输入为奇数长度或含非十六进制字符时会抛异常，请确保入参合法
8. Android WebSocket 基于 okhttp（config.json 已声明三方依赖），本地真机运行需在 HBuilderX 配置离线运行环境（含 mavenCentral 依赖缓存），或提交云端打自定义基座
9. Modbus 未连接时发起请求会立即 reject（MODBUS_LOCAL_ERR_DISCONNECTED）；串行模式下（serialRequests: true 或 RTU）前一个请求失败/超时不会阻塞后续请求
10. 对响应数据长度的强校验（byteCount 异常返回 MODBUS_LOCAL_ERR_RESPONSE）可提前发现非 Modbus 设备串扰或错误分帧

开发计划

• [x] TCP 长连接基座
• [x] 指数退避重连
• [x] 心跳保活 + 超时检测 + 读超时检测（1006）
• [x] 可配置粘包分包处理器（含 CRC16 校验与长度上限防卡死）
• [x] Modbus TCP 协议封装（含参数边界校验）
• [x] Modbus RTU（Android）
• [x] USB 转串口（流控 + DTR/RTS 控制 + 热插拔监听）
• [x] TLS/SSL 加密传输
• [x] 多回调监听、状态主动查询、统一错误码、sendAsync
• [x] 寄存器转换工具
• [x] 多连接管理器
• [x] iOS 平台支持（TCP / Modbus TCP）
• [x] WebSocket 支持（Android / iOS）
• [x] Modbus 大段自动分片（count>125）+ 不连续地址批量读取
• [x] Modbus 请求串行队列（TCP serialRequests）、动态 setUnitId、未连接立即报错
• [x] Modbus 响应 byteCount 强校验（-6）、位越界保护
• [x] 64 位寄存器转换（int64/uint64/float64）

License

Apache-2.0