快速开始与接入指南

本文档介绍如何将杰理 OTA SDK（Android-JL_OTA）接入到你的 Android 工程中，包括环境要求、依赖配置、权限申请、参数配置与基本升级流程，帮助你用最短时间跑通 RCSP OTA 固件升级。

Purpose and Scope

本页面向首次接入的开发者，覆盖从「克隆仓库」到「运行升级」的完整接入链路：

• 运行环境与硬件要求
• 依赖库（AAR）引入方式与工程结构
• AndroidManifest 权限配置
• OTAManager 与 BluetoothOTAConfigure 的核心参数配置
• 一次完整 OTA 升级的流程与调试手段

不属于本页范围、由其他页面承载的内容：

• 传输通道（BLE/SPP）的底层实现细节 → 参见 BLE/SPP 升级相关页面
• 固件打包、RCSP 协议细节 → 参见协议与固件相关页面
• SDK 各版本间的行为差异 → 参见版本历史相关页面

Overview

Android-JL_OTA 是珠海市杰理科技股份有限公司为杰理蓝牙类产品提供的固件升级开发平台，专门实现本公司蓝牙类产品的 RCSP OTA 升级功能，支持 BLE、SPP 等多种传输方式，提供完整的固件升级流程。SDK 以 AAR 核心库形式交付（如 jl_bt_ota_V1.11.0_11015-release.aar），仓库同时附带完整的参考 Demo 源码工程，方便直接对照学习。

SDK 的核心能力一览：

接入方只需要：引入 AAR → 声明权限 → 构造 OTAManager 并配置 BluetoothOTAConfigure → 设置固件文件 → 发起升级并监听回调。核心流程全部由 SDK 内部完成。

Architecture

flowchart TD
    subgraph sg_App["接入方 App"]
        Demo["参考 Demo 工程<br/>BroadcastBoxActivity"]
        UI["升级界面<br/>UpgradeFragment"]
        FileObs["固件文件监听<br/>OtaFileObserverHelper"]
    end
    subgraph sg_SDK["JL OTA 核心库 (AAR)"]
        Mgr["OTAManager"]
        Cfg["BluetoothOTAConfigure"]
        Ble["BLE 传输通道<br/>BleManager / BleEventCallbackManager"]
        Spp["SPP 传输通道"]
        Rcsp["RCSP 协议处理"]
    end
    subgraph sg_Dev["杰理蓝牙设备"]
        Chip["AC69xx / AC70xx 芯片"]
    end

    Demo --> Mgr
    UI --> Demo
    FileObs --> UI
    Mgr --> Cfg
    Mgr --> Ble
    Mgr --> Spp
    Ble --> Rcsp
    Spp --> Rcsp
    Rcsp --> Chip

架构要点：

• OTAManager 是 SDK 对外统一入口，负责升级流程控制（configure / start / stop / 回调分发）。
• BluetoothOTAConfigure 是传输与连接行为的参数载体，OTAManager.configure() 接收它完成初始化。
• BleManager / BleEventCallbackManager 位于 com.jieli.otasdk.tool.ota.ble 包，封装 BLE 连接、事件回调与数据收发；SPP 通道与之并列，由 priority 参数决定走哪条通道。
• OtaFileObserverHelper 等工具类位于 com.jieli.otasdk.tool.file 包，用于监听升级文件目录变化，属于参考工程的辅助设施。
• 参考 Demo 的界面层位于 com.jieli.broadcastbox 包（BroadcastBoxActivity、UpgradeFragment、DialogUpgradeDevice、DialogUpgradeFilePicker 等），演示了完整的交互流程，是接入时最好的对照模板。

Source: README.md · README.md

运行环境

Source: README.md

快速开始

1. 克隆仓库

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

Source: README.md

2. 导入参考工程到 Android Studio

1. 打开 Android Studio；
2. 选择 "Open an existing project"；
3. 导航到仓库中的 code/ 目录；
4. 打开参考 Demo 源码工程中的项目文件。

参考工程入口为 code/JL_OTA_Android_V1.9.0_SDK_V1.11.0/otasdk，其中 com.jieli.broadcastbox.BroadcastBoxActivity 是演示主界面，UpgradeFragment 承载升级流程 UI。

3. 添加依赖库

核心依赖为 jl_bt_ota_Vxxx-release.aar（xxx 为版本号），包含 RCSP 协议处理、升级流程控制等功能。将 libs/ 目录下的 AAR 文件放入工程对应 module 的 libs 目录，并在 build.gradle 中添加依赖：

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

Source: README.md

4. 权限配置

接入 SDK 时应在 AndroidManifest.xml 中申请以下权限：

<!--使用蓝牙权限-->
<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_SCAN / BLUETOOTH_CONNECT 为 Android 12+ 运行时权限，需在代码中动态申请；Android 10+ 分区存储下 WRITE_EXTERNAL_STORAGE 行为受限，v1.10.0 起 SDK 已针对 Android 14+ 的存储权限申请失败问题做了兼容处理。

5. 工程结构总览

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

Source: README.md

其中 apk/ 目录提供了可直接安装的测试 APK，可用于在接入前先体验 SDK 功能、确认设备与固件文件是否匹配。

参数配置与 API 使用

OTAManager 初始化

SDK 的接入入口是 OTAManager，配合 BluetoothOTAConfigure 完成参数注入。核心代码模式如下：

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

关键设计意图：

• setFirmwareFilePath 与 setFirmwareFileData 二者选其一：路径方式适用于固件存放于本地文件系统的场景（便于断点续传与日志追踪），字节数组方式适用于固件已加载进内存（如从网络下载）的场景。
• setMtu 建议取 500 或 270：MTU 直接决定 BLE 单次传输的数据量，值过小会显著拖慢升级速率；同时该值会使 OTA 库在 BLE 连接时主动改变 MTU，因此接入方自己的 BLE SDK 需要对此做兼容处理。
• setUseReconnect(false) 时走 SDK 默认回连方式；若客户有自定义回连需求，可将 isUseReconnect 置为 true 或自行实现 connectBluetoothDevice 接口（见下方配置表说明）。

BluetoothOTAConfigure 配置项

bleConnectParam 的行为矩阵：

• 若 isUseReconnect 为 true，该字段不生效；
• 若 isUseReconnect 为 false 且该字段不为空，则 OTA 库自动回连；
• 若 isUseReconnect 为 false 且该字段为空，则客户需要实现 connectBluetoothDevice 接口自行完成连接。

Source: README.md

标准升级流程

1. 打开 APP：初次打开应用，需授予蓝牙、存储等对应权限；
2. 添加升级文件，支持以下方式：
   • 拷贝升级文件到固定存放位置 手机根目录/Android/data/com.jieli.otasdk/files/upgrade/；
   • 存放到手机 Download 文件夹，然后选择本地文件；
   • 通过局域网传输文件到手机；
3. 连接目标设备：搜索并连接需要升级的蓝牙设备；
4. 开始 OTA 升级：选择目标升级文件，开始 OTA 升级。

Source: README.md

升级流程示意图

flowchart TD
    Start([开始]) --> Perm["授予蓝牙 / 存储权限"]
    Perm --> File["添加升级文件<br/>upgrade/ 目录 或 Download 或 局域网"]
    File --> Scan["扫描并连接目标蓝牙设备"]
    Scan --> Cfg["配置 OTAManager 参数<br/>priority / mtu / 固件路径"]
    Cfg --> Run["启动 OTA 升级"]
    Run --> Auth{"设备认证 isUseAuthDevice"}
    Auth -->|"通过"| Send["按 MTU 分片传输固件数据"]
    Auth -->|"失败"| Fail1["升级失败回调"]
    Send --> Verify{"校验结果"}
    Verify -->|"成功"| Done["升级完成 / 设备重启"]
    Verify -->|"失败"| Retry["重试或结束流程"]
    Fail1 --> End([结束])
    Done --> End
    Retry --> End

升级链路说明：认证（RCSP 认证）发生在数据传输之前，避免向非杰理设备或未授权设备下发固件；mtu 决定分片大小；isPriorityCallbackOtaFinish 决定「升级完成」回调是立即触发还是等设备重启后再触发，接入方应根据 UI 展示需要选择。

调试技巧

• 日志输出：SDK 提供详细的日志输出，可通过日志查看 OTA 连接状态和数据交互；
• 设备调试：使用 Android Studio 的 Logcat 查看实时日志；
• 问题排查：
  • SDK 行为：参考 SDK 调试说明；
  • 常见问题：参考 常见问题答疑。

Source: README.md

失败模式与边界情况

根据 README 的版本历史与配置语义，接入时需特别注意以下边界：

• 权限兼容性：Android 12+ 必须处理 BLUETOOTH_SCAN / BLUETOOTH_CONNECT 运行时权限；Android 14+ 存储权限申请曾出现失败（v1.10.0 修复），Android 15 兼容处理于 v1.11.0 加入。接入时应按 API level 分派权限请求。
• MTU 变更冲突：配置 setMtu(500) 时 OTA 库会在 BLE 连接时主动改 MTU。若接入方自有 BLE SDK 也管理 MTU，可能产生竞争；建议通过 setNeedChangeMtu(false) 让接入方在连接时自行调好 MTU。
• 回连行为三态：isUseReconnect / bleConnectParam 组合决定了「自定义回连 / 库自动回连 / 客户实现 connectBluetoothDevice」三种模式，配置不当会导致单备份 OTA 升级后设备重启无法自动重连（历史上曾出现"设备回连失败"问题，v1.9.0 修复）。
• SPP 与双模设备：SPP 方式单备份 OTA 曾存在失败问题（v1.10.0 修复）；双模同地址设备 OTA 失败在 v1.9.0 修复。使用 SPP 通道或双模设备时建议先对照 apk/ 中测试 APK 验证。
• 并发升级：v1.9.0 起支持多设备升级（去掉单例使用，流程独立），意味着多个 OTAManager 实例可并行驱动不同设备的升级流程；SN 生成器在多线程发命令场景下需保证唯一（v1.6.0 曾修复多线程 SN 相同的问题），多库联合使用时请通过 snGenerator 注入统一的 SN 生成器。
• 固件文件缺失：firmwareFilePath / firmwareFileData 升级前必须设置，两者都为空时升级无法启动；文件路径与文件数据不可同时混用（以最后一次赋值为准）。

版本与升级建议

Source: README.md

接入建议：新项目直接使用最新版 AAR（当前仓库内为 jl_bt_ota_V1.11.0_11015-release.aar）；存量项目升级 SDK 时重点关注回连方式、MTU 管理与多设备并发的行为变化。

Related Links

• README（中文） — 本指南的一手来源，包含完整功能表、配置说明与版本历史
• README_en.md（English） — 英文版说明
• 参考 Demo 主界面 BroadcastBoxActivity — 完整升级交互流程的对照实现
• 升级流程 Fragment UpgradeFragment — 升级 UI 与状态展示
• BLE 事件回调管理 BleEventCallbackManager — BLE 通道事件分发的参考实现
• 在线文档中心 — 杰理 OTA SDK 完整开发文档