集成SDK依赖

本文介绍如何将杰理之家 SDK（Android-JL_Bluetooth）以 AAR 依赖的形式集成到 Android 工程中，涵盖依赖库清单、Gradle 构建配置、权限声明与初始化入口。

Purpose and Scope

本页面向首次接入 SDK 的 Android 开发者，说明集成依赖所需的全部步骤：

• libs/ 目录下各 AAR 核心库的职责与版本对应关系；
• 在模块 build.gradle 中声明本地 AAR 依赖与第三方依赖（Gson）；
• 仓库镜像与构建脚本配置（jitpack、阿里云镜像等）；
• AndroidManifest.xml 中的蓝牙与定位权限声明；
• SDK 初始化入口 RCSPController.init() 与 BluetoothOption 配置项。

以下主题属于其他页面，本页仅做指引、不展开：设备扫描/连接的完整流程（见"设备连接"相关页面）、RCSP 命令协议细节（见"RCSP 协议"页面）、OTA 升级（见"OTA 升级"页面）。

Overview

Android-JL_Bluetooth 是珠海市杰理科技股份有限公司为杰理音箱、耳机类产品提供的蓝牙控制开发平台，基于 RCSP 协议（远程控制系统协议） 实现手机与设备之间的双向控制。SDK 以 AAR（Android Archive） 形式发布，不通过远程 Maven 坐标分发，而是随仓库的 libs/ 目录一起提供，集成时直接以本地文件依赖方式引入。

这种"本地 AAR + 文件树依赖"的集成模式设计意图在于：

• 版本可控：SDK 与固件配套发布，本地 AAR 可精确锁定与固件匹配的协议版本；
• 离线可用：不依赖远端 Maven 仓库，构建环境无需外网即可编译；
• 开箱即用：仓库同时提供完整参考工程（code/PiHome_V1.13.0_SDK_V4.2.0），可直接作为集成的起点。

集成依赖是使用 SDK 一切能力的前提：只有完成 AAR 引入与权限声明，才能调用 RCSPController 完成初始化、扫描、连接与命令下发。

Architecture

下图为 SDK 依赖集成后的工程结构：应用模块通过 build.gradle 将 libs/ 中的 AAR 核心库与 Gson 引入，并在 AndroidManifest.xml 声明权限，最终通过 RCSPController.init() 完成 SDK 初始化。

flowchart TD
    subgraph sg_Repo["仓库根目录 libs/（AAR 核心库）"]
        AAR1["jl_bluetooth_rcsp_Vxxx-release.aar<br/>蓝牙控制与RCSP协议处理"]
        AAR2["jldecryption_Vxxx-release.aar<br/>加密解密"]
        AAR3["jl_bt_ota_Vxxx-release.aar<br/>OTA升级"]
        AAR4["jl_eq_Vxxx-release.aar<br/>均衡器算法"]
        AAR5["jl_audio_decode_Vxxx-release.aar<br/>OPUS编解码"]
        AAR6["jl_audio_v2_Vxxx-release.aar<br/>JLA_V2编解码"]
        AAR7["BmpConvert / GifConvert<br/>图片转码"]
    end

    subgraph sg_App["应用工程（示例 btsmart 模块）"]
        GRADLE["build.gradle<br/>implementation fileTree(include: ['*.aar'], dir: 'libs')"]
        GSON["implementation 'com.google.code.gson:gson:2.13.1'"]
        MANIFEST["AndroidManifest.xml<br/>蓝牙 + 定位权限"]
        INIT["RCSPController.init(context, bluetoothOption)"]
    end

    subgraph sg_Runtime["运行时能力"]
        BLE["BLE/SPP 通讯通道"]
        CMD["RCSP 命令收发"]
        AUTH["设备认证"]
    end

    AAR1 --> GRADLE
    AAR2 --> GRADLE
    AAR3 --> GRADLE
    AAR4 --> GRADLE
    AAR5 --> GRADLE
    AAR6 --> GRADLE
    AAR7 --> GRADLE
    GSON --> GRADLE
    GRADLE --> MANIFEST
    MANIFEST --> INIT
    INIT --> BLE
    INIT --> CMD
    INIT --> AUTH

各组件职责：

• jl_bluetooth_rcsp_*：SDK 主库，封装蓝牙扫描、连接管理与 RCSP 协议编解码，是唯一必需的依赖；
• jldecryption_*：加解密库，用于设备认证与 HASH 过滤规则（配合 BluetoothOption.setUseDeviceAuth 与 HASH_FILTER 扫描策略）；
• jl_bt_ota_* 等扩展库：按需引入，分别对应 OTA、均衡器、音频编解码、图片转码能力，不引入不影响主流程；
• Gson：SDK 内部序列化依赖，官方示例明确要求声明 com.google.code.gson:gson:2.13.1；
• RCSPController.init()：SDK 全局初始化入口，所有后续 API 调用均依赖其完成。

依赖库清单

官方快速开始文档（README.md）指出，集成 SDK 最少需要两个 AAR：

PS: xxx 为版本号，AAR 文件名中的版本需与仓库发布版本对应。

仓库 libs/ 目录（见 README.md 工程结构）还包含以下按需库：

选择策略：仅做基础蓝牙控制时只需前两个 AAR；使用 OTA、音效、彩屏仓等高级功能时再引入对应扩展库，以避免不必要的包体增大与依赖冲突。

集成步骤详解

步骤一：获取 AAR 并放入 libs 目录

从仓库 libs/ 目录（或发布 Tag 的 Releases 附件）下载所需 AAR，复制到目标工程模块的 libs/ 文件夹下。仓库示例工程中 code/PiHome_V1.13.0_SDK_V4.2.0/btsmart/build.gradle 即采用此方式。

步骤二：声明 Gradle 依赖

在模块的 build.gradle 的 dependencies 块中添加依赖。官方示例（README.md）：

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

	implementation 'com.google.code.gson:gson:2.13.1'
}

要点说明：

• fileTree(include: ['*.aar'], dir: 'libs') 会将 libs/ 目录下所有 AAR 一次性引入，新增 AAR 后无需改动 Gradle 脚本；
• Gson 是 SDK 运行所依赖的序列化库，必须显式声明，否则运行时可能抛出 NoClassDefFoundError；
• 若模块同时使用 implementation fileTree(...) 引入 jar 包，可扩展为 include: ['*.aar', '*.jar']。

步骤三：配置仓库镜像（可选但推荐）

示例工程根 build.gradle 中配置了 JitPack、阿里云镜像、Google Maven 等仓库（build.gradle）：

maven { url 'https://jitpack.io' }
maven { url 'https://maven.aliyun.com/repository/apache-snapshotse' }
maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
maven { url 'https://maven.aliyun.com/repository/public' }
maven { url 'https://maven.aliyun.com/repository/central' }
mavenCentral()
maven { url 'https://maven.google.com' }

设计意图：AAR 本地依赖本身不经过 Maven 仓库，但这些仓库用于解析 Gson 及示例工程依赖的其他开源库（如 TarsosDSP、小米 Maven 仓库等）；阿里云镜像专为国内网络加速，可显著缩短首次构建下载时间。

步骤四：声明 AndroidManifest 权限

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

注意事项：

• BLUETOOTH_SCAN / BLUETOOTH_CONNECT 是 Android 12（API 31）起新增的运行时权限，除 Manifest 声明外还需在代码中动态申请；
• 定位权限是 Android 扫描 BLE 设备的硬性要求（系统层面依赖位置服务发现蓝牙广播），缺少时 startScan 将无回调或直接失败；
• 建议同时为 BLUETOOTH_SCAN 与定位权限声明 usesPermissionFlags="neverForLocation" 的场景按需评估，官方示例未做该裁剪。

步骤五：初始化 SDK

依赖与权限就绪后，在应用启动入口（如 Application.onCreate）创建 BluetoothOption 并调用 RCSPController.init() 完成初始化（详见下文"SDK 初始化配置"）。

SDK 初始化配置

BluetoothOption 与 RCSPController.init()

官方示例（README.md）展示了完整的初始化代码：

BluetoothOption bluetoothOption = BluetoothOption.createDefaultOption();//创建默认配置
bluetoothOption.setPriority(BluetoothOption.PREFER_BLE)//通信方式，支持ble和spp
           .setUseMultiDevice(true) //是否支持多设备管理
           .setTimeoutMs(2000)//命令超时时间, 默认2000ms
           .setMtu(509)       //调节蓝牙MTU
           .setUseDeviceAuth(true);//是否开启设备认证。 与固件工程师确认
    /**
     * 扫描设备策略
     *  - BluetoothConstant#NONE_FILTER : 不过滤设备
     *  - BluetoothConstant#ALL_FILTER : 使用所有过滤规则
     *  - BluetoothConstant#FLAG_FILTER : 仅用标识过滤规则 (音箱)
     *  - BluetoothConstant#HASH_FILTER : 仅用加密过滤规则 (耳机,音箱,等等)
     */
    //bluetoothOption.setBleScanStrategy(BluetoothConstant.ALL_FILTER);

    //修改BLE的通讯uuid
    //bluetoothOption.setBleUUID(serviceUUID, writeCharacteristicUUID, notificationCharacteristicUUID);

    //修改SPP的通讯uuid
    //bluetoothOption.setSppUUID(uuid);

//配置参数
RCSPController.init(context, bluetoothOption);
//JL_BluetoothManager.getInstance(context).configure(bluetoothOption);

初始化流程说明

1. BluetoothOption.createDefaultOption() 返回带默认值的配置对象，链式调用各 setter 覆盖默认值；
2. RCSPController.init(context, bluetoothOption) 为全局单例初始化，内部完成蓝牙适配器绑定、通讯通道（BLE/SPP）准备、扫描过滤规则构建与设备认证开关装载；
3. 初始化通常放在 Application.onCreate()，保证任何 Activity 使用 SDK 前已就绪；
4. 代码中被注释的 JL_BluetoothManager.getInstance(context).configure(bluetoothOption) 为另一兼容入口，同一工程内二选一，不要同时调用。

配置项与默认值

表格内容依据 README.md 配置说明 整理，具体字段以 AAR 内 BluetoothOption 实际 API 为准。

API 参考（初始化入口）

RCSPController.init(Context context, BluetoothOption option)

SDK 全局初始化入口，需在首次使用 SDK 前调用一次（建议 Application.onCreate）。

参数：

• context（Context）：应用上下文，建议传入 Application 实例，避免 Activity 泄漏；
• option（BluetoothOption）：蓝牙配置对象，传入 BluetoothOption.createDefaultOption() 或自定义配置。

返回： 无（void）。

说明：

• 内部完成通讯通道与扫描策略装配，失败场景（如设备不支持蓝牙）由 SDK 内部日志输出，建议初始化后自行校验 BluetoothAdapter 可用性；
• 同一进程重复调用以首次配置为准。

BluetoothOption.createDefaultOption(): BluetoothOption

创建携带全部默认值的配置对象，是链式配置的起点。

BluetoothOption.setPriority(int priority) / setUseMultiDevice(boolean) / setTimeoutMs(int) / setMtu(int) / setUseDeviceAuth(boolean)

链式 setter，返回 BluetoothOption 自身以支持连续调用；各参数含义与默认值见上方配置表。

失败模式与边界情况

• AAR 未放入 libs/ 或路径错误：Gradle 同步报 Could not find ... aar / 运行时 ClassNotFoundException。排查：确认 dir: 'libs' 相对的是模块目录（如 btsmart/libs），且 include: ['*.aar'] 匹配到文件。
• 缺少 Gson 依赖：SDK 反序列化 RCSP 报文时抛出 NoClassDefFoundError: com/google/gson/...。务必显式声明 implementation 'com.google.code.gson:gson:2.13.1'，或至少同版本兼容的 Gson。
• 缺少定位权限（Android 6+ 运行时权限）：BLUETOOTH_SCAN 静默失败、扫描无回调。需在代码中动态申请 ACCESS_FINE_LOCATION 与 BLUETOOTH_SCAN 后再调用扫描接口。
• 设备认证开关不一致：isUseDeviceAuth 默认 true，若固件端未开启认证，连接校验将失败。README 明确提示"与固件工程师确认"，这是 SDK/固件联调最常见的坑。
• MTU 越界：mtu 取值范围 [20, 514]，超出范围可能导致协商失败或连接异常，建议按目标设备能力设置（示例工程用 509）。
• 双初始化入口混用：RCSPController.init(...) 与 JL_BluetoothManager.configure(...) 二选一，混用可能造成配置覆盖或重复初始化。
• Android 12 蓝牙权限变更：未声明/未申请 BLUETOOTH_CONNECT 时，所有蓝牙 API 直接抛 SecurityException。

并发与一致性考虑

• RCSPController.init() 应仅在主线程（Application 启动阶段）调用一次，避免与扫描/连接流程并发初始化导致竞态；
• timeoutMs 默认 2000ms，多设备场景（setUseMultiDevice(true)）下命令序号由 cmdSnGenerator 统一分配，防止并发下发时响应错配——多 RCSP 库共存时必须注入同一生成器实例；
• 命令超时与重连逻辑由 SDK 内部线程管理，应用层回调均回到主线程，回调中不宜执行耗时操作。

性能与运维建议

• 按需引入 AAR：仅主库+解密库即可跑通基础流程，避免一次性引入 OTA/编解码/转码库导致 APK 增大；
• 国内构建加速：配置阿里云镜像仓库（示例工程已内置），首次 Gradle 同步耗时显著降低；
• MTU 调优：大文件传输（如彩屏壁纸、OTA）场景将 mtu 调至 509 可减少分包、提升吞吐；
• 扫描功耗：前台页面建议 bleScanMode = SCAN_MODE_LOW_LATENCY 缩短发现延迟，退后台切换 LOW_POWER；
• 版本对齐：AAR 版本需与固件 SDK 版本配套，升级固件能力（如新增 ANC 命令）时同步升级主库 AAR。

扩展点

• scanFilterData / bleScanStrategy：通过自定义设备特征标识与过滤策略（FLAG/HASH），精确匹配自家产品，避免串扫到其他杰理设备；
• 自定义 UUID：setBleUUID(...) 与 setSppUUID(...) 支持按 OEM 需求替换通讯 UUID，适配私有化固件；
• cmdSnGenerator：实现该接口可将多个 RCSP 库的命令序号统一管理，是接入多个杰理库时的关键扩展点；
• 自定义命令：SDK 支持客户自定义命令扩展（README 功能清单中的"自定义命令"），在协议层之上追加私有指令。

相关链接

• README.md（快速开始与配置说明）
• 示例工程根构建脚本（仓库镜像配置）
• 示例应用模块构建脚本
• 英文版 README
• 配套开发文档：doc/JieLi_Home_SDK_V4.2.0_html_zh（SDK 开发说明，中文版）、doc/杰理OTA(Android)在线开发文档（OTA 集成）