项目概述与能力总览

JL_OTA_Flutter 是珠海市杰理科技股份有限公司（Jieli Tech）为杰理蓝牙类产品推出的 RCSP OTA 固件升级 Flutter SDK，提供基于 BLE、SPP、Gatt Over BR/EDR 等多种传输通道的完整固件升级能力，配套示例工程与中文/英文接入文档。

Purpose and Scope

本页是仓库的总览入口页，用于帮助新接入者在最短时间内建立对项目的整体认知，包括：

• 项目的定位与核心业务价值（RCSP OTA 固件升级）
• 能力清单（BLE 升级、SPP 升级、自动回连、复用空间升级等）
• 工程结构（libs/ 核心收发接口、code/ 示例工程、doc/ 文档）
• 运行环境要求与快速开始路径
• 版本历史、许可证与社区支持渠道

以下内容不在本页展开，请前往对应页面阅读：

• 发送接口详解：核心发送接口 libs/ble_method.dart 的完整方法签名与调用约定。
• 接收接口详解：核心接收接口 libs/ble_event_stream.dart 的事件流模型与回调解析。
• SDK 接入文档：仓库 doc/ 目录下中文/英文《Jieli OTA Upgrade (Flutter) - Send/Receive Interface Introduction》文档。

Overview

项目定位

杰理科技（zh-jieli.com）的蓝牙产品线（如 AC707N、AC703N、AC701N、AC697N、AC696N、AC695N 等）在出厂后需要通过 OTA（Over-The-Air） 方式升级固件。JL_OTA_Flutter 正是面向这一场景的官方 SDK：它以 Flutter 插件形式封装底层蓝牙通信与 RCSP 升级协议，让应用开发者不必关心蓝牙链路细节，即可在自己的 App 中集成固件升级能力。

来源：README.md

关键概念

平台形态

SDK 采用「Flutter Dart 层接口 + 原生平台插件」的双层结构：

• Dart 层：libs/ble_method.dart（发送接口）与 libs/ble_event_stream.dart（接收接口）向上层暴露统一 API；
• 原生层：通过 JlOtaPlugin 插件类对接 Android（包名 com.jieli.otasdk）与 iOS 的杰理原生 OTA SDK。

来源：README.md

Architecture

下面这张架构图展示了应用从调用 SDK 到完成设备升级的完整分层关系：

flowchart TD
    subgraph sg_App["应用层 (Flutter / Dart)"]
        App["业务 App / 示例工程 code/JL_OTA"]
    end

    subgraph sg_SDK["JL_OTA_Flutter SDK 核心 (libs/)"]
        Send["ble_method.dart<br/>发送接口"]
        Recv["ble_event_stream.dart<br/>接收接口"]
    end

    subgraph sg_Plugin["原生插件层 (JlOtaPlugin)"]
        Android["Android 插件<br/>com.jieli.otasdk"]
        IOS["iOS 插件"]
    end

    subgraph sg_Device["杰理蓝牙设备 (RCSP OTA)"]
        BLE["BLE 通道"]
        SPP["SPP 通道"]
        BREDR["Gatt Over BR/EDR"]
    end

    App -->|"调用发送接口"| Send
    App -->|"订阅事件流"| Recv
    Send -->|"MethodChannel"| Android
    Send -->|"MethodChannel"| IOS
    Android -->|"蓝牙连接"| BLE
    Android -->|"蓝牙连接"| SPP
    IOS -->|"蓝牙连接"| BLE
    IOS -->|"蓝牙连接"| BREDR
    Recv -.->|"升级状态/结果回调"| App

分层说明：

1. 应用层：业务 App 或仓库内示例工程（code/JL_OTA/）是唯一的直接使用者，负责发起升级、展示进度与处理用户交互。
2. SDK 核心层：libs/ 目录下的两个 Dart 文件是 SDK 的对外门面——ble_method.dart 承载所有「下发」类操作（连接、开始升级、发送固件数据、自定义命令等），ble_event_stream.dart 承载所有「接收」类通知（连接状态、升级进度、升级结果等）。
3. 原生插件层：JlOtaPlugin 分别在 Android（com.jieli.otasdk）与 iOS 上桥接杰理原生 SDK，屏蔽平台差异。
4. 设备层：升级数据最终经由 BLE、SPP 或 Gatt Over BR/EDR 通道写入设备 Flash，设备按 RCSP 协议应答，驱动状态机流转。

这种「接口层下沉、原生能力上抛」的架构设计意图在于：将平台相关的蓝牙栈差异完全隔离在插件层之下，使上层业务代码可以跨 Android/iOS 复用同一套 Dart API。

能力清单

SDK 官方声明支持以下核心升级能力（详见 README.md）：

能力分层视图

flowchart LR
    subgraph sg_Transport["传输通道层"]
        BLE["BLE"]
        SPP["SPP"]
        BREDR["Gatt Over BR/EDR"]
    end

    subgraph sg_Upgrade["升级流程层"]
        NORMAL["普通 OTA 升级"]
        SINGLE["单备份 OTA + 自动回连"]
        REUSE["复用空间升级"]
    end

    subgraph sg_Ext["扩展能力层"]
        CMD["自定义命令"]
        LOG["日志输出/调试"]
    end

    BLE --> NORMAL
    BLE --> SINGLE
    SPP --> NORMAL
    BREDR --> NORMAL
    REUSE -.->|"特殊流程"| NORMAL
    CMD -.->|"额外控制"| NORMAL
    LOG -.->|"可观测性"| NORMAL

设计意图解读：

• 通道与流程解耦：传输通道（怎么传）与升级流程（传什么、按什么顺序传）在实现上相互独立，因此同一套升级流程可以复用在 BLE / SPP / BR/EDR 三种通道上，未来扩展新通道（如 2.4G 私有协议）时无需重写流程逻辑。
• 特殊流程显式建模：单备份自动回连与复用空间升级属于「流程变体」，在 V1.1.0 中作为独立能力加入，说明 SDK 将设备端 Flash 布局差异视为一等公民，而不是在普通流程里打补丁。
• 自定义命令是扩展点：通过自定义命令接口，接入方可以在不升级 SDK 的前提下调试设备、读写私有参数，是 RCSP 协议开放性的体现。

工程结构

仓库根目录结构如下（详见 README.md 第四节）：

JL_OTA_Flutter/
├── code/                                    # 参考源码工程文件夹
│   └── JL_OTA                               # 杰理OTA(Flutter)项目源码
│       ├── pubspec.yaml                     # 示例工程依赖与插件声明
│       └── example/                         # 示例 App
├── doc/                                     # 文档文件夹
│   ├── Jieli OTA Upgrade (Flutter) - Send/Receive Interface Introduction_en.md
│   ├── Jieli OTA Upgrade (Flutter) - Send/Receive Interface Introduction.md
│   └── ReadMe.txt                           # 说明文件
├── libs/                                    # 核心收发接口文件夹
│   ├── ble_event_stream.dart                # 杰理OTA升级(Flutter)的接收接口
│   └── ble_method.dart                      # 杰理OTA升级(Flutter)的发送接口
├── README.md                                # 中文说明
├── README_EN.md                             # 英文说明
└── LICENSE                                  # Apache License 2.0

各目录职责

说明：libs/ 下的两个 Dart 文件即 SDK 对外提供的全部接口面——接入方通常只需引入这两个文件即可完成升级功能集成，因此它们也是本仓库其他页面的核心主题。

运行环境

官方声明的最低运行要求（详见 README.md 第二节）：

兼容性设计要点：

• Android 6.0（API 23）对应运行时权限模型（蓝牙/定位权限动态申请），iOS 12.0 对应 CoreBluetooth 后台模式稳定版本，两个下限共同保证 SDK 所需系统能力齐备。
• 硬件列表均为杰理经典蓝牙 SoC，升级协议栈（RCSP）在固件侧实现，因此 SDK 无需针对单颗芯片做特判，接入方只需确认设备固件支持 RCSP OTA。

快速开始

1. 克隆仓库

git clone https://github.com/Jieli-Tech/JL_OTA_Flutter.git
cd JL_OTA_Flutter

来源：README.md

2. 导入示例工程

打开 Android Studio → "Open an existing project" → 导航到 code/ 目录 → 打开 JL_OTA 中的项目文件。

3. 声明平台插件

在接入方 Flutter 工程的 pubspec.yaml 中声明 JlOtaPlugin，这是 SDK 与原生层通信的桥接契约：

plugin:
  platforms:
    android:
      package: com.jieli.otasdk
      pluginClass: JlOtaPlugin
    ios:
      pluginClass: JlOtaPlugin

来源：README.md

要点解读：Android 侧同时指定 package（com.jieli.otasdk）与 pluginClass（JlOtaPlugin），iOS 侧仅需 pluginClass，这与 Flutter 平台通道机制一致——MethodChannel/EventChannel 由插件类注册，Dart 侧通过 libs/ 下的收发接口与之一一对应。

4. 运行

运行项目到 Android 或 iOS 设备，即可使用示例 App 的各项升级功能。

OTA 升级核心流程

SDK 驱动的升级生命周期可概括为「连接 → 升级 → 回连/结束」三个阶段：

sequenceDiagram
    participant App as 业务App
    participant SDK as JL_OTA_Flutter SDK (libs/)
    participant Plugin as JlOtaPlugin (原生)
    participant Dev as 杰理蓝牙设备

    App->>SDK: 1. 调用发送接口 (连接/扫描)
    SDK->>Plugin: MethodChannel 调用
    Plugin->>Dev: 建立 BLE/SPP 连接
    Dev-->>Plugin: 连接成功
    Plugin-->>SDK: 状态回调
    SDK-->>App: 事件流通知 (ble_event_stream)

    App->>SDK: 2. 发起 OTA 升级
    SDK->>Plugin: 下发升级指令
    Plugin->>Dev: RCSP 升级握手
    Dev-->>Plugin: 进入升级模式
    loop 固件分包传输
        App->>SDK: 推送固件数据
        SDK->>Plugin: 分包下发
        Plugin->>Dev: 写入固件
        Dev-->>Plugin: ACK / 进度
        Plugin-->>SDK: 进度事件
        SDK-->>App: 进度通知
    end

    alt 单备份 OTA
        Plugin->>Dev: 升级完成，自动回连 BLE
        Dev-->>Plugin: 回连确认
        Plugin-->>App: 升级成功 (含回连结果)
    else 普通/复用空间 OTA
        Plugin-->>App: 升级成功
    end

流程要点：

• 一切从 libs/ 两个接口出发：业务代码只面向 Dart 层收发接口编程，不接触任何原生 API；升级状态通过事件流异步回调，避免阻塞 UI。
• 固件分包传输是核心循环：升级数据按协议分包下发，设备逐包应答，SDK 据此驱动进度上报与错误处理（超时、丢包重传等逻辑位于原生 SDK 内部）。
• 单备份 OTA 的特殊收尾：V1.1.0 引入的自动回连能力在升级完成后主动重连 BLE，解决单备份设备重启后需手动回连的体验问题。

版本历史

来源：README.md

演进趋势解读：V1.1.0 的变更集中在「通道扩展」与「流程完备性」两个方向——Gatt Over BR/EDR 扩展了传输通道，自动回连与复用空间升级补齐了设备端不同 Flash 布局下的升级路径，自定义命令则把协议能力开放给接入方。这暗示 SDK 的长期设计方向是：协议内核稳定，通道与流程持续扩展。

调试与问题排查

SDK 提供详细的日志输出，可通过日志查看 OTA 连接状态与数据交互（详见 README.md 第六节）：

调试建议：

• 升级前先通过日志确认设备连接状态与 RSSI，排除蓝牙信号问题；
• 升级失败时重点核对日志中的错误码与失败阶段（连接失败 / 握手失败 / 传输中断 / 校验失败），再对照官方调试文档定位；
• 单备份 OTA 若出现回连超时，优先升级到 V1.1.0（已修复 iOS 回连超时问题）。

失败模式与边界情况

基于版本历史与能力声明，接入时需特别关注以下边界：

说明：上述边界主要依据官方能力声明与版本变更记录推断；具体的错误码集合、重传策略与超时参数以 libs/ 收发接口文档及原生 SDK 调试文档为准。

许可证与社区支持

• 开源协议：本项目采用 Apache License 2.0，版权所有 © 2024 珠海市杰理科技股份有限公司。
• 官方网站：杰理科技（活跃）
• 问题反馈：GitHub Issues（活跃）
• 数据手册：仓库 doc/ 目录下的中英文接口介绍文档

Related Links

• README.md（仓库总览）
• README_EN.md（英文总览）
• libs/ble_method.dart（发送接口）
• libs/ble_event_stream.dart（接收接口）
• code/JL_OTA/pubspec.yaml（示例工程配置）
• LICENSE（Apache 2.0）