工程结构与发布物

Android-JL_OTA 是珠海市杰理科技股份有限公司为杰理蓝牙类产品提供的 RCSP OTA 固件升级 Android SDK 仓库。本文档说明仓库的顶层目录布局、各目录承载的发布物（OTA 核心 AAR、测试 APK、开发文档、参考 Demo 工程）以及版本演进，帮助接入方快速定位所需资源并按正确姿势集成。

Purpose and Scope

本页覆盖：

• 仓库顶层目录布局（apk/、code/、doc/、libs/ 及根目录文件）的逐一说明；
• 发布物（deliverables）定义：核心库 AAR、测试 APK、更新说明、开发文档、参考 Demo 源码；
• 发布物命名约定与版本历史；
• 从仓库到客户工程的导入路径（clone → 打开 Demo → 引用 AAR → 编译）。

本页不展开以下主题（属于相邻目录页）：

• BluetoothOTAConfigure 各参数含义与 OTA 升级流程细节 —— 见"OTA 参数配置"相关页面；
• RCSP 协议、BLE/SPP 传输与升级流程的内部实现 —— 见 SDK 在线文档中心；
• Demo APK 的具体操作步骤（添加升级文件、连接设备、开始升级）—— 见"使用流程"相关页面。

Overview

该仓库本身是一个 SDK 交付仓库：它不直接以 Gradle 工程形式发布，而是以"目录即发布物"的方式组织。每个顶层目录对应一类交付资源：

仓库当前版本配套的核心库为 jl_bt_ota_V1.11.0_11015-release.aar，测试 APK 为 JLOTA_V1.9.0_10905-debug.apk，两者版本号独立演进（详见版本历史）。

Architecture

下图展示仓库内部资源与接入方工程之间的关系，以及各发布物的消费路径：

flowchart TD
    subgraph sg_Repo["Android-JL_OTA 仓库"]
        APK["apk/ 测试APK"]
        CODE["code/ 参考Demo工程"]
        DOC["doc/ 开发文档"]
        LIBS["libs/ OTA核心AAR"]
        README["README.md 接入说明"]
    end

    subgraph sg_Consumer["接入方工程"]
        BUILD["build.gradle 依赖声明"]
        APP["客户 App"]
    end

    LIBS -->|"implementation fileTree(include: ['*.aar'])"| BUILD
    CODE -->|"参考实现"| APP
    DOC -->|"开发指引"| APP
    APK -->|"功能体验/验证"| APP
    README -->|"接入总览"| APP
    BUILD --> APP

各节点的职责：

• libs/（OTA 核心 AAR）：唯一的运行时依赖来源，包含 RCSP 协议处理与升级流程控制逻辑。它是接入方 build.gradle 中 implementation fileTree(include: ['*.aar'], dir: 'libs') 的目标物。
• code/（参考 Demo 工程）：展示核心库的完整调用方式，是"如何写代码"的最直接证据，接入方应以此为准核对 API 用法。
• apk/（测试 APK）：预编译的调试版安装包，用于在真实设备上体验升级流程，辅助问题定位。
• doc/（开发文档）：离线开发说明与在线文档链接，覆盖配置、调试与常见问题。
• README.md：仓库总入口，串起目录、快速开始、配置说明、版本历史与许可证。

设计意图：以"目录即发布物"的方式交付，可以让接入方按需取用——只需要库就只拷 libs/，需要参考代码就看 code/，需要验证就装 apk/，避免把完整源码工程作为依赖引入带来的耦合。

目录结构详解

仓库在 README.md 中给出了权威的工程结构树（README.md#L135-L151）：

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                          # 说明文件

libs/ —— OTA 核心库（二进制发布物）

libs/ 是接入方唯一必须引入的运行时依赖目录，核心交付物为：

• jl_bt_ota_V1.11.0_11015-release.aar：OTA 升级核心库，包含 RCSP 协议处理、升级流程控制等功能（README.md#L85）。
• ReadMe.txt：核心库说明文件，一般注明库的版本、使用前提与注意事项。

命名约定：AAR 文件名遵循 jl_bt_ota_V<主版本>.<次版本>.<修订>_<构建号>-release.aar。其中 V 后的三段数字是 SDK 语义化版本，_ 后的五位数字是构建号。例如 V1.11.0_11015 表示 SDK 版本 1.11.0、构建号 11015。-release 后缀表明这是发布版（非 debug 版）产物。

该目录是闭源二进制发布物，接入方无法直接查看其源码；问题排查依赖 SDK 输出的日志与在线文档。

apk/ —— 测试 APK（体验发布物）

• JLOTA_V1.9.0_10905-debug.apk：OTA 测试版本安装包，用于在真机上体验完整升级流程（添加升级文件 → 连接设备 → 开始升级）。
• UpdateContent.txt：更新说明，记录该 APK 版本的变更点。

注意：APK 版本号（1.9.0）与核心库版本号（1.11.0）相互独立，并不强制一致。仓库在快速开始中提示参考 apk/ 目录中的测试 APK 了解 SDK 功能和使用方法（README.md#L127）。

code/ —— 参考 Demo 源码工程

存放 OTA Demo 项目的完整 Android 源码工程。接入时的标准做法是：解压仓库后用 Android Studio "Open an existing project" 导航到 code/ 目录打开 Demo 工程（README.md#L77-L79）。该工程是核心库 API 用法（OTAManager、BluetoothOTAConfigure 等）的最直接参考。

doc/ —— 开发文档

• JieLi_OTA_SDK_Android_Development_Doc：杰理 OTA 外接库（Android）离线开发文档。
• 杰理OTA外接库(Android)开发文档链接：指向在线开发文档的地址入口（在线文档中心：https://doc.zh-jieli.com/Apps/Android/ota/zh-cn/master/index.html）。

根目录文件

• README.md / README_en.md：中英双语接入总览，含目录、快速开始、工程结构、配置说明、调试技巧、版本历史与许可证。
• LICENSE：Apache License 2.0 开源协议全文。
• ReadMe.txt：仓库级说明文件（与 libs/ 下的 ReadMe.txt 不同，后者是核心库专项说明）。

发布物清单

版本历史

核心库 SDK 的版本演进记录在 README.md 的"八、版本历史"一节（README.md#L252-L263），是判断"当前仓库配套哪个 SDK 版本、升级了哪些能力"的依据：

从版本演进可看出两条设计主线：

1. 系统兼容性跟随 Android 大版本迭代（Android 11/13/14/15 的兼容处理），因为 SDK 依赖蓝牙与存储权限，高版本系统的权限模型变化会直接影响 OTA 流程可用性；
2. 传输与多设备能力持续增强（SPP、双模、TWS、多设备升级、自动回连），说明核心库把"连接管理"与"升级流程"解耦，使回连、MTU 调整等能力可独立演进。

核心流程：从仓库到客户工程

接入方把仓库资源转化为自身 App 能力的标准路径如下：

flowchart LR
    Start([获取仓库]) --> Clone["git clone / 下载ZIP"]
    Clone --> Open["Android Studio 打开 code/ 参考工程"]
    Open --> Demo["运行 Demo 体验 OTA 流程"]
    Clone --> Import["拷贝 libs/ 下 AAR 到客户工程 libs/"]
    Import --> Dep["build.gradle 添加依赖"]
    Dep --> Config["配置 BluetoothOTAConfigure"]
    Config --> Build["编译并验证客户 App"]
    Demo --> Build

流程要点：

• 获取仓库：git clone https://github.com/Jieli-Tech/Android-JL_OTA.git 或从发行页下载 ZIP（README.md#L67-L69）。
• 参考先行：先运行 code/ 中的 Demo，建立对 SDK 能力的直观认识，再在客户工程中复刻同样调用序列。
• 依赖最小化：客户工程只需 libs/ 下的 AAR，无需引入 Demo 工程源码，避免 SDK 与业务代码耦合。

使用示例

以下示例全部摘自仓库 README.md，展示从"引入核心库"到"首次配置"的完整代码路径。

1. 获取仓库

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

来源：README.md#L67-L69

2. 在客户工程中引入核心库

将 libs/ 目录下的 AAR 放入客户工程对应 module 的 lib 文件夹，并在 build.gradle 声明依赖：

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

来源：README.md#L91-L97

设计意图：通过 fileTree 通配 *.aar，客户工程升级核心库时只需替换 libs/ 下的文件即可，build.gradle 无需改动，降低版本切换成本。

3. 声明必要权限

接入 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"/>

来源：README.md#L105-L121

4. 初始化 OTA 参数（核心库 API 入口）

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参数

来源：README.md#L163-L176

该示例说明 OTAManager + BluetoothOTAConfigure 是核心库暴露的统一配置入口：连接方式（BLE/SPP）、认证、超时、MTU、回连策略均通过链式调用一次性注入，configure() 之后即可启动升级。完整的参数说明见"OTA 参数配置"相关页面。

环境与硬件要求

仓库 README 明确了 SDK 的运行前提（README.md#L52-L55）：

平台支持随版本演进扩展：1.9.3 起增加 x86 / x86_64 支持，1.9.0 起支持多设备升级，1.11.0 起增加 Gatt Over BR/EDR 连接方式。

注意事项、边界与失败模式

基于仓库文档中可验证的信息，接入方应特别关注以下风险点：

版本对齐问题

仓库内 APK 版本（1.9.0）与核心库 AAR 版本（1.11.0）相互独立。若接入方以 apk/ 中旧版 APK 的体验结果来推断新版核心库行为，可能出现认知偏差（例如 1.9.x 尚无 Android 15 兼容与自动回连能力）。建议：以 libs/ 中 AAR 的版本为基准，对照版本历史确认所需能力是否已具备，再决定升级策略。

二进制闭源导致的黑盒风险

核心库以 AAR 二进制交付（jl_bt_ota_V1.11.0_11015-release.aar），内部 RCSP 协议处理与升级流程不可见。出现异常时只能依赖：

• SDK 输出日志（README 提示 SDK 提供详细日志输出，可通过日志查看 OTA 连接状态和数据交互，README.md#L216）；
• code/ 参考 Demo 工程的行为对照；
• 在线调试说明与常见问题文档。

权限申请失败是高发失败模式

版本历史多次出现与权限相关的修复（1.10.0 修复 Android 14+ 存储权限申请失败、1.9.2/1.9.0 增加 Android 13/11 兼容处理）。根因是 Android 高版本把蓝牙（BLUETOOTH_SCAN/BLUETOOTH_CONNECT）与存储权限改为运行时权限。接入方必须在运行时动态申请权限，而非仅声明静态权限，否则 OTA 流程会在扫描或读取固件文件阶段失败。

传输配置不一致导致升级中断

BluetoothOTAConfigure 中 setMtu/setNeedChangeMtu 的组合需要与客户工程自己的 BLE 连接层协调：若库被配置为需要调整 MTU（setNeedChangeMtu(true)），客户 SDK 必须对此处理；若关闭调整，则客户需在连接时自行调好 MTU。配置不一致会造成传输速率异常甚至升级失败（README.md#L170-L171）。

固件文件路径/数据二选一

setFirmwareFilePath 与 setFirmwareFileData 二者选其一；若两者都未设置，升级前必然失败（README 明确标注"默认为空，升级前需要设置"，README.md#L189-L190）。

扩展点与运维提示

• 连接层可插拔：BluetoothOTAConfigure.isUseReconnect 为 false 且 bleConnectParam 为空时，客户需实现 connectBluetoothDevice 接口自行回连；snGenerator（ICmdSnGenerator）为 null 时采用默认 SN 生成器，适用于杰理多库联合使用场景（README.md#L194-L196）。这些接口即 SDK 的官方扩展点。
• 升级文件存放约定：Demo 默认把升级文件放到 手机根目录/Android/data/com.jieli.otasdk/files/upgrade/，也支持 Download 目录选择与局域网传输（README.md#L202-L207）。
• 多设备升级：自 1.9.0 起核心库去掉单例使用、升级流程独立，支持同时管理多个设备的 OTA 流程（README.md#L261）。

相关链接

• README.md（中文接入总览）
• README_en.md（英文接入总览）
• LICENSE（Apache License 2.0）
• 杰理 OTA SDK 在线文档中心
• 相邻主题："OTA 参数配置"（BluetoothOTAConfigure 属性详解）、"使用流程"（Demo 操作步骤）、"调试技巧"（日志与问题排查）——详见仓库 README 对应章节。