运行示例应用

本文介绍如何运行 Android-JL_Bluetooth（杰理之家 SDK）仓库中自带的示例应用，包括直接安装 apk/ 目录下预编译的测试 APK，以及从 code/ 源码工程编译运行两种方式，并涵盖运行环境、依赖库、权限、SDK 初始化、常见问题与调试方法。

Purpose and Scope

本页面向首次接触该 SDK 的开发者，说明如何把示例应用跑起来：从拿到仓库到在真机上看到「杰理之家」App 扫描并连接杰理音箱/耳机设备（如 AC701N、AC697N 等支持 RCSP 协议的芯片）的完整过程。

本页覆盖的内容：

• 运行环境与硬件要求
• 两种运行方式：直接安装测试 APK、从源码编译运行
• 仓库中与运行相关的目录（apk/、code/、libs/）及其作用
• 运行前必须完成的依赖库与权限配置
• SDK 启动初始化配置（BluetoothOption）
• 调试与问题排查指引

以下内容属于兄弟页面的主题，本页仅做交叉引用、不展开：

• SDK 的详细接入步骤、build.gradle 依赖声明方式 → 见「快速开始」相关页面
• BluetoothOption 全部字段的深层语义 → 见「SDK 配置说明」相关页面
• RCSP 协议细节与各功能模块（音乐控制、ANC、AI 翻译等）的 API → 见各功能模块页面
• OTA 升级、音频编解码库的使用 → 见对应库的文档页面

Overview

Android-JL_Bluetooth 是珠海市杰理科技股份有限公司面向杰理音箱/耳机类产品（智能音箱、TWS 耳机、彩屏仓、翻译耳机等）提供的蓝牙控制开发平台。SDK 基于 RCSP 协议（远程控制系统协议），仓库以「源码 + 预编译 AAR + 测试 APK + 文档」的方式交付，让开发者可以零成本先跑通示例应用，再逐步接入自己的产品。

仓库中与「运行示例应用」直接相关的资源：

为什么要先运行示例应用？ 示例应用（杰理之家）是 SDK 功能最完整的参考实现：它演示了扫描、连接、多设备管理、音乐控制、ANC、AI 翻译等几乎所有 RCSP 能力。开发者可以先安装 APK 验证硬件设备与手机兼容性，再对照源码工程理解 API 的调用方式，最后将 libs/ 中的 AAR 与示例代码迁移到自己的工程中。

Architecture

下图展示「运行示例应用」所涉及的仓库资源与运行路径：

flowchart TD
    subgraph sg_Repo["Android-JL_Bluetooth 仓库"]
        subgraph sg_Apk["apk/ 预编译产物"]
            APK["btsmart-V1.13.0...-debug.apk"]
            UPD["UpdateContent.txt"]
        end
        subgraph sg_Code["code/ 源码工程"]
            SRC["PiHome_V1.13.0_SDK_V4.2.0"]
        end
        subgraph sg_Libs["libs/ 核心库"]
            RCSP["jl_bluetooth_rcsp_V4.2.0...aar"]
            DEC["jldecryption_v0.4...aar"]
            OTHERS["jl_bt_ota / jl_audio / jl_eq / ..."]
        end
    end

    subgraph sg_Dev["开发环境"]
        AS["Android Studio"]
        PHONE["Android 5.1+ 手机"]
    end

    subgraph sg_Device["目标设备"]
        HW["RCSP 音箱/耳机<br/>(AC701N/AC697N/AC695N 等)"]
    end

    APK -->|"方式一：直接安装"| PHONE
    SRC -->|"方式二：编译运行"| AS
    AS -->|"Gradle 打包"| PHONE
    RCSP -->|"Gradle 依赖引入"| SRC
    DEC -->|"Gradle 依赖引入"| SRC
    OTHERS -->|"按需依赖引入"| SRC
    PHONE -->|"BLE/SPP 连接"| HW
    UPD -.->|"版本与测试限制说明"| APK

架构说明：

• 两条运行路径互不冲突：直接安装 apk/ 下的 APK 最快（无需任何编译），适合先验证设备兼容性；从 code/PiHome_V1.13.0_SDK_V4.2.0 编译运行则能获得源码级参考，适合学习 API 调用与二次开发。
• libs/ 是运行时依赖的根基：无论走哪条路径，最终 App 都依赖 jl_bluetooth_rcsp（RCSP 协议与蓝牙控制）和 jldecryption（设备认证/加密）这两个核心 AAR，OTA、音频编解码、EQ 等库按需引入。
• 目标硬件必须支持 RCSP：示例应用通过 BLE 或 SPP 与杰理芯片通信，因此需要 AC701N、AC707N、AC697N、AC696N、AC695N 等支持 RCSP 功能的 SDK 芯片。

运行环境要求

在运行示例应用之前，请确认满足以下环境条件（源自 README.md 运行环境章节）：

注意：硬件要求针对的是被控制的杰理设备（音箱/耳机），而非手机。手机只需 Android 5.1+ 并开启蓝牙与定位权限。

运行方式一：直接安装测试 APK（最快路径）

仓库在 apk/ 目录下提供预编译的调试版 APK，适合在不编写任何代码的情况下先体验 SDK 的全部功能：

• APK 文件：apk/btsmart-V1.13.0-202601231637-113126-debug.apk
• 配套说明：apk/UpdateContent.txt（版本与更新内容）、apk/杰理之家导出打印日志说明.pdf（日志导出方法）

操作步骤：

1. 将 APK 文件拷贝到 Android 5.1+ 手机，或通过 adb install 安装：

   adb install apk/btsmart-V1.13.0-202601231637-113126-debug.apk
   

2. 打开 App，授予蓝牙（BLUETOOTH_SCAN / BLUETOOTH_CONNECT）与定位权限。

3. 打开被控杰理设备电源，在 App 中执行扫描，选择设备建立 RCSP 连接。

4. 依次体验音乐控制、ANC 设置、AI 翻译等功能，并通过「导出打印日志」功能收集日志用于排查。

APK 版本与更新内容

根据 apk/UpdateContent.txt，该测试 APK 的版本为 btsmart-V1.13.0-202601231637-113126-debug，更新内容包括：

AI 翻译功能的测试限制（重要）

apk/UpdateContent.txt 明确说明：AI 翻译依赖豆包火山大模型的云服务，由于云服务有流量限制，测试前需要扫描二维码验证身份，且二维码有使用时效（约一周）。如果授权二维码过期，需联系 SDK 负责人更新；建议客户替换为自己的豆包火山大模型账号（修改 DoubaoTranslationMessage 和 DoubaoTTSMessage 即可完成账号更改），或更换其他 AI 平台。

运行方式二：从源码编译运行（学习路径）

若要深入学习 API 调用或进行二次开发，应编译 code/PiHome_V1.13.0_SDK_V4.2.0 源码工程。该目录在 README.md 工程结构章节 中有说明，是「杰理之家」项目的完整源码。

操作步骤（对应 README.md 快速开始章节）：

1. 克隆仓库：

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

2. 导入工程：打开 Android Studio，选择 "Open an existing project"，导航到 code/ 目录，打开 PiHome_V1.13.0_SDK_V4.2.0 中的项目文件。

3. 引入依赖库：将 libs/ 目录下的 AAR 文件复制到工程对应 module 的 libs 目录（jl_bluetooth_rcsp_Vxxx-release.aar 为蓝牙控制与 RCSP 协议处理核心库，jldecryption_Vxxx-release.aar 为加密相关库，xxx 为版本号）。

4. 编译运行：连接 Android 5.1+ 真机（示例应用涉及 BLE 与定位，不建议使用模拟器），点击 Run 构建并安装。

编译前请重点检查第 3 步依赖引入与第 4 步权限配置，两者缺一不可，详见下文「依赖库与权限配置」。

依赖库与权限配置

无论编译源码工程还是自行搭建新工程，运行前都必须完成依赖库与权限两件事。这是示例应用能够扫描、连接设备的前置条件。

依赖库（libs/）

仓库 libs/ 目录下提供多个预编译 AAR（见 README.md 工程结构章节）：

在 module 的 build.gradle 中按 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'
}

Source: README.md

fileTree(include: ['*.aar'], dir: 'libs') 会将 libs 目录下的全部 AAR 一并引入，示例工程依赖 Gson 用于协议数据的 JSON 序列化。

权限配置

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

Source: README.md

设计意图：BLUETOOTH / BLUETOOTH_ADMIN 是 Android 12 之前的传统蓝牙权限；BLUETOOTH_SCAN / BLUETOOTH_CONNECT 是 Android 12+ 的运行时蓝牙权限；定位权限则是官方对 BLE 扫描的强制要求（Android 6–11 需要运行时申请，Android 12+ 蓝牙扫描不再依赖定位但系统仍可能要求）。示例应用在 Android 5.1 到 Android 15 之间均需兼容，因此四组权限全部声明。

SDK 启动配置（BluetoothOption）

示例应用启动后通过 RCSPController.init(context, bluetoothOption) 完成 SDK 初始化。初始化配置决定了连接方式（BLE/SPP）、扫描策略、超时时间、MTU 等关键行为（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);

Source: README.md

设计意图：示例应用默认优先使用 BLE（PREFER_BLE）并支持多设备（setUseMultiDevice(true)）；setUseDeviceAuth(true) 开启设备认证，该选项必须与固件工程师协商一致，否则可能出现连上后无法通信的情况。注释掉的 setBleUUID / setSppUUID 用于对接非标准 UUID 的定制固件。

BluetoothOption 关键字段

README.md 给出了字段级说明，摘录运行示例应用时最常涉及的字段：

核心运行流程

从安装到成功操控杰理设备的完整时序如下：

sequenceDiagram
    participant Dev as 开发者
    participant Phone as 手机 (Android 5.1+)
    participant App as 杰理之家示例App
    participant SDK as jl_bluetooth_rcsp SDK
    participant Dev2 as 杰理设备 (RCSP芯片)

    Dev->>Phone: 安装 APK / Android Studio 编译安装
    Dev->>Phone: 开启蓝牙、授予定位与蓝牙权限
    Dev->>App: 启动 App
    App->>SDK: RCSPController.init(context, BluetoothOption)
    SDK->>SDK: 按 BluetoothOption 配置 BLE/SPP、超时、MTU、认证
    Dev->>App: 点击扫描
    App->>SDK: 发起 BLE 扫描 (按 bleScanStrategy 过滤)
    SDK->>Dev2: 广播发现 (扫描到目标设备)
    App->>SDK: 选择设备发起连接
    SDK->>Dev2: 建立 BLE 连接 + 设备认证 (isUseDeviceAuth)
    Dev2-->>SDK: 认证通过，RCSP 通道就绪
    SDK-->>App: 连接成功回调
    App->>SDK: 发送 RCSP 命令 (音乐控制/ANC/翻译等)
    SDK->>Dev2: 命令下发并等待响应 (timeoutMs=2000ms)
    Dev2-->>SDK: 响应数据
    SDK-->>App: 解析结果并刷新 UI

流程要点：

1. 初始化阶段：RCSPController.init() 必须在使用任何功能前调用，BluetoothOption 中的通讯方式、超时、MTU、认证开关在此刻生效。
2. 扫描阶段：SDK 按 bleScanStrategy（默认 ALL_FILTER）过滤广播包，只展示符合杰理标识/HASH 规则的设备，避免用户被无关蓝牙设备干扰。
3. 连接与认证阶段：若 isUseDeviceAuth=true，连接后需完成设备认证握手，认证失败会中断通信——这正是「需与固件工程师协商」的原因。
4. 命令交互阶段：所有 RCSP 命令都有 timeoutMs（默认 2000ms）超时保护，超时后 SDK 会向 UI 层回调失败。

失败模式、边界情况与并发

基于 README 与 APK 更新说明，运行示例应用时可能遇到以下问题：

1. AI 翻译功能无法使用（时效性限制）

症状：AI 翻译提示需要验证，或验证后仍失败。

原因：杰理提供的 AI 翻译云服务（豆包火山大模型）有流量限制，授权二维码有效期约一周。

处理：联系 SDK 负责人更新二维码；或按 apk/UpdateContent.txt 的建议，将 DoubaoTranslationMessage 和 DoubaoTTSMessage 替换为自有账号后自行编译。

2. 扫描不到设备或连接失败

• 权限未授予：Android 12+ 必须授予 BLUETOOTH_SCAN / BLUETOOTH_CONNECT；Android 11 及以下必须授予定位权限，否则 BLE 扫描被系统拦截。运行时权限需在代码中申请，仅声明 AndroidManifest.xml 不够。
• 设备不支持 RCSP：目标硬件必须是 AC701N、AC707N、AC697N、AC696N、AC695N 等支持 RCSP 功能的芯片（见 README.md 运行环境）。
• 过滤规则不匹配：若固件标识与 bleScanStrategy / scanFilterData 不匹配，设备会被过滤掉，可先改用 NONE_FILTER 验证设备广播是否正常。

3. 连接后无法通信（设备认证问题）

isUseDeviceAuth 默认开启认证，若固件端未启用对应的认证逻辑，连接看似成功但命令无响应。务必与固件工程师确认该开关（README.md），必要时关闭或对齐认证算法。

4. 命令超时（2000ms 默认值）

timeoutMs 默认 2000ms，部分耗时操作（如文件浏览、OTA 查询）可能超时。示例应用中可通过 setTimeoutMs() 调大；同时注意 MTU 越小，单包承载数据越少，大文件类命令耗时越长（默认 MTU 为 20，示例中配置为 509 以提升吞吐）。

5. Android 版本兼容边界

• 最低支持 Android 5.1（BLE 基本能力）。
• 示例 APK 已针对 Android 15 做兼容处理（见 apk/UpdateContent.txt）。
• Android 12+ 的蓝牙权限模型变更、Android 13+ 的通知权限等都可能影响示例 App 的某些功能展示，建议在目标真机上逐一验证。

6. 多设备并发的注意点

示例应用开启了 setUseMultiDevice(true)，可同时保持多个 RCSP 通讯通道。并发场景下需关注：命令超时计时、多设备消息回包的路由（按设备区分）、以及 cmdSnGenerator 命令序列号生成器的唯一性（当多个杰理 RCSP 库共存时用于统一命令序列号，避免序号冲突）。

调试与运维

日志定位

README.md 调试技巧章节 给出了两条排查路径：

• SDK 层：SDK 提供详细的日志输出，可通过 Android Studio 的 Logcat 查看蓝牙连接状态与数据交互，参考 SDK 调试说明。
• App 层：杰理之家 App 支持导出打印日志，使用说明见 杰理之家导出打印日志说明.pdf。向官方反馈问题时，附带导出的日志可显著加速定位。

版本对齐

• 示例 APK 版本 btsmart-V1.13.0-202601231637-113126-debug 对应 SDK 版本 4.2.0（RCSP 库 jl_bluetooth_rcsp_V4.2.0_40250-release.aar）。
• SDK 版本历史见 README.md 版本历史章节：4.2.0（2026/01/21）新增 LE Audio 与 RCSP 并存、AI 翻译、Auracast Broadcast、Gatt Over BR/EDR，并增加 Android 15 兼容；4.1.0 起支持 701N/707N 彩屏仓；4.0.0 分离了蓝牙实现与 RCSP 功能实现。
• 升级 SDK 时，建议同时更新核心 AAR 与示例 APK，避免协议版本不一致导致的兼容问题。

性能观察点

• 扫描功耗：bleScanMode 默认 SCAN_MODE_BALANCED，前台测试时可切到 SCAN_MODE_LOW_LATENCY 提升发现速度（功耗更高）；后台场景建议 SCAN_MODE_LOW_POWER。
• MTU 与吞吐：示例中 setMtu(509) 大幅提升单包数据量，对文件浏览、彩屏仓资源下发等大流量命令至关重要；BLE 默认 20 字节会明显拖慢传输。
• 重连策略：reconnect=true 时异常断开会自动回连，多设备场景下注意回连风暴与命令队列积压。

扩展点

示例应用本身即是最好的扩展参考，常见的二次开发路径：

1. 替换 AI 翻译服务商：修改 DoubaoTranslationMessage 和 DoubaoTTSMessage 中的账号信息即可切换为自有豆包火山大模型账号，或更换其他 AI 平台（apk/UpdateContent.txt）。
2. 自定义 UUID 对接定制固件：通过 setBleUUID(serviceUUID, writeCharacteristicUUID, notificationCharacteristicUUID) 与 setSppUUID(uuid) 适配非标准固件（README.md）。
3. 按产品形态裁剪功能：从 code/PiHome_V1.13.0_SDK_V4.2.0 源码中保留所需模块（音乐控制、ANC、闹钟、FM 等），去掉无关页面，替换为自己的品牌 UI。
4. 对接杰理开放平台：如需云服务能力（如 AI 翻译、消息推送），参考 杰理开放平台接入说明文档.pdf。
5. 命令序列号统一：多个杰理 RCSP 库共存时，通过 cmdSnGenerator 提供统一的命令序列号生成器，避免多库序号冲突。

相关链接

• README.md（中文） — 仓库总览、快速开始、配置说明、调试技巧
• README_en.md（英文） — 英文版说明
• apk/UpdateContent.txt — 测试 APK 版本与更新说明、AI 翻译测试限制
• apk/杰理之家导出打印日志说明.pdf — App 日志导出方法
• libs/ReadMe.txt — 核心库说明
• 杰理之家 SDK 在线文档中心 — SDK 开发文档（线上版）
• 杰理之家 APP 用户手册 V1.2 — 杰理之家 App 操作说明
• 问题反馈 — GitHub Issues