调试与问题排查

本文介绍 JL_OTA_Flutter（杰理 OTA SDK for Flutter）的调试基础设施与常见问题排查方法，涵盖 SDK 日志输出、日志查看方式、日志文件管理 API、PlatformException 错误处理模式，以及 OTA 连接/升级失败时的标准排查流程。

目的与范围

本页面向集成 JL_OTA_Flutter SDK 的开发者与测试人员，系统说明：

• SDK 的日志输出机制与各平台日志查看方式（Android Logcat / iOS Console）
• 日志文件管理 API（获取目录、列出文件、选择、删除、分享）
• 统一的 PlatformException 错误处理模式与设计意图
• BLE 连接、MTU、OTA 升级失败等常见问题的排查路径
• 版本信息查询在问题定位中的作用与官方反馈渠道

本页不包含：SDK 的完整收发接口逐条说明（见仓库 doc/ 下的《Jieli OTA Upgrade (Flutter) Send/Receive Interface Introduction》）、SDK 接入与配置步骤（见 README「快速开始」「配置说明」章节）、以及 Android/iOS 原生 SDK 内部的详细调试命令（官方文档中心另有专门页面）。对于底层原生 SDK 的调试细节，请参考官方文档中心的 Android SDK 调试说明 与 iOS SDK 调试说明。

概述

JL_OTA_Flutter 是珠海市杰理科技股份有限公司为杰理蓝牙类产品（AC707N、AC703N、AC701N、AC697N、AC696N、AC695N 等支持 RCSP OTA 的芯片）提供的 Flutter 固件升级 SDK，支持 BLE、SPP、Gatt Over BR/EDR 等传输方式（见 README.md）。

在调试与排查维度上，该 SDK 的设计呈现以下特点：

1. 日志即接口：SDK 提供详细日志输出，可通过日志查看 OTA 连接状态和数据交互；同时提供一整套日志文件管理接口（getLogFileDirPath / getLogFiles / clickLogFileIndex / deleteAllLogFiles / shareLogFile），使开发者能够把设备端 SDK 的日志文件导出出来做事后分析——这是 OTA 这类"偶发失败难复现"问题的关键排查手段。
2. 统一错误模型：所有 Dart 侧发送接口都遵循同一错误处理模板——try { invokeMethod(...) } on PlatformException catch (e) { print(...); rethrow; }。原生端任何失败都以 PlatformException 形式穿透到 Flutter 侧，消息体携带失败原因，调用方必须处理或向上传播。
3. 版本可查：getSdkVersion() 与 getAppVersion() 用于在排查时确认 SDK/APP 版本是否匹配固件升级要求（例如 V1.1.0 修复了 iOS 端 OTA 回连超时问题，见 README.md）。
4. 排查链路完整：从"实时日志"（Logcat/Console）到"离线日志文件"再到"官方问题反馈"（GitHub Issues），形成闭环。

架构

flowchart TD
    subgraph sg_App["应用层 (Flutter App)"]
        UI["App UI / 业务逻辑"]
        BleMethod["BleMethod 发送接口"]
        BleEventStream["BleEventStream 接收接口"]
    end

    subgraph sg_Channel["MethodChannel 桥接层"]
        MC["MethodChannel"]
    end

    subgraph sg_Native["原生插件层"]
        AndroidPlugin["JlOtaPlugin (Android/Kotlin)"]
        IOSPlugin["JlOtaPlugin (iOS/Swift)"]
        LogFile["日志文件管理"]
    end

    subgraph sg_Device["蓝牙设备"]
        Device["杰理蓝牙芯片 (RCSP OTA)"]
    end

    UI --> BleMethod
    UI --> BleEventStream
    BleMethod -->|"invokeMethod 发送指令"| MC
    BleEventStream -->|"EventChannel 接收事件"| MC
    MC --> AndroidPlugin
    MC --> IOSPlugin
    AndroidPlugin --> LogFile
    IOSPlugin --> LogFile
    AndroidPlugin -->|"BLE / SPP"| Device
    IOSPlugin -->|"BLE / Gatt Over BR/EDR"| Device

架构说明：

• **Dart 层（BleMethod / BleEventStream）**是开发者直接使用的收发接口。BleMethod 负责发送（含上述日志文件管理、版本查询、MTU 设置等全部命令），BleEventStream 负责接收设备事件。调试信息（如连接失败）在接收侧通过 log() 输出（见 接口介绍文档）。
• MethodChannel 是 Dart 与原生之间的唯一桥接通道，所有命令常量定义在 BleMethodConstants 中（如 METHOD_GET_LOG_FILE_DIR_PATH、METHOD_GET_LOG_FILES、METHOD_DELETE_ALL_LOG_FILE 等）。
• 原生插件层：Android 端与 iOS 端同为 JlOtaPlugin，分别基于 Kotlin/Swift 实现，负责 BLE/SPP 连接管理、OTA 流程与日志文件读写。这一层是 PlatformException 的产生源头。
• 日志文件由原生端管理，Flutter 侧只能通过方法通道间接操作，这保证了日志的完整性与文件系统隔离。

调试基础设施

SDK 日志输出

SDK 在运行过程中持续输出日志，覆盖 OTA 连接状态与数据交互过程。README「调试技巧」章节明确说明：

日志输出：SDK提供详细的日志输出，可通过日志查看OTA连接状态和数据交互

（见 README.md）

此外，Dart 侧每个方法在异常路径上都会输出 print("Failed to ...: ${e.message}")，接收侧在连接/断开失败时使用 log("Failed to connect to device: $e") 输出。也就是说，任何一次失败的交互都会留下日志痕迹，这是定位问题的基础。

日志查看方式

（见 README.md）

当实时日志不足以定位问题时，README 指引开发者前往官方文档中心查阅原生 SDK 的调试说明（Android 与 iOS 各有一份），那里包含更底层的调试命令与协议细节。

日志文件管理

SDK 原生层会把运行日志写入本地文件。Flutter 侧通过 5 个方法管理这些日志文件（见 接口介绍文档）：

设计意图：OTA 失败往往依赖设备端上下文（信号强度、时序、协议交互记录），仅靠实时日志难以覆盖"用户手机上报问题时已无法复现"的场景。日志文件管理 API 让 App 可以在用户侧一键导出完整日志，实现事后回溯式排查——这是该类 SDK 调试链路中最重要的一环。

错误处理模式（PlatformException）

SDK 的 Dart 侧所有方法使用统一的错误处理模板：调用 invokeMethod 时捕获 PlatformException，先 print 输出失败信息，再 rethrow 将异常抛给调用方。以日志文件目录查询为例（接口介绍文档）：

static Future<String> getLogFileDirPath() async {
    try {
      return await _methodChannel.invokeMethod(
            BleMethodConstants.METHOD_GET_LOG_FILE_DIR_PATH,
          ) ??
          '';
    } on PlatformException catch (e) {
      print("Failed to get log file directory path: ${e.message}");
      rethrow;
    }
  }

来源：Jieli OTA Upgrade (Flutter) Send:Receive Interface Introduction.md

这一模式的设计意图有三层：

1. 失败可见：print 保证失败信息一定出现在日志流中，与上文"日志即接口"的理念一致；
2. 失败可传播：rethrow 不吞掉异常，调用方（App 层）可以决定是弹提示、重试还是上报，符合 Flutter 的异常传播约定；
3. 失败可预期：所有方法失败时抛出的都是 PlatformException，App 侧只需一种 catch 类型即可统一处理，无需针对不同方法编写不同异常分支。

接收侧（事件流）的错误处理则采用 catch (e) + log() 的方式，例如连接失败：

    } catch (e) {
      log("Failed to connect to device: $e");
      // Optionally show an error message to the user

来源：Jieli OTA Upgrade (Flutter) Send:Receive Interface Introduction.md

发送侧用 print+rethrow、接收侧用 log+可选提示，二者互补：前者强调调用链上异常不丢失，后者强调异步事件失败不中断主流程。

核心排查流程

一次典型的 OTA 问题排查，遵循"复现 → 取日志 → 分析 → 反馈"的路径。其中日志文件的获取与分享是整个流程的关键环节：

sequenceDiagram
    participant Dev as 开发者/测试
    participant App as App (Flutter)
    participant MC as MethodChannel
    participant Plugin as 原生插件 (JlOtaPlugin)
    participant Log as 日志文件系统

    Dev->>App: 复现 OTA 失败问题
    App->>MC: getLogFileDirPath()
    MC->>Plugin: METHOD_GET_LOG_FILE_DIR_PATH
    Plugin-->>App: 日志目录路径
    App->>MC: getLogFiles()
    MC->>Plugin: METHOD_GET_LOG_FILES
    Plugin-->>App: 日志文件列表
    App->>MC: clickLogFileIndex(index)
    MC->>Plugin: METHOD_LOG_FILE_INDEX
    Plugin-->>App: 选中日志文件
    App->>MC: shareLogFile(index)
    MC->>Plugin: 原生分享日志文件
    Plugin->>Log: 读取日志内容
    Plugin-->>App: 分享完成/异常
    App->>Dev: PlatformException 或成功提示
    Dev->>Dev: 分析日志、核对版本、定位根因

完整排查决策路径如下：

flowchart TD
    Start([发现问题]) --> Env["确认环境<br/>Android 6.0+ / iOS 12.0+<br/>芯片支持 RCSP OTA"]
    Env --> Conn{"连接失败?"}
    Conn -->|"是"| Logs["查看实时日志<br/>Logcat / Xcode Console"]
    Logs --> Err{"日志中出现异常?"}
    Err -->|"是"| Exc["读取 PlatformException.message"]
    Err -->|"否"| MTU["检查 MTU 设置<br/>setBleRequestMtu(500)"]
    Exc --> OTA{"OTA 升级失败?"}
    MTU --> OTA
    OTA -->|"是"| Export["获取并分享日志文件<br/>getLogFiles + shareLogFile"]
    OTA -->|"否"| Ver["核对版本<br/>getSdkVersion / getAppVersion"]
    Export --> Issue["反馈至 GitHub Issues<br/>附日志与版本信息"]
    Ver --> Issue
    Issue --> End([定位并解决])

各环节要点：

• 环境确认：SDK 要求 Android 6.0+、iOS 12.0+，且设备芯片需支持 RCSP OTA（见 README.md），不满足条件时问题可能并非 SDK 缺陷；
• 实时日志优先：连接失败/断开、数据交互异常都会输出日志，先用 Logcat/Console 缩小范围；
• MTU 是高频根因：BLE 数据交互失败常见于 MTU 协商过小，可调用 setBleRequestMtu(500) 调整（见 接口介绍文档）；
• 离线日志兜底：无法现场复现时，依靠日志文件管理 API 导出设备端日志；
• 版本对齐：iOS 端 OTA 回连超时问题已在 V1.1.0 修复（见 README.md），排查前先确认 SDK 版本，避免上报已修复的问题。

使用示例

获取日志文件目录路径

使用示例:await BleMethod.getLogFileDirPath();

来源：Jieli OTA Upgrade (Flutter) Send:Receive Interface Introduction.md

获取并选中日志文件

使用示例:await BleMethod.getLogFiles();
使用示例:await BleMethod.clickLogFileIndex(1); // 1:当前logFileIdnex

来源：Jieli OTA Upgrade (Flutter) Send:Receive Interface Introduction.md

清理与导出日志

使用示例:await BleMethod.deleteAllLogFiles();
使用示例:await BleMethod.shareLogFile(/* 目标日志文件索引 */);

来源：Jieli OTA Upgrade (Flutter) Send:Receive Interface Introduction.md

deleteAllLogFiles 返回 Future<bool> 表示删除结果；shareLogFile 需要传入有效的日志文件索引，分享前建议先调用 getLogFiles() 刷新列表。

设置 BLE MTU

使用示例:await BleMethod.setBleRequestMtu(500);

来源：Jieli OTA Upgrade (Flutter) Send:Receive Interface Introduction.md

当升级过程中出现数据包交互异常、传输卡顿时，可尝试将 MTU 调大（示例为 500），观察日志中交互是否恢复正常。

核对 SDK 与 APP 版本

使用示例:await BleMethod.getSdkVersion();
使用示例:await BleMethod.getAppVersion();

来源：Jieli OTA Upgrade (Flutter) Send:Receive Interface Introduction.md

版本信息用于：确认是否已包含已知问题修复（如 iOS 回连超时）、确认 SDK 与固件/芯片能力匹配、以及在反馈问题时报出准确环境信息。

配置选项

SDK 本身不通过配置文件暴露调试开关，调试相关"配置"主要体现在运行环境约束与运行期可调参数上：

（环境与能力信息见 README.md 与 README.md）

API 参考

以下均为调试与排查直接相关的方法。所有方法在原生端调用失败时都会抛出 PlatformException，message 字段携带失败原因，调用方需捕获处理（各方法内部已 print 并 rethrow）。

getLogFileDirPath(): Future<String>

获取 SDK 日志文件的目录路径。用于向用户展示日志存储位置。

• 返回：日志文件目录路径字符串；失败时抛 PlatformException。

getLogFiles(): Future<void>

触发原生端获取日志文件列表。调用后应等待事件流刷新，再通过 clickLogFileIndex 选择。

• 返回：无；失败时抛 PlatformException。

clickLogFileIndex(logFileIndex: int): Future<void>

按索引选中一份日志文件，为后续 shareLogFile 做准备。

参数：

• logFileIndex (int)：日志文件在列表中的索引，从 0 开始。

返回：无；失败时抛 PlatformException。

deleteAllLogFiles(): Future<bool>

删除全部日志文件，用于清理历史日志后重新复现问题。

• 返回：bool，删除是否成功；失败时抛 PlatformException。

shareLogFile(logFileIndex: int): Future<void>

分享指定索引的日志文件（调起系统分享），用于把日志导出给技术支持分析。

参数：

• logFileIndex (int)：目标日志文件索引。

返回：无；失败时抛 PlatformException。

setBleRequestMtu(mtu: int): Future<void>

设置 BLE 请求 MTU 大小，用于优化大数据传输（如 OTA 固件包下发）。

参数：

• mtu (int)：请求的 MTU 值，示例 500。

返回：无；失败时抛 PlatformException。

getSdkVersion(): Future<String>

获取 SDK 版本号，用于确认是否包含已知问题修复。

• 返回：版本号字符串（如 V1.1.0）；失败时返回 'V?.?.?(?)' 或抛 PlatformException。

getAppVersion(): Future<String>

获取 APP 版本号，用于排查时对齐 App 与 SDK 版本。

• 返回：版本号字符串；失败时返回 'V?.?.?(?)' 或抛 PlatformException。

以上方法签名与行为均来自 接口介绍文档 与 接口介绍文档。

失败模式、边界情况与并发

PlatformException 传播

所有发送接口的失败都收敛为 PlatformException。边界情况：getLogFileDirPath 在原生返回 null 时回退为空字符串（?? ''），getSdkVersion/getAppVersion 回退为 'V?.?.?(?)' 占位符，deleteAllLogFiles 回退为 false——即"拿不到结果时给出安全默认值"，避免空指针崩溃，但调用方应意识到默认值不等于真实结果。

连接失败与断开

接收侧在连接/断开异常时输出 log("Failed to connect to device: $e") / log("Failed to disconnect from device: $e") 并可选提示用户。排查时应结合日志中的连接状态确认：芯片是否处于可发现/可连接状态、手机蓝牙权限是否开启、距离与干扰是否过大。

BLE MTU 过小

固件包按包下发，MTU 过小会导致吞吐低、超时甚至升级中断。若日志显示传输异常，优先尝试 setBleRequestMtu(500) 调整后复测。

已知历史问题

• iOS OTA 回连超时：V1.1.0（2026/07/03）已修复。遇到 iOS 回连超时先升级 SDK，避免重复排查已修复问题（见 README.md）。

并发与异步边界

• 所有方法均为异步 Future，内部通过 MethodChannel 串行/并发调用由原生层调度；Dart 侧不保证也不建议并发操作同一日志文件（如一边 deleteAllLogFiles 一边 shareLogFile），应先完成前一个 await 再执行下一个。
• clickLogFileIndex 依赖 getLogFiles() 之后的列表状态，索引越界属于调用方责任，原生端行为未在文档中定义为越界保护，使用时应对索引有效性做前置校验。

性能与运维注意事项

• 日志输出级别：Dart 侧 print 仅适合开发期调试。发布版本建议控制日志输出量，或依赖原生 SDK 提供的日志开关（详见官方 Android/iOS 调试说明），避免日志刷屏影响性能与用户隐私。
• 日志文件增长：SDK 日志文件持续写入，长期运行会占用存储。运营上建议定期调用 deleteAllLogFiles() 清理，或在用户反馈问题后先 getLogFiles() + shareLogFile() 导出再清理。
• 升级前版本核对：建议在升级流程入口调用 getSdkVersion()，与已知问题修复版本对比；同时确认 APP 版本与 SDK 匹配，避免新旧接口混用。
• 反馈信息最小集：向官方反馈问题时，附上日志文件 + getSdkVersion()/getAppVersion() 结果 + 芯片型号 + 传输方式（BLE/SPP/Gatt Over BR/EDR），可显著缩短定位周期。官方反馈渠道为 GitHub Issues（见 README.md）。

扩展点

• 自定义命令：V1.1.0 起 SDK 支持自定义命令（Android/iOS 均已增加），可用于扩展调试命令，例如自定义的寄存器读取、协议自检等，是深度调试时的扩展入口（见 README.md）。
• 收发接口对：BleMethod（发送）+ BleEventStream（接收）是开发者可扩展的边界，App 可基于事件流实现自己的状态机与日志上报逻辑，作为 SDK 日志的补充。
• 示例工程：仓库 code/JL_OTA/example/ 提供完整可运行的示例 App，可视为官方维护的"集成测试脚手架"，调试自定义场景时可直接基于示例改造复现。

测试

仓库未提供独立的单元测试工程；官方质量保障方式为：

• 示例应用集成验证：code/JL_OTA/example/ 下的示例工程可在 Android/iOS 真机运行，覆盖 BLE 连接、OTA 升级全流程，是验证 SDK 行为与复现问题的主要手段（见 README.md）。
• 版本迭代回归：版本历史显示每个版本针对已知问题做回归修复（如 V1.1.0 修复 iOS 回连超时、增加 Gatt Over BR/EDR 支持），说明官方以发布版本为单元进行兼容性验证。

排查问题时建议以示例工程为基线：先在示例中复现，确认是 SDK 行为还是宿主 App 集成差异，再决定反馈内容。

相关链接

• README.md（调试技巧章节）
• Jieli OTA Upgrade (Flutter) Send/Receive Interface Introduction（接口说明，中文）
• Jieli OTA Upgrade (Flutter) Send/Receive Interface Introduction（接口说明，英文）
• Android SDK 调试说明（官方文档中心）
• iOS SDK 调试说明（官方文档中心）
• 问题反馈（GitHub Issues）