更新记录

2.0.0（2025-05-15）

支持多串口同时使用

1.0.0（2024-04-01）

V1.0 上线

平台兼容性

原生插件通用使用流程：

1. 购买插件，选择该插件绑定的项目。
2. 在HBuilderX里找到项目，在manifest的app原生插件配置中勾选模块，如需要填写参数则参考插件作者的文档添加。
3. 根据插件作者的提供的文档开发代码，在代码中引用插件，调用插件功能。
4. 打包自定义基座，选择插件，得到自定义基座，然后运行时选择自定义基座，进行log输出测试。
5. 开发完毕后正式云打包

付费原生插件目前不支持离线打包。
Android 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/android
iOS 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/ios

注意事项：使用HBuilderX2.7.14以下版本，如果同一插件且同一appid下购买并绑定了多个包名，提交云打包界面提示包名绑定不一致时，需要在HBuilderX项目中manifest.json->“App原生插件配置”->”云端插件“列表中删除该插件重新选择

uniapp串口插件使用说明

简介

本插件提供了在uniapp中使用串口的能力，支持多串口实例管理、串口参数配置、数据收发等功能。

安装

1. 将插件包复制到项目的nativeplugins目录下
2. 在manifest.json中添加插件引用：

{
    "plugins": {
        "SerialPort": {
            "__plugin_info__": {
                "name": "SerialPort",
                "description": "串口通信插件"
            }
        }
    }
}

API说明

createSerialPort(portId)

创建串口实例。

参数说明：

• portId：{String} 串口实例标识符

返回值：

• {Boolean} 是否创建成功

setPath(portId, port)

设置串口路径。

参数说明：

• portId：{String} 串口实例标识符
• port：{String} 串口路径

setBaudRate(portId, baudRate)

设置波特率。

参数说明：

• portId：{String} 串口实例标识符
• baudRate：{Number} 波特率

setDataBits(portId, dataBits)

设置数据位。

参数说明：

• portId：{String} 串口实例标识符
• dataBits：{Number} 数据位

setStopBits(portId, stopBits)

设置停止位。

参数说明：

• portId：{String} 串口实例标识符
• stopBits：{Number} 停止位

setParity(portId, parity)

设置校验位。

参数说明：

• portId：{String} 串口实例标识符
• parity：{Number} 校验位

open(portId, callback)

打开串口。

参数说明：

• portId：{String} 串口实例标识符
• callback：{Function} 回调函数
  • status：{Boolean} 是否成功
  • msg：{String} 错误信息

isOpen(portId, callback)

检查串口是否打开。

参数说明：

• portId：{String} 串口实例标识符
• callback：{Function} 回调函数
  • data：{Boolean} 是否打开
  • msg：{String} 错误信息

getAllDeviceList(portId, callback)

获取所有可用串口设备列表。

参数说明：

• portId：{String} 串口实例标识符
• callback：{Function} 回调函数，返回设备列表数组

getAllDevicePath(portId, callback)

获取所有可用串口设备路径。

参数说明：

• portId：{String} 串口实例标识符
• callback：{Function} 回调函数，返回设备路径数组

错误码说明

常见问题解决方案

1. 串口打开失败

• 检查串口是否被其他程序占用
• 确认串口路径是否正确
• 验证是否有足够的权限
• 检查串口驱动是否正确安装

2. 数据收发异常

• 确认波特率等参数配置是否匹配
• 检查数据格式（ASCII/HEX）是否正确
• 验证数据长度是否符合要求
• 考虑添加数据校验机制

3. 性能优化建议

• 合理设置缓冲区大小
• 避免频繁打开关闭串口
• 及时释放不使用的资源
• 实现数据包分片处理

多串口并发操作最佳实践

1. 实例管理

• 使用Map或对象统一管理多个串口实例
• 为每个串口实例分配唯一的标识符
• 实现串口状态监控机制

2. 资源控制

• 控制同时打开的串口数量
• 实现串口连接池管理
• 及时关闭不使用的串口

3. 错误处理

• 实现全局错误处理机制
• 添加串口状态自动恢复功能
• 记录详细的错误日志

使用示例

const serialPort = uni.requireNativePlugin('SerialPort');

// 创建串口实例
const portId = 'COM1';
const result = serialPort.createSerialPort(portId);
if (!result) {
    console.log('串口实例创建失败');
    return;
}

// 配置串口参数
serialPort.setPath(portId, '/dev/ttyUSB0');
serialPort.setBaudRate(portId, 9600);
serialPort.setDataBits(portId, 8);
serialPort.setStopBits(portId, 1);
serialPort.setParity(portId, 0);

// 打开串口
serialPort.open(portId, (result) => {
    if (result.status) {
        console.log('串口打开成功');

        // 设置数据监听
        serialPort.onMessage(portId, (data) => {
            console.log('收到数据：', data);
        });

        // 发送数据
        serialPort.sendHex(portId, 'FF01020304');
    } else {
        console.log('串口打开失败：' + result.msg);
    }
});

// 检查串口状态
serialPort.isOpen(portId, (result) => {
    if (result.data) {
        console.log('串口已打开');
    } else {
        console.log('串口未打开：' + result.msg);
    }
});

// 获取设备列表
serialPort.getAllDeviceList(portId, (devices) => {
    console.log('可用设备列表：', devices);
});

// 使用完毕后关闭串口
serialPort.close(portId, (result) => {
    if (result.status) {
        console.log('串口关闭成功');
    } else {
        console.log('串口关闭失败：' + result.msg);
    }
});

### sendHex(portId, message)

以十六进制格式发送数据。适用于需要发送二进制数据或与设备进行原始数据通信的场景。

**参数说明：**
- portId：{String} 串口实例标识符
- message：{String} 要发送的十六进制字符串

**使用场景：**
- 与工业设备通信
- 发送控制指令
- 二进制协议通信

**注意事项：**
- 确保十六进制字符串格式正确（偶数长度）
- 建议使用大写字母表示十六进制数据
- 不要包含空格或其他分隔符

### sendASCII(portId, message)

以ASCII格式发送数据。适用于发送文本数据或人类可读的指令。

**参数说明：**
- portId：{String} 串口实例标识符
- message：{String} 要发送的ASCII字符串

**使用场景：**
- 发送AT指令
- 文本数据传输
- 调试信息输出

**注意事项：**
- 确保数据为有效的ASCII字符
- 注意字符编码问题
- 避免发送特殊控制字符

### onMessage(portId, callback, sendCallback)

监听串口数据。提供最原始的数据接收方式，适用于需要自定义数据处理的场景。

**参数说明：**
- portId：{String} 串口实例标识符
- callback：{Function} 接收数据回调函数
  - data：{Uint8Array} 接收到的数据
- sendCallback：{Function} 发送数据回调函数（可选）
  - data：{Uint8Array} 发送的数据

**使用场景：**
- 自定义数据解析
- 二进制协议实现
- 高性能数据处理

**注意事项：**
- 注意处理数据粘包问题
- 建议实现数据校验机制
- 合理设计数据缓冲区

### onMessageHex(portId, callback, sendCallback)

以十六进制格式监听串口数据。适用于需要以十六进制格式查看和处理数据的场景。

**参数说明：**
- portId：{String} 串口实例标识符
- callback：{Function} 接收数据回调函数
  - data：{String} 接收到的十六进制字符串
- sendCallback：{Function} 发送数据回调函数（可选）
  - data：{String} 发送的十六进制字符串

**使用场景：**
- 数据调试和分析
- 协议开发和测试
- 设备通信监控

**注意事项：**
- 注意数据转换效率
- 考虑大数据量时的性能
- 建议实现数据过滤机制

### onMessageASCII(portId, callback, sendCallback)

以ASCII格式监听串口数据。适用于需要以ASCII字符串形式处理数据的场景，如文本数据传输。

**参数说明：**
- portId：{String} 串口实例标识符
- callback：{Function} 接收数据回调函数
  - data：{String} 接收到的ASCII字符串
- sendCallback：{Function} 发送数据回调函数（可选）
  - data：{String} 发送的ASCII字符串

**使用场景：**
- 文本数据传输
- 人机交互界面
- 调试信息输出

### close(portId, callback)

关闭串口连接。在不再使用串口时，应及时调用此方法释放资源。

**参数说明：**
- portId：{String} 串口实例标识符
- callback：{Function} 回调函数
  - status：{Boolean} 是否成功关闭
  - msg：{String} 错误信息

**使用场景：**
- 页面销毁时
- 切换串口连接时
- 异常处理时

### destroySerialPort(portId)

销毁串口实例，释放资源。在完全不再使用该串口实例时调用，会自动关闭串口连接。

**参数说明：**
- portId：{String} 串口实例标识符

**返回值：**
- {Boolean} 是否销毁成功

**使用场景：**
- 应用退出时
- 需要重新创建串口实例时
- 资源回收时

## 使用示例

```javascript
const serialPort = uni.requireNativePlugin('SerialPort');

// 创建串口实例
const portId = 'COM1';
const result = serialPort.createSerialPort(portId);
if (!result) {
    console.log('串口实例创建失败');
    return;
}

// 配置串口参数
serialPort.setPath(portId, '/dev/ttyUSB0');
serialPort.setBaudRate(portId, 9600);
serialPort.setDataBits(portId, 8);
serialPort.setStopBits(portId, 1);
serialPort.setParity(portId, 0);

// 打开串口
serialPort.open(portId, (result) => {
    if (result.status) {
        console.log('串口打开成功');

        // 监听数据
        serialPort.onMessageHex(portId, (data) => {
            console.log('接收到数据：', data);
        }, (data) => {
            console.log('发送数据：', data);
        });

        // 发送数据
        serialPort.sendHex(portId, 'FF01020304');

    } else {
        console.log('串口打开失败：' + result.msg);
    }
});

// 在页面销毁时释放资源
onUnload(() => {
    serialPort.destroySerialPort(portId);
});

注意事项

1. 使用前请确保Android设备已获取串口访问权限
2. 建议在页面销毁时调用destroySerialPort方法关闭串口连接并释放资源
3. 多串口并发操作时：
   • 使用不同的portId进行区分
   • 每个串口实例独立配置参数
   • 注意控制并发数量，避免资源占用过多
4. 串口操作可能需要一定时间，建议使用异步回调处理结果
5. 数据收发建议：
   • 根据设备协议选择合适的数据格式（Hex/ASCII）
   • 注意数据校验和超时处理
   • 建议实现错误重试机制
6. 资源管理：
   • 及时关闭不再使用的串口连接
   • 在页面切换时注意串口资源的释放
   • 避免重复创建相同portId的实例