更新记录

1.0.0（2026-06-03）

初版发布 读取usb串口数据

平台兼容性

uni-app(4.85)

uni-app x(4.85)

其他

estplugin-usbserial

Android USB 串口通信 UTS 插件，适用于 uni-app / uni-app x 项目在 App-Android 端连接 USB 串口设备，实现设备检测、USB 授权、打开串口、发送指令、接收串口数据以及监听 USB 设备插拔事件。

功能特性

• 支持 Android App 端 USB Serial 串口通信
• 支持检测当前是否存在可用 USB 串口设备
• 支持申请 USB 设备访问权限
• 支持按指定波特率打开串口
• 支持发送字节数组指令
• 支持持续接收串口返回数据
• 支持监听 USB 设备插入、拔出事件
• 内置常见 USB 串口驱动适配：CH34x、CP21xx、FTDI、Prolific、CDC ACM

平台兼容

说明：非 Android 平台会返回“USB串口仅支持Android”等降级提示，不具备真实串口通信能力。

当前支持的驱动型号

插件当前通过 Android 端内置驱动表识别 USB 串口设备，支持以下 Vendor ID / Product ID 组合：

如果你的设备未被识别，请先通过 USB 工具确认设备的 Vendor ID / Product ID 是否在上表中。未列出的设备需要在插件驱动表中新增 VID/PID 适配后才能被默认探测到。

安装方式

1. 在 DCloud 插件市场导入本插件到项目。
2. 确认插件目录位于 uni_modules/estplugin-usbserial。
3. 在需要使用的页面或模块中按需导入 API。

import {
  registerReceiver,
  hasPermission,
  requestPermission,
  hasUsbDevice,
  isOpen,
  open,
  close,
  sendMsg
} from '@/uni_modules/estplugin-usbserial'

使用流程

推荐调用顺序：

1. 调用 hasUsbDevice 检测是否存在 USB 串口设备。
2. 调用 requestPermission 申请 USB 设备权限。
3. 调用 open 按指定波特率打开串口。
4. 在 open 的回调中接收串口数据。
5. 调用 sendMsg 发送字节数组指令。
6. 页面关闭或不再使用时调用 close 释放串口连接。

API 说明

registerReceiver(callback)

注册 USB 设备插拔广播监听。

registerReceiver((res : any) => {
  console.log('USB 设备状态变化：', res)
})

返回示例：

{
  "action": "android.hardware.usb.action.USB_DEVICE_ATTACHED"
}

常见 action：

• android.hardware.usb.action.USB_DEVICE_ATTACHED：USB 设备已插入
• android.hardware.usb.action.USB_DEVICE_DETACHED：USB 设备已拔出

hasUsbDevice(callback)

检测当前是否存在可识别的 USB 串口设备。

hasUsbDevice((res : any) => {
  console.log('USB 设备检测结果：', res)
})

成功返回示例：

{
  "status": true,
  "code": 0,
  "vender_id": 6790,
  "product_id": 29987,
  "device_id": 1002,
  "manufacturer": "wch.cn",
  "product_name": "USB2.0-Serial",
  "driver_name": "Ch34xSerialDriver",
  "msg": "获取USB串口设备成功"
}

失败返回示例：

{
  "status": false,
  "code": 101,
  "msg": "获取USB设备失败"
}

hasPermission(callback)

检测当前应用是否已拥有 USB 设备访问权限。

hasPermission((res : any) => {
  console.log('USB 授权状态：', res.status)
})

返回示例：

{
  "status": true
}

requestPermission(callback)

请求 USB 设备访问权限。Android 会弹出系统授权确认框。

requestPermission((res : any) => {
  console.log('USB 授权结果：', res)
})

成功返回示例：

{
  "status": true,
  "code": 0,
  "msg": "USB授权成功"
}

失败返回示例：

{
  "status": false,
  "code": 102,
  "msg": "USB授权失败"
}

open(baud, callback)

打开 USB 串口。baud 为波特率，例如 9600、57600、115200。

open 的回调既会返回打开结果，也会持续回调串口接收到的数据。

open(57600, (res : any) => {
  console.log('串口回调：', res)
})

打开成功返回示例：

{
  "code": 0,
  "vender_id": 6790,
  "product_id": 29987,
  "device_id": 1002,
  "manufacturer": "wch.cn",
  "product_name": "USB2.0-Serial",
  "msg": "打开串口设备成功"
}

已连接时再次调用返回示例：

{
  "code": 200,
  "msg": "已经连接，已更新数据回调"
}

串口数据回调说明：

• 设备返回的数据会以字节数组形式回调。
• 可根据业务协议自行转换为十六进制字符串、文本或其他结构。

isOpen(callback)

检测串口是否处于打开状态。

isOpen((res : any) => {
  console.log('串口是否已打开：', res)
})

返回示例：

true

sendMsg(options, callback)

向已打开的串口发送字节数组指令。

sendMsg({
  cmd: [0x01, 0x03, 0x00, 0x00, 0x00, 0x01]
}, (res : any) => {
  console.log('发送结果：', res)
})

成功返回示例：

{
  "code": 200,
  "msg": "发送完成"
}

失败返回示例：

{
  "code": -200,
  "msg": "尚未连接或连接断开"
}

close()

关闭串口连接并释放资源。

close()

建议在页面卸载、设备拔出或业务结束时调用。

完整示例

import {
  registerReceiver,
  hasUsbDevice,
  requestPermission,
  open,
  sendMsg,
  close
} from '@/uni_modules/estplugin-usbserial'

export function initUsbSerial() {
  registerReceiver((res : any) => {
    console.log('USB 插拔事件：', res)
  })

  hasUsbDevice((deviceRes : any) => {
    if (deviceRes.status != true) {
      console.log('未检测到 USB 串口设备：', deviceRes)
      return
    }

    requestPermission((permissionRes : any) => {
      if (permissionRes.status != true) {
        console.log('USB 授权失败：', permissionRes)
        return
      }

      open(57600, (serialRes : any) => {
        console.log('串口打开结果或接收数据：', serialRes)
      })
    })
  })
}

export function sendCommand() {
  sendMsg({
    cmd: [0x01, 0x03, 0x00, 0x00, 0x00, 0x01]
  }, (res : any) => {
    console.log('发送结果：', res)
  })
}

export function destroyUsbSerial() {
  close()
}

返回码说明

注意事项

• 插件仅支持 Android App 端，真机需要具备 USB Host 能力。
• 使用前请确认设备已通过 OTG 或 USB 方式连接到 Android 设备。
• open 内部会在未授权时触发授权申请，授权成功后自动打开设备。
• 如业务需要先单独处理授权流程，可先调用 requestPermission，再调用 open。
• open 的回调会被持续用于接收串口数据，请避免在回调中执行耗时逻辑。
• 发送前请先确认串口已打开，否则 sendMsg 会返回连接失败提示。
• 页面销毁、设备拔出或不再使用串口时，请调用 close 释放资源。

常见问题

为什么检测不到 USB 设备？

请确认 Android 设备支持 USB Host，USB 串口设备已正确连接，并且设备芯片属于插件内置驱动支持范围。

为什么发送指令失败？

请先确认已完成 USB 授权并成功调用 open 打开串口。未连接或连接断开时，sendMsg 会返回 code: -200。

如何处理接收到的串口数据？

open 回调中的串口数据为字节数组，可根据设备协议自行解析。例如转成十六进制字符串后再处理业务逻辑。

Web / H5 可以使用吗？

不支持。该插件依赖 Android 原生 USB Host 与串口驱动能力，Web / H5、小程序、iOS、HarmonyOS 均不支持真实串口通信。

版本

当前版本：1.0.0