# ch934x_serial 插件使用说明 `ch934x_serial` 是基于南京沁恒微电子 **CH934X 系列** USB 转多串口芯片 Android SDK 封装的 Flutter 插件,文档面向其他 Flutter 开发者,介绍如何把它集成到自己的应用中并使用全部对外 API。 > 全部接口语义与官方 Android 文档 `docs/CH934X_Android_开发说明.md` > 保持一致,本说明不再重复其原始描述,而是说明在 Flutter 中如何调用。 --- ## 1. 插件概述 - **支持的平台:** Android(已实现,iOS / Web / Desktop 暂不支持)。 - **主要能力:** - CH934X 设备枚举、序列号读取、芯片类型识别 - 多串口打开 / 关闭 / **同设备内串口切换** - 字节级串口读写 - GPIO 输出 / 输入 / 方向控制 / 使能 - Modem 控制 (DTR/RTS) 与状态 (CTS/DSR/RI/DCD) 读取 - **主动申请 USB 权限** - **Break 信号控制** - **串口参数配置(波特率/数据位/停止位/校验/流控)** - **查询设备连接状态与已打开设备列表** - **查询 GPIO 数量、组信息** - 设备拔出、Modem 错误等异常事件回调 - **底层依赖:** 沁恒官方 `CH934XLib.jar`(插件随包发布,位于 `android/libs/CH934XLib.jar`),通过原生 `CH934XManager` 单例直接调用, 无需在调用方业务代码中额外处理反射。 - **平台通道名称:** `ch934x_serial` - **Dart 包名:** `ch934x_serial`(主类 `Ch934xSerial`) - **Android 包名:** `com.xiarui.ch934x_serial` --- ## 2. 集成步骤 ### 2.1 在 `pubspec.yaml` 中加入依赖 ```yaml dependencies: flutter: sdk: flutter ch934x_serial: ^1.0.0 ``` 执行 `flutter pub get` 完成依赖拉取。 ### 2.2 Android 工程准备 1. 确认 `android/app/build.gradle` 中 `minSdk >= 24`,CH934X SDK 不支持更低版本。 2. **无需在 `AndroidManifest.xml` 中声明 USB Host 能力**——插件自带 `android/src/main/AndroidManifest.xml` 已声明 ``, 应用侧合并后即可生效。 3. **USB 权限处理可省略**——`openPort` 在底层若检测到未授权,会自动调用 `UsbManager.requestPermission` 弹出系统对话框并等待用户回应; 也可以在业务侧通过 `requestUsbPermission(deviceId)` 提前主动申请。插件内部 `BroadcastReceiver` 会在需要时动态注册/反注册,无需在 `AndroidManifest.xml` 中额外声明。 > 如果你仍想自己接管权限流程(例如在主界面"刷新设备列表"之后 > 立刻弹一次授权请求),直接调用 `Ch934xSerial.requestUsbPermission` > 即可,内部会等待用户的回应并以 `bool` 返回结果。 ### 2.3 第一次调用 ```dart import 'package:ch934x_serial/ch934x_serial.dart'; Future scan() async { final plugin = Ch934xSerial(); final devices = await plugin.getDeviceList(); for (final d in devices) { debugPrint('发现设备: VID=0x${d.vendorId.toRadixString(16)} ' 'SN=${d.serialNumber}'); } } ``` > **注意:** `getSerialPortList` 在设备尚未 `openPort` 时会返回空 > 列表,因为 SDK 的 `getSerialCount` 必须先 `openDevice` 才能返回 > 真实值。完整流程是:扫描 → 选设备 → `openPort` → > `getSerialPortList` 拿真实串口数,详见 §3.2。 --- ## 3. API 接口说明所有 API 都挂在 `Ch934xSerial` 单例上,命名风格与原 SDK 文档保持一致, 参数使用 `int` 表示芯片/引脚编号,数据以 `Uint8List` 形式传递。 ### 3.1 设备查找 | Dart 方法 | 原 SDK 接口 | 说明 | | --------- | ----------- | ---- | | `getDeviceList()` | `CH934XManager.enumDevice` + `getChipType` | 获取全部 CH934X 设备 | | `getSerialNumber(deviceId)` | `UsbDevice.getSerialNumber` | 获取指定设备的序列号 | | `getDeviceType(deviceId)` | `CH934XManager.getChipType` | 获取设备类型常量 | | `getSerialPortList(deviceId, interfaceNumber: n)` | `CH934XManager.getSerialCount` | 获取设备串口列表(需先 `openPort`) | 返回类型: - `getDeviceList()` → `List` - `getSerialPortList(...)` → `List` - `Ch934xDeviceInfo` 包含 `deviceId / vendorId / productId / deviceType / serialNumber / productName / manufacturerName / interfaceCount / serialPorts`,可通过 `isCh934x` 判定是否被识别为 CH934X 设备。 - **`isCh934x`:** 当 `deviceType` 落在 `ch9344..ch934xOther` 范围内时返回 `true`(`unknown = -1` 不算)。 - `Ch934xSerialPortInfo` 包含 `portIndex / devicePath / driverName`。 - `deviceType` 取值为 `Ch934xDeviceType` 中的常量(`ch9344`、`ch9344L`、 `ch9350`、`ch9348Q`、`ch9342`、`ch934xOther`,未识别为 `unknown = -1`)。 ### 3.2 设备打开、关闭与串口切换 ```dart final target = Ch934xPortTarget( deviceId: device.deviceId, interfaceNumber: 0, // 多数设备只有 1 个接口 serialPortIndex: port.portIndex, ); final ok = await plugin.openPort(target); if (!ok) { debugPrint('打开失败'); return; } // ... 进行业务通信 await plugin.closePort(); ``` - `Ch934xPortTarget` 封装了 `deviceId` / `interfaceNumber` / `serialPortIndex` 三个参数,可通过 `toMap()` 调试其字段,也可通过 `Ch934xPortTarget.fromMap` 从 MethodChannel 回包中还原。 - **`openPort` 内部会自动处理 USB 权限申请**:若 SDK 抛 `NoPermissionException`,会主动调起系统对话框并等待用户回应 (最多 60 秒),授权成功后会自动重试 `openDevice`。 - **同设备内串口切换(`setActivePort`)**:CH934X 设备一次 `openPort` 之后所有串口都已连接,后续读写只需切换 `serialPortIndex`, 无需重新 `open`。`setActivePort(idx)` 仅切换当前活跃串口, 不重复打开设备: ```dart // 串口 #0 已打开,切换到 #2 await plugin.setActivePort(2); ``` - **主动申请 USB 权限**(`requestUsbPermission`): ```dart final granted = await plugin.requestUsbPermission(device.deviceId); if (granted) { // 用户已授权,可继续 openPort } ``` - 同一会话仅保留最近一次打开的串口对象,与原 SDK 行为一致;打开新串口前请先 `closePort()` 或在 `finally` 块中清理。 ### 3.3 串口读写 ```dart // 写入当前活跃端口（向后兼容） final bytes = Uint8List.fromList([0x01, 0x02, 0x03]); final written = await plugin.write(bytes); debugPrint('写入字节数: $written'); // 写入指定端口，不改变当前活跃端口；多端口客户端应使用此形式。 final portWritten = await plugin.write(bytes, serialPortIndex: 2); // 读取(单次) final recv = await plugin.read(1024); if (recv.isEmpty) debugPrint('暂无数据'); // 持续接收:使用 dataStream final sub = plugin.dataStream(chunkSize: 1024).listen((chunk) { debugPrint('收到: $chunk'); }); // 取消订阅 await sub.cancel(); ``` - `read(length)` 返回 `Uint8List`,无数据或失败时为空。 - `length <= 0` 时**不会调用原生层**,直接返回空数组。 - SDK 的 `readData` 会返回内部缓冲的所有数据,插件按 `min(data.length, length)` 截断后回传。 - `write(data, serialPortIndex: n)` 返回实际写入字节数；传入端口时直接写入该端口且不改变当前活跃端口，失败时为 0。省略 `serialPortIndex` 时保持原有的当前活跃端口行为。 - `dataStream` 默认 `chunkSize = 1024`、`interval = 20ms`,内部持续以 [interval] 为周期反复调用 `read`;当底层无数据时返回空缓冲区,消费者可据此判定。`chunkSize <= 0` 会抛 `ArgumentError`。 - 业务方在 widget dispose 时记得 `cancel` 订阅并 `closePort`。 - `read` 默认针对当前活跃串口，也可传入显式端口；`write` 省略 `serialPortIndex` 时针对当前活跃串口，传入时直接写入指定端口。多端口并发客户端应使用显式端口写入，避免通过 `setActivePort` 共享切换端口。 ### 3.4 GPIO 接口 ```dart // 设置 GPIO 输出电平 final ok = await plugin.setGpioOutput(gpioNumber: 0, level: 1); // 读取 GPIO 输入电平(负值表示失败) final value = await plugin.getGpioInput(0); ``` - `gpioNumber` 与 `level` 与原文档保持一致(0/1)。 - `getGpioInput` 失败时返回 -1,业务方需要自行处理。 - GPIO 操作同样作用于**当前活跃串口**。 ### 3.4.1 GPIO 方向控制 ```dart // 使能 GPIO(需要先获取 chipType,可从 Ch934xDeviceInfo.deviceType 取得) await plugin.enableGpio(chipType: device.deviceType, gpioGroup: 0, enable: 1); // 设置 GPIO 方向 await plugin.setGpioDir(gpioGroup: 0, gpioNumber: 0, dir: GpioDirection.out); // 从缓存查询 GPIO 方向 final dir = await plugin.queryGpioDirFromCache(gpioGroup: 0, gpioNumber: 0); if (dir == GpioDirection.out) { /* 输出 */ } // 查询 GPIO 数量与组数 final count = await plugin.getGpiocount(device.deviceId); final groups = await plugin.getGpiogroup(device.deviceId); ``` - `GpioDirection` 常量: `in_ = 0`(输入)、`out = 1`(输出)。 - `enableGpio` 的 `enable` 参数: CH9344 传 1/0 控制整组;CH348 使用位掩码。 - 方向查询返回 -1 表示失败。 - `getGpiocount`/`getGpiogroup` 失败时返回 -1,需先 `openPort`。 ### 3.5 Modem 控制接口 ```dart await plugin.setModemControl(dtr: 1, rts: 0); final status = await plugin.getModemStatus(); if (ModemStatus.isSet(status, ModemStatus.cts)) { debugPrint('CTS 高电平'); } ``` - `ModemStatus` 暴露位掩码常量 `cts(0x01) / dsr(0x02) / ri(0x04) / dcd(0x08)` 与工具方法 `isSet(status, mask)`,取值与文档表格一致。 - `getModemStatus()` 返回**最近一次由 SDK 回调推送的位掩码**; 若 SDK 尚未推送过任何状态,返回 0。业务方注意判空。 ### 3.6 异常回调 ```dart final sub = await plugin.setExceptionCallback((event) { debugPrint('设备异常: ${event.type} ${event.message}'); // 业务方应主动关闭串口、刷新设备列表或提示用户重新插拔 }); // 主动取消监听 await sub.cancel(); ``` - 异常类型见 `Ch934xExceptionType`: - `deviceDetached = 1`:设备被拔出(由 SDK 的 `usbDeviceDetach` 触发)。 - `ioError = 2`:Modem overrun / parity / frame 等错误。 - `sdk = 3`:原生 SDK 主动抛出的其他异常(目前未触发,保留语义)。 - `unknown = 0`:未识别(当前未触发,保留语义)。 - `Ch934xException` 包含 `type / message / cause`,`toString()` 会把 `type` 翻译为对应的常量名,方便日志/UI 显示。 - 返回的 `StreamSubscription` **必须在合适时机 `cancel`**,以便释放底层 `StreamController` 与 `MethodCallHandler`。 ### 3.7 其他接口 #### 3.7.1 Break 信号 ```dart final ok = await plugin.setBreak(true); // 设置 Break(低电平有效) ``` - 作用于**当前活跃串口**。 #### 3.7.2 获取当前串口模式 ```dart final mode = await plugin.getCurrentMode(); // mode 取值见 Ch934xMode 常量 ``` - `Ch934xMode` 常量: `normal = 0`(普通)、`hardflow = 1`(硬件流控)、`gpio = 2`(GPIO)。 - **仅对 CH934X 型号有效**,CH348 返回 -1。 #### 3.7.3 设备连接状态 ```dart final connected = await plugin.isConnected(device.deviceId); final ids = await plugin.getConnectedDevices(); ``` - `isConnected`: 查询指定设备是否已被打开。 - `getConnectedDevices`: 返回当前已打开设备的 `deviceId` 列表。 ### 3.8 串口参数配置 ```dart // 配置波特率为 9600 final ok = await plugin.setSerialParameter( baud: 9600, dataBit: 8, stopBit: 1, parityBit: 0, flow: false, ); ``` - 作用于**当前活跃串口**。`openPort` 内部默认设为 `115200/8/1/N/无流控`, 如需修改可在此之后调用。 - `stopBit`: 0=1 停止位,1=1.5 停止位,2=2 停止位。 - `parityBit`: 0=无校验,1=奇校验,2=偶校验。 --- ## 4. 完整示例 ```dart final sub = await plugin.setExceptionCallback((event) { debugPrint('设备异常: ${event.type} ${event.message}'); // 业务方应主动关闭串口、刷新设备列表或提示用户重新插拔 }); // 主动取消监听 await sub.cancel(); ``` - 异常类型见 `Ch934xExceptionType`: - `deviceDetached = 1`:设备被拔出(由 SDK 的 `usbDeviceDetach` 触发)。 - `ioError = 2`:Modem overrun / parity / frame 等错误。 - `sdk = 3`:原生 SDK 主动抛出的其他异常(目前未触发,保留语义)。 - `unknown = 0`:未识别(当前未触发,保留语义)。 - `Ch934xException` 包含 `type / message / cause`,`toString()` 会把 `type` 翻译为对应的常量名,方便日志/UI 显示。 - 返回的 `StreamSubscription` **必须在合适时机 `cancel`**,以便释放底层 `StreamController` 与 `MethodCallHandler`。 --- ## 4. 完整示例下面给出一个最小可运行示例,演示"扫描 → 打开 → 收发 → 关闭"的完整流程,完整可交互的 demo 见 `example/lib/main.dart`。 ```dart import 'dart:async'; import 'dart:typed_data'; import 'package:ch934x_serial/ch934x_serial.dart'; class SerialBridge { SerialBridge() : _plugin = Ch934xSerial(); final Ch934xSerial _plugin; StreamSubscription? _exceptionSub; StreamSubscription? _dataSub; Future connect(Ch934xDeviceInfo device, Ch934xSerialPortInfo port) async { final opened = await _plugin.openPort( Ch934xPortTarget( deviceId: device.deviceId, interfaceNumber: 0, serialPortIndex: port.portIndex, ), ); if (!opened) throw StateError('串口打开失败'); _exceptionSub = await _plugin.setExceptionCallback((e) { // 设备拔出时通常会触发 deviceDetached。 print('异常: $e'); }); _dataSub = _plugin.dataStream().listen((chunk) { print('接收: $chunk'); }); } Future sendString(String s) async { final bytes = Uint8List.fromList(s.codeUnits); await _plugin.write(bytes); } /// 切换到同一设备的另一个串口,无需重新 open。 Future switchToPort(int index) async { await _plugin.setActivePort(index); } Future dispose() async { await _dataSub?.cancel(); await _exceptionSub?.cancel(); await _plugin.closePort(); } } ``` --- ## 5. 平台接口与单元测试插件使用 `plugin_platform_interface` 暴露抽象层 `Ch934xSerialPlatform`, 默认实现是 `MethodChannelCh934xSerial`(绑定到 `ch934x_serial` 通道)。注入自定义平台实现即可在宿主测试中验证上层逻辑,无需启动 Android: ```dart import 'package:ch934x_serial/ch934x_serial.dart'; import 'package:ch934x_serial/ch934x_serial_method_channel.dart'; import 'package:ch934x_serial/ch934x_serial_platform_interface.dart'; import 'package:flutter_test/flutter_test.dart'; import 'package:plugin_platform_interface/plugin_platform_interface.dart'; class FakePlatform extends Ch934xSerialPlatform with MockPlatformInterfaceMixin { @override Future> getDeviceList() async => const []; // ... 其它方法按需返回 } void main() { TestWidgetsFlutterBinding.ensureInitialized(); test('替换为 mock 后 Ch934xSerial 委托给 fake', () async { Ch934xSerialPlatform.instance = FakePlatform(); final plugin = Ch934xSerial(); expect(await plugin.getDeviceList(), isEmpty); }); } ``` 也可以直接用 `Ch934xSerial.withPlatform(fake)` 局部注入,避免污染 `Ch934xSerialPlatform.instance`。完整 mock 示例见 `test/ch934x_serial_test.dart` 与 `test/ch934x_serial_method_channel_test.dart`。 --- ## 6. 常见问题(FAQ) **Q1. `getDeviceList()` 返回空数组。** - 确认 OTG 数据线连接稳固。 - 部分设备需要先在系统设置中开启"USB 调试"或插入 OTG 后等几秒。 - 确认 `minSdk >= 24`。 **Q2. `openPort()` 返回 false。** - 多数情况是 USB 权限未授予:确认 `requestUsbPermission` / `openPort` 内部弹出的授权框被用户点击了"允许"。 - 如果目标设备具有多个接口,请尝试修改 `interfaceNumber`。 - 确认设备中至少有一个 `Ch934xSerialPortInfo`(`getSerialPortList` 返回),否则原 SDK 也无法打开。**注意:** 该方法必须先 `openPort` 才返回真实数据,枚举阶段调用只会得到空列表。 **Q3. `read()` 一直返回空数组。** - 确认对端设备正在发送数据,且波特率/校验位等参数匹配。可通过 `setSerialParameter(baud: 9600, dataBit: 8, stopBit: 1, parityBit: 0, flow: false)` 配置串口参数。 - 检查线序:RX/TX 是否接反,以及硬件流控是否正确。 - 确认 `setActivePort` 已切换到正确的串口索引。 **Q4. `setExceptionCallback` 没有触发。** - 本插件仅在原生层主动推送时才会触发回调,目前沁恒 SDK 在以下场景会自动调用:设备热拔插(`usbDeviceDetach`)、USB 权限被拒绝(`usbDevicePermission(result=false)`)、Modem overrun / parity / frame 错误。其他异常(超时、CRC 错误等)目前不会触发,可在原生层 `Ch934xSerialPlugin.java` 中扩展 `MethodChannel.invokeMethod("onException", payload)` 上报。 **Q5. 是否支持 iOS / 桌面 / Web?** - 当前仅在 Android 端验证通过;`CH934XLib.jar` 由沁恒官方提供 Android 端 SDK,其他平台需要厂商另行提供或自行实现。 **Q6. 如何做单元测试?** - 注入自定义的 `Ch934xSerialPlatform` 即可,详见 §5。 **Q7. 同一设备如何在多个串口之间切换?** - 使用 `setActivePort(serialPortIndex)`,无需重新 `openPort`。 `openPort` 之后该设备的所有串口都已连接,后续读写/GPIO/Modem 都作用于"当前活跃串口"。 **Q8. Android 侧需要哪些初始化?** - 插件自带 ``。 - 业务侧不需要在 `AndroidManifest.xml` 中声明 USB 权限 `BroadcastReceiver`——插件会在需要时动态注册(`NOT_EXPORTED`)。 - 若希望应用启动即初始化 SDK,可在 `Application.onCreate` 中调用 `CH934XManager.getInstance().init(this)`;不调用也不影响插件工作,插件会在 `onAttachedToEngine` 兜底初始化。 --- ## 7. 接口总览下表汇总插件中暴露的全部 API,具体调用示例见上文第 3 节。 | Dart 方法 | 文档编号 | 分类 | | --------- | -------- | ---- | | `getDeviceList` | 4.1.4 | 设备查找 | | `getSerialNumber` | 4.1.1 | 设备查找 | | `getDeviceType` | 4.1.2 | 设备查找 | | `getSerialPortList` | 4.1.3 | 设备查找 | | `openPort` | 5.1.1 | 设备打开 | | `closePort` | 5.2.1 | 设备关闭 | | `setActivePort` | 5.1 增强 | 串口切换(插件新增) | | `requestUsbPermission` | 2.2 增强 | 主动授权(插件新增) | | `read` | 6.1.1 | 串口读写 | | `write` | 6.2.1 | 串口读写 | | `setSerialParameter` | setSerialParameter | 串口参数 | | `setBreak` | setBreak | 其他 | | `getCurrentMode` | getCurrentMode | 其他 | | `isConnected` | isConnected | 设备状态 | | `getConnectedDevices` | getConnectedDevices | 设备状态 | | `setGpioOutput` | setGPIOValue | GPIO | | `getGpioInput` | getGPIOValue | GPIO | | `setGpioDir` | setGPIODir | GPIO 方向 | | `queryGpioDirFromCache` | queryGPIODirFromCache | GPIO 方向 | | `enableGpio` | enableGPIO | GPIO | | `getGpiocount` | getGPIOCount | GPIO | | `getGpiogroup` | getGPIOGroup | GPIO | | `setModemControl` | 7.2.1 | Modem | | `getModemStatus` | 7.2.2 | Modem | | `setExceptionCallback` | 7.3.1 | 异常 | | `dataStream` | 6.1 增强 | 串口流(插件新增) | | `portDataStream` | 6.1 增强 | 多端口轮询流(插件新增) | --- ## 8. 反馈与贡献遇到问题请提供: - 复现步骤(设备型号、Android 版本、是否开启 USB 调试) - 完整日志(建议使用 `adb logcat` 过滤 `ch934x_serial` 标签) - 期望结果 vs 实际结果提交 Issue 时附上以上信息可以大幅加快排查速度。