更新记录

1.0.0（2026-07-28）

• 首次发布
• 支持 TCP/UART 硬件通信
• 支持长连接、断线重连、心跳保活
• 支持粘包分包、Modbus TCP、USB 转串口

平台兼容性

uni-app(3.8.1)

uni-app x(3.8.1)

uni-hardware-connect

UniApp 硬件通信 UTS 原生插件。提供 TCP 长连接、Modbus TCP、USB 转串口 能力，专为工控平板、PDA、物联网设备设计。

特性

• TCP 二进制长连接（子线程非阻塞读写）
• 断线自动重连（指数退避，可设最大次数）
• 心跳保活 + 超时检测
• 可配置的粘包分包处理器（帧头 + 长度域）
• Modbus TCP 协议封装（Promise API）
• USB 转串口 RS232/RS485/TTL（via usb-serial-for-android）
• 单例多连接管理，页面销毁自动释放

环境要求

快速开始

1. 安装

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

2. 基础 TCP 通信

import { HardwareTcpClient } from '@/uni_modules/uni-hardware-connect/utssdk/app-android/index'

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)

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

3. Modbus TCP

import { ModbusTcpClient } from '@/uni_modules/uni-hardware-connect/utssdk/modbus-tcp'

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

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

// 读取保持寄存器（Promise API）
const values = await modbus.readHoldingRegisters(0, 10)
console.log("寄存器值:", values)

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

4. USB 转串口

import { HardwareSerialClient } from '@/uni_modules/uni-hardware-connect/utssdk/app-android/serial-bridge'

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

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

serial.onData((buf) => {
    console.log("串口收到:", HardwareTcpClient.buf2hex(buf))
})

serial.connect()
serial.send(new Uint8Array([0xAA, 0xBB, 0x00, 0x01]).buffer as ArrayBuffer)

API 参考

HardwareTcpClient

构造参数

方法

ModbusTcpClient

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

方法

配置粘包分包

编辑 utssdk/app-android/index.uts 中的 handlePacket() 方法：

const HEADER: number[] = [0xAA, 0xBB]          // ← 改你的帧头
const bodyLen = view.getUint16(2, false)        // ← 改长度域位置/字节序
const totalFrameLen = 4 + bodyLen + 2            // ← 改帧结构

示例：三菱 MC 协议（帧头 0x50 0xFF）

const HEADER = [0x50, 0xFF]
// 长度域在第 3-4 字节，小端
const bodyLen = view.getUint16(2, true)
// 固定头 4 字节 + 数据 + 尾 2 字节
const totalFrameLen = 4 + bodyLen + 2

注意事项

1. 页面卸载（onUnload/onHide）必须调用 client.destroy()，否则线程泄漏、后台持续连接
2. TCP 粘包解析代码是示例协议，对接硬件时必须修改帧头、长度解析规则
3. USB 串口需要 Android USB Host 支持，且需用户授权（调用 requestPermission()）
4. 模拟器网络行为与真机有差异，建议使用真实 Android 工控平板/PDA 调试

开发计划

• [x] TCP 长连接基座
• [x] 指数退避重连
• [x] 心跳保活 + 超时检测
• [x] 粘包分包处理器
• [x] Modbus TCP 协议封装
• [x] USB 转串口（基础框架）
• [ ] iOS 平台支持
• [ ] WebSocket 支持
• [ ] 多连接管理器
• [ ] 串口 DTR/RTS 控制

License

Apache-2.0