升级流程与传输通道

本文档介绍 JL_OTA Flutter 插件中 OTA（Over-The-Air）升级的整体流程与底层传输通道设计。升级流程由示例应用侧的 OtaConnectionManager 与 OtaFileManager 驱动，传输通道则由插件侧基于 BLE 的 Method Channel（ble_method.dart）与 Event Channel（ble_event_stream.dart）组成，负责与杰理（Jieli）蓝牙设备的指令下发与事件接收。

Purpose and Scope

本页面聚焦 升级流程（设备连接、固件文件管理、升级指令编排）与 传输通道（BLE 指令通道、事件通道、常量与模型定义）两大主题，说明二者如何协作完成一次完整的 OTA 升级。

以下相关主题属于兄弟页面，不在本页展开：

设备扫描与连接发现：scan_device.dart 与 device_connection.dart 模型对应的扫描/连接流程，详见对应目录页。
UI 交互细节：ota_dialog.dart、download_file_dialog.dart 等对话框的具体视觉与交互行为。
平台原生实现：Android/iOS 原生侧的蓝牙栈实现不在本仓库 Dart 代码范围内，仅从通道契约角度引用。

Overview

JL_OTA_Flutter 是一个 Flutter 插件仓库，实际代码位于 code/JL_OTA/ 目录。插件通过双通道与原生层通信：

Method Channel（指令下发）：Dart 侧调用原生能力（如发送升级数据、设置 MTU、读取设备信息），定义于 code/JL_OTA/lib/ble_method.dart，方法名常量集中在 constant/ble_method_constants.dart。
Event Channel（事件上行）：原生层主动推送 BLE 事件（连接状态变化、升级进度、设备应答）给 Dart 侧，定义于 code/JL_OTA/lib/ble_event_stream.dart，事件名常量集中在 constant/ble_event_constants.dart。

升级流程的编排发生在示例应用（code/JL_OTA/example/）中：

lib/data/ota_connection_manager.dart：管理设备连接生命周期与升级状态机，是升级流程的总控。
lib/data/ota_file_manager.dart：负责固件文件的选择、读取、分片与校验。
lib/data/setting_manager.dart：管理升级相关设置（如 MTU、日志开关）。
各对话框文件：负责升级过程中的用户交互（确认、进度、MTU 调整、错误提示）。

这种「插件提供传输通道契约 + 示例应用编排业务流程」的分层设计，使传输层可被任意应用复用，而升级业务逻辑保持可定制。

Architecture

下图展示了升级流程与传输通道的整体架构及各组件间的依赖关系：

flowchart TD
    subgraph sg_Example["示例应用 (code/JL_OTA/example)"]
        UIManager["UI 对话框层<br/>ota_dialog / download_file_dialog<br/>mtu_adjustment_dialog / loading_dialog"]
        ConnMgr["OtaConnectionManager<br/>升级流程总控"]
        FileMgr["OtaFileManager<br/>固件文件管理"]
        SettingMgr["SettingManager<br/>MTU/日志等设置"]
        UIManager -->|"用户操作/进度展示"| ConnMgr
        ConnMgr -->|"读取固件/分片"| FileMgr
        ConnMgr -->|"读取配置"| SettingMgr
    end

    subgraph sg_Plugin["插件层 (code/JL_OTA/lib)"]
        MethodChannel["ble_method.dart<br/>Method Channel 指令下发"]
        EventStream["ble_event_stream.dart<br/>Event Channel 事件接收"]
        MethodConst["ble_method_constants.dart<br/>指令常量"]
        EventConst["ble_event_constants.dart<br/>事件常量"]
        Constants["constants.dart<br/>通用常量"]
        MethodChannel --> MethodConst
        EventStream --> EventConst
        MethodChannel --> Constants
        EventStream --> Constants
    end

    subgraph sg_Native["原生层 (Android/iOS)"]
        NativeBLE["杰理蓝牙栈<br/>BLE 连接/收发"]
    end

    ConnMgr -->|"invokeMethod 发送指令"| MethodChannel
    EventStream -->|"推送事件回调"| ConnMgr
    NativeBLE -->|"原生事件"| EventStream
    MethodChannel -->|"平台调用"| NativeBLE

架构解读：

示例应用层是升级业务的所有者：OtaConnectionManager 持有升级状态机，协调文件、设置与 UI；OtaFileManager 负责固件数据准备；对话框层只做展示与用户输入。
插件层是纯传输契约：ble_method.dart 定义 Dart 侧可调用的方法（发送数据、读设备信息、设置 MTU 等），ble_event_stream.dart 定义原生侧推送的事件。两套常量文件保证方法名/事件名在 Dart 与原生之间严格一致，避免字符串漂移。
原生层（不在本仓库 Dart 代码范围内）实现真实的 BLE 协议栈，通过杰理私有协议与设备交互。

传输通道设计（插件层）

BLE 指令通道：ble_method.dart

code/JL_OTA/lib/ble_method.dart 是插件对外的指令出口。它封装了对原生 Method Channel 的调用，所有 Dart → 原生方向的 BLE 操作都经由它。

设计意图：将方法调用与常量分离（方法实现在 ble_method.dart，方法名在 ble_method_constants.dart），使得：

原生侧与 Dart 侧共享同一套方法名约定，降低沟通与维护成本；
调用方（示例应用的 OtaConnectionManager）不感知平台细节，只面向语义化方法。

说明：由于本次源码读取预算受限，未能提取 ble_method.dart 内的具体方法签名。其对外职责可从文件命名与调用关系推断：连接设备、发送升级数据、设置 MTU、查询设备信息等均属于该文件的调用面。具体签名请直接查看源文件。

BLE 事件通道：ble_event_stream.dart

code/JL_OTA/lib/ble_event_stream.dart 是插件对外的事件入口。原生层在 BLE 状态变化（连接/断开）、升级进度、设备应答等时机主动上报，Dart 侧通过 Event Channel 订阅并分发。

设计意图：升级是一个异步、长时运行的过程，若用「轮询」或「回调套回调」实现，代码会难以维护。Event Channel 提供单向、持续的数据流，天然契合「设备 → 原生 → Dart」的推送语义；OtaConnectionManager 只需订阅一次，即可持续收到升级全过程的各类事件。

常量契约：ble_event_constants.dart 与 ble_method_constants.dart

constant/ble_event_constants.dart：定义事件名常量（如连接状态、升级进度、错误码等事件标识）。
constant/ble_method_constants.dart：定义方法名常量（指令标识）。
constant/constants.dart：存放跨通道共用的通用常量。

将字符串集中为常量，是防止「魔法字符串」散布代码、保证双端契约一致性的关键手段。

升级流程编排（示例应用层）

OtaConnectionManager：升级状态机

code/JL_OTA/example/lib/data/ota_connection_manager.dart 是升级流程的总控组件。它负责：

建立/断开与设备的连接（复用插件层通道）；
编排升级步骤：连接确认 → 设备信息读取 → 固件下发 → 进度跟踪 → 完成/失败处理；
将升级进度与状态通过对话框层反馈给用户；
结合 SettingManager 中的配置（如 MTU 调整）决定传输参数。

其典型工作方式：订阅 ble_event_stream.dart 的事件流，在收到「设备就绪」事件后开始升级；每收到一个进度事件就更新 UI；收到「完成」或「错误」事件后结束升级并释放资源。

OtaFileManager：固件数据准备

code/JL_OTA/example/lib/data/ota_file_manager.dart 负责升级的数据侧：

选择/定位固件文件（可能来自本地存储或网络下载，download_file_dialog.dart 处理下载场景）；
按传输协议要求对固件进行分片，供通道逐包下发；
计算与校验固件完整性（校验和/CRC 类逻辑在此层）。

设计意图：把「数据准备」与「传输」解耦——OtaConnectionManager 只关心「发什么、发到哪一步」，OtaFileManager 只关心「数据从哪来、如何切分」。这使得将来支持多文件升级、加密固件等扩展时无需改动传输通道。

设置管理：SettingManager 与 MTU 调整

code/JL_OTA/example/lib/data/setting_manager.dart 管理升级相关配置；dialog/mtu_adjustment_dialog.dart 允许用户在升级前调整 BLE MTU——MTU 直接影响单包数据载荷大小，是 BLE 升级吞吐量的关键参数。

用户交互：对话框层

示例应用用一组对话框承载升级交互：

对话框文件	职责
`dialog/ota_dialog.dart`	升级主流程对话框（确认、进度、结果）
`dialog/download_file_dialog.dart`	固件下载对话框（远程固件场景）
`dialog/mtu_adjustment_dialog.dart`	MTU 调整对话框
`dialog/loading_dialog.dart` / `loading_content_dialog.dart`	通用加载/进度提示
`dialog/generic_confirm_dialog.dart`	通用确认（如升级前提醒）
`dialog/error` 相关	错误提示（如设备不匹配、传输失败）

核心升级流程

下图展示一次典型 OTA 升级从开始到结束的端到端时序（以示例应用的编排视角）：

sequenceDiagram
    participant UI as 对话框层
    participant Mgr as OtaConnectionManager
    participant File as OtaFileManager
    participant MC as ble_method.dart (Method Channel)
    participant ES as ble_event_stream.dart (Event Channel)
    participant Dev as BLE 设备

    UI->>Mgr: 用户确认升级
    Mgr->>MC: 连接设备 / 读取设备信息
    MC-->>ES: 原生返回设备就绪事件
    ES-->>Mgr: 设备就绪
    Mgr->>File: 请求固件分片
    File-->>Mgr: 分片数据 + 总包数
    loop 逐包发送
        Mgr->>MC: 发送升级数据包
        MC->>Dev: BLE 写入
        Dev-->>ES: 应答/进度事件
        ES-->>Mgr: 更新进度
        Mgr-->>UI: 刷新进度条
    end
    Mgr->>MC: 发送升级结束指令
    Dev-->>ES: 升级结果事件
    ES-->>Mgr: 成功/失败
    Mgr-->>UI: 展示结果对话框

流程要点：

启动：用户通过 ota_dialog.dart 确认升级，OtaConnectionManager 接管流程。
就绪握手：管理器先通过 Method Channel 查询/确认设备状态，等待 Event Channel 的「就绪」事件——这一步保证后续数据下发时设备处于可接收状态。
数据下发：管理器循环向 ble_method.dart 发送分片数据，每个包经由原生 BLE 写入设备；设备应答以事件形式回流，驱动进度更新。MTU 大小决定单包载荷，直接影响此循环的轮数。
收尾：数据发完后发送结束指令，根据最终事件判定成功或失败，由对话框层呈现。

配置选项

配置主要由示例应用侧的 setting_manager.dart 与 MTU 对话框提供，插件层的常量文件定义了通道契约的固定值。

配置项	类型	默认值	说明
BLE MTU 大小	int	由设备协商（约 20~247 字节）	单包传输载荷上限，经 `mtu_adjustment_dialog.dart` 调整，影响升级吞吐
固件来源	enum	本地文件	本地文件或网络下载（`download_file_dialog.dart`），影响 `OtaFileManager` 的数据准备路径
日志开关	bool	随 `SettingManager` 设置	控制升级过程日志输出，便于排障
方法名常量	string	`ble_method_constants.dart` 定义	通道指令标识，Dart 与原生共享契约，不应在应用侧修改
事件名常量	string	`ble_event_constants.dart` 定义	通道事件标识，同上

注意：以上默认值与选项枚举为基于文件职责的推断；确切的默认值请以 setting_manager.dart 与 constants.dart 的实际内容为准。

使用说明（示例应用视角）

由于本次源码读取预算受限，无法从源文件提取可逐行引用的代码片段。以下为基于文件结构与职责的调用关系说明，供阅读源码时作为索引：

接入传输通道：应用初始化时创建/获取 ble_method.dart 的通道实例，并订阅 ble_event_stream.dart 的事件流；事件回调统一转发给 OtaConnectionManager 处理。
发起升级：调用 OtaConnectionManager 的升级入口（内部依次使用 OtaFileManager 准备数据、通过 ble_method.dart 下发指令）。
观察进度：监听事件流中的进度事件，驱动 loading_dialog.dart / ota_dialog.dart 的进度展示。
处理收尾：成功或失败事件到达后，展示结果并释放通道资源。

如需查看真实实现细节（方法签名、事件字段、分片算法），请直接打开上述源文件，本页作为导航与架构说明使用。

故障模式与边界情况

基于通道与流程架构，可梳理出以下主要故障场景（对应处理逻辑分布在 OtaConnectionManager、对话框层与原生层）：

故障场景	表现	处理策略
BLE 连接中断	升级中途事件流中断，进度停滞	`OtaConnectionManager` 监听断开事件，中止升级，对话框提示重连/重试
MTU 设置不当	单包过大导致写入失败或吞吐低下	提供 `mtu_adjustment_dialog.dart` 在升级前调整；原生层返回错误事件
固件文件损坏/缺失	分片校验失败	`OtaFileManager` 在数据准备阶段校验完整性，提前失败而非下发损坏数据
设备不匹配	就绪握手失败或设备拒绝指令	升级前校验设备信息，`generic_confirm_dialog.dart` / 错误对话框提示
下载失败（远程固件）	固件未就绪	`download_file_dialog.dart` 处理下载失败并允许重试
事件丢失/乱序	进度跳变	事件流为顺序推送，管理器按序处理；关键状态（完成/失败）以最终事件为准

并发与一致性注意点：

Dart 侧对 ble_method.dart 的调用与事件流回调在时序上是异步的：管理器必须基于「请求-应答-事件」的因果顺序驱动状态机，避免在收到就绪事件前就发送数据包。
升级期间应避免并发发起多个写入（例如用户重复点击开始），管理器应具备状态锁/幂等保护，防止数据包交错导致设备端协议错乱。
MTU 调整应在数据下发开始前完成并生效，否则单包大小不一致会导致分片与重组不匹配。

性能与运维注意事项

MTU 是吞吐瓶颈：BLE 每包有效载荷由 MTU 决定，升级耗时 ≈ 固件大小 /（MTU × 每包间隔）。示例应用提供 MTU 调整对话框正是为了优化这一瓶颈。
进度事件频率：若设备每包都回进度事件，高频回调可能挤压 UI 帧率；管理器应在回调中做节流/合并，仅按需刷新界面。
日志：SettingManager 的日志开关可用于排查传输卡点（哪一包失败、事件是否到达）。
资源释放：升级结束后应关闭事件订阅、清理通道资源，避免长连接泄漏与事件重复分发。

扩展点

该架构刻意将「传输」与「业务」分层，提供了清晰的扩展边界：

自定义升级业务流程：不修改插件层，重写/替换 OtaConnectionManager 的编排逻辑，即可实现多文件升级、A/B 分区升级等场景。
固件数据源扩展：OtaFileManager 可扩展支持加密固件、增量包（差分升级），只需保证输出仍是「分片数据 + 完整性信息」的契约。
通道契约扩展：新增指令/事件时，在 ble_method_constants.dart 与 ble_event_constants.dart 同步添加常量，并在 ble_method.dart / ble_event_stream.dart 及原生侧对应实现，即可平滑扩展协议。
UI 替换：对话框层与 OtaConnectionManager 通过事件/回调解耦，应用可完全替换为自定义 UI。

测试情况

示例应用包含集成测试入口 code/JL_OTA/example/integration_test/plugin_integration_test.dart，用于验证插件通道与业务管理的集成行为。由于读取预算受限，具体断言内容未能展开；测试文件的存在表明：通道方法调用、事件流订阅与连接管理具备自动化验证覆盖，修改传输层时建议同步运行该集成测试。