快速开始与 SDK 集成

JL_OTA_Flutter 是珠海市杰理科技股份有限公司为杰理蓝牙类产品（AC69xN、AC70xN 等）提供的 RCSP OTA 固件升级 Flutter SDK。本页说明如何获取 SDK、搭建开发环境、将插件依赖集成进宿主工程，并介绍工程结构与核心收发接口的位置与用法。

Purpose and Scope

本页面向首次接入杰理 OTA（Flutter）SDK 的开发者，覆盖：

• 运行环境与硬件要求
• 获取 SDK 源码（克隆仓库）
• 导入参考工程到 Android Studio
• 在 pubspec.yaml 中声明插件依赖（JlOtaPlugin）
• 工程目录结构（code/、doc/、libs/）与核心接口文件职责
• SDK 内部的平台通道架构与 OTA 升级基本数据流
• 配置、调试技巧、常见失败模式与版本历史

以下内容属于其他页面，不在本页展开：发送/接收接口的逐方法 API 签名请参阅 doc/ 目录下的接口说明文档；各传输通道（BLE / SPP / Gatt Over BR/EDR）的协议细节与升级流程状态机属于对应主题页面的范围。

Overview

JL_OTA_Flutter 是杰理科技官方提供的固件升级开发平台，专门实现杰理蓝牙类产品的 RCSP OTA 升级功能。它不是一个独立的业务 App，而是一个可嵌入宿主 Flutter 应用的插件包：宿主应用通过平台通道（MethodChannel）调用原生 SDK，由原生层完成与蓝牙设备的连接和数据收发，升级结果与进度再通过事件流回传 Dart 层。

SDK 支持的主要升级能力（来源：README.md）：

典型使用场景：厂商 App 内嵌固件升级模块，用户连接杰理耳机/音箱等设备后，App 通过本 SDK 完成固件版本检测、固件下发、进度上报与升级结果回调。

Architecture

SDK 采用标准的 Flutter 插件架构：Dart 侧仅暴露收发接口，所有蓝牙协议栈逻辑位于原生平台实现中，通过 MethodChannel 桥接。

flowchart TD
    subgraph sg_App["宿主 App（Flutter 应用）"]
        UI["业务页面 / UI"]
        Method["libs/ble_method.dart<br/>发送接口"]
        Stream["libs/ble_event_stream.dart<br/>接收接口"]
    end

    subgraph sg_Plugin["jl_ota Flutter 插件（code/JL_OTA）"]
        Plugin["JlOtaPlugin"]
    end

    subgraph sg_Native["原生平台实现"]
        Android["Android 平台<br/>com.jieli.otasdk"]
        IOS["iOS 平台<br/>JlOtaPlugin"]
    end

    subgraph sg_Device["杰理蓝牙设备"]
        Device["RCSP OTA 设备<br/>AC707N / AC703N / AC701N / AC697N / AC696N / AC695N"]
    end

    UI --> Method
    UI --> Stream
    Method --> Plugin
    Stream --> Plugin
    Plugin -->|"MethodChannel"| Android
    Plugin -->|"MethodChannel"| IOS
    Android -->|"BLE / SPP / Gatt Over BR/EDR"| Device
    IOS -->|"BLE / Gatt Over BR/EDR"| Device

各组件职责：

• 宿主 App：业务入口。App 直接调用 libs/ 下的发送接口发起指令，并监听接收接口的升级事件流刷新 UI。
• JlOtaPlugin：Flutter 插件注册类。Android 端包名为 com.jieli.otasdk，iOS 端插件类同为 JlOtaPlugin，作为 MethodChannel 的载体（见 README.md）。
• 原生平台层：Android/iOS 原生 SDK 负责真正的蓝牙连接、RCSP 协议组包/解包、固件数据下发。
• 杰理蓝牙设备：固件升级的目标设备，需内置支持 RCSP OTA 的杰理 SDK。

设计意图：把协议栈下沉到原生层，是因为 BLE/SPP 通信与系统蓝牙 API 强绑定（Android 的 BluetoothGatt、iOS 的 CoreBluetooth），Dart 层无法直接访问；同时保持 Dart 接口极简，让 Flutter 业务方只关心"发送指令、接收事件"两个维度，屏蔽协议细节。

工程结构

仓库顶层布局（来源：README.md）：

JL_OTA_Flutter/
├── code/                                    # 参考源码工程文件夹
│   └── JL_OTA                               # 杰理OTA(Flutter)项目源码
├── 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)的发送接口

• code/JL_OTA/：参考源码工程，是标准的 Flutter 插件包结构（jl_ota），内含 Android/iOS 平台实现与 example/ 示例应用。开发者集成时通常以本目录为模板或依赖来源。
• libs/：核心收发接口，是宿主 App 唯一需要直接接触的 Dart 代码：
  • ble_method.dart —— 发送接口：封装向设备发送的各类 OTA 指令。
  • ble_event_stream.dart —— 接收接口：封装来自设备的升级事件/回调流，供 App 订阅。
• doc/：接口说明文档（中英双语），包含完整的发送/接收接口逐方法说明。

快速开始

从获取源码到在设备上运行示例，共四步（来源：README.md）。

1. 克隆仓库

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

注：仓库镜像同步在 Gitee，可通过 https://gitee.com/Jieli-Tech/JL_OTA_Flutter.git 获取。

2. 导入项目到 Android Studio

1. 打开 Android Studio；
2. 选择 "Open an existing project"；
3. 导航到解压后的 code/ 目录；
4. 打开 JL_OTA 中的项目文件（即 code/JL_OTA，Flutter 插件工程）。

3. 添加依赖库

在宿主工程（或示例工程）的 pubspec.yaml 中声明插件平台注册信息。SDK 使用 JlOtaPlugin 作为统一的插件类：

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

来源：README.md

package: com.jieli.otasdk 是 Android 端的原生包名；pluginClass: JlOtaPlugin 是插件注册入口类，两端同名，这意味着 Dart 侧只需面向一个统一的插件通道编程，平台差异由原生层消化。

4. 运行示例应用

将工程运行到 Android 或 iOS 真机设备，即可使用 App 的各项功能（扫描、连接、升级等）。

flowchart TD
    Start([开始集成]) --> Clone["克隆仓库<br/>git clone"]
    Clone --> Import["Android Studio 导入<br/>code/JL_OTA"]
    Import --> Dep["pubspec.yaml 声明插件依赖<br/>pluginClass: JlOtaPlugin"]
    Dep --> Run["运行示例应用到<br/>Android/iOS 真机"]
    Run --> Connect{"设备支持<br/>RCSP OTA?"}
    Connect -->|"是"| Use["调用发送/接收接口<br/>完成固件升级"]
    Connect -->|"否"| Check["核对硬件 SDK 与<br/>系统版本要求"]
    Check --> Run
    Use --> End([完成])

Core Flow：OTA 升级数据流

一次典型升级的数据流向：App 通过发送接口下发指令 → MethodChannel 转发到原生 → 原生蓝牙栈与设备通信 → 设备回包 → 原生层解析后通过事件流回传 Dart。

sequenceDiagram
    participant App as 宿主 App
    participant Send as ble_method.dart 发送接口
    participant Plugin as JlOtaPlugin
    participant Native as 原生平台（Android/iOS SDK）
    participant Device as 杰理蓝牙设备
    participant Recv as ble_event_stream.dart 接收接口

    App->>Send: 发送指令（连接/开始升级/下发数据）
    Send->>Plugin: MethodChannel 调用
    Plugin->>Native: 平台通道转发
    Native->>Device: BLE/SPP 建立连接并下发固件
    Device-->>Native: 应答 / 进度回包
    Native-->>Recv: 升级事件回调
    Recv-->>App: Stream 事件（连接状态 / 升级进度 / 结果）

该模型是单向指令 + 异步事件的 CQRS 风格：写路径（发送）与读路径（接收）分离为两个文件，避免在单个接口上叠加双向语义。App 侧订阅 ble_event_stream.dart 的事件流即可持续获得升级进度，无需轮询。

配置说明

运行环境要求

SDK 对操作系统、硬件和开发平台有明确要求（来源：README.md）：

注意：iOS 12.0+ 与 Android 6.0+ 是 BLE 能力的硬性门槛——低于该版本的系统无法使用 SDK 的蓝牙通道；设备端芯片必须内置支持 RCSP OTA 的杰理 SDK，否则升级指令不会被设备识别。

工程配置（code/JL_OTA）

来源：README.md

核心接口（libs/）

libs/ 目录是宿主 App 与 SDK 交互的唯一 Dart 入口，只有两个文件，职责边界清晰：

集成方在 Dart 层只需要：通过 ble_method 发起指令，通过 ble_event_stream 监听结果。

各方法的完整签名（参数、返回值、回调类型）未在本仓库根 README 中逐条列出，官方以 doc/ 目录下的《Jieli OTA Upgrade (Flutter) Send:Receive Interface Introduction.md》（英文版）为准，集成前请以该文档核对最新签名。

调试技巧

SDK 提供详细的日志输出，可用于观察 OTA 连接状态与数据交互（来源：README.md）：

• Android：使用 Android Studio 的 Logcat 工具查看实时日志。
• iOS：使用 Xcode 的 Console（控制台） 查看实时日志。

排查问题时按传输通道分流：

• Android SDK 调试说明：https://doc.zh-jieli.com/Apps/Android/ota/zh-cn/master/other/debug.html
• iOS SDK 调试说明：https://doc.zh-jieli.com/Apps/iOS/ota/zh-cn/master/Other/debug.html

建议在集成初期优先通过 Logcat/Console 确认：① 蓝牙连接是否建立；② 指令是否成功下发；③ 设备是否回包。三步日志齐全即说明 SDK 链路正常，问题大概率在业务侧逻辑。

Failure Modes、边界情况与并发注意

结合 README 中运行环境与版本历史描述，集成时需注意以下风险点：

V1.1.0 版本更新中还修复了 iOS OTA 回连超时问题（见版本历史），说明回连场景在 iOS 上曾存在时序缺陷；集成方若依赖自动回连，建议在 iOS 上重点回归该路径。

扩展点与版本演进

SDK 的扩展能力随版本演进逐步开放：

• V1.1.0（2026/07/03）：
  • Android：新增复用空间特殊升级流程、单备份 OTA 自动回连 BLE、Gatt Over BR/EDR 连接方式、自定义命令；
  • iOS：修复 OTA 回连超时问题，新增 Gatt Over BR/EDR 与自定义命令。
• V1.0.0（2025/11/19）：初始版本发布。

来源：README.md

其中自定义命令是最重要的扩展点：允许宿主 App 下发 SDK 未内置的私有指令，适用于厂商自定义功能场景。Gatt Over BR/EDR 则为传统蓝牙场景复用 BLE GATT 通道提供了统一入口。

社区与支持

来源：README.md

相关链接

• README.md（仓库主文档） — 概述、快速开始、配置与版本历史的权威来源
• README_EN.md（英文版）
• 发送/接收接口说明（中文） — 逐方法 API 签名，集成时的必读文档
• 发送/接收接口说明（英文）
• libs/ble_method.dart（发送接口）
• libs/ble_event_stream.dart（接收接口）
• code/JL_OTA（插件参考工程）
• 许可证（Apache License 2.0）