更新记录

1.2.1（2026-09-16）

• 修复 HarmonyOS 严格类型编译失败的问题，兼容 ArkTS 对命名类型、错误回调、缓冲区和 UTF-8 编解码的检查。
• 升级后无需修改现有串口配置或调用代码。
• 本版本修改了 HarmonyOS 原生实现，需要重新制作并安装匹配的 HarmonyOS HAP 或自定义基座。

1.2.0（2026-09-12）

• 新增 HarmonyOS 通过 USB OTG 识别和连接 CH340/CH341，支持设备扫描、系统授权、芯片初始化、常用串口参数、数据读写、持续读取、请求响应和断线资源清理。
• 现有公开 API 和 Android 调用方式无需调整；HarmonyOS 使用 listPorts 获取设备后继续调用 openUsb。
• 本版本包含 HarmonyOS 原生串口能力，升级后需要重新制作并安装匹配的 HarmonyOS HAP 或自定义基座；是否完成真实通信仍需使用实际 CH340/CH341 设备验收。

1.1.0（2026-09-06）

• 2026-09-06：调整 uni-app x Android 示例的函数声明顺序，修复查询、连接与发送示例的编译错误。

• 新增 CH34x、CP210x、FTDI、PL2303、CDC ACM USB 转串口驱动，USB 模式现在会真实应用波特率、数据位、校验位、停止位和流控配置。

• 首次打开 USB 设备时会主动请求 Android 系统访问授权；允许后自动继续连接，拒绝或超时返回明确错误。

• 新增“串口连接与验收中心”，提供“没有设备，先体验”和“我已连接串口设备”两种入口，并按发现、授权、连接、发送、接收逐步引导。

• USB 端口列表新增驱动名称、驱动支持状态、授权状态和端口数量，便于在页面中直接展示设备是否具备通信条件。

• USB 读写、缓冲区清理和断线重连统一使用已匹配的芯片驱动；未知设备保留 Generic Bulk 兼容模式。

• 修复 Android 从 uni-app 传入普通参数对象时能力查询、端口扫描等接口可能收到空参数的问题，现有调用代码无需调整。

• 无设备自检改为依据能力查询和端口扫描的真实回调结果判定，不再把未成功执行的公开入口显示为通过。

• 优化插件市场标题、能力描述与客户文档，按使用场景整理连接、发送、接收和运维示例，无需修改现有公开 API 调用。

• 本次包含 Android 原生能力和依赖变化，升级后需要重新制作并安装 Android 自定义基座。

平台兼容性

uni-app(5.07)

uni-app x(5.07)

lizhao-serial-port

面向 uni-app / uni-app x Android 与 HarmonyOS 应用的专业串口通信插件：从 USB 设备发现、系统授权、芯片驱动到多会话收发与结果验收，提供一条清晰、可诊断、可落地的接入链路。

功能特色

• 新手也能完成验收：内置“串口连接与验收中心”，先判断环境，再引导连接、授权、配置、发送、接收和导出结果。
• 没有设备也知道下一步：选择“没有设备，先体验”可验证公开 API、Hex 与字节转换；依赖硬件的项目明确显示“等待设备”，不伪造通信成功。
• 主流 USB 芯片直接接入：内置 CH34x、CP210x、FTDI、PL2303、CDC ACM 驱动，连接常见 USB 转串口线时无需业务层自己处理芯片初始化。
• USB 授权闭环：首次打开 USB 设备时按平台申请系统访问授权，授权成功后继续建立会话，拒绝或超时均返回可定位错误。
• 路径与 USB 双通道：Android 可连接设备节点和外部 USB 串口，HarmonyOS 通过 USB Host 连接外部 CH340/CH341 串口设备。
• 三种发送方式：支持 ArrayBuffer、Hex、UTF-8 / ASCII 文本，协议指令可按业务习惯直接发送。
• 三种接收方式：支持单次读取、持续监听，以及发送后等待指定 Hex / 文本响应。
• 多设备互不干扰：通过独立 sessionId 同时管理多个串口，并分别记录状态、重连次数和收发字节数。
• 异常恢复与诊断：提供有限自动重连、错误事件、会话快照、全局运行态和累计流量，现场问题更容易复现和说明。
• 兼容旧调用：保留 openSerial / writeData / readData / closeSerial，已有项目可分阶段迁移。

适用场景

• 工控平板、PDA、边缘网关连接 RS232、RS485、TTL 转换器。
• Android 或 HarmonyOS 手机、平板通过 OTG 连接 CH340 / CH341；Android 另支持 CP210x、FTDI、PL2303、CDC ACM 设备。
• 仪表、传感器、继电器、读卡器、控制板、打印控制器等自定义串口协议设备。
• 设备持续上报、轮询查询、指令响应匹配、多个串口同时在线的业务。
• 需要把“是否发现设备、是否授权、使用什么驱动、是否收到真实响应”清楚展示给实施人员的项目。

不适合以下场景：

• iOS、Web 或小程序直接访问真实串口。
• 只用普通 USB 数据线把电脑和手机相连，却没有 USB 转串口设备。电脑连接手机的数据线只用于调试，不是串口设备。
• 需要插件直接实现 Modbus RTU、CRC 或某个厂商私有协议。插件负责可靠字节收发，业务协议可在上层组合。

支持平台

Android 最低系统版本为 5.0。Android 与 HarmonyOS 的真实 USB 串口能力需要包含本插件原生代码的匹配自定义基座、HAP 或正式安装包。

三步开始

第一步：先打开验收中心

导入插件后先运行随插件提供的“串口连接与验收中心”。首页只有两个明确入口：

• 没有设备，先体验：适合暂时没有串口外设的情况。它会检查能力查询、端口扫描和数据转换，并把真实硬件项目标成“等待设备”。
• 我已连接串口设备：适合 Android 或 HarmonyOS 手机已通过 OTG 连接 USB 转串口线；Android 也可连接设备节点。

如果目前只有手机和连接电脑的数据线，可先走无设备体验。要完成真实收发，还需要手机支持的 OTG 转接头和 CH340/CH341 USB 转串口设备；做自发自收测试时，可将转换器的 TX 与 RX 交叉连接。

第二步：从插件根目录导入

import * as SerialPort from '@/uni_modules/lizhao-serial-port'

先检查能力，再扫描端口：

SerialPort.getCapabilities({
  success(capabilities) {
    if (!capabilities.supported) {
      console.log('当前平台不支持真实串口', capabilities.restrictedReason)
      return
    }

    SerialPort.listPorts({
      includeBusy: true,
      success(res) {
        console.log('发现的串口', res.ports)
      },
      fail(err) {
        console.log('扫描串口失败', err)
      }
    })
  }
})

USB 端口会返回 driverName、driverSupported、permissionGranted 和 portCount，Android 与 HarmonyOS 页面都可以直接告诉使用者当前匹配了什么驱动、是否已授权。

第三步：连接并取得真实响应

下面示例从扫描结果中选择一个 USB 设备，首次连接时插件会按平台自动请求系统授权；HarmonyOS 的 CH340/CH341 也使用同一调用方式：

const sessionId = 'main-device'

function connectUsb(port) {
  SerialPort.openUsb({
    vendorId: port.vendorId,
    productId: port.productId,
    serialNumber: port.serialNumber,
    sessionId,
    lineConfig: {
      baudRate: 9600,
      dataBits: 8,
      parity: 'none',
      stopBits: 1,
      flowControl: 'none'
    },
    success(res) {
      console.log('连接成功，当前驱动', res.session.descriptor.driverName)
    },
    fail(err) {
      console.log('连接失败', err.errCode, err.details)
    }
  })
}

连接成功只代表端口已打开。建议至少完成一次“发送指令并收到设备响应”，再把业务状态显示为“真实通信通过”。

核心配置

串口线参数 lineConfig

USB 芯片驱动会应用上述线参数。路径串口会保留配置快照，但设备节点最终采用的线参数仍取决于设备系统和节点驱动，接入板载串口前应与硬件系统方确认。

会话参数 config

接入方式选择

分类实战示例

连接类：路径串口与 USB 串口

// 板载设备节点。
SerialPort.openPath({
  path: '/dev/ttyS3',
  sessionId: 'board-uart',
  lineConfig: { baudRate: 115200 }
})

// USB 转串口设备。vendorId/productId 应取自 listPorts 返回值。
SerialPort.openUsb({
  vendorId: 0x1A86,
  productId: 0x7523,
  sessionId: 'usb-uart',
  lineConfig: { baudRate: 9600 }
})

发送类：文本、Hex 与二进制

// 文本设备，例如 AT 指令或带换行的命令。
SerialPort.writeText({
  sessionId: 'usb-uart',
  text: 'STATUS\r\n',
  encoding: 'ascii'
})

// 协议文档直接给出十六进制帧时使用。
SerialPort.writeHex({
  sessionId: 'usb-uart',
  hex: '010300000002C40B'
})

// 已在业务层组装好原始字节时使用。
const buffer = new ArrayBuffer(3)
const bytes = new Uint8Array(buffer)
bytes[0] = 0xAA
bytes[1] = 0x55
bytes[2] = 0x01
SerialPort.writeBytes({ sessionId: 'usb-uart', data: buffer })

接收类：单次、持续与请求响应

// 读取一包。
SerialPort.readOnce({
  sessionId: 'usb-uart',
  timeoutMs: 1500,
  success(res) {
    console.log('收到 Hex', res.hex)
  }
})

// 持续接收设备主动上报。
const onData = (event) => {
  console.log('持续数据', event.payload.hex)
}
SerialPort.on('data', onData)
SerialPort.startRead({ sessionId: 'usb-uart' })

// 发送后等待符合条件的响应。
SerialPort.sendAndWait({
  sessionId: 'usb-uart',
  hex: '010300000002C40B',
  matchHex: '010304',
  timeoutMs: 2000,
  success(res) {
    console.log('匹配成功', res.hex)
  }
})

// 页面卸载时使用同一个回调引用解绑。
SerialPort.stopRead({ sessionId: 'usb-uart' })
SerialPort.off('data', onData)

同一个会话不建议同时运行 startRead 与 readOnce / sendAndWait，否则多个读取者可能竞争同一批字节。

运维类：清空、状态与统一释放

// 开始新一轮测试前清理旧数据。
SerialPort.flush({ sessionId: 'usb-uart' })

// 查看一个会话。
SerialPort.getSessionState({
  sessionId: 'usb-uart',
  success(res) {
    console.log('连接状态与收发统计', res.session)
  }
})

// 查看全部会话和累计收发字节。
SerialPort.getRuntimeState({
  success(res) {
    console.log('运行态', res)
  }
})

// 应用退出串口业务时统一释放。
SerialPort.closeAllSessions({})

API 参考

API 一览

公共回调

所有异步 API 均支持以下回调：

连接参数

收发参数

关键返回字段

事件

const onError = (event) => {
  console.log('串口异常', event.sessionId, event.payload)
}

SerialPort.on('error', onError)

// 不再使用时必须传入原函数引用。
SerialPort.off('error', onError)

错误码

常见问题

只有手机和电脑数据线，能测试真实串口吗？

不能。普通数据线建立的是调试连接，不会在手机端生成可供本插件通信的 USB 串口。可先使用“没有设备，先体验”；真实测试至少需要 OTG 转接头与 CH340/CH341 USB 转串口设备，或一台提供串口设备节点的 Android 工控设备。

为什么能看到 USB 设备，打开后仍然不能通信？

先查看 driverName / driverSupported / permissionGranted，再确认波特率、数据位、校验位、停止位和流控与外设一致。未知芯片可能进入 Generic Bulk 降级模式，但“存在 Bulk Endpoint”不代表设备一定遵循通用串口协议。

第一次打开为什么出现系统弹窗？

这是 Android 或 HarmonyOS 对目标 USB 设备的访问授权，不是普通运行时权限。允许访问目标设备后插件会继续连接；拒绝或等待超时会返回 9015005。

为什么发送成功却不能显示“真实通信通过”？

写入成功只代表数据已交给串口驱动。只有读取到外设返回的数据，或 sendAndWait 匹配到预期响应，才能证明双方参数和协议都正确。

为什么路径串口提示没有权限？

/dev/tty* 的访问权限由 Android 设备系统、固件和节点权限控制。普通消费级手机通常不能直接访问任意节点；工控设备需由系统厂商提供可访问的节点或对应系统授权。

更新插件后需要重新制作 Android 自定义基座或 HarmonyOS HAP 吗？

如果只修改页面、样式或业务调用，重新运行资源即可。升级后若包含本插件 Android 原生能力或 HarmonyOS USB 芯片驱动变化，需要重新制作并安装对应平台的自定义基座、HAP 或正式包；旧包不会自动获得新的原生能力。

如何避免页面退出后仍在读取？

页面卸载时依次执行 stopRead、closeSession，并使用注册时保存的同一个函数引用调用 off。应用需要一次释放全部设备时可调用 closeAllSessions。

注意事项

• 不要把扫描到设备、授权成功或写入成功当作业务通信成功；以真实响应为最终依据。
• Hex 字符串必须由有效十六进制字符组成并保持偶数长度。
• 协议分帧、CRC、Modbus RTU 和厂商命令由业务层实现，插件负责字节级通信与会话管理。
• 修改 Android 或 HarmonyOS 原生能力、依赖或授权流程后，必须重新制作并安装匹配平台的自定义基座、HAP 或正式包。
• 真实设备兼容性受手机 OTG 能力、USB 转串口芯片、供电、系统版本、线序和外设协议共同影响，建议先在验收中心完成完整闭环；HarmonyOS 当前以 CH340/CH341 为支持范围。

作者系列 UTS 插件

以下为已在 DCloud 插件市场上架的作者系列 UTS 插件，可按业务场景组合使用。未列出的插件表示当前未确认公开市场页，后续上架后再补充。