更新记录

0.3.0（2026-06-13） 下载此版本

初次提交

平台兼容性

uni-app(5.0)

uni-app x(5.0)

其他

laoqianjunzi-serial

laoqianjunzi-serial 是一个面向 uni-app x 的 UTS 串口能力插件，统一封装了 Android 原生串口、Harmony USB 串口、Web Serial，以及跨平台可复用的报文编解码、CRC、Modbus 工具。

插件目标很明确：

• 在支持原生串口的平台上，提供统一的扫描、连接、收发、监听能力。
• 在暂不支持原生串口的平台上，仍然提供可直接复用的报文工具能力。
• API 命名与参数模型保持统一，页面层按同一套调用方式即可完成接入。

适用场景

• 工控、网关、采集器等串口设备接入
• Modbus RTU 报文构造与 CRC 校验
• 浏览器环境下通过 Web Serial 调试真实串口设备
• 在 iOS 或其他不支持原生串口的平台上复用纯算法工具

平台能力矩阵

说明：

• Android 使用设备节点方式，例如 /dev/ttyS4、/dev/ttyUSB0。
• Harmony 当前面向 USB 串口，建议始终使用 SerialPlatform.scanPorts() 返回的 path 作为连接参数。
• Web 依赖浏览器原生 Web Serial API，通常要求 Chromium 内核浏览器，并在 HTTPS 或 localhost 环境下运行。
• iOS 当前不提供原生串口访问，但 SerialCodec、SerialChecksum、SerialModbus 等工具能力可直接使用。

安装与运行要求

• HBuilderX: 5.07+
• uni-app x: 5.0+
• Android: minSdkVersion 21
• Web: Chrome / Edge 等支持 Web Serial API 的 Chromium 浏览器

插件目录

• utssdk/app-android：Android 串口实现
• utssdk/app-harmony：Harmony USB 串口实现
• utssdk/web：Web Serial 实现
• utssdk/common：跨平台字节、文本、CRC、Modbus 工具
• pages/index.uvue：插件内置演示页

快速开始

1. 导入 API

import {
  SerialPlatform,
  SerialSession,
  SerialCodec,
  SerialChecksum,
  SerialModbus
} from '@/uni_modules/laoqianjunzi-serial'

2. 扫描串口

const ports = SerialPlatform.scanPorts()
console.log('ports', ports)

3. 建立会话并连接

const session = new SerialSession()

session.onEvent((event) => {
  if (event.kind == 'opened') {
    console.log('opened', event.path)
  }
  if (event.kind == 'received') {
    console.log('received hex', event.hex)
  }
  if (event.kind == 'openFailed') {
    console.log('failed', event.code, event.message)
  }
})

session.applyProfile({
  path: '/dev/ttyS4',
  baudRate: 9600,
  dataBits: 8,
  parity: 0,
  stopBits: 1,
  flowControl: 0,
  autoGrantPermission: true,
  shellPath: 'su'
})

session.connect()

4. 开启持续监听并发送数据

session.beginRead()
session.writeHex('010300000002C40B')
session.writeText('hello serial', 'utf-8')

5. 断开连接

session.endRead()
session.disconnect()

API 总览

SerialPlatform

scanPorts(options?)

扫描当前平台可访问的串口列表，返回值字段如下：

options 当前支持：

runCommand(options)

仅 Android 支持，用于执行本地命令。

const report = SerialPlatform.runCommand({
  command: 'ls /dev/tty*',
  shellPath: 'sh',
  waitFor: true,
  captureOutput: true
})

返回值字段：

writeTextFile(path, content)

仅 Android 支持，用于向系统文件或业务文件写入文本内容。

SerialSession

applyProfile(profile)

应用连接参数，但不立即打开串口。

profile 字段：

snapshot()

获取当前会话快照，适合页面调试时展示最后一次已应用的连接配置与连接状态。

onEvent(callback)

注册事件监听。插件会派发以下事件：

事件对象字段：

connect(profile?)

连接串口。

• 传入 profile 时，会先自动执行 applyProfile(profile)。
• 未先设置参数时会抛出 1203 错误。
• Web 平台在 autoGrantPermission = true 且当前路径未授权时，会触发浏览器选口流程。

disconnect()

主动断开串口连接。

opened()

返回当前串口是否已连接。

beginRead() / endRead()

开始或结束持续监听。

• beginRead() 仅在已连接时可调用。
• endRead() 会关闭持续监听状态，但不会断开串口。

pendingBytes()

返回当前已缓存但尚未被同步消费的字节数。

readChunk(total, offset, length)

同步读取一段缓存或设备数据。

• total：本次希望获取的总字节数
• offset：从结果中的哪个偏移开始截取
• length：最终返回的长度

注意：当已开启 beginRead() 持续监听时，readChunk() 会抛出 1213，用于避免同步读取与持续读取并发冲突。

writeBytes(data) / writeHex(hex) / writeText(text, charsetName)

三种发送方式分别对应：

• 已准备好的字节数组
• 十六进制字符串
• 文本与字符集编码

字符集参数不能为空；当字符集不受当前平台支持时，会抛出 1208。

SerialCodec

SerialCodec 为纯工具类，不依赖串口连接状态。

字节与十六进制

• hexToBytes(source)
• bytesToHex(source)
• concat(first, second)
• slice(source, start, length)

进制转换

• reverseBits(value, bitCount)
• binaryToDecimal(source)
• decimalToBinary(value)
• hexToDecimal(source)
• decimalToHex(value)

文本编解码

• textToBytes(text, charsetName)
• bytesToText(bytes, charsetName)
• textToHex(text, charsetName)
• hexToText(hex, charsetName)

示例：

const hex = SerialCodec.textToHex('串口工具演示', 'utf-8')
const text = SerialCodec.hexToText(hex, 'utf-8')

SerialChecksum

支持 CRC8、CRC16、CRC32 三类校验。

crc8(options)

支持模式：

• CRC8_DEFAULT
• CRC8_MAXIM
• CRC8_ROHC

crc16(options)

支持模式：

• CRC16_MODBUS
• CRC16_XMODEM
• CRC16_CCITT_FALSE

crc32(options)

支持模式：

• CRC32_DEFAULT
• CRC32_BZIP2

返回值结构：

示例：

const crc = SerialChecksum.crc16({
  data: SerialCodec.hexToBytes('010300000002'),
  mode: 'CRC16_MODBUS'
})

SerialModbus

当前提供以下常用构帧方法：

• buildFrame(address, functionCode, payload, crcMode?, lowByteFirst?)
• buildReadHoldingRegisters(address, startRegister, registerCount, crcMode?, lowByteFirst?)
• buildWriteSingleRegister(address, registerAddress, registerData, crcMode?, lowByteFirst?)

示例：

const readFrame = SerialModbus.buildReadHoldingRegisters(1, 0, 2)
const writeFrame = SerialModbus.buildWriteSingleRegister(1, 1, [0x00, 0x64])

演示页面

插件内置了一个完整示例页：

• 页面路径：uni_modules/laoqianjunzi-serial/pages/index

页面演示内容包括：

• 扫描串口并回填默认路径
• 建立会话、连接、断开、持续监听、同步读取
• 发送 Hex 与文本
• 文本编解码、CRC、Modbus 构帧
• Android 平台下的命令执行与文本文件写入演示

如果你希望先确认插件接入方式，建议直接运行该页面进行联调。

平台接入说明

Android

• 建议优先通过 SerialPlatform.scanPorts() 获取可用设备
• 如设备节点需要额外权限，可结合 autoGrantPermission 与 shellPath 使用
• runCommand() 与 writeTextFile() 仅在该平台可用

Harmony

• 当前实现面向 USB 串口设备
• 当 autoGrantPermission = true 时，插件会按需触发系统授权
• flowControl = 1/2 当前不支持

Web

• scanPorts() 返回的是当前浏览器已经授权过的串口缓存
• 若要首次连接未授权串口，可在 connect() 时配置 autoGrantPermission: true
• 浏览器取消选口或拒绝授权时，会通过 openFailed 事件返回错误信息

iOS

• 原生串口 API 会明确返回不支持
• 可继续使用 SerialCodec、SerialChecksum、SerialModbus

错误码

使用建议

• 页面层尽量先监听 onEvent()，再执行连接和读写，便于统一处理状态变化。
• 连接路径优先使用 scanPorts() 返回结果，不要手写猜测路径。
• 需要同步读取时，先调用 endRead()，避免与持续监听冲突。
• Web 环境建议将“连接串口”按钮放在用户手势触发路径内，便于浏览器弹出选口框。

License

按项目需要自行约定。