OTA 核心库集成

杰理 OTA 核心库（jl_bt_ota_Vxxx-release.aar）是 Android-JL_OTA SDK 中承载 RCSP 协议处理与固件升级流程控制能力的二进制组件。本文档说明如何将该 AAR 核心库集成到 Android 工程中，包括依赖配置、权限声明、OTA 参数配置、核心 API 与运行流程。

Purpose and Scope

本页面向集成方（需要把杰理 OTA 能力接入自有 App 的开发者），完整覆盖：

• 核心库 AAR 的获取与放置方式
• build.gradle 依赖声明与工程配置
• AndroidManifest.xml 权限声明
• OTAManager + BluetoothOTAConfigure 的参数配置
• 核心库运行架构、升级主流程、失败模式与版本兼容性

以下主题属于兄弟页面的范畴，本页只做衔接引用，不展开：

• BLE/SPP 传输通道的具体实现细节 → 参见各传输通道相关页面
• Demo 应用 UI（BroadcastBoxActivity、UpgradeFragment、文件选择器等）→ 参见 OTA Demo 应用页面
• RCSP 协议指令级细节 → 参见 RCSP 协议文档
• 设备端（AC697N/AC696N 等）固件开发 → 参见杰理官方芯片 SDK 文档

概述

Android-JL_OTA 是珠海市杰理科技股份有限公司为杰理蓝牙类产品提供的固件升级开发平台，专门实现 RCSP OTA 升级功能，支持 BLE、SPP 等多种传输方式。整个 SDK 的能力边界中，核心库 AAR 是唯一的二进制闭源组件，对外暴露 OTAManager、BluetoothOTAConfigure 等公开 API，而协议状态机、升级流程控制、传输调度全部封装在 AAR 内部。

核心库提供的能力（摘自 README.md）：

运行环境要求（摘自 README.md）：操作系统 Android 5.1+（minSdk 21）、支持 RCSP OTA 的杰理 SDK 硬件（AC707N、AC703N、AC701N、AC697N、AC696N、AC695N 等）、Java/Kotlin 均支持。

设计意图：将协议与流程控制封装为二进制 AAR，一方面保护 RCSP 协议实现的商业机密，另一方面为集成方提供稳定的 API 面——集成方只需"放置 AAR → 声明依赖 → 配置参数 → 调用升级"，无需关心底层协议细节。1.9.0 版本起核心库去掉单例使用限制、升级流程独立，支持多设备并发升级。

架构

flowchart TD
    subgraph sg_App["应用层（otasdk Demo 工程）"]
        UI["BroadcastBoxActivity / UpgradeFragment"]
        Picker["UpgradeFilePickerAdapter"]
        Dialog["DialogUpgradeDevice"]
    end

    subgraph sg_Core["核心库 jl_bt_ota_V1.11.0-release.aar"]
        OTA["OTAManager"]
        Cfg["BluetoothOTAConfigure"]
        Flow["升级流程控制"]
        RCSP["RCSP 协议处理"]
        BLE["BLE 传输通道"]
        SPP["SPP 传输通道"]
    end

    subgraph sg_Device["设备端"]
        DEV["杰理蓝牙设备<br/>（AC697N / AC696N 等）"]
    end

    UI -->|"调用公开 API"| OTA
    OTA -->|"配置参数"| Cfg
    OTA --> Flow
    Flow --> RCSP
    Flow --> BLE
    Flow --> SPP
    BLE -->|"BLE / Gatt Over BR/EDR"| DEV
    SPP -->|"经典蓝牙 SPP"| DEV
    Picker --> UI
    Dialog --> UI

架构解读：

• 应用层（otasdk）：参考 Demo 工程 com.jieli.otasdk 命名空间下的 UI 组件（升级文件选择器、设备连接对话框、进度展示），它们只通过公开 API 与核心库交互，不接触协议实现。
• 核心库 AAR：对外暴露 OTAManager（升级管理入口）与 BluetoothOTAConfigure（传输配置）。内部由升级流程控制调度 RCSP 协议处理，并依据 priority 配置选择 BLE 或 SPP 传输通道。
• 设备端：支持 RCSP OTA 的杰理蓝牙芯片，通过 BLE（含 Gatt Over BR/EDR）或经典蓝牙 SPP 与核心库通信。

这种分层使集成方与协议实现解耦：更换传输方式（PREFER_BLE ↔ PREFER_SPP）只需修改一行配置，无需改动业务代码。

核心库组成与职责

核心库以 AAR 二进制形式随仓库分发，存放于仓库根目录 libs/ 文件夹下（摘自 README.md）：

Android-JL_OTA/
├── apk/                                # 测试APK文件夹
│   ├── JLOTA_V1.9.0_10905-debug.apk         # OTA测试版本
│   └── UpdateContent.txt                    # 更新说明
├── code/                                    # 参考源码工程文件夹
│   └── 参考Demo源码工程                  # OTA Demo项目源码
├── doc/                                     # 开发文档文件夹
├── libs/                               # 核心库文件夹
│   ├── jl_bt_ota_V1.11.0_11015-release.aar  # 杰理OTA核心库
│   └── ReadMe.txt                           # 核心库说明文件
└── ReadMe.txt                          # 说明文件

核心库 AAR 封装的三层职责：

1. RCSP 协议处理：RCSP（Remote Control Simple Protocol）是杰理设备端与手机端通信的自有协议，负责指令编解码、认证流程、数据分包与校验。这部分完全闭源，通过公开 API 暴露能力。
2. 升级流程控制：管理"连接 → 认证 → 固件传输 → 校验 → 重启"的状态机，处理单备份/双备份、复用空间等不同升级策略，并向调用方回调进度与状态。
3. 传输调度：根据 BluetoothOTAConfigure.priority 选择 BLE（含 Gatt Over BR/EDR）或 SPP 通道，内部处理 MTU 协商、回连、断点续传等传输层细节。

设计意图：把协议层做成闭源 AAR，既保护协议实现，又让集成方获得稳定的 API 契约。集成方不需要了解 RCSP 指令格式即可完成固件升级。

集成步骤

步骤 1：获取核心库 AAR

从仓库 libs/ 目录获取 jl_bt_ota_V1.11.0_11015-release.aar（文件名中 V1.11.0 为核心库版本号，11015 为 versionCode）。版本演进见下文"版本兼容性"一节。

步骤 2：放置 AAR 文件

将 AAR 文件复制到目标工程对应 module 的 libs/ 文件夹下（摘自 README.md）：

dependencies {
    //1.将上面的aar文件放入工程目录中的对应moudle的lib文件夹下
	//2.在moudlu的build.gradle中添加
	implementation fileTree(include: ['*.aar'], dir: 'libs')
}

Source: README.md

步骤 3：配置 build.gradle 依赖

参考 Demo 工程 otasdk/build.gradle 中同时声明 JAR 与 AAR 本地依赖的做法（摘自 build.gradle）：

dependencies {
    implementation fileTree(include: ['*.jar'], dir: 'libs')
    implementation fileTree(dir: 'libs', include: ['*.aar'])

    implementation 'org.jetbrains.kotlin:kotlin-bom:1.8.0'
    implementation 'androidx.appcompat:appcompat:1.4.2'
    // ... 其他第三方依赖
}

Source: build.gradle

Demo 工程的 SDK 环境基线（摘自 build.gradle）：compileSdk 36、minSdk 21、targetSdk 36，Java/Kotlin 均编译到 1.8（jvmTarget = '1.8'），并启用了 dataBinding、viewBinding 与 buildConfig。集成方可按自身工程实际调整，但 minSdk 21（Android 5.1+）是核心库的兼容底线。

步骤 4：声明系统权限

接入 SDK 时需要在 AndroidManifest.xml 申请蓝牙、定位与存储权限（摘自 README.md）：

<!--使用蓝牙权限-->
<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>

<!--高版本安卓系统要求-->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

<!--定位权限，官方要求使用蓝牙或网络开发，需要位置信息-->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<!--存储权限-->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

Source: README.md

权限说明：

• BLUETOOTH / BLUETOOTH_ADMIN：传统蓝牙 API 所需；Android 12+ 被 BLUETOOTH_SCAN / BLUETOOTH_CONNECT 取代，需同时声明以兼容高低版本。
• 定位权限：官方要求使用蓝牙或网络开发时必须具备位置信息，否则部分机型上 BLE 扫描不返回结果。
• 存储权限：用于读取固件升级文件；1.10.0 起针对 Android 14+ 修复了存储权限申请失败问题，高版本系统建议改用 SAF（Storage Access Framework）方式选择固件文件。

步骤 5：工程构建与验证

• 确保 AAR 被 Gradle 打包进 APK：构建后在 APK Analyzer 中应能看到 jl_bt_ota 相关包路径。
• 运行 Demo 参考 APK（apk/JLOTA_V1.9.0_10905-debug.apk）验证核心库功能，再迁移到自有工程。
• 调试时通过 Logcat 查看 SDK 输出的 OTA 连接状态与数据交互日志（详见 SDK 调试说明）。

OTA 参数配置

核心库的公开配置入口是 OTAManager 与 BluetoothOTAConfigure。接入时需在代码中构建 BluetoothOTAConfigure 配置对象并调用 OTAManager#configure() 应用（摘自 README.md）：

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文件的数据, 与setFirmwareFilePath，二者选其一
otaManager.configure(bluetoothOption); //设置OTA参数

Source: README.md

关键配置决策（设计意图）：

• 传输方式（priority）：PREFER_BLE 优先走 BLE，PREFER_SPP 走经典蓝牙。BLE 功耗低但速率受 MTU 限制；SPP 速率高但需要经典蓝牙配对。按产品形态选择。
• 设备认证（isUseAuthDevice）：默认开启，具体取决于固件配置。认证失败会中断升级，这是 RCSP 协议的安全防线。
• MTU 策略：核心库在 BLE 连接时会主动改变 MTU，因此集成方的用户 SDK 必须对此处理，避免连接参数冲突。建议 MTU 取 500 或 270。
• 回连策略（isUseReconnect + bleConnectParam）：默认走 SDK 内部自动回连；设为 true 时由客户自定义回连方式，此时 bleConnectParam 不生效。

BluetoothOTAConfigure 配置项

以下配置项来源于 README.md 的官方说明：

代码示例中额外出现的 setter（setBleIntervalMs(500)、setTimeoutMs(3000)）对应 BLE 发数间隔与命令超时时间，用于控制传输节奏与容错窗口。

使用流程

端到端升级流程

flowchart TD
    Start([开始]) --> Perm["授予蓝牙/存储/定位权限"]
    Perm --> File["添加升级文件<br/>拷贝至固定目录或选择本地文件"]
    File --> Cfg["构建 BluetoothOTAConfigure 并 configure"]
    Cfg --> Connect["搜索并连接目标设备"]
    Connect --> Auth{"设备认证通过?"}
    Auth -->|"是"| Transfer["核心库分块传输固件"]
    Auth -->|"否"| Fail1["回调失败/中断"]
    Transfer --> Verify["设备端校验并烧录"]
    Verify --> Reboot["设备重启"]
    Reboot --> Done["OTA 结束回调<br/>onStop / onEnd"]
    Fail1 --> End([结束])
    Done --> End

Source: README.md（使用流程）

核心库与设备交互时序

sequenceDiagram
    participant App as App（集成方）
    participant OTA as OTAManager（核心库）
    participant Ch as BLE/SPP 通道
    participant Dev as 杰理蓝牙设备

    App->>OTA: configure(BluetoothOTAConfigure)
    App->>OTA: 发起升级（设备信息 + 固件）
    OTA->>Ch: 建立连接
    Ch->>Dev: 连接 / 认证指令
    Dev-->>OTA: 认证结果
    OTA->>Ch: 分块发送固件数据
    Ch->>Dev: 固件数据块
    Dev-->>OTA: 进度反馈
    OTA-->>App: onProgress / 状态回调
    Dev-->>OTA: 烧录完成
    OTA-->>App: OTA 结束回调

流程说明（结合 README.md 与核心库职责划分）：

1. 打开 APP 并授权：首次打开需授予蓝牙、存储等权限（步骤 4 所列），否则后续扫描/读文件会失败。
2. 添加升级文件：支持三种途径——拷贝到固定位置 手机根目录/Android/data/com.jieli.otasdk/files/upgrade/、从 Download 目录选择本地文件、通过局域网传输文件到手机。固件文件需在升级前通过 firmwareFilePath 或 firmwareFileData 提供给核心库。
3. 连接目标设备：Demo 使用 DialogUpgradeDevice 完成设备搜索与连接；集成方也可自行实现 connectBluetoothDevice 回连接口。
4. 开始 OTA 升级：核心库按 priority 选择传输通道，执行认证 → 分块传输 → 校验 → 重启，期间通过回调向 App 汇报进度与状态；isPriorityCallbackOtaFinish 决定结束状态在设备重启前还是重启后回调。

核心 API 参考

核心库 AAR 为闭源组件，以下 API 签名与语义均以 README.md 官方说明为准；AAR 内部方法不在本页范围内。

OTAManager

升级管理入口，1.9.0 起不再强制单例，每个升级流程实例独立，支持多设备并发升级。

构造：

• new OTAManager() — 创建升级管理器实例

方法：

• configure(BluetoothOTAConfigure option) — 应用 OTA 参数。必须在发起升级前调用，参数错误（如固件路径与数据均未设置）会导致后续升级无法启动。

BluetoothOTAConfigure

蓝牙 OTA 传输配置，使用链式 setter 构建。

• static BluetoothOTAConfigure createDefault() — 创建默认配置实例（默认 PREFER_BLE、开启设备认证、MTU 20、不调节 MTU、不自定义回连）
• setPriority(int priority) — 设置通讯方式，取值 BluetoothOTAConfigure.PREFER_BLE / PREFER_SPP
• setUseAuthDevice(boolean) — 是否启用设备认证
• setBleIntervalMs(int) — BLE 发数间隔，默认 500ms
• setTimeoutMs(int) — 命令超时时间
• setMtu(int) — BLE 底层通讯 MTU，建议 500 或 270
• setNeedChangeMtu(boolean) — 是否需要核心库调节 MTU
• setUseReconnect(boolean) — 是否使用自定义回连方式
• setFirmwareFilePath(String) — 设置固件文件路径
• setFirmwareFileData(byte[]) — 设置固件文件数据（与路径二选一）

参数约束： mtu 取值范围 [20, 509]；firmwareFilePath 与 firmwareFileData 至少设置其一，否则升级前需补设。

行为约定： bleConnectParam 非空且 isUseReconnect=false 时，核心库执行自动回连；isUseReconnect=true 时，bleConnectParam 不生效，客户需实现 connectBluetoothDevice 接口完成回连。

说明：回调接口（进度/状态/结束）的具体方法签名位于 AAR 内部，源码仓库未公开，本页不做臆测；集成时可参考 doc/ 目录下的《杰理OTA外接库(Android)开发文档》。

失败模式与边界情况

以下问题与修复均记录于 README.md 版本历史，集成方应据此规避：

边界情况：

• MTU 变更冲突：核心库会在 BLE 连接时主动改 MTU（setMtu），集成方用户 SDK 若同时管理连接参数，必须配合处理，否则连接会异常。
• 回连策略三分支：isUseReconnect / bleConnectParam / connectBluetoothDevice 三者组合决定回连行为，配置不一致时按 README 的优先级规则执行（自定义回连 > 自动回连 > 客户实现连接接口）。
• 固件输入二选一：firmwareFilePath 与 firmwareFileData 只能二选一，同时设置时行为以 README 注释为准（"二者选其一"）。
• Android 15 兼容：1.11.0 起增加 Android 15 兼容处理，targetSdk 36 的工程应使用 1.11.0+ 核心库。

性能与操作注意事项

• MTU 与速率：mtu 直接影响 BLE 传输速率，建议 500 或 270；但调大 MTU 会增加底层链路负担，需在设备端固件支持范围内取值（README.md）。
• 扫描功耗：bleScanMode 提供低功耗/平衡/低延时三档；低延时模式功耗高且仅前台有效，适合升级前快速发现设备，日常扫描用平衡模式。
• 发数间隔与超时：setBleIntervalMs(500) 与 setTimeoutMs(3000) 控制传输节奏与容错窗口；间隔过小易触发设备端丢包，超时过短会误判失败。
• 日志排查：SDK 输出详细日志，通过 Logcat 可观察 OTA 连接状态与数据交互，是定位升级中断的首选手段（调试说明）。
• 多设备并发：1.9.0+ 每个升级流程实例独立，可支撑多设备同时升级；多实例场景建议通过 snGenerator 保证 SN 唯一。

扩展点

核心库通过配置项暴露扩展能力，源码层不可修改（闭源 AAR）：

1. 自定义 SN 生成器：实现 ICmdSnGenerator 并注入 snGenerator，适用于杰理多库联合使用（如 OTA 库与设备控制库共用链路）时保证命令 SN 不冲突。
2. 自定义回连：setUseReconnect(true) 后接管回连逻辑，客户可在自己的连接框架中实现 connectBluetoothDevice 接口，实现与业务连接策略的统一。
3. 固件来源扩展：firmwareFilePath / firmwareFileData 双入口支持"文件系统"与"内存数据"两种固件供给方式，便于从网络下载或加密包解出固件后直接注入。
4. Demo 参考实现：otasdk 模块的 BroadcastBoxActivity、UpgradeFragment、UpgradeFilePickerAdapter 等源码展示了核心库 API 的典型调用姿势，可作为集成模板；多设备扩展见 com.jieli.broadcastbox.model.ota 包下的 MultiOTA* 状态模型。

若需要更深的协议级扩展（如自定义升级策略），需联系杰理官方获取配套文档与支持。

版本兼容性

核心库版本与 Demo 工程版本的对应关系（摘自 README.md 与 build.gradle）：

集成建议：新工程直接采用仓库随附的 1.11.0 核心库；老工程升级时重点关注 Android 版本兼容（13/14/15）与传输通道修复项，避免携带已知缺陷。

相关链接

• README.md — 项目总览与快速开始
• README.md — OTA 参数配置说明
• otasdk/build.gradle — Demo 工程依赖与构建配置
• 杰理 OTA SDK 在线开发文档
• SDK 调试说明
• 常见问题答疑
• 相关兄弟页面：BLE/SPP 传输通道、OTA Demo 应用、RCSP 协议（如目录中存在对应页面，可由此跳转）