diff --git a/docs/CH934X_Plugin_使用说明.md b/docs/CH934X_Plugin_使用说明.md index c21647f..077f996 100644 --- a/docs/CH934X_Plugin_使用说明.md +++ b/docs/CH934X_Plugin_使用说明.md @@ -14,14 +14,18 @@ Android SDK 封装的 Flutter 插件,文档面向其他 Flutter 开发者,介绍 - **支持的平台:** Android(已实现,iOS / Web / Desktop 暂不支持)。 - **主要能力:** - CH934X 设备枚举、序列号读取、芯片类型识别 - - 多串口打开 / 关闭 + - 多串口打开 / 关闭 / **同设备内串口切换** - 字节级串口读写 - GPIO 输出 / 输入 - Modem 控制 (DTR/RTS) 与状态 (CTS/DSR/RI/DCD) 读取 - - 设备拔出等异常事件回调 + - **主动申请 USB 权限** + - 设备拔出、Modem 错误等异常事件回调 - **底层依赖:** 沁恒官方 `CH934XLib.jar`(插件随包发布,位于 - `android/libs/CH934XLib.jar`),通过反射方式桥接,无需在调用方 - 业务代码中额外处理。 + `android/libs/CH934XLib.jar`),通过原生 `CH934XManager` 单例直接调用, + 无需在调用方业务代码中额外处理反射。 +- **平台通道名称:** `ch934x_serial` +- **Dart 包名:** `ch934x_serial`(主类 `Ch934xSerial`) +- **Android 包名:** `com.xiarui.ch934x_serial` --- @@ -42,48 +46,19 @@ dependencies: 1. 确认 `android/app/build.gradle` 中 `minSdk >= 24`,CH934X SDK 不支持 更低版本。 -2. 在 `android/app/src/main/AndroidManifest.xml` 中声明 USB Host 能力: +2. **无需在 `AndroidManifest.xml` 中声明 USB Host 能力**——插件自带 + `android/src/main/AndroidManifest.xml` 已声明 + ``, + 应用侧合并后即可生效。 +3. **USB 权限处理可省略**——`openPort` 在底层若检测到未授权,会自动 + 调用 `UsbManager.requestPermission` 弹出系统对话框并等待用户回应; + 也可以在业务侧通过 `requestUsbPermission(deviceId)` 提前主动申请。 + 插件内部 `BroadcastReceiver` 会在需要时动态注册/反注册,无需在 + `AndroidManifest.xml` 中额外声明。 - ```xml - - ``` - -3. **运行时申请 USB 权限**。本插件不主动申请权限,需业务方调用 - Android `UsbManager` 申请并接收广播,例如在 `MainActivity.onCreate` - 中: - - ```kotlin - private val actionDevicePermission = "com.example.USB_PERMISSION" - private val usbPermissionReceiver = object : BroadcastReceiver() { - override fun onReceive(context: Context, intent: Intent) { - if (intent.action != actionDevicePermission) return - val device: UsbDevice? = - intent.getParcelableExtra(UsbManager.EXTRA_DEVICE) - val granted = - intent.getBooleanExtra(UsbManager.EXTRA_PERMISSION_GRANTED, false) - if (granted && device != null) { - // 此处可继续打开串口 - } - } - } - - override fun onCreate(savedInstanceState: Bundle?) { - super.onCreate(savedInstanceState) - val usbManager = getSystemService(Context.USB_SERVICE) as UsbManager - val pendingIntent = PendingIntent.getBroadcast( - this, 0, Intent(actionDevicePermission), 0 - ) - registerReceiver(usbPermissionReceiver, IntentFilter(actionDevicePermission)) - usbManager.deviceList.values.forEach { device -> - usbManager.requestPermission(device, pendingIntent) - } - } - ``` - - 也可以监听 `UsbManager.ACTION_USB_DEVICE_ATTACHED` 让系统在插入设备 - 时主动弹出授权框。 +> 如果你仍想自己接管权限流程(例如在主界面"刷新设备列表"之后 +> 立刻弹一次授权请求),直接调用 `Ch934xSerial.requestUsbPermission` +> 即可,内部会等待用户的回应并以 `bool` 返回结果。 ### 2.3 第一次调用 @@ -100,7 +75,10 @@ Future scan() async { } ``` -> 如果调用后列表为空,请先确认已经完成第 2.2 步的 USB 权限申请。 +> **注意:** `getSerialPortList` 在设备尚未 `openPort` 时会返回空 +> 列表,因为 SDK 的 `getSerialCount` 必须先 `openDevice` 才能返回 +> 真实值。完整流程是:扫描 → 选设备 → `openPort` → +> `getSerialPortList` 拿真实串口数,详见 §3.2。 --- @@ -113,10 +91,10 @@ Future scan() async { | Dart 方法 | 原 SDK 接口 | 说明 | | --------- | ----------- | ---- | -| `getDeviceList()` | `UsbHelper.getCH934XDeviceList` | 获取全部 CH934X 设备 | -| `getSerialNumber(deviceId)` | `UsbHelper.CH934XSerialNum` | 获取指定设备的序列号 | -| `getDeviceType(deviceId)` | `UsbHelper.CH934XDeviceType` | 获取设备类型常量 | -| `getSerialPortList(deviceId, interfaceNumber: n)` | `UsbHelper.getCH934XSerialPortList` | 获取设备串口列表 | +| `getDeviceList()` | `CH934XManager.enumDevice` + `getChipType` | 获取全部 CH934X 设备 | +| `getSerialNumber(deviceId)` | `UsbDevice.getSerialNumber` | 获取指定设备的序列号 | +| `getDeviceType(deviceId)` | `CH934XManager.getChipType` | 获取设备类型常量 | +| `getSerialPortList(deviceId, interfaceNumber: n)` | `CH934XManager.getSerialCount` | 获取设备串口列表(需先 `openPort`) | 返回类型: @@ -125,10 +103,13 @@ Future scan() async { - `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 设备打开与关闭 +### 3.2 设备打开、关闭与串口切换 ```dart final target = Ch934xPortTarget( @@ -146,9 +127,32 @@ await plugin.closePort(); ``` - `Ch934xPortTarget` 封装了 `deviceId` / `interfaceNumber` / - `serialPortIndex` 三个参数,可通过 `toMap()` 调试其字段。 + `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 块中清理。 + 串口前请先 `closePort()` 或在 `finally` 块中清理。 ### 3.3 串口读写 @@ -171,9 +175,16 @@ await sub.cancel(); ``` - `read(length)` 返回 `Uint8List`,无数据或失败时为空。 + - `length <= 0` 时**不会调用原生层**,直接返回空数组。 + - SDK 的 `readData` 会返回内部缓冲的所有数据,插件按 + `min(data.length, length)` 截断后回传。 - `write(data)` 返回实际写入字节数,失败时为 0。 -- `dataStream` 默认每 20ms 轮询一次,可调整 `interval` 与 `chunkSize`。 - 业务方在 widget dispose 时记得 `cancel` 订阅并 `closePort`。 +- `dataStream` 默认 `chunkSize = 1024`、`interval = 20ms`,内部 + 持续以 [interval] 为周期反复调用 `read`;当底层无数据时返回 + 空缓冲区,消费者可据此判定。`chunkSize <= 0` 会抛 + `ArgumentError`。 +- 业务方在 widget dispose 时记得 `cancel` 订阅并 `closePort`。 +- `read`/`write` 都针对**当前活跃串口**;切换串口用 `setActivePort`。 ### 3.4 GPIO 接口 @@ -184,6 +195,7 @@ final value = await plugin.getGpioInput(0); // 负值表示失败 - `gpioNumber` 与 `level` 与原文档保持一致(0/1)。 - `getGpioInput` 失败时返回 -1,业务方需要自行处理。 +- GPIO 操作同样作用于**当前活跃串口**。 ### 3.5 Modem 控制接口 @@ -195,9 +207,10 @@ if (ModemStatus.isSet(status, ModemStatus.cts)) { } ``` -- `ModemStatus` 暴露位掩码常量 `cts / dsr / ri / dcd` 与工具方法 - `isSet(status, mask)`,取值与文档表格一致。 -- `getModemStatus()` 返回 0 时表示无有效状态,业务方注意判空。 +- `ModemStatus` 暴露位掩码常量 `cts(0x01) / dsr(0x02) / ri(0x04) / + dcd(0x08)` 与工具方法 `isSet(status, mask)`,取值与文档表格一致。 +- `getModemStatus()` 返回**最近一次由 SDK 回调推送的位掩码**; + 若 SDK 尚未推送过任何状态,返回 0。业务方注意判空。 ### 3.6 异常回调 @@ -211,10 +224,15 @@ final sub = await plugin.setExceptionCallback((event) { await sub.cancel(); ``` -- 异常类型见 `Ch934xExceptionType`(`deviceDetached / ioError / sdk / - unknown`)。 -- 返回的 `StreamSubscription` 需要在合适时机 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`。 --- @@ -261,6 +279,11 @@ class SerialBridge { await _plugin.write(bytes); } + /// 切换到同一设备的另一个串口,无需重新 open。 + Future switchToPort(int index) async { + await _plugin.setActivePort(index); + } + Future dispose() async { await _dataSub?.cancel(); await _exceptionSub?.cancel(); @@ -271,32 +294,70 @@ class SerialBridge { --- -## 5. 常见问题(FAQ) +## 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()` 返回空数组。** -- 确认已声明 ``。 -- 确认 Android `UsbManager` 已对目标设备授权(系统会弹出对话框,需要 - 用户点击"允许")。 -- 确认 OTG 数据线连接稳固,并尝试调用 `setExceptionCallback` 监听 - `deviceDetached` 事件,排查设备是否被系统频繁弹出。 +- 确认 OTG 数据线连接稳固。 +- 部分设备需要先在系统设置中开启"USB 调试"或插入 OTG 后等几秒。 +- 确认 `minSdk >= 24`。 **Q2. `openPort()` 返回 false。** -- 多数情况是 USB 权限未授予;请在 `UsbManager.requestPermission` - 返回 true 后再调用 `openPort`。 +- 多数情况是 USB 权限未授予:确认 `requestUsbPermission` / + `openPort` 内部弹出的授权框被用户点击了"允许"。 - 如果目标设备具有多个接口,请尝试修改 `interfaceNumber`。 - 确认设备中至少有一个 `Ch934xSerialPortInfo`(`getSerialPortList` - 返回),否则原 SDK 也无法打开。 + 返回),否则原 SDK 也无法打开。**注意:** 该方法必须先 `openPort` + 才返回真实数据,枚举阶段调用只会得到空列表。 **Q3. `read()` 一直返回空数组。** - 确认对端设备正在发送数据,且波特率/校验位等参数与原 SDK 默认值 一致(`CH934XLib` 提供独立的 `setConfig` 接口,本插件当前未做 - 封装,需要时可扩展原 SDK 反射调用)。 + 封装,需要时可扩展原 SDK 直接调用)。 - 检查线序:RX/TX 是否接反,以及硬件流控是否正确。 +- 确认 `setActivePort` 已切换到正确的串口索引。 **Q4. `setExceptionCallback` 没有触发。** -- 本插件仅在原生层主动推送时才会触发回调,目前沁恒 SDK 在设备热拔 - 插场景下会自动调用,其他异常(超时、CRC 错误等)可能不会触发。 - 如需丰富事件类型,可在原生层 `Ch934xSerialPlugin.java` 中扩展 +- 本插件仅在原生层主动推送时才会触发回调,目前沁恒 SDK 在以下 + 场景会自动调用:设备热拔插(`usbDeviceDetach`)、USB 权限被 + 拒绝(`usbDevicePermission(result=false)`)、Modem overrun / + parity / frame 错误。其他异常(超时、CRC 错误等)目前不会 + 触发,可在原生层 `Ch934xSerialPlugin.java` 中扩展 `MethodChannel.invokeMethod("onException", payload)` 上报。 **Q5. 是否支持 iOS / 桌面 / Web?** @@ -304,27 +365,26 @@ class SerialBridge { Android 端 SDK,其他平台需要厂商另行提供或自行实现。 **Q6. 如何做单元测试?** -- 注入自定义的 `Ch934xSerialPlatform` 即可: +- 注入自定义的 `Ch934xSerialPlatform` 即可,详见 §5。 - ```dart - class FakePlatform extends Ch934xSerialPlatform - with MockPlatformInterfaceMixin { - @override - Future> getDeviceList() async => const []; - // ... 其它方法按需返回 - } +**Q7. 同一设备如何在多个串口之间切换?** +- 使用 `setActivePort(serialPortIndex)`,无需重新 `openPort`。 + `openPort` 之后该设备的所有串口都已连接,后续读写/GPIO/Modem + 都作用于"当前活跃串口"。 - Ch934xSerialPlatform.instance = FakePlatform(); - final plugin = Ch934xSerial(); - ``` - - 插件仓库的 `test/ch934x_serial_test.dart` 给出了完整 mock 示例。 +**Q8. Android 侧需要哪些初始化?** +- 插件自带 ``。 +- 业务侧不需要在 `AndroidManifest.xml` 中声明 USB 权限 + `BroadcastReceiver`——插件会在需要时动态注册(`NOT_EXPORTED`)。 +- 若希望应用启动即初始化 SDK,可在 `Application.onCreate` 中 + 调用 `CH934XManager.getInstance().init(this)`;不调用也不影响 + 插件工作,插件会在 `onAttachedToEngine` 兜底初始化。 --- -## 6. 接口总览 +## 7. 接口总览 -下表汇总了插件中暴露的全部 API,具体调用示例见上文第 3 节。 +下表汇总插件中暴露的全部 API,具体调用示例见上文第 3 节。 | Dart 方法 | 文档编号 | 分类 | | --------- | -------- | ---- | @@ -334,6 +394,8 @@ class SerialBridge { | `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 | 串口读写 | | `setGpioOutput` | 7.1.1 | GPIO | @@ -345,7 +407,7 @@ class SerialBridge { --- -## 7. 反馈与贡献 +## 8. 反馈与贡献 遇到问题请提供: