发送接口 BleMethod

BleMethod 是杰理 OTA Flutter SDK 面向业务层的静态发送/操作接口门面，封装了 BLE 扫描、连接、断开与连接方式设置等蓝牙操作，供 App 以 await BleMethod.xxx() 的方式异步调用。

Purpose and Scope

本页介绍 JL OTA Flutter SDK 中 BleMethod 这一发送接口的完整职责与用法，包括：

• BleMethod 在 SDK 分层中的位置与设计意图（静态门面模式）；
• 每个公开方法的调用方式、参数语义与典型使用场景；
• 扫描 → 连接 → 设置连接方式 → 发送 → 断开的完整调用流程；
• 失败模式、边界情况与并发注意事项。

⚠️ 重要说明：本仓库（Jieli-Tech/JL_OTA_Flutter）实际包含的内容为接口介绍文档（doc/ 目录下的《Jieli OTA Upgrade (Flutter) Send:Receive Interface Introduction》）与 README，未包含 SDK 的 Dart 实现源码。因此本页内容以官方接口介绍文档为依据整理，凡是文档未明确给出的方法签名细节，均如实标注为"文档未详述"，不做臆造。

本页属于 SDK 核心 API（2-sdk-core-api）目录下的叶子页面。接收侧回调、数据解析等其他能力由目录中的其他页面（如接收接口/回调相关页面）分别介绍，不在本页展开。

Overview

在杰理 OTA 升级流程中，App 需要通过低功耗蓝牙（BLE）与内置杰理芯片的耳机/音箱等设备交互：先扫描发现设备，再建立连接，随后通过蓝牙通道发送固件升级数据。BleMethod 正是 SDK 提供给业务层的这组操作的统一入口。

从官方文档的用法示例可以看到，BleMethod 的全部方法都是异步的（以 await 调用），业务层无需关心底层蓝牙协议细节——扫描、连接状态机、连接方式协商等都被收敛在 SDK 内部。这种设计带来的好处：

1. 调用面极简：业务代码只需几行即可完成扫描/连接/断开等操作；
2. 错误处理统一：异步方法配合 try/catch 即可捕获失败场景；
3. 平台无关：底层 BLE 实现（Flutter 插件/系统蓝牙栈）被门面隔离，App 跨平台行为一致。

BleMethod 提供的操作可归纳为三类：

Architecture

BleMethod 在 SDK 中扮演"静态门面"（Static Facade）角色：App 只依赖 BleMethod 这一组静态方法，SDK 内部再将调用分发到蓝牙扫描、连接管理等具体模块。

flowchart TD
    subgraph sg_App["应用层 (App)"]
        App["OTA 页面 / 业务逻辑<br/>await BleMethod.xxx()"]
    end

    subgraph sg_SDK["JL OTA Flutter SDK"]
        BM["BleMethod<br/>静态发送接口"]
        Scan["扫描模块<br/>startScan / stopScan"]
        Conn["连接模块<br/>connectDevice / disconnectBtDevice"]
        Way["连接方式模块<br/>getConnectWay / setConnectWay"]
        Const["AppConstants<br/>communicationWayBle 等常量"]
    end

    subgraph sg_BLE["系统 BLE 栈"]
        Stack["Flutter 蓝牙插件 / 系统蓝牙"]
        Device["目标设备<br/>（杰理芯片耳机/音箱）"]
    end

    App -->|"await 调用"| BM
    BM --> Scan
    BM --> Conn
    BM --> Way
    Way -.->|"引用常量"| Const
    Scan -->|"扫描指令"| Stack
    Conn -->|"连接/断开指令"| Stack
    Stack <-->|"BLE 数据通道"| Device

各节点职责说明：

• App（应用层）：OTA 页面与业务逻辑，只通过 BleMethod 的静态方法操作蓝牙，不直接触碰底层 API。
• BleMethod：统一入口门面，把所有操作组织为可 await 的异步方法，并向上抛出异常供业务层捕获。
• 扫描/连接/连接方式模块：SDK 内部按职责拆分的功能模块，被门面调度；对业务层透明。
• AppConstants：连接方式等配置常量的存放处，setConnectWay() 需要传入其中的常量值。
• 系统 BLE 栈与目标设备：数据最终经系统蓝牙通道到达杰理芯片设备。

分层动机：将蓝牙细节封装在门面之后，业务层获得稳定的调用契约；未来 SDK 更换底层蓝牙实现（例如从 flutter_blue 切换到 flutter_blue_plus）时，BleMethod 的签名可保持不变。

主要接口解析

以下每个方法均以官方接口介绍文档中的用法示例为来源，逐一说明其语义、调用方式与设计意图。代码块均摘自 doc/Jieli OTA Upgrade (Flutter) Send:Receive Interface Introduction.md。

startScan() —— 启动 BLE 扫描

扫描是 OTA 流程的第一步：必须先发现周围处于广播状态的杰理设备，才能拿到设备索引用于后续连接。

// 开始扫描
await BleMethod.startScan();

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

• 异步方法，await 等待扫描启动动作完成（非阻塞业务 UI）。
• 扫描结果通常通过接收侧回调/事件通知业务层（扫描到的设备列表由 SDK 维护，业务层随后用索引引用设备）。
• 设计意图：把"扫描启动"这一动作原子化，避免业务层自行管理蓝牙适配器状态。

stopScan() —— 停止扫描

扫描会持续消耗蓝牙资源与电量，找到目标设备后应立即停止扫描，再进入连接阶段。

// 停止扫描
await BleMethod.stopScan();

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

• 与 startScan() 成对使用，官方文档将其单独列出，提示业务层在合适的时机主动调用。

connectDevice(index) —— 按索引连接设备

连接需要传入扫描结果中的设备索引（index），SDK 内部根据索引定位设备并发起 BLE 连接。官方文档示例使用 try/catch 包裹，说明连接失败是预期内的常见场景（设备离开广播范围、连接超时、配对失败等）：

try {
  // 连接设备，index 为扫描到的设备索引
  await BleMethod.connectDevice(index);
} catch (e) {
  // 连接失败处理
}

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

• 参数 index：设备在扫描列表中的索引，必须来自扫描结果，业务层不可自行编造。
• 异常：连接失败时抛出异常，由调用方捕获处理（示例中 catch (e)）。
• 设计意图：以索引代替设备对象，简化跨层传递；同时强制"先扫描后连接"的顺序约束。

disconnectBtDevice(index) —— 断开设备连接

OTA 升级完成或用户主动取消时，通过设备索引断开 BLE 连接，释放蓝牙资源。

try {
  // 断开连接
  await BleMethod.disconnectBtDevice(index);
} catch (e) {
  // 断开失败处理
}

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

• 同样以 index 定位设备，并与 connectDevice(index) 使用同一套索引体系。
• 断开同样可能抛异常（如设备已不在连接表中），示例同样以 try/catch 处理。

getConnectWay() —— 获取当前连接方式

查询 SDK 当前使用的通信方式（如 BLE）。返回值为表示连接方式的整数，业务层可据此判断当前链路类型。

// 获取当前连接方式
await BleMethod.getConnectWay();

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

• 返回值语义与 AppConstants 中的连接方式常量对应（详见下文"配置选项"）。

setConnectWay(communicationMethod) —— 设置连接方式

在连接/发送前，业务层需要明确本次通信走哪种方式。官方示例使用 AppConstants.communicationWayBle 常量作为参数，表示使用 BLE 通信：

// 设置连接方式为 BLE
int communicationMethod = AppConstants.communicationWayBle;
await BleMethod.setConnectWay(communicationMethod);

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

• 参数 communicationMethod：整数，取值来自 AppConstants（文档明确出现的常量为 communicationWayBle；SDK 是否还提供经典蓝牙等其他方式，文档未在已采集片段中详述）。
• 设计意图：将"通信方式"显式化为可配置参数而非硬编码，为后续支持多种无线通信方式（BLE / 经典蓝牙等）预留扩展点。

核心调用流程

一次典型的 OTA 前置流程（扫描 → 连接 → 设置连接方式 → 断开）如下：

sequenceDiagram
    participant App as App 业务层
    participant BM as BleMethod
    participant Stack as 系统 BLE 栈
    participant Dev as 杰理设备

    App->>BM: startScan()
    BM->>Stack: 启动扫描
    Stack-->>App: 扫描到设备（回调/事件）
    App->>BM: stopScan()
    BM->>Stack: 停止扫描
    App->>BM: connectDevice(index)
    BM->>Stack: 发起 BLE 连接
    Stack->>Dev: 连接请求
    Dev-->>Stack: 连接成功
    Stack-->>BM: 连接结果
    App->>BM: getConnectWay()
    BM-->>App: 当前连接方式
    App->>BM: setConnectWay(AppConstants.communicationWayBle)
    BM->>Stack: 协商/设置 BLE 通道
    Note over App,Dev: OTA 固件数据通过发送接口下发（本页主题）
    App->>BM: disconnectBtDevice(index)
    BM->>Stack: 断开连接

流程要点：

1. 先扫描后连接：connectDevice(index) 依赖扫描结果索引，顺序颠倒会因索引无效而失败；
2. 扫描有始有终：startScan() 与 stopScan() 成对出现，避免持续耗电；
3. 连接失败可重试：connectDevice 抛出的异常应被捕获，业务层可提示用户后重新扫描/连接；
4. 连接方式先行：在发送数据前用 setConnectWay() 明确通信方式，保证后续发送走预期通道；
5. 善后断开：流程结束后用 disconnectBtDevice() 释放蓝牙资源。

API 参考

方法签名基于官方接口介绍文档中的调用方式（全部为 await 异步调用）整理；本仓库不含 SDK 实现源码，具体返回类型与底层实现细节以官方 SDK 为准。文档片段中 index 为扫描结果中的设备索引。

异常约定：

• connectDevice(index) / disconnectBtDevice(index)：操作失败时抛出异常，业务层应使用 try/catch 捕获（见官方文档示例）。

配置选项

BleMethod 自身的可配置项不多，主要配置通过 AppConstants 常量与 setConnectWay() 传入：

说明：AppConstants 中除 communicationWayBle 外是否还有其他通信方式常量（例如经典蓝牙、双模等），官方文档已采集片段未详述，可查阅 SDK 的 AppConstants 定义确认。

使用示例

基础示例：扫描并连接设备

摘自官方接口介绍文档的完整流程片段：

// 1. 开始扫描
await BleMethod.startScan();

// 2. 停止扫描
await BleMethod.stopScan();

// 3. 连接设备（index 为扫描结果中的索引）
try {
  await BleMethod.connectDevice(index);
} catch (e) {
  // 连接失败处理
}

// 4. 断开连接
try {
  await BleMethod.disconnectBtDevice(index);
} catch (e) {
  // 断开失败处理
}

来源：Jieli OTA Upgrade (Flutter) Send:Receive Interface Introduction.md（示例由文档中 L34、L49、L71、L98 各片段合并整理）

进阶示例：设置 BLE 连接方式

// 获取当前连接方式
await BleMethod.getConnectWay();

// 设置连接方式为 BLE 后开始发送
int communicationMethod = AppConstants.communicationWayBle;
await BleMethod.setConnectWay(communicationMethod);

来源：Jieli OTA Upgrade (Flutter) Send:Receive Interface Introduction.md（示例由文档中 L121、L140 片段合并整理）

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

失败模式

边界情况

• 索引语义：index 是"扫描列表中的位置"，不是设备地址；connectDevice 与 disconnectBtDevice 必须使用同一批扫描结果中的索引，跨扫描批次混用会定位到错误设备或直接失败。
• 方法顺序：官方文档的流程暗示严格的顺序约束（扫描 → 连接 → 设置连接方式 → 断开）。跳过扫描直接连接、连接前未设置连接方式，都可能产生未定义行为。
• 重复调用：startScan() 重复调用、未停止扫描就连接等场景，文档未明确其行为；建议业务层自行保证调用顺序，避免依赖未文档化的内部状态。

并发注意

• BleMethod 的方法是异步的，多个 await 并发调用（例如同时触发扫描与连接）可能相互干扰。官方文档示例均为顺序 await，业务层应保持"一个操作完成再发起下一个"的串行节奏。
• 断开连接与发送数据并发执行时，应以断开结果为准，防止对已释放通道继续写入。

性能与运维建议

• 及时停止扫描：BLE 扫描是耗电大户，startScan() 后应在发现目标设备时立即 stopScan()，再进入连接流程。
• 失败重试策略：连接失败后建议带退避地重试（如重新扫描 → 重新连接），避免高频重试冲击蓝牙协议栈。
• 日志与状态：建议业务层记录扫描、连接、断开、连接方式设置等关键节点的结果与耗时，便于定位 OTA 链路问题。

扩展点

• 连接方式扩展：setConnectWay(communicationMethod) 把通信方式参数化，SDK 未来可新增其他连接方式常量（如经典蓝牙、双模），业务层只需传入对应常量即可切换链路，无需改动调用结构。
• 门面模式隔离：BleMethod 是唯一稳定契约，底层蓝牙实现可独立演进（换插件、改协议栈）而不影响业务代码。

测试情况

本仓库为接口文档仓库，未包含 SDK 的单元测试或集成测试源码，因此无法给出测试覆盖说明。业务接入时建议自行验证以下用例：

• 扫描到设备 → 停止扫描 → 按索引连接成功；
• 传入非法索引（越界/过期）时 connectDevice 正常抛异常且不影响后续调用；
• 设置连接方式后 getConnectWay() 返回一致；
• 断开后再次连接同一索引的链路恢复行为。

Related Links

• 官方接口介绍文档（中文版）：Jieli OTA Upgrade (Flutter) Send:Receive Interface Introduction.md
• 官方接口介绍文档（英文版）：Jieli OTA Upgrade (Flutter) Send:Receive Interface Introduction_en.md
• 项目根目录说明：README.md 与 README_EN.md
• 接收侧回调与数据解析：见 SDK 核心 API 目录下的接收接口/回调相关页面（本仓库未包含对应实现源码，以官方 SDK 为准）