OTA 参数配置

本页介绍 Android-JL_OTA SDK 中 OTA 参数配置（BluetoothOTAConfigure）的完整机制：配置类的职责、全部可配置项、配置生效流程（OtaManager.configure()）、固件文件设置方式以及回连参数配置，并给出从仓库源码提取的真实使用示例。

Purpose and Scope

本页聚焦于 OTA 参数配置 这一能力：即通过 BluetoothOTAConfigure 构建配置对象，并在 OTA 开始前通过 configure() 应用到 OTA 管理器（BluetoothOTAManager）的完整过程。

本页覆盖：

  • 配置类 BluetoothOTAConfigure 的职责与设计（优先级、鉴权、BLE 时序、MTU、超时、回连等）
  • 固件来源配置（setFirmwareFilePath / setFirmwareFileData）
  • 配置生效的入口 OtaManager.configure() 与读取入口 getBluetoothOption()
  • 自动回连场景下的 BleConnectParam 配置
  • 从 OtaDemo.java 提取的真实用法、时序与边界情况

不在此页覆盖（留给兄弟页面）：

  • OTA 升级主流程（startOTA、进度回调、IUpgradeCallback）—— 参见 OTA 升级流程页面
  • BLE 连接管理与数据透传实现（BleManager、OtaFileObserver）—— 参见 BLE 连接管理页面
  • 强制升级查询与设备信息解析（queryMandatoryUpdate、TargetInfoResponse）—— 参见设备信息页面

说明：BluetoothOTAConfigure 类本体位于外部依赖库 com.jieli.jl_bt_ota（AAR 依赖）中，本仓库不包含其源码；本页依据仓库内 OtaDemo.java 中对其公开 API 的实际调用方式、参数注释与常量引用进行归纳整理。仓库内未出现的配置项不会凭空杜撰。

Overview

OTA（Over-The-Air）升级是蓝牙设备固件更新的核心能力。在开始升级之前，SDK 必须知道一组关键参数：走哪种蓝牙通道（BLE 还是 SPP）、是否校验设备鉴权、BLE 发包间隔、命令超时时间、BLE MTU 值、是否需要回连、以及固件文件从哪里读取。这些参数全部收敛在 BluetoothOTAConfigure 配置对象中。

设计意图：

  • 集中配置、一次生效：所有参数通过链式 setter 构建，在 OTA 开始前调用一次 configure() 即可整体生效，避免散落在各调用点的魔法值。
  • 默认值先行：BluetoothOTAConfigure.createDefault() 提供一组经过验证的默认参数（如 BLE 发包间隔默认 500ms），开发者只需按项目需要覆盖少数几项。
  • 运行时可读可改：通过 otaManager.getBluetoothOption() 可在 OTA 流程中读取（甚至在开始前修改）配置，例如在获取到固件路径后再设置 setFirmwareFilePath()。
  • 关注点分离：连接层（BluetoothOTAManager 抽象方法）与配置层（BluetoothOTAConfigure）解耦；SDK 只依赖配置对象驱动行为，具体蓝牙连接由接入方实现。
flowchart TD
    subgraph sg_App["接入方 App"]
        App["App / 业务代码"]
    end

    subgraph sg_Config["OTA 参数配置层"]
        Config["BluetoothOTAConfigure"]
        Builder["链式 setter 构建<br/>setPriority / setMtu / setTimeoutMs ..."]
        Firmware["固件来源<br/>setFirmwareFilePath / setFirmwareFileData"]
    end

    subgraph sg_Manager["OTA 管理核心 (外部库 jl_bt_ota)"]
        Manager["BluetoothOTAManager"]
        Configure["configure(BluetoothOTAConfigure)"]
        Option["getBluetoothOption()"]
        OtaEngine["OTA 升级引擎"]
    end

    subgraph sg_Impl["接入方实现层"]
        OtaManager["OtaManager (继承 BluetoothOTAManager)"]
        Ble["BleManager / 连接实现"]
    end

    App --> Config
    Config --> Builder
    Config --> Firmware
    App --> OtaManager
    OtaManager --> Manager
    Configure --> OtaEngine
    Option --> Config
    OtaEngine --> Ble

架构说明：接入方 App 构建 BluetoothOTAConfigure（链式 setter 与固件来源），随后通过继承自 BluetoothOTAManager 的 OtaManager.configure() 将配置注入 OTA 核心；升级引擎按配置驱动行为，并通过接入方实现的连接层（BleManager）收发数据。配置对象在运行时仍可通过 getBluetoothOption() 读取/修改，形成"构建 → 注入 → 读取/微调"的闭环。

配置类 BluetoothOTAConfigure 详解

类定位与包结构

BluetoothOTAConfigure 位于外部 OTA 库 com.jieli.jl_bt_ota.model 包，是 OTA 参数的唯一载体。仓库代码中的引用方式：

import com.jieli.jl_bt_ota.model.BluetoothOTAConfigure;
import com.jieli.jl_bt_ota.model.ble.BleConnectParam;

Source: OtaDemo.java

与之配套的类型包括：

  • BluetoothOTAManager（com.jieli.jl_bt_ota.impl）：OTA 管理器基类，提供 configure() 与 getBluetoothOption()；
  • BleConnectParam（com.jieli.jl_bt_ota.model.ble）：自动回连 BLE 时的连接参数；
  • BaseError / ErrorCode / StateCode：错误与状态常量。

创建默认配置

BluetoothOTAConfigure.createDefault() 是官方推荐的构造入口，返回带有一组内置默认值的配置对象，之后通过链式 setter 覆盖需要调整的项：

BluetoothOTAConfigure bluetoothOption = BluetoothOTAConfigure.createDefault();
bluetoothOption.setPriority(BluetoothOTAConfigure.PREFER_BLE) //请按照项目需要选择
        .setUseAuthDevice(true) //具体根据固件的配置选择
        .setBleIntervalMs(500) //默认是500毫秒
        .setTimeoutMs(3000) //超时时间
        .setMtu(500) //BLE底层通讯MTU值，会影响BLE传输数据的速率。建议用500 或者 270。该MTU值会使OTA库在BLE连接时改变MTU，所以用户SDK需要对此处理。
        .setNeedChangeMtu(false) //不需要调整MTU，建议客户连接时调整好BLE的MTU
        .setUseReconnect(false); //是否自定义回连方式，默认为false，走SDK默认回连方式，客户可以根据需求进行变更
bluetoothOption.setFirmwareFilePath(firmwarePath); //设置本地存储OTA文件的路径

Source: OtaDemo.java

设计意图：

  • createDefault() + 链式 setter 的组合让"安全默认值"与"按需覆盖"并存——大多数项目只需关心通道优先级、MTU 与回连策略；
  • 注释中明确标注了每个参数的建议值（MTU 500/270、BleIntervalMs 500），说明这些默认值来自 Jieli 在大量设备上的实测经验；
  • setNeedChangeMtu(false) 的注释（"建议客户连接时调整好 BLE 的 MTU"）表明 SDK 刻意将 MTU 协商职责留给接入方，避免在 OTA 过程中二次修改 MTU 引入时序问题。

配置项一览

以下配置项均依据 OtaDemo.java 中对 BluetoothOTAConfigure 的实际调用与注释整理：

配置项设置方法类型默认值/建议值作用与注意事项
通道优先级setPriority(int)intPREFER_BLE选择 OTA 通讯方式。常量 BluetoothOTAConfigure.PREFER_BLE（另有 PREFER_SPP 对应 SPP 通道），需按项目硬件能力选择
设备鉴权setUseAuthDevice(boolean)boolean依固件而定是否校验设备鉴权，须与固件配置一致，否则连接校验失败
BLE 发包间隔setBleIntervalMs(int)int500BLE 发送数据包的间隔（毫秒），影响传输速率与稳定性
命令超时setTimeoutMs(int)int3000OTA 命令超时时间（毫秒），超时后按错误处理
MTU 值setMtu(int)int500（或 270）BLE 底层通讯 MTU，直接影响单包载荷与传输速率；SDK 会在 BLE 连接时按此值尝试改变 MTU，接入方需对此处理
是否调整 MTUsetNeedChangeMtu(boolean)booleanfalse是否由 OTA 库在连接时调整 MTU；建议接入方在连接阶段自行协商好 MTU
是否自定义回连setUseReconnect(boolean)booleanfalsefalse 走 SDK 默认回连方式；true 时需在 onNeedReconnect() 回调中自行回连
回连 BLE 参数setBleConnectParam(BleConnectParam)BleConnectParam新建默认对象自动回连 BLE 时的连接参数（如扫描/连接策略）
固件文件路径setFirmwareFilePath(String)String无本地 OTA 固件文件路径，startOTA() 前必须设置
固件文件数据setFirmwareFileData(byte[])byte[]无与路径二选一：直接以字节数组提供固件内容，适合已加载到内存的场景

说明：PREFER_SPP 常量与 setFirmwareFileData 之外的 setter 为仓库代码注释/调用所隐含或直接使用；由于依赖库源码不在本仓库，凡未在仓库调用点出现的 API 均未列入上表，避免臆测。

配置生效流程

配置通过 BluetoothOTAManager.configure(BluetoothOTAConfigure) 注入 OTA 核心，源码调用点如下：

otaManager.configure(bluetoothOption); //设置OTA参数

//设置OTA参数，需要开始OTA之前配置才会生效
otaManager.configure(bluetoothOption);

Sources: OtaDemo.java 与 OtaDemo.java

关键约束（源码注释明确强调）：配置必须在开始 OTA 之前设置才会生效。即 configure() 应发生在 startOTA() 之前；流程中如需变更固件路径，可在 startOTA() 前通过 getBluetoothOption() 读取配置对象再修改：

//2.进行OTA升级
//* 需要先设置升级文件路径 - filePath
otaManager.getBluetoothOption().setFirmwareFilePath(filePath);
//* 进行OTA升级，然后根据回调进行UI更新
otaManager.startOTA(new IUpgradeCallback() { ... });

Source: OtaDemo.java

这意味着配置对象在 configure() 之后仍保持可读可写，getBluetoothOption() 返回的是同一实例的引用，便于 OTA 引擎内部按需读取（如 isUseReconnect() 判断回连策略）：

if (otaManager.getBluetoothOption().isUseReconnect()) {
    //2-1 进行自定义回连流程
}

Source: OtaDemo.java

自动回连场景的配置

对于需要断连后自动回连的场景（双备份 OTA / 升级中设备重启），autoReconnectDeviceConfigure() 展示了最小配置集：

public void autoReconnectDeviceConfigure(){
    //构建OTA管理者对象
    OtaManager otaManager = new OtaManager();
    //构建蓝牙OTA库配置
    BluetoothOTAConfigure bluetoothOption = BluetoothOTAConfigure.createDefault();
    //设置开启自动连接BLE设备功能
    bluetoothOption.setUseReconnect(false)
            //配置回连BLE的参数
            .setBleConnectParam(new BleConnectParam());
    //设置OTA参数，需要开始OTA之前配置才会生效
    otaManager.configure(bluetoothOption);
}

Source: OtaDemo.java

设计意图：回连参数独立封装为 BleConnectParam，与 OTA 传输参数分离，反映"回连"是连接层职责而非升级引擎职责；setUseReconnect(false) 表示默认使用 SDK 内置回连流程，接入方仅需提供 BleConnectParam 即可。

核心流程：从构建配置到 OTA 开始

下图展示配置对象从构建、注入到被 OTA 引擎消费的完整时序，节点与调用均来自仓库源码：

sequenceDiagram
    participant App as App 业务代码
    participant CFG as BluetoothOTAConfigure
    participant OM as OtaManager (BluetoothOTAManager)
    participant Engine as OTA 引擎
    participant Conn as 连接层 (BleManager)

    App->>CFG: createDefault()
    App->>CFG: setPriority / setMtu / setTimeoutMs / setUseAuthDevice ...
    App->>CFG: setFirmwareFilePath(path)
    App->>OM: configure(bluetoothOption)
    OM->>Engine: 注入配置（开始 OTA 前必须完成）
    App->>OM: startOTA(callback)
    OM->>Engine: 按配置驱动升级流程
    Engine->>OM: getConnectedDevice() / getConnectedBluetoothGatt()
    OM->>Conn: 使用已配置的 MTU / 发包间隔发送数据
    Engine-->>App: onProgress / onError / onStopOTA 回调

流程要点（按调试/排查顺序理解）：

  1. 构建：createDefault() 拿到带默认值的配置对象，链式 setter 覆盖项目所需项。此阶段不触发任何 IO 或蓝牙操作，纯内存对象构建。
  2. 注入：configure() 将配置对象交给 OTA 管理器。注释强调"开始 OTA 之前配置才会生效"，因此该调用必须先于 startOTA()。
  3. 读取与微调：getBluetoothOption() 返回同一配置实例的引用，可在 startOTA() 前补设固件路径（如示例中先查询强制升级再设置路径）。
  4. 消费：升级引擎依据配置中的通道优先级、鉴权开关、MTU、发包间隔与超时值执行升级；回连策略（isUseReconnect()）在断连回调 onNeedReconnect() 中生效。

使用示例

示例 1：标准 OTA 参数初始化（推荐模板）

public void initOTA(Context context, String firmwarePath) {
    OtaManager otaManager = new OtaManager();
    BluetoothOTAConfigure bluetoothOption = BluetoothOTAConfigure.createDefault();
    bluetoothOption.setPriority(BluetoothOTAConfigure.PREFER_BLE) //请按照项目需要选择
            .setUseAuthDevice(true) //具体根据固件的配置选择
            .setBleIntervalMs(500) //默认是500毫秒
            .setTimeoutMs(3000) //超时时间
            .setMtu(500) //BLE底层通讯MTU值，会影响BLE传输数据的速率。建议用500 或者 270。该MTU值会使OTA库在BLE连接时改变MTU，所以用户SDK需要对此处理。
            .setNeedChangeMtu(false) //不需要调整MTU，建议客户连接时调整好BLE的MTU
            .setUseReconnect(false); //是否自定义回连方式，默认为false，走SDK默认回连方式，客户可以根据需求进行变更
    bluetoothOption.setFirmwareFilePath(firmwarePath); //设置本地存储OTA文件的路径
//        bluetoothOption.setFirmwareFileData(firmwareData);//设置本地存储OTA文件的数据
    otaManager.configure(bluetoothOption); //设置OTA参数
}

Source: OtaDemo.java

这是接入方应照抄的最小模板：7 个 setter 覆盖了通道、鉴权、时序、MTU 与回连五类参数；setFirmwareFilePath 与 setFirmwareFileData 二选一提供固件内容。

示例 2：固件路径后置 + 回连策略读取

//2.进行OTA升级
//* 需要先设置升级文件路径 - filePath
otaManager.getBluetoothOption().setFirmwareFilePath(filePath);
//* 进行OTA升级，然后根据回调进行UI更新
otaManager.startOTA(new IUpgradeCallback() {
    @Override
    public void onNeedReconnect(String addr, boolean isNewReconnectWay) {
        //回调需要回连的设备地址
        //如果客户设置了BluetoothOTAConfigure#setUseReconnect()为true，则需要在此处回调进行自定义回连设备流程
        if (otaManager.getBluetoothOption().isUseReconnect()) {
            //2-1 进行自定义回连流程
        }
    }
});

Source: OtaDemo.java

该示例展示两个关键模式：延迟设置固件路径（在确定升级文件后再写入配置）与运行时读取配置（在回连回调中根据 isUseReconnect() 决定走自定义回连还是 SDK 默认回连）。

示例 3：自动回连配置

public void autoReconnectDeviceConfigure(){
    //构建OTA管理者对象
    OtaManager otaManager = new OtaManager();
    //构建蓝牙OTA库配置
    BluetoothOTAConfigure bluetoothOption = BluetoothOTAConfigure.createDefault();
    //设置开启自动连接BLE设备功能
    bluetoothOption.setUseReconnect(false)
            //配置回连BLE的参数
            .setBleConnectParam(new BleConnectParam());
    //设置OTA参数，需要开始OTA之前配置才会生效
    otaManager.configure(bluetoothOption);
}

Source: OtaDemo.java

适用于双备份 OTA / 升级中设备重启断连的场景：只需配置回连参数即可复用 SDK 内置回连流程，无需实现任何连接代码。

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

以下结论均来自仓库源码注释与示例代码中的显式约束，未在源码中体现的行为不作推测。

配置时机错误（最常见故障）

  • 症状：configure() 在 startOTA() 之后调用，参数不生效或行为异常。
  • 依据：源码注释明确"设置OTA参数，需要开始OTA之前配置才会生效"（OtaDemo.java L56-L57）。
  • 规避：将 configure() 收敛在 initOTA() 等初始化入口，与 startOTA() 分离；如需调整，通过 getBluetoothOption() 在开始前修改。

固件来源缺失

  • 症状：未设置 setFirmwareFilePath 也未设置 setFirmwareFileData 就调用 startOTA()，升级无法启动。
  • 依据：示例代码注释"需要先设置升级文件路径 - filePath"（OtaDemo.java L105-L106）。
  • 规避：路径与字节数据二选一，且必须在 startOTA() 前赋值；推荐使用路径方式，避免大固件常驻内存。

鉴权参数与固件不匹配

  • setUseAuthDevice(true) 的注释注明"具体根据固件的配置选择"（OtaDemo.java L36）。若与固件实际鉴权策略不一致，连接校验阶段会失败。
  • 规避：与固件团队确认鉴权开关后固定该参数，避免运行时动态切换。

MTU 相关边界

  • setMtu(500) 注释说明 SDK 会在 BLE 连接时按该值尝试改变 MTU，接入方需对此处理（OtaDemo.java L39）。
  • setNeedChangeMtu(false) 建议接入方在连接阶段自行协商好 MTU（OtaDemo.java L40）。
  • 风险点：若接入方在连接后自行协商了 MTU，而配置中 setNeedChangeMtu(true) 且 setMtu() 值更小，OTA 库可能再次发起 MTU 协商，造成短时窗口内数据包分片不一致。示例中给出的建议组合是：连接时协商好 MTU，OTA 配置 setNeedChangeMtu(false)。

重复连接状态上报

示例中 OtaManager 构造函数内对连接状态上报有明确要求：不要重复传入相同状态（连接中-已连接-断开 或 已连接-断开 的完整状态机）（OtaDemo.java L163-L166）。配置层虽不直接涉及并发，但 getBluetoothOption() 返回的是共享实例引用——若在 OTA 进行中从多线程修改配置，可能引发竞态。建议：配置对象在 OTA 开始后视为只读，修改只发生在 startOTA() 之前。

回连策略不一致

  • setUseReconnect(false) 时 SDK 走默认回连；setUseReconnect(true) 时必须在 onNeedReconnect() 回调中自行回连（OtaDemo.java L115-L121）。
  • 风险点：设置为 true 但未实现回调内的回连逻辑，设备升级中断后将无法恢复，导致升级流程挂起直至超时。

性能与运维注意事项

  • MTU 与传输速率：setMtu(500) 注释指出 MTU 直接影响 BLE 传输数据的速率，建议 500 或 270（OtaDemo.java L39）。MTU 越大单包载荷越大，同等发包间隔下吞吐越高；但过大的 MTU 在信号弱时丢包重传成本也更高，需按设备能力权衡。
  • 发包间隔：setBleIntervalMs(500) 默认 500ms（OtaDemo.java L37）。间隔越小传输越快，但对 CPU 与蓝牙栈调度更敏感，需实测确认稳定性。
  • 超时配置：setTimeoutMs(3000) 为命令超时（OtaDemo.java L38）。过短会在弱信号下误判失败，过长会拖慢失败恢复，建议按目标设备实测。
  • 内存占用：优先使用 setFirmwareFilePath，仅在固件已加载到内存时使用 setFirmwareFileData，避免大固件（数百 KB ~ 数 MB）常驻堆内存。

扩展点

配置层的扩展点集中在 OtaManager extends BluetoothOTAManager 的抽象方法上（OtaDemo.java L152-L184）：

扩展点方法说明
连接状态透传onBtDeviceConnection(device, status)接入方把自有连接库的状态转换为 OTA 库状态机后上报；注意状态转换规则（连接中-已连接-断开）
数据透传onReceiveDeviceData(device, data)把蓝牙收到的通知数据交给 OTA 库解析
MTU 变更透传onMtuChanged(gatt, mtu, status)非必要实现，建议接入方在连接时自行协商 MTU，与 setNeedChangeMtu(false) 配套
已连接设备getConnectedDevice()返回当前连接的 BluetoothDevice，断开时返回 null
GATT 对象getConnectedBluetoothGatt()仅 BLE 通道 OTA 需要实现
回连/断开/发送connectBluetoothDevice / disconnectBluetoothDevice / 数据发送回连流程由 setUseReconnect() 与 BleConnectParam 驱动

这些扩展点与配置层的关系：配置决定"做什么"（策略），扩展点决定"怎么做"（通道实现）。接入方最小工作量为实现连接状态与数据透传两个回调，其余可按需覆盖。

相关链接

说明：BluetoothOTAConfigure、BluetoothOTAManager、BleConnectParam 等类的源码位于外部依赖 com.jieli.jl_bt_ota 库中，本仓库不包含其实现；本文基于仓库内真实调用点整理，未在仓库中出现的 API 未作收录。