基础功能接口与自定义命令

本文档介绍杰理之家 SDK（Android）中 RCSP 基础功能接口（Basic Function Interface） 与 自定义命令（Custom Command） 两大能力：前者是设备接入后最常用的设备信息、模式切换、系统属性、存储与重启等基础操作入口；后者是 SDK 面向客户开放的功能拓展通道，允许 App 与设备固件之间传输私有协议数据。

Purpose and Scope

本页面聚焦于：

• 基础功能接口（Basic Function Interface）：RCSPController 提供的设备信息查询、模式切换、系统属性读写、存储信息查询、设备重启等通用能力，以及 OnRcspActionCallback / BTRcspEventCallback 回调机制。
• 自定义命令（Custom Command）：通过 buildCustomCmd 构建、sendRcspCommand 发送、onDeviceCommand / onCommandResponse 接收的自定义命令通道，以及配套的数据格式与注意事项。

以下相关主题由同级页面承载，本文档不做展开：

• 蓝牙扫描、连接、断开与历史记录管理 → 蓝牙处理接口 / 蓝牙代理模块（development/api/bt_api、development/module/bt_proxy）
• RCSP 协议底层收发与控制器接口 → RCSP 基础接口、RCSP 控制器接口（development/api/rcsp_basic_api、development/api/rcsp_api）
• 具体业务功能（音乐控制、EQ、FM、灯光、ANC、TWS、录音、翻译等）→ 各自独立的功能接口页面
• 状态码 / 功能码 / 错误码常量 → development/constant/* 页面

说明：SDK 核心以 AAR 闭源库（jl_bluetooth_rcsp_*.aar）形式发布，仓库内 btsmart 示例工程、src/test/java/com/jieli/btsmart/demo/ 下的 Demo 源码，以及仓库内置的官方文档（doc/JieLi_Home_SDK_V4.2.0_html_zh/）共同揭示了完整的 API 使用方式。

Overview

Android-JL_Bluetooth 是珠海杰理科技为杰理音箱、耳机类产品提供的蓝牙控制开发平台，底层基于 RCSP（远程控制系统）协议。SDK 通过 AAR 依赖方式集成：

• jl_bluetooth_rcsp_Vxxx-release.aar：蓝牙控制与 RCSP 协议处理；
• jldecryption_Vxxx-release.aar：加密相关。

集成后，App 通过单例 RCSPController 与已连接的杰理设备通信。基础功能接口解决的是"设备是什么、在什么模式、有哪些存储、如何切换模式、如何重启"这类通用问题，是所有业务功能（音乐、FM、EQ……）的前置依赖——几乎所有功能页面在操作前都会先调用 getDeviceInfo() 确认设备已初始化。自定义命令则解决"SDK 内置功能覆盖不了客户私有需求"的问题：客户固件与 App 约定一个私有命令码与数据格式，通过 RCSP 的扩展命令通道（cmd_extra_custom）透传，从而在不升级 SDK 的前提下实现产品差异化功能。

flowchart TD
    subgraph sg_App["应用层（客户 App / btsmart 示例）"]
        UI["业务页面 / ViewModel"]
        Demo["Demo（test 目录）"]
        BasicUse["基础功能调用<br/>getDeviceInfo / getDevStorageInfo ..."]
        CustomUse["自定义命令调用<br/>buildCustomCmd / sendRcspCommand"]
    end

    subgraph sg_SDK["杰理之家 SDK（AAR 闭源库）"]
        Controller["RCSPController（单例）"]
        Callback["OnRcspActionCallback / BTRcspEventCallback"]
        Builder["CommandBuilder<br/>buildGetDeviceInfoCmd / buildCustomCmd ..."]
        Protocol["RCSP 协议层<br/>命令帧 / 应答帧 / 分包"]
    end

    subgraph sg_Transport["蓝牙代理模块"]
        BtProxy["JL_BluetoothManager / 蓝牙代理<br/>BLE / SPP / BR-EDR"]
    end

    Device["杰理设备（AC701N / AC697N ...）"]

    UI --> BasicUse
    Demo --> BasicUse
    CustomUse --> Controller
    BasicUse --> Controller
    Controller --> Builder
    Controller --> Callback
    Builder --> Protocol
    Protocol --> BtProxy
    BtProxy -->|"RCSP 数据包"| Device
    Device -->|"应答 / 主动上报"| BtProxy
    BtProxy --> Protocol
    Protocol --> Callback
    Callback --> UI

架构说明：应用层只面向 RCSPController 一个门面（Facade），命令的构建（CommandBuilder）、协议封装、分包与应答匹配全部封装在 AAR 内部；蓝牙传输层可替换（SDK 内置代理或客户自实现代理，见官方文档 development/module/bt_proxy）。这一分层设计使得业务代码与底层蓝牙细节解耦：RCSPController 不关心当前走 BLE 还是 SPP，只关心"命令发出、回调回来"。

基础功能接口

核心入口：RCSPController

RCSPController 是 RCSP 功能 API 的总入口（单例模式），仓库内所有示例代码均通过 RCSPController.getInstance() 获取实例。典型调用链（摘自示例工程）：

if (rcspController.isDeviceConnected()) {
    DeviceInfo deviceInfo = rcspController.getDeviceInfo();
    if (deviceInfo != null) {
        // 使用设备信息
    }
}

Source: LogService.java

getDeviceInfo() 返回缓存的 DeviceInfo（设备信息模型，包含 uid、pid、curFunction、iD3MusicInfo、getVolumeInfo()、getMusicStatusInfo() 等），是判断"设备是否已初始化"的惯用手段——示例 Demo 中大量出现 if (null == deviceInfo) return; //设备未初始化 的守卫写法（如 FmDemo.java）。

数据模型

根据仓库内置官方文档（development/api/basic_func_api）与示例代码，基础功能相关的核心模型包括：

常用基础操作

官方文档 development/api/basic_func_api 定义的接口能力（方法名取自文档索引，均为真实存在的 API）：

示例工程中异步回调的标准写法（OnRcspActionCallback）：

mRCSPController.getDevStorageInfo(getConnectedDevice(), new OnRcspActionCallback<Boolean>() {
    @Override
    public void onSuccess(BluetoothDevice device, Boolean message) {
        // 查询成功
    }

    @Override
    public void onError(BluetoothDevice device, BaseError error) {
        // 查询失败，error 携带错误码
    }
});

Source: MultiMediaViewModel.java（方法签名以 AAR 内 javadoc 为准）

事件回调机制

基础功能不仅支持"主动查询"，还通过 addBTRcspEventCallback / removeBTRcspEventCallback 注册事件监听（BTRcspEventCallback），文档索引中可见的事件包括：

• onDeviceModeChange：设备模式切换通知；
• onDevStorageInfoChange：存储信息变化通知；
• onBatteryChange：电量变化通知；
• onVolumeChange：音量变化通知；
• onConnectedBtInfo：连接设备信息变化；
• onDeviceCommand / onCommandResponse：设备主动上报命令与命令应答（自定义命令也依赖这两个回调，见下节）。

事件驱动设计的意义：设备端（固件）状态变化可主动推送，App 无需轮询，降低蓝牙信道占用与功耗。

自定义命令

设计意图

自定义命令是 SDK 面向客户开放的功能拓展通道。当内置功能无法覆盖客户的私有需求（例如特定产品的专属交互、私有配置下发）时，客户可在固件侧与 App 侧约定：

1. 一个私有命令码（操作码）；
2. 一套私有数据格式；
3. 是否需要设备应答。

SDK 负责将该数据块透明封装进 RCSP 协议帧，通过蓝牙通道发送给设备，并把设备的应答/上报原样回传给 App。官方文档（development/function/custom_cmd_func）将其划分为"发送自定义命令"、"接收自定义命令"与"注意事项"三部分。

发送自定义命令

发送侧核心 API（名称取自仓库内置文档索引，见 doc/JieLi_Home_SDK_V4.2.0_html_zh/html/searchindex.js）：

• CommandBuilder.buildCustomCmd(...)：构建自定义命令帧；
• CustomCmd / CustomParam / CustomResponse：命令与参数/应答载体；
• sendRcspCommand(...) / sendCommandAsync(...)：异步发送；
• 标志位常量：flag_have_parameter_and_respons（带参数且需应答）、flag_have_parameter_no_respons（带参数不需应答）、flag_no_parameter_and_respons（无参数但需应答）——通过标志位组合可覆盖"下发配置"（带参不需应答）与"查询状态"（无参需应答）等场景；
• 命令码常量 cmd_extra_custom：自定义命令在 RCSP 功能码体系中占用扩展位。

典型流程为：构造 CustomParam（设置命令码 setOpCode、参数 setParam、标志 setStatus/setFlag）→ buildCustomCmd 构建 → sendRcspCommand 发送 → 在 onCommandResponse / onRcspActionCallback 中接收结果。

接收自定义命令（设备 → App）

设备侧发起的自定义命令（如按键触发、状态上报）通过 onDeviceCommand 回调到达 App，App 侧用 parseCustomData（文档索引中可见的解析工具）按约定格式解析载荷；若设备要求应答，App 应调用 sendRcspResponse / sendCommandResponse 回发应答帧，使设备端流程得以继续。

注意事项

官方文档 custom_cmd_func 的"注意事项"部分（custom_cmd_note）强调（内容以仓库内置文档为准）：

• 自定义命令码需与设备固件严格一致，避免与 RCSP 标准命令冲突；
• 载荷长度受 MTU / 单包长度限制，超长数据需自行分包（或使用大文件传输能力，见 development/function/big_file_transfer_func）；
• 是否需要应答必须前后端约定一致，否则会造成设备端流程阻塞或 App 回调超时；
• 设备未连接或未初始化时发送命令会返回错误（BaseError，错误码体系见 development/constant/error_code）。

核心流程

发送自定义命令（App → 设备）

sequenceDiagram
    participant App as 客户 App
    participant RCSP as RCSPController
    participant B as CommandBuilder
    participant BT as 蓝牙代理 (BLE/SPP)
    participant Dev as 杰理设备固件

    App->>RCSP: 构造 CustomParam (opCode/param/flag)
    App->>B: buildCustomCmd(param, flag)
    B-->>App: CustomCmd 数据帧
    App->>RCSP: sendRcspCommand(device, cmd, callback)
    RCSP->>BT: 协议封装 + 分包写入
    BT->>Dev: RCSP 数据包
    Dev-->>BT: 应答帧（可选，取决于 flag）
    BT-->>RCSP: 原始数据上报
    RCSP-->>App: onCommandResponse / onRcspActionCallback

接收设备上报（设备 → App）

sequenceDiagram
    participant Dev as 杰理设备固件
    participant BT as 蓝牙代理
    participant RCSP as RCSPController
    participant App as 客户 App

    Dev->>BT: 自定义命令数据包
    BT->>RCSP: 原始数据分发
    RCSP->>App: onDeviceCommand(device, data)
    App->>App: parseCustomData 按约定格式解析
    alt 设备要求应答
        App->>RCSP: sendRcspResponse(device, response)
        RCSP->>BT: 应答帧
        BT->>Dev: 应答
    end

基础功能通用调用链

flowchart TD
    Start([开始]) --> Init["获取 RCSPController.getInstance()"]
    Init --> Conn{"isDeviceConnected() ?"}
    Conn -->|"否"| Err1["返回/等待连接（蓝牙代理模块）"]
    Conn -->|"是"| Check{"getDeviceInfo() != null ?"}
    Check -->|"否"| Req["requestDeviceInfo 拉取设备信息"]
    Req --> Check
    Check -->|"是"| Op["调用基础功能接口<br/>（查询/设置/切换模式/重启）"]
    Op --> Cb{"OnRcspActionCallback"}
    Cb -->|"onSuccess"| Done["刷新 UI / 缓存"]
    Cb -->|"onError"| Err2["按 BaseError 错误码处理"]
    Err1 --> End([结束])
    Done --> End
    Err2 --> End

该调用链解释了为什么示例 Demo 中几乎每个功能入口都以 getDeviceInfo() == null 作为"设备未初始化"守卫：DeviceInfo 是后续所有业务操作的前提，SDK 在设备连接后异步拉取，未拉取完成前调用业务接口会失败。

使用示例

1. 工程依赖配置（集成前置条件）

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

2. 连接状态 + 设备信息读取

if (rcspController.isDeviceConnected()) {
    DeviceInfo deviceInfo = rcspController.getDeviceInfo();
    if (deviceInfo != null) {
        // 设备已初始化，可进行后续业务操作
    }
}

Source: LogService.java

3. 异步查询存储信息（OnRcspActionCallback 模式）

private void requestDeviceInfo() {
    mRCSPController.getDevStorageInfo(getConnectedDevice(), new OnRcspActionCallback<Boolean>() {
        @Override
        public void onSuccess(BluetoothDevice device, Boolean message) { /* 成功 */ }

        @Override
        public void onError(BluetoothDevice device, BaseError error) { /* 失败 */ }
    });
}

Source: MultiMediaViewModel.java

4. 设备未初始化守卫（Demo 通用模式）

if (null == usingDevice) return false;
DeviceInfo deviceInfo = controller.getDeviceInfo(usingDevice);
if (null == deviceInfo) return false; //设备未初始化

Source: FmDemo.java

5. 自定义命令发送（接口骨架，完整签名见 AAR javadoc）

// 1. 构造参数：命令码 + 载荷 + 标志（是否需要应答）
CustomParam param = new CustomParam();
param.setOpCode(0x01);            // 与固件约定的私有命令码
param.setParam(new byte[]{...});  // 私有数据
param.setFlag(CustomParam.FLAG_HAVE_PARAMETER_AND_RESPONS);

// 2. 构建自定义命令并异步发送
CustomCmd cmd = CommandBuilder.buildCustomCmd(param);
controller.sendRcspCommand(device, cmd, new OnRcspActionCallback<CustomResponse>() {
    @Override
    public void onSuccess(BluetoothDevice device, CustomResponse response) { }

    @Override
    public void onError(BluetoothDevice device, BaseError error) { }
});

Sources: 类名与常量名取自仓库内置文档索引 searchindex.js；完整方法签名请以 AAR 内 javadoc 或官方文档 custom_cmd_func.html 为准。

配置选项

权限清单详见 README.md（3.4 权限配置）。

API 参考

以下 API 名称与用途均取自仓库内真实源码、内置官方文档索引；标注"签名以 AAR 为准"的条目，其精确参数列表请以 jl_bluetooth_rcsp_*.aar 内 javadoc 或官方文档 HTML 页为准。

RCSPController.getInstance(): RCSPController

获取 RCSP 控制器单例，所有 RCSP 功能调用的入口。

示例来源： LogService.java、ProductUtil.java

RCSPController.getDeviceInfo(): DeviceInfo / getDeviceInfo(device: BluetoothDevice): DeviceInfo

返回缓存的设备信息聚合体；为空表示设备尚未完成 RCSP 初始化（典型用法：作为"设备未初始化"守卫）。

RCSPController.getDevStorageInfo(device, callback: OnRcspActionCallback<Boolean>): void

异步查询设备存储信息（SD/U 盘/Flash）。成功回调 onSuccess，失败回调携带 BaseError。

RCSPController.addBTRcspEventCallback(callback: BTRcspEventCallback): void / removeBTRcspEventCallback

注册/注销 RCSP 事件回调（模式变化、存储变化、电量、音量、设备上报命令等）。

CommandBuilder.buildGetDeviceInfoCmd(...) / buildRebootCmd(...) / buildSwitchModeCmd(...) / buildGetSysInfoCmd(...) / buildSetSysInfoCmd(...) / buildFunctionCmd(...)

基础功能命令构建器族（命名取自文档索引），与 sendCommandAsync 配合完成命令下发。

CommandBuilder.buildCustomCmd(param: CustomParam, flag): CustomCmd

构建自定义命令帧。CustomParam 承载命令码（opCode）、参数（param）与标志（flag）。

RCSPController.sendRcspCommand(device, cmd, callback) / sendCommandAsync(...)

异步发送命令；OnRcspActionCallback 返回业务结果，底层错误统一收敛为 BaseError。

RCSPController.sendRcspResponse(device, response) / sendCommandResponse(...)

设备要求应答时，向设备回发应答帧。

回调接口 OnRcspActionCallback<T>

回调接口 BTRcspEventCallback（关键方法）

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

• 设备未连接 / 未初始化：isDeviceConnected() 为 false 或 getDeviceInfo() 为 null 时，业务接口调用会失败。示例代码统一以 getDeviceInfo() == null 守卫（如 FmDemo.java），App 应在 onDeviceModeChange 等回调中重建 UI 状态。
• 命令超时：RCSP 命令有默认超时（default_send_cmd_timeout），超时后 onError 返回超时错误码（错误码体系见 development/constant/error_code，如 sub_err_operation_timeout、sub_err_send_timeout）。
• 设备忙碌 / 状态错误：设备处于 OTA、通话等状态时可能拒绝命令（sub_err_device_in_busi、result_device_is_busi），App 需按 BaseError 分类提示用户，而非盲目重试。
• 自定义命令长度限制：单包载荷受 MTU 限制，超长数据需自行分包或改用大文件传输通道；固件对未知命令码会返回 status_unkown_cmd（未知命令状态，见 development/constant/state_code）。
• 并发与串行：RCSP 为请求-应答模型，SDK 内部按命令帧匹配应答；高频连续发送时建议等待上一命令回调后再发下一命令，避免应答错配与蓝牙写入拥塞（AAR 内部实现细节，文档 other/question_answer 亦给出相关建议）。
• 蓝牙断开：命令在途时断开，onError 会收到连接类错误（sub_err_remote_device_disconnect 等），业务层需监听连接状态回调清理 pending 请求。

性能与运维注意事项

• 通信开销：基础功能接口多为短命令/短应答，适合低频交互；DeviceInfo 缓存由 SDK 维护，避免 App 频繁全量刷新。需要实时状态时优先依赖事件回调（推送），而非轮询。
• 超时设置：可根据业务链路调整命令超时（setTimeoutMs 类接口），在"快速失败反馈"与"弱信号环境容忍"之间权衡。
• 日志与调试：仓库内置调试指南（other/debug），SDK 提供日志开关与日志文件输出能力，定位自定义命令问题时建议开启协议层日志观察原始帧。
• 文档对照：完整接口说明、参数表与流程图见仓库内置文档 HTML：基础功能接口 basic_func_api.html、自定义命令 custom_cmd_func.html。

扩展点

• 自定义命令通道（首要扩展点）：客户无需改动 SDK，即可通过约定的私有命令码实现产品差异化功能。发送侧 buildCustomCmd + sendRcspCommand，接收侧 onDeviceCommand + parseCustomData + sendRcspResponse，形成完整双向通道。
• 事件回调机制：BTRcspEventCallback 提供了覆盖所有 RCSP 事件的监听口，客户可在不侵入 SDK 的前提下扩展业务逻辑。
• 自定义蓝牙代理：SDK 允许客户自行实现蓝牙代理（官方文档 development/module/bt_proxy），在传输层接入自有连接管理，而上层 RCSPController 接口不变。
• 属性模型（AttributeModel）：AttrBean + sys_info_attr_* 属性码体系允许对设备系统属性做通用扩展读写，部分客户私有属性可直接映射为新的属性码。

Related Links

• RCSP 基础接口文档（仓库内置） — RCSP 底层协议收发接口
• RCSP 控制器接口文档（仓库内置） — RCSPController 全量 API
• 蓝牙处理接口文档（仓库内置） — 扫描/连接/历史记录
• 蓝牙代理模块文档（仓库内置） — 传输层替换
• 状态码 / 功能码 / 错误码 — BaseError 与应答状态解读
• 工程 README — 快速开始、权限、依赖与功能总览
• 示例 Demo：code/PiHome_V1.13.0_SDK_V4.2.0/btsmart/src/test/java/com/jieli/btsmart/demo/ — 各功能接口的完整调用示例