辅助连接与广播音箱

本页介绍 JL_OTA_Flutter（杰理 OTA SDK，Flutter 版）中"辅助连接"与"广播音箱"相关的连接建立、通道选择与 OTA 升级辅助机制，涵盖 Gatt Over BR/EDR 辅助通道、单备份自动回连、BLE/SPP 多通道传输以及音箱类设备通过 RCSP OTA 完成固件升级的端到端流程。

Purpose and Scope

本页面向需要接入或排查"辅助连接 / 广播音箱"场景的 SDK 集成工程师，说明：

SDK 的整体分层结构与收发接口（libs/ble_method.dart 发送接口、libs/ble_event_stream.dart 接收接口）；
辅助连接涉及的通道机制：BLE、SPP、Gatt Over BR/EDR，以及单备份 OTA 自动回连 BLE 的辅助策略；
音箱类产品（广播音箱）在 RCSP OTA 升级流程中的角色与数据流向；
平台/芯片支持范围、工程配置方式与已知问题（如 iOS OTA 回连超时）的排查线索。

重要说明（诚实性声明）：当前仓库快照仅包含 README.md、README_EN.md、LICENSE 三个文件，README 中列出的 code/（Flutter 参考工程）、doc/（接口文档）与 libs/（核心收发接口）目录未包含在本快照内。因此本页以 README 公开信息为事实依据，凡涉及具体实现细节（方法签名、事件字段等）均明确标注"实现细节未在源码中找到"，并给出官方文档中心指引，不做臆测填充。

相邻目录页（如 BLE 升级、SPP 升级、自动回连等专题）与本页属于同一 SDK 的不同侧面，本页聚焦"辅助连接 + 广播音箱"的通道与机制视角，不重复展开各通道的完整升级细节。

Overview

JL_OTA_Flutter 是珠海市杰理科技股份有限公司面向杰理蓝牙类产品（耳机、音箱等）提供的固件升级开发平台，专门实现 RCSP OTA 升级功能，支持 BLE、SPP 等多种传输方式（见 README.md）。

在该生态中：

辅助连接（Assist Connection）：指不依赖单一"扫描→连接→升级"直连路径、而是通过辅助机制建立或维持升级链路的连接方式，典型包括：
- Gatt Over BR/EDR：在经典蓝牙 BR/EDR 链路上承载 GATT 服务，使不支持 BLE 外设或需要更稳定长连接的场景仍可使用 GATT 读写完成 RCSP OTA；
- 单备份 OTA 自动回连 BLE：单备份（Single Bank）固件升级过程中设备会重启切换固件，SDK 自动回连 BLE 以续传或完成后续流程，提升用户体验；
- 自定义命令：通过 SDK 透传自定义 RCSP 命令，供上层实现私有辅助业务。
广播音箱（Broadcast Speaker）：指音箱类目标设备。音箱通常体积大、Flash 容量充足，往往作为"广播/转发"节点参与多设备联动升级；在 SDK 视角下，它仍是一个通过 BLE/SPP/BR-EDR 通道承载 RCSP OTA 协议的升级目标。

版本历史（V1.1.0，2026/07/03）显示辅助能力随版本演进持续增强：Android 侧增加复用空间特殊升级流程、单备份 OTA 自动回连 BLE、Gatt Over BR/EDR 连接方式与自定义命令；iOS 侧修复 OTA 回连超时问题、增加 Gatt Over BR/EDR 与自定义命令（见 README.md）。

Architecture

flowchart TD
    subgraph sg_App["App 应用层 (Flutter)"]
        UI["OTA 业务界面"]
        Biz["业务逻辑/状态机"]
    end

    subgraph sg_Libs["SDK 收发接口层 (libs/)"]
        Sender["ble_method.dart 发送接口"]
        Receiver["ble_event_stream.dart 接收接口"]
    end

    subgraph sg_Plugin["平台插件层"]
        Plugin["JlOtaPlugin (Android / iOS)"]
    end

    subgraph sg_Channel["蓝牙传输通道"]
        BLE["BLE (GATT)"]
        SPP["SPP 经典蓝牙"]
        BREDR["Gatt Over BR/EDR"]
    end

    Device["目标设备<br/>(耳机 / 广播音箱等 RCSP OTA 设备)"]

    UI --> Biz
    Biz --> Sender
    Sender -->|"MethodChannel 调用"| Plugin
    Plugin --> BLE
    Plugin --> SPP
    Plugin --> BREDR
    BLE -->|"建立连接/传输"| Device
    SPP -->|"建立连接/传输"| Device
    BREDR -->|"建立连接/传输"| Device
    Device -->|"事件/应答/升级进度"| Receiver
    Receiver -->|"Stream 事件分发"| UI

架构说明（节点名均取自 README 工程结构，见 README.md）：

App 应用层：上层业务通过"发送接口→事件流回调"的请求/响应模型驱动升级流程，无需关心底层蓝牙细节——这是 SDK 将收发分离的设计意图：发送接口单向发起指令，接收接口以事件流推送设备侧状态，天然适配蓝牙异步回调模型。
libs/ 收发接口层：ble_method.dart 封装全部"发送"动作（连接、下发 OTA 数据、自定义命令等）；ble_event_stream.dart 封装"接收"动作（连接状态、升级进度、错误码等）。该层是 Flutter 侧唯一直接接触平台插件的边界。
平台插件层：JlOtaPlugin 以 Android（com.jieli.otasdk）与 iOS 双端实现，负责把 Dart 调用桥接到原生蓝牙栈，并把原生回调转成事件流。
传输通道：BLE / SPP / Gatt Over BR/EDR 三种通道并行存在，由上层按目标设备能力选择；Gatt Over BR/EDR 是"辅助连接"的关键通道——它复用 GATT 协议语义，却运行在经典蓝牙链路上，扩大了可升级设备范围。
目标设备：耳机、音箱（含广播音箱）等支持 RCSP OTA 的杰理芯片产品（AC707N、AC703N、AC701N、AC697N、AC696N、AC695N 等，见 README.md）。

注：libs/ 与 code/ 目录未包含在当前仓库快照中，上述通道与插件层的具体方法签名、事件字段定义无法在本仓库内直接验证；如需精确 API，请参考官方 SDK 接入文档与 doc/ 目录下的收发接口介绍文档。

工程结构与收发接口

README 定义的参考工程结构如下（当前快照中 code/、doc/、libs/ 目录未包含）：

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)的发送接口

Source: README.md

对"辅助连接与广播音箱"场景而言，本结构传递了两个关键设计意图：

收发分离（Send/Receive split）：发送（ble_method.dart）与接收（ble_event_stream.dart）是两个独立文件。蓝牙通信天然是异步的——指令发出后，设备的应答、连接状态、升级进度都通过事件流异步到达。将两者分离后，上层业务可以"先订阅事件流、再发指令"，避免回调地狱，也便于多设备/多通道场景下按设备分发事件。
接口层独立于业务层：libs/ 是纯接口层，code/JL_OTA 是参考业务实现。集成方只需依赖 libs/ 两个文件即可接入，业务界面可完全自定义——这解释了为何升级界面、多设备管理（如一拖多音箱）属于应用层职责，而 SDK 只保证通道与协议正确。

连接方式与辅助机制

三种传输通道

通道	链路类型	适用场景	与"辅助连接"的关系
BLE 升级	BLE GATT	支持 BLE 的耳机/音箱	默认通道；单备份 OTA 时用于自动回连
SPP 升级	经典蓝牙 SPP	传统经典蓝牙设备	独立通道，指令/数据走 RFCOMM
Gatt Over BR/EDR	经典蓝牙链路承载 GATT	仅支持经典蓝牙、或 BLE 信号不稳的复杂环境	核心辅助通道：复用 GATT 协议语义，运行于 BR/EDR 链路，扩展可升级设备范围

辅助连接的三种形态

通道级辅助（Gatt Over BR/EDR）：V1.1.0 起 Android 与 iOS 均支持。设计动机是：部分杰理产品（尤其大容量音箱）只有经典蓝牙栈，或环境中 BLE 信道拥塞；在 BR/EDR 链路上运行 GATT 服务，既保留 RCSP OTA 的分包读写模型，又获得经典蓝牙更长的连接距离与更稳定的链路。
流程级辅助（单备份 OTA 自动回连 BLE）：单备份升级时设备会重启切换到新固件，连接必然中断。SDK 在检测到断开后自动发起 BLE 回连，续传或完成升级收尾（如校验、重启指令）。这是"辅助连接"最典型的自动化形态——上层无需处理重连逻辑，由 SDK 兜底。
业务级辅助（自定义命令）：V1.1.0 新增自定义命令透传能力，上层可下发 RCSP 私有命令（例如查询音箱能力、触发广播组网、读取设备信息），作为辅助业务的基础。

广播音箱场景

音箱类目标设备在 RCSP OTA 中的特点：

芯片平台支持面广（AC707N / AC703N / AC701N / AC697N / AC696N / AC695N 等），Flash 容量通常大于耳机，可承载完整固件与多备份区；
支持复用空间特殊升级流程（V1.1.0 Android 新增）：利用音箱 Flash 中的复用分区进行特殊升级，提升空间利用率；
若音箱具备"广播/转发"角色（一拖多或多设备联动），各音箱仍各自通过 BLE/SPP/BR-EDR 通道与 SDK 建立独立 RCSP OTA 会话，SDK 侧通过事件流区分设备来源。

说明：广播音箱的组网广播协议、多设备联动调度属于应用层/设备固件侧能力，未在本仓库 README 中展开，本页不臆测其实现；SDK 侧仅保证单设备 OTA 会话的正确性与通道多样性。

核心流程

辅助连接下的 OTA 升级时序

以下时序基于 README 定义的收发分离架构（ble_method.dart 发送 / ble_event_stream.dart 接收 / JlOtaPlugin 平台桥接），展示辅助连接（含自动回连）场景下的端到端数据流：

sequenceDiagram
    participant App as App (Flutter)
    participant Sender as ble_method.dart (发送接口)
    participant Plugin as JlOtaPlugin (平台插件)
    participant Device as 目标设备 (音箱/耳机)
    participant Receiver as ble_event_stream.dart (接收接口)

    App->>Sender: 发起连接/升级指令
    Sender->>Plugin: MethodChannel 调用
    Plugin->>Device: 建立 BLE / SPP / Gatt Over BR/EDR 连接
    Device-->>Plugin: 连接建立应答
    Plugin-->>Receiver: 连接状态事件
    Receiver-->>App: 事件分发 (onConnect)
    App->>Sender: 下发 OTA 固件数据
    Sender->>Plugin: 分包透传 RCSP 指令
    Plugin->>Device: 固件数据包
    Device-->>Plugin: ACK/进度
    Plugin-->>Receiver: 进度事件流
    Receiver-->>App: 进度回调 (onProgress)
    alt 单备份升级需重启
        Device--xPlugin: 连接断开 (设备重启)
        Plugin-->>Receiver: 断开事件
        Receiver-->>App: onDisconnect
        App->>Sender: SDK 自动回连 BLE
        Sender->>Plugin: 自动重连指令
        Plugin->>Device: 重新建立 BLE 连接
        Device-->>Plugin: 回连成功
    end
    Plugin->>Device: 升级完成/校验指令
    Device-->>Plugin: 升级结果
    Plugin-->>Receiver: 结果事件
    Receiver-->>App: 完成回调 (onComplete)

流程要点：

先订阅、后发送：上层先监听 ble_event_stream.dart，再通过 ble_method.dart 发指令——事件与指令一一对应，避免丢失早期回调。
通道可替换：建立连接的通道（BLE/SPP/BR-EDR）由插件层按设备能力选择，上层业务感知的是同一套事件语义。
自动回连是辅助连接的核心闭环：单备份升级的设备重启导致连接中断是预期内的事件，SDK 自动回连 BLE 后继续完成升级，无需用户干预——这正是 V1.1.0"单备份OTA自动回连BLE功能"的设计意图（提升用户体验）。
广播音箱多设备：每个音箱是独立会话，事件流按设备来源分发；多会话并发时，上层需按设备 ID 匹配事件（多设备调度细节属应用层职责）。

通道选择决策流程

flowchart TD
    Start(["开始升级"]) --> Scan["扫描/发现目标设备"]
    Scan --> CheckChip{"设备支持哪种通道?"}
    CheckChip -->|"支持 BLE"| BLEPath["BLE 连接 (GATT)"]
    CheckChip -->|"仅经典蓝牙 + GATT 服务"| BRPath["Gatt Over BR/EDR 连接"]
    CheckChip -->|"仅 SPP"| SPPPath["经典蓝牙 SPP 连接"]
    BLEPath --> Reconnect{"升级中设备重启?"}
    BRPath --> Reconnect
    SPPPath --> Reconnect
    Reconnect -->|"是 (单备份)"| AutoRC["自动回连 BLE"]
    Reconnect -->|"否"| Upgrade["执行 RCSP OTA 升级"]
    AutoRC --> Upgrade
    Upgrade --> Done(["升级完成"])

该决策树说明了辅助连接的"兜底"属性：无论主通道是哪种，只要单备份升级发生重启，SDK 都以 BLE 自动回连作为统一恢复路径（BLE 扫描与重连成本最低、对用户最透明）。

使用示例

工程依赖配置（pubspec.yaml 插件声明）

接入 SDK 时需在 pubspec.yaml 中声明平台插件，Android 侧注册 JlOtaPlugin，iOS 侧声明同名插件类：

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

Source: README.md

快速开始（运行参考工程）

参考工程位于 code/JL_OTA，通过 Android Studio 打开后直接运行到 Android/iOS 设备即可体验各项功能（含辅助连接与音箱升级）：

git clone https://github.com/Jieli-Tech/JL_OTA_Flutter.git
cd JL_OTA_Flutter
# 打开 Android Studio → "Open an existing project" → 选择 code/ 目录下的 JL_OTA 项目

Source: README.md

说明：由于 code/ 与 libs/ 不在当前快照中，本页无法给出 ble_method.dart / ble_event_stream.dart 的真实调用代码示例；上层接入范式（先订阅事件流、再通过发送接口发指令）以 README 的收发分离结构为依据，具体方法签名请以官方收发接口介绍文档为准。

配置选项

配置项	类型	默认/要求	说明
`plugin.platforms.android.package`	string	`com.jieli.otasdk`	Android 插件包名，接入时按需替换为自己的包名
`plugin.platforms.android.pluginClass`	string	`JlOtaPlugin`	Android 插件实现类
`plugin.platforms.ios.pluginClass`	string	`JlOtaPlugin`	iOS 插件实现类
操作系统	-	Android 6.0+ / iOS 12.0+	需支持 BLE 功能（自动回连依赖 BLE 扫描）
硬件	-	支持 RCSP OTA 的杰理 SDK 芯片	AC707N、AC703N、AC701N、AC697N、AC696N、AC695N 等
开发平台	-	Android Studio（建议最新版）	支持 Flutter 工程

API Reference

发送接口（`libs/ble_method.dart`）

角色：封装所有"发送"动作——发起连接、下发 OTA 固件数据、透传自定义 RCSP 命令等。

状态：⚠️ 该文件未包含在当前仓库快照中，方法签名无法从源码验证。依据 README 工程结构（README.md），其职责边界为：

连接/断开目标设备（按通道类型选择 BLE、SPP 或 Gatt Over BR/EDR）；
启动 RCSP OTA 升级并分包发送固件；
发送自定义命令（V1.1.0 新增能力）；
触发/管理自动回连流程。

接收接口（`libs/ble_event_stream.dart`）

角色：以事件流（Stream）形式推送设备侧异步事件——连接状态、升级进度、结果与错误。

状态：⚠️ 同样未包含在当前快照中。依据收发分离设计，预期事件类别包括（推测自 README 的调试描述"查看OTA连接状态和数据交互"，见 README.md）：

连接建立/断开事件（自动回连的触发信号）；
升级进度与结果事件；
错误/异常事件。

如实声明：以上为基于架构角色与 README 描述的职责推断，不是从源码提取的真实签名。精确的参数、返回值与异常类型请查阅官方 SDK 接入文档或仓库 doc/ 目录下的《Jieli OTA Upgrade (Flutter) - Send/Receive Interface Introduction》文档。

故障模式、边界情况与并发

以下内容基于 README 中的版本历史与调试章节（README.md），并标注可验证性：

故障/边界	现象	SDK 侧处理/排查	来源依据
OTA 回连超时（iOS）	单备份升级重启后 BLE 回连迟迟不成功	V1.1.0 已修复"OTA回连超时问题"	版本历史，V1.1.0
单备份升级中途断连	设备重启导致连接中断	触发自动回连 BLE 机制，续传/完成升级	功能表"自动回连"、版本历史 V1.1.0
通道不支持	目标设备无 BLE，仅有经典蓝牙	使用 Gatt Over BR/EDR 或 SPP 通道	功能表、版本历史 V1.1.0
连接/数据异常	升级卡住、数据交互错误	通过 SDK 日志查看"连接状态和数据交互"	调试技巧章节
多设备并发（一拖多音箱）	多个音箱同时升级	事件流按设备分发，需上层按设备匹配；并发调度属应用层职责	收发分离架构（推断）

并发与一致性要点：

蓝牙链路本身是串行的，SDK 通过"发送接口 + 事件流"模型天然串行化指令与应答，避免多线程竞态——这是收发分离设计的另一动机；
自动回连期间，上层不应重复发起连接指令，否则可能造成双重连接；回连状态应完全依赖 SDK 事件驱动（推断，需官方文档确认）。

性能与运维注意事项

日志是主要排障手段：SDK 提供详细日志，覆盖 OTA 连接状态与数据交互；
- Android：Android Studio Logcat 实时查看；
- iOS：Xcode Console 实时查看。
环境要求：Android 6.0+ / iOS 12.0+，设备需支持 BLE（自动回连依赖 BLE 栈）；建议使用最新版 Android Studio。
通道选择影响体验：BLE 功耗低但重连快；Gatt Over BR/EDR 链路更稳定但建立较慢；SPP 适合经典蓝牙外设。升级大固件（音箱）时优先考虑链路稳定性。
官方调试指引：Android SDK 调试说明、iOS SDK 调试说明（来源：README.md）。

扩展点

基于版本历史与功能表（README.md），SDK 提供的扩展能力：

自定义命令（V1.1.0 新增）：通过 SDK 透传 RCSP 私有命令，是接入私有辅助业务（设备信息查询、广播组网控制等）的主要扩展点；
复用空间升级（Android，V1.1.0）：复用空间特殊升级流程，适用于需要提升 Flash 利用率的产品（如音箱）；
Gatt Over BR/EDR 通道（Android/iOS，V1.1.0）：为仅支持经典蓝牙的设备提供 GATT 语义的升级通道；
参考工程 code/JL_OTA：提供完整业务示例，可在其上扩展多设备管理、广播音箱联动等应用层能力（该目录未包含在当前快照中）。

README.md（中文总览）
README_EN.md（英文总览）
LICENSE（Apache 2.0）
官方文档中心：Android OTA SDK 文档、iOS OTA SDK 文档
相邻专题页（目录导航）：BLE 升级 / SPP 升级 / 自动回连 / 复用空间升级 —— 各页分别覆盖对应通道与流程的完整升级细节，本页仅从辅助连接与广播音箱视角引用其通道与机制