杰理 OTA SDK 项目简介

Android-JL_OTA 是珠海市杰理科技股份有限公司（JieLi）面向杰理蓝牙类产品提供的 Android 固件升级（OTA）集成 SDK，专注于实现 RCSP OTA 升级功能，支持 BLE、SPP 等多种传输通道，并提供完整的固件升级流程与配套 Demo 工程。

Purpose and Scope

本页面是「杰理 OTA SDK（Android）」项目的总览入口，涵盖：

• SDK 的定位、核心能力与设计意图（为什么需要 RCSP OTA、为什么选择 BLE/SPP 双通道）；
• 运行环境要求与支持硬件平台；
• 快速接入方式（依赖引入、权限配置、Demo 运行）；
• 仓库工程结构（apk/、code/、doc/、libs/）；
• 核心配置模型 BluetoothOTAConfigure 与 OTAManager 的用法；
• OTA 升级的标准使用流程、调试技巧、版本历史与许可证。

本页面为项目级简介，属于系统性接入文档的入口。更细化的主题（如 RCSP 协议内部机制、BLE 回连细节、各接口逐条 API 参考）应参考杰理 OTA SDK 在线文档中心以及仓库 doc/ 目录下的《杰理OTA外接库(Android)开发文档》。

说明（信息完整性）：当前 Git 仓库中实际提交的内容为 README.md、README_en.md 与 LICENSE 三个文件。README 中描述的 apk/、code/、doc/、libs/ 目录属于 SDK 发布包（Release）中的内容，并未提交到本仓库。因此本页面以 README 为准，对发布包内的细节仅作结构级描述，不臆测未提供的源码实现。

Overview

项目定位

Android-JL_OTA 是杰理科技为自家蓝牙芯片产品（AC707N、AC703N、AC701N、AC697N、AC696N、AC695N 等）打造的固件升级开发平台。SDK 以 RCSP（杰理私有升级协议） 为核心，封装了协议处理、升级流程控制、设备认证、MTU 协商、自动回连等能力，让第三方 App 开发者无需理解底层蓝牙协议即可完成固件升级。

其核心设计意图可归纳为三点：

1. 协议屏蔽：将 RCSP 协议与底层 BLE/SPP 传输细节封装进 jl_bt_ota_*.aar 核心库，App 侧只需配置参数并调用 OTAManager；
2. 多通道适配：同一套升级流程可跑在 BLE（含 Gatt Over BR/EDR）与经典蓝牙 SPP 之上，屏蔽通道差异；
3. 流程可控：通过 BluetoothOTAConfigure 暴露传输优先级、MTU、超时、认证、回连策略等开关，兼顾不同产品与场景。

核心功能

版本载体

• 核心库：jl_bt_ota_Vxxx-release.aar（xxx 为版本号），包含 RCSP 协议处理、升级流程控制等功能；
• Demo 工程：code/ 目录下的参考 Demo 源码工程，展示 SDK 的完整用法；
• 测试 APK：apk/ 目录下的 JLOTA_V1.9.0_10905-debug.apk，可直接安装体验。

Architecture

整体架构

flowchart TD
    subgraph sg_App["应用层（参考 Demo）"]
        DemoAPP["Android 应用 / 参考 Demo 源码工程"]
        OM["OTAManager"]
    end

    subgraph sg_Core["OTA 核心库 jl_bt_ota.aar"]
        RCSP["RCSP 协议处理"]
        Flow["升级流程控制"]
        Auth["设备认证"]
        BLE["BLE 传输通道<br/>（支持 Gatt Over BR/EDR）"]
        SPP["SPP 传输通道"]
    end

    subgraph sg_Device["蓝牙设备端"]
        Dev["杰理蓝牙芯片<br/>AC707N / AC703N / AC697N 等"]
    end

    subgraph sg_File["固件资源"]
        FW["固件文件<br/>路径 或 byte[] 数据"]
    end

    DemoAPP -->|"new / configure"| OM
    OM -->|"setFirmwareFilePath / Data"| FW
    OM -->|"配置 OTA 参数"| RCSP
    OM -->|"启动升级"| Flow
    RCSP --> Auth
    RCSP --> Flow
    Flow --> BLE
    Flow --> SPP
    BLE -->|"BLE 连接 / 自动回连"| Dev
    SPP -->|"SPP 连接"| Dev

分层职责

• 应用层（Demo）：负责权限申请、固件文件选择、设备搜索连接与 UI 展示；通过 OTAManager 与核心库交互。
• 核心库 jl_bt_ota.aar：SDK 主体，包含：
  • RCSP 协议处理：命令封装、分包/拼包、SN 生成、应答校验；
  • 升级流程控制：固件推送、进度上报、结束状态回调；
  • 设备认证：RCSP 认证流程（setUseAuthDevice 控制开关）；
  • 传输通道：BLE（含 Gatt Over BR/EDR）与 SPP 双通道抽象。
• 设备端：支持 RCSP OTA 的杰理蓝牙芯片（如 AC707N、AC697N、AC696N、AC695N 等），固件侧配合完成升级动作。
• 固件资源：升级文件既可以走本地路径（firmwareFilePath），也可以直接传入字节数据（firmwareFileData），二者选其一。

依赖关系

核心库对外暴露的唯一入口是 OTAManager，App 通过 OTAManager#configure(BluetoothOTAConfigure) 完成参数注入后即可调用升级能力；核心库内部依赖 RCSP 协议栈与蓝牙传输层，但对 App 完全屏蔽。这种「门面（Facade）+ 配置对象（Options）」的设计让接入成本集中在参数配置上，符合 README 中「只需配置 OTA 参数」的接入主张。

运行环境

设计意图：Android 5.1（API 22）是 BLE 能力相对成熟的门槛版本，因此 SDK 将最低版本定在此处；同时 SDK 在版本历史中持续跟进 Android 13/14/15 的系统兼容（如存储权限、蓝牙权限拆分），保证新系统下的可用性。

快速开始

克隆仓库

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

Source: README.md

导入工程

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

添加核心库依赖

将 libs/ 目录下的 jl_bt_ota_Vxxx-release.aar（xxx 为版本号）放入工程对应 module 的 libs 目录，并在 build.gradle 中添加依赖：

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

Source: README.md

权限配置

接入 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+ 的运行时蓝牙权限（对应 README 中"高版本安卓系统要求"）；定位权限源于系统对蓝牙扫描的隐式要求；存储权限用于读取固件升级文件。SDK 版本历史中反复修复 Android 14+ 存储权限申请失败问题，说明这些权限的运行时申请逻辑随系统版本演化，接入时应以最新版本 SDK 的 Demo 为参照。

运行示例应用

参考 apk/ 目录中的测试 APK（如 JLOTA_V1.9.0_10905-debug.apk）了解 SDK 功能和使用方法。

工程结构

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

各目录角色：

• libs/：SDK 的二进制核心，jl_bt_ota_*.aar 是唯一需要引入的依赖，其余目录均围绕它服务；
• code/：可运行的参考工程，是理解 OTAManager/BluetoothOTAConfigure 用法的最佳范本；
• apk/：预编译测试包，便于先体验后接入；
• doc/：离线开发文档与在线文档链接，与 README 互补。

仓库状态提示：当前 Git 提交中仅包含 README.md、README_en.md、LICENSE，上述发布包目录需通过 Release/Tag 或 SDK 交付物获取。仓库版本历史与 Tag 可参考 GitHub Tags。

OTA 参数配置（核心 API 概览）

SDK 的接入核心是两个类：OTAManager（门面入口）与 BluetoothOTAConfigure（配置对象）。README 给出的标准配置代码如下：

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

设计意图：

• 链式 API：BluetoothOTAConfigure 采用 builder 风格，使可选参数一目了然，未调用的项使用 createDefault() 的默认值；
• 传输优先级：setPriority 决定走 BLE 还是 SPP，是 SDK 双通道设计的开关；
• MTU 决策前置：MTU 直接影响 BLE 传输速率，SDK 允许 setNeedChangeMtu 选择「库内调整」或「由客户连接时调整」，把对系统蓝牙栈的干预权交给集成方；
• 固件来源二选一：setFirmwareFilePath 与 setFirmwareFileData 两者选其一，分别适配「文件系统读取」与「内存/网络获取」两种固件获取场景。

BluetoothOTAConfigure 属性一览

Source: README.md

其中值得注意的联动关系：

• isUseReconnect、bleConnectParam 与 connectBluetoothDevice 接口构成三种回连策略（自定义回连 / 库内自动回连 / 客户手动回连），这是「单备份 OTA 自动回连 BLE」功能的配置基础；
• isPriorityCallbackOtaFinish 控制 OTA 结束回调的时机——设备重启前还是重启后，涉及升级完成状态的判定口径；
• snGenerator（ICmdSnGenerator）是杰理多库联合使用时的 SN 协调点，用于避免多库并发下发命令时 SN 冲突（版本历史中曾修复「多线程发命令，SN 相同的问题」）。

使用流程

标准升级流程

flowchart TD
    Start([开始]) --> Perm["打开 APP，授予蓝牙 / 存储等权限"]
    Perm --> File{"添加升级文件"}
    File -->|"方式一：拷贝到固定目录"| Dir["手机根目录/Android/data/<br/>com.jieli.otasdk/files/upgrade/"]
    File -->|"方式二：选择本地文件"| Down["手机 Download 文件夹"]
    File -->|"方式三：局域网传输"| LAN["通过局域网传输文件到手机"]
    Dir --> Connect["搜索并连接目标蓝牙设备"]
    Down --> Connect
    LAN --> Connect
    Connect --> OTA["选择目标升级文件，开始 OTA 升级"]
    OTA --> End([完成])

Source: README.md

端到端时序

sequenceDiagram
    participant App as Android App（Demo）
    participant OM as OTAManager
    participant Lib as jl_bt_ota 核心库
    participant Dev as 蓝牙设备（RCSP OTA）

    App->>OM: new OTAManager()
    App->>OM: configure(BluetoothOTAConfigure)
    OM->>Lib: 注入优先级 / MTU / 认证 / 回连等参数
    App->>Lib: 搜索并连接目标设备（BLE/SPP）
    Lib->>Dev: 建立连接 / 设备认证（RCSP Auth）
    Dev-->>Lib: 认证通过
    App->>Lib: 启动升级（携带固件文件）
    Lib->>Dev: 分包推送固件数据
    Dev-->>Lib: 进度 / 校验应答
    Lib-->>App: 升级进度回调
    App->>Dev: 升级完成，设备重启
    Lib-->>App: OTA 结束状态回调（按 isPriorityCallbackOtaFinish 决定时机）

时序要点：

1. 配置先行：configure() 必须在升级前调用，所有传输与流程参数由此确定；
2. 连接与认证：核心库建立连接后按 isUseAuthDevice 执行 RCSP 认证，失败则流程终止；
3. 固件推送：核心库按 RCSP 协议分包下发并处理应答，MTU 与 bleIntervalMs 决定发送速率；
4. 结束判定：升级结束后依据 isPriorityCallbackOtaFinish 选择在设备重启前或重启后回调结束状态，用于 App 侧刷新 UI 或执行后续动作。

调试技巧

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

Source: README.md

调试的关键路径：当升级失败时，优先核对 Logcat 中的连接状态日志（确认 BLE/SPP 连接是否建立）、RCSP 交互日志（确认认证与命令应答是否正常）以及发送间隔/MTU 参数（确认是否因速率过快导致丢包）。

失败模式、边界情况与兼容性

SDK 的版本历史是理解其失败模式与边界情况的最佳素材，每条修复记录都对应一类真实场景：

Source: README.md

从中可提炼的工程要点：

• 多设备并发：1.9.0 起 SDK 去掉单例、流程独立，说明同一进程内可并行管理多台设备的升级任务——接入方不应假设全局唯一实例；
• SN 唯一性：多线程下发命令时 SN 必须唯一，ICmdSnGenerator 接口正是为此提供的外部扩展点；
• 系统兼容优先级：Android 11/13/14/15 的兼容处理持续迭代，接入时建议始终使用最新版本核心库；
• 数据完整性：拼包出错会导致数据丢失，RCSP 的分包/校验逻辑是升级可靠性的关键，调试时如遇升级中断应优先检查日志中的拼包/校验记录。

性能与操作注意事项

性能相关的配置项集中在 BluetoothOTAConfigure 中：

扩展点

SDK 通过以下接口/开关开放定制能力：

• ICmdSnGenerator（snGenerator）：自定义命令 SN 生成器，用于杰理多库联合使用场景，保证多库并发时 SN 不冲突；
• connectBluetoothDevice 接口：当不启用自定义回连且未设置 bleConnectParam 时，客户需自行实现设备连接逻辑——这是完全自定义连接流程的入口；
• 回连策略三态：isUseReconnect=true（自定义回连）/ false + bleConnectParam（库内自动回连）/ false + 空参数（客户手动连接），覆盖从全托管到全自研的连接管理需求；
• isPriorityCallbackOtaFinish：调整 OTA 结束回调时机（设备重启前/后），适配不同 App 的结束判定流程。

这些扩展点共同体现了 SDK「默认可用、按需定制」的设计取向：绝大多数接入方只需默认配置即可完成升级，特殊产品（多库联合、自定义连接、复用空间升级）则通过开关与接口平滑扩展。

社区与支持

Source: README.md

许可证

本项目采用 Apache License 2.0 开源协议：

Copyright 2024 珠海市杰理科技股份有限公司

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Source: README.md · LICENSE

Related Links

• README.md（中文主文档） — 本页内容的原始依据，包含完整接入说明
• README_en.md（英文版） — 英文接入文档
• LICENSE — Apache 2.0 许可文本
• 杰理 OTA SDK 在线文档中心 — 协议细节、API 逐条参考与 FAQ
• 杰理科技官网 — 芯片与 SDK 生态信息
• 版本 Tag 列表 — 各版本核心库（AAR）与发布包下载

说明：SDK 的协议级实现、逐方法 API 参考与 Demo 源码解析属于更细粒度的主题；当仓库后续提交 code/、libs/、doc/ 等源码/文档目录时，可在对应子页面中展开，本页保持项目级总览定位。