SDK分层架构与RCSP协议

杰理健康 SDK（Android-JL_Health）是基于 RCSP 协议（远程控制系统协议） 构建的蓝牙穿戴设备开发平台。本文档深入解析 SDK 的分层架构设计——从应用层、SDK 服务层、RCSP 协议层到蓝牙连接层与设备层——并说明各层之间的数据流、命令封装与回传机制。

Purpose and Scope

本页面向需要理解 SDK 内部机理的工程师，覆盖以下内容：

• SDK 整体的分层架构：各 AAR 依赖库的职责与依赖关系；
• RCSP 协议在 SDK 中的角色：命令封装、数据透传与设备通信机制；
• 各功能模块（健康数据、OTA、表盘、音乐等）与协议层、连接层的关系；
• SDK 初始化、连接设备、下发命令、接收回传数据的端到端流程；
• 运行环境、依赖配置与扩展方式。

以下主题属于兄弟页面范畴，本文档只做指引、不展开细节：

• 具体功能模块的 API 用法（如健康数据采集、表盘管理、OTA 升级），请参阅对应的功能文档页；
• 杰理健康服务器相关接口（jl_health_http），请参阅服务端集成文档；
• 蓝牙连接细节（扫描、配对、连接参数），请参阅蓝牙连接文档。

重要说明（资料来源）：jl_rcsp、JL_Watch 等核心库以 AAR 二进制形式发布（见 README.md），仓库内不包含其 Java 源码。因此本文档中关于协议内部实现的描述基于 README 与公开工程结构；凡未能在仓库源码中验证的细节均明确标注，不做臆测。

概述

Android-JL_Health 是珠海市杰理科技股份有限公司为蓝牙穿戴类产品（智能手表、健康手环、智能徽章、智能戒指等）提供的健康数据与设备管理开发平台。SDK 以 RCSP 协议为通信基石，为上层应用屏蔽了 BLE 连接的复杂性，提供统一的设备控制与数据同步接口。

SDK 的能力矩阵（摘自 README.md）：

这些功能表面上各自独立，但全部复用同一套分层通信架构：上层功能模块把业务请求转化为 RCSP 命令，由协议层统一封装，再经蓝牙连接层下发到设备；设备回传的数据再沿同一条链路反向还原为业务回调。这正是"分层架构 + 统一协议"设计的核心价值——新增功能模块时无需重新实现通信链路。

架构

SDK 整体采用五层架构，从上到下依次为：应用层 → SDK 服务层 → RCSP 协议层 → 蓝牙连接层 → 设备层。

flowchart TD
    subgraph sg_App["应用层"]
        App["Android 应用<br/>(Java/Kotlin)"]
    end

    subgraph sg_Sdk["SDK 服务层"]
        Watch["JL_Watch 核心库<br/>健康/表盘/闹钟/音乐等"]
        Ota["jl_bt_ota<br/>OTA升级"]
        HealthHttp["jl_health_http<br/>健康服务器"]
        Convert["BmpConvert / GifConvert<br/>图像转换"]
        Audio["jl_audio_decode<br/>Opus/Speex解码"]
    end

    subgraph sg_Protocol["协议层"]
        Rcsp["jl_rcsp<br/>RCSP基础协议"]
    end

    subgraph sg_Connect["连接层"]
        Ble["jl_bluetooth_connect<br/>蓝牙连接"]
    end

    subgraph sg_Device["设备层"]
        Device["穿戴设备<br/>(AC701N/AC707N/AC695N)"]
    end

    App --> Watch
    App --> Ota
    App --> HealthHttp
    App --> Convert
    App --> Audio
    Watch --> Rcsp
    Ota --> Rcsp
    Rcsp --> Ble
    Ble --> Device

各层职责

应用层：开发者集成 SDK 的入口。通过 JL_Watch 核心库暴露的 API 调用设备能力，不直接接触 BLE 或协议细节。SDK 同时支持 Java 与 Kotlin（见 README.md）。

SDK 服务层：按业务域拆分为多个 AAR 模块，这是"分层"的关键体现——每个模块只负责一类业务：

• JL_Watch_Vxxx-release.aar：SDK 核心库，提供穿戴设备主要功能（健康、表盘、消息、闹钟、音乐等）；
• jl_bt_ota_Vxxx-release.aar：OTA 升级（固件空中升级、4G 模块 OTA、差分升级）；
• jl_health_http_Vxxx-release.aar：杰理健康服务器通信，处理云端数据；
• BmpConvert_Vxxx-release.aar / GifConvert_Vxxx-release.aar：表盘、图片素材的格式转换；
• jl_audio_decode_Vxxx-release.aar：Opus/Speex 音频解码，用于语音消息等场景。

协议层（jl_rcsp）：RCSP（远程控制系统协议）基础实现，是整条链路的"翻译官"。它负责将上层业务请求编码为协议命令、解析设备回传的协议包。所有需要与设备交互的功能模块都汇聚到这一层，避免各模块各自实现一套通信格式。

连接层（jl_bluetooth_connect）：封装 BLE 的扫描、连接、收发与断线重连，向上提供透明的数据通道。协议层与连接层分离的设计意图：即使底层从 BLE 更换为其他传输方式（如 4G），协议层与上层业务无需改动。

设备层：支持 RCSP 功能的杰理穿戴芯片平台，如 AC701N、AC707N、AC695N 等（见 README.md）。设备固件侧同样实现了 RCSP 协议栈，与 SDK 侧形成对称的命令/响应语义。

RCSP 协议机制

什么是 RCSP 协议

RCSP（Remote Control System Protocol，远程控制系统协议）是杰理为穿戴类设备设计的应用层控制协议，运行在 BLE 数据通道之上。它定义了"命令—响应"的通信语义：手机端（SDK）作为主机下发控制命令，设备作为从机执行并回传结果；同时设备也可主动上报数据（如心率、血氧、步数等健康数据），SDK 侧通过监听机制接收。

RCSP 协议的设计目标可以概括为三点：

1. 统一通信语言：所有业务功能（健康、表盘、OTA、音乐……）共用同一套协议格式，上层模块只需要关心业务字段，不需要关心底层字节流；
2. 可扩展性：协议支持命令扩展（SDK 暴露"自定义命令"能力，支持客户拓展功能，见 README.md），新业务可以通过新增命令号接入，而不破坏既有协议结构；
3. 传输无关性：协议层与蓝牙连接层解耦，同一套 RCSP 命令既可以通过 BLE 下发，也为后续 4G 等传输通道留出空间（README 中"4G模块OTA"即体现了这一点）。

命令的封装与流转

一次典型的功能调用在协议层经历以下阶段：

1. 命令构造：上层模块（如健康数据）把业务参数填充为 RCSP 命令结构（命令号 + 参数区）；
2. 协议编码：jl_rcsp 将命令结构序列化为协议包，交给连接层；
3. 通道发送：jl_bluetooth_connect 通过 BLE 特征值写入下发；
4. 设备响应：设备解析并执行，将结果打包回传；
5. 协议解码：jl_rcsp 还原协议包为业务数据；
6. 回调上抛：核心库把结果回调给应用层。

诚实说明：上述阶段为基于分层结构的合理归纳；jl_rcsp 的具体帧格式、命令号分配表与编解码实现位于 AAR 二进制中，仓库内没有源码可供逐行引用。需要精确的协议字段定义时，请以杰理文档中心（doc.zh-jieli.com）的协议文档为准。

数据方向与通道复用

RCSP 在 SDK 中承担双向数据流：

• 下行（手机 → 设备）：控制类命令——闹钟增删改查、表盘插入删除、消息推送、天气同步、音乐播放控制等；
• 上行（设备 → 手机）：数据类上报——健康监测数据（心率/血氧/血压/体温/睡眠）、运动数据（步数/卡路里）、设备查找回执等。

无论上行还是下行，都复用同一条"协议层 → 连接层 → BLE 通道"的链路。这种设计避免了每个功能模块各自维护连接状态，也让断线重连、数据分包等横切关注点集中在连接层统一处理。

功能模块与协议的对应关系

表中每个功能域都对应 jl_rcsp 中一组命令族；JL_Watch 核心库把这些命令族封装成高层的 Java/Kotlin 方法，应用层无需感知协议细节。

核心流程

设备连接与命令下发流程

下面以"应用获取设备健康数据"为例，展示一条完整的端到端调用链。这是 SDK 分层架构最典型的运行路径：应用只与核心库打交道，核心库负责协议封装，协议层负责编解码，连接层负责 BLE 传输。

sequenceDiagram
    participant App as 应用层
    participant SDK as JL_Watch 核心库
    participant RCSP as jl_rcsp 协议层
    participant BLE as jl_bluetooth_connect
    participant Dev as 穿戴设备

    App->>SDK: 初始化SDK / 连接设备
    SDK->>BLE: 建立蓝牙连接
    BLE-->>SDK: 连接成功回调
    App->>SDK: 调用功能接口(如获取心率)
    SDK->>RCSP: 构造RCSP命令(命令号+参数)
    RCSP->>RCSP: 协议编码/分包
    RCSP->>BLE: 下发协议包
    BLE->>Dev: BLE特征值写入
    Dev->>Dev: 固件解析并执行命令
    Dev-->>BLE: 回传数据包(主动上报/响应)
    BLE-->>RCSP: 原始数据上抛
    RCSP->>RCSP: 协议解码/组包
    RCSP-->>SDK: 还原为业务数据
    SDK-->>App: 回调结果给应用

流程要点：

1. 初始化阶段：应用先集成各 AAR 依赖并完成 SDK 初始化；JL_Watch 核心库依赖 jl_rcsp 与 jl_bluetooth_connect（见架构图依赖关系）；
2. 连接阶段：jl_bluetooth_connect 负责 BLE 扫描与连接，连接成功后 SDK 才能下发命令；
3. 下行阶段：业务请求在协议层被编码为 RCSP 命令包，经 BLE 写入设备；大文件场景（OTA、音乐传输）会涉及分片/组包，这是协议层内部逻辑，对上层透明；
4. 上行阶段：设备响应或主动上报的数据沿同一条链路反向流转，协议层完成解码后由核心库回调给应用。

SDK 集成的宏观流程

flowchart TD
    Start([开始]) --> Dep["导入AAR依赖库"]
    Dep --> Init["初始化SDK"]
    Init --> Connect["连接设备"]
    Connect --> Ok{"连接成功?"}
    Ok -->|"否"| Retry["重试/等待回调"]
    Retry --> Connect
    Ok -->|"是"| Biz["调用业务功能"]
    Biz --> BizType{"功能类型?"}
    BizType -->|"OTA"| OtaFlow["OTA升级"]
    BizType -->|"健康"| HealthFlow["健康数据同步"]
    BizType -->|"表盘"| WatchFlow["表盘管理"]
    BizType -->|"自定义"| CustomFlow["自定义命令"]
    OtaFlow --> RcspFlow["RCSP协议封装"]
    HealthFlow --> RcspFlow
    WatchFlow --> RcspFlow
    CustomFlow --> RcspFlow
    RcspFlow --> BleFlow["BLE通道下发"]
    BleFlow --> Callback["接收设备回传/回调"]
    Callback --> End([结束])

该流程图反映了仓库快速开始文档描述的使用路径（见 README.md）：克隆工程 → 导入 Android Studio → 添加 AAR 依赖 → 调用 SDK API。无论调用哪个业务功能，最终都会汇聚到 RCSP 协议封装与 BLE 下发这一公共路径——这正是分层架构带来的复用效果。

使用示例

示例一：克隆工程

SDK 仓库以工程形式发布，包含示例应用与 libs/ 目录（AAR 依赖库）：

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

Source: README.md

示例二：添加 AAR 依赖

这是 SDK 分层架构在工程集成层面的直接体现——应用通过引入多个职责单一的 AAR 模块，组合出完整的设备控制能力：

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

Source: README.md

各 AAR 与分层架构的对应关系如下（摘自 README.md）：

说明：xxx 为版本号。业务代码示例（如 SDK 初始化、健康数据回调等）位于示例应用工程中，本文档仓库源码探索范围内未读取到相关文件，故不在此编造示例代码。

配置选项

运行环境要求

SDK 对运行环境的要求体现了其技术栈边界（见 README.md）：

工程集成配置

环境要求中"支持 RCSP 功能的 SDK（AC701N、AC707N、AC695N 等）"明确了协议层与设备平台的绑定关系：SDK 侧与设备固件侧必须同时实现 RCSP 协议栈，通信才能成立。

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

以下分析基于分层架构的工程常识与 README 中可验证的信息；涉及 jl_rcsp / jl_bluetooth_connect 内部实现的部分，因源码位于 AAR 二进制中，标注为"未在仓库源码中验证"。

连接失败与断线

• 连接失败：jl_bluetooth_connect 层负责 BLE 扫描与连接，连接失败时 SDK 不会进入业务命令下发阶段。集成方应监听连接状态回调并触发重试（见核心流程图中"重试/等待回调"分支）。
• 断线重连：协议层与连接层解耦的设计使断线重连成为连接层内部职责，上层业务无需感知链路中断细节——这是分层架构在可靠性方面的主要收益。

大文件传输与分包

• OTA 升级、音乐文件传输等场景涉及大流量数据（README 中"文件传输：大文件传输（如音乐文件）"）。
• 分包/组包逻辑位于协议层内部：下行时分片发送、上行时重组。这部分实现未在仓库源码中验证，集成大文件功能时应关注进度回调与中断续传能力。

并发与多命令交错

• 多个功能模块（健康、闹钟、音乐……）可能同时下发命令，全部汇聚到 jl_rcsp 协议层。协议层需要保证命令-响应的配对与有序性，避免响应错乱；这属于协议层内部机制，未在仓库源码中验证。
• 对集成方的启示：健康数据等多路上报回调通常以监听器形式分发，应用层应按功能域注册独立回调，避免回调串扰。

版本配套

• 各 AAR 存在版本配套要求（Vxxx 版本号）。混用不配套版本可能导致协议字段不匹配、设备无法识别命令等隐性故障；升级 SDK 时应整体替换 libs/ 下的 AAR 集合。

性能与运维考量

• 链路收敛：所有业务共用一条协议/连接链路，减少了重复的连接资源开销，但也意味着协议层与连接层是性能与稳定性热点——大文件传输会占用通道，可能影响并发的小命令（如闹钟设置）时效。
• 资源约束：BLE 通道带宽有限，健康数据上报、OTA 分片等高频传输应遵循 SDK 建议的传输节奏，避免通道拥塞。
• 日志与调试：README 提供"调试技巧"章节（见目录 README.md），建议结合协议层日志定位命令收发问题。

扩展点

自定义命令

SDK 明确支持自定义命令——"支持客户拓展功能"（见 README.md）。这是 RCSP 协议可扩展性的直接体现：

• 客户可以在既有 RCSP 协议框架下定义私有命令号与参数区；
• 自定义命令沿同一分层链路（核心库 → jl_rcsp → jl_bluetooth_connect → 设备）透传，无需改动协议层与连接层；
• 适合接入 SDK 未内置的差异化产品功能。

图像与音频转换能力

BmpConvert / GifConvert / jl_audio_decode 作为独立 AAR 提供，可按需取舍：仅做表盘业务时可只引入图像转换库，不引入音频解码库，降低应用体积。

测试

仓库以示例应用（code/ 目录）形式提供集成验证手段：开发者可打开对应示例项目，在真实设备（AC701N 等支持 RCSP 的硬件）上验证功能链路。仓库内未发现独立的单元测试工程；协议层与连接层的自动化测试覆盖情况因 AAR 二进制分发而无法从源码确认。集成测试建议覆盖：连接建立 → 命令下发 → 数据回传的完整链路，以及断线重连、OTA 中断恢复等异常路径。

相关链接

• README.md — 工程总览、功能矩阵、快速开始与版本历史
• README_en.md — 英文版说明
• 杰理文档中心：https://doc.zh-jieli.com/Apps/Android/health/zh-cn/master/index.html — SDK 完整 API 文档（含 RCSP 协议细节）
• 仓库主页：https://github.com/Jieli-Tech/Android-JL_Health（issue 报告入口）