项目简介与核心能力

杰理健康SDK（Android-JL_Health） 是珠海市杰理科技股份有限公司为蓝牙穿戴类产品提供的健康数据与设备管理开发平台，基于 RCSP 协议（远程控制系统协议）为智能手表、健康手环等穿戴设备提供从蓝牙连接、健康数据同步到 OTA 升级、表盘管理、支付激活等完整的一站式开发能力，并配套「宜动健康」与「手表测试工具」两个开源示例应用。

Purpose and Scope

本文档是项目总览页，用于帮助读者快速建立对 Android-JL_Health 仓库的整体认知，包括：

• 项目的定位、适用场景与目标硬件平台
• SDK 提供的十六大核心能力及其背后的 AAR 库体系
• 仓库的工程结构（apk/、code/、doc/、libs/）与角色划分
• SDK 接入的核心步骤（依赖引入、权限配置、初始化、数据透传）
• 运行环境、版本演进与许可证信息

本文档聚焦"项目是什么、能做什么、怎么组织"，属于 1-overview 目录下的总览页面。具体到某项能力的实现细节（如 OTA 升级的差分升级流程、表盘文件操作协议、健康数据的命令格式等），请在各自的能力专题页面中查阅；README.md 中引用的在线文档中心（杰理健康SDK开发文档）提供了按模块展开的详细说明。

Overview

Android-JL_Health 不是单一功能的示例工程，而是一个完整的穿戴设备开发平台。它采用"核心 AAR 库 + 开源示例应用"的架构：业务能力全部封装在 libs/ 目录下的闭源 AAR 库中（核心库为 JL_Watch，基础协议为 jl_rcsp，连接层为 jl_bluetooth_connect），而 code/ 目录则提供「宜动健康」和「手表测试工具」两个开源参考实现，展示如何正确调用 SDK。

适用场景

来源：README.md

核心设计思想

1. 协议驱动：所有设备能力基于 RCSP（远程控制系统协议）封装，SDK 内部将业务命令编码为协议数据包，应用层只需面向 Java 接口编程，无需关心协议细节。
2. 单向依赖的分层架构：应用层 → SDK 核心库 → 基础协议库 → 蓝牙连接库 → 设备，数据回传则通过回调/通知反向流动。
3. "设备代理"模式：SDK 操作都基于"当前连接设备"（getConnectedDevice()），应用负责蓝牙连接的建立与数据收发，SDK 负责协议解析与业务逻辑。
4. 示例驱动：code/app（宜动健康）展示完整功能调用，code/tool（手表测试工具）面向功能验证与调试，二者互补。

Architecture

总体架构

flowchart TD
    subgraph sg_App["应用层 (Android App)"]
        App_YD["宜动健康<br/>com.jieli.healthaide"]
        App_Tool["手表测试工具<br/>com.jieli.watchtesttool"]
    end

    subgraph sg_SDK["杰理健康SDK 核心库 (libs/)"]
        JL_Watch["JL_Watch<br/>健康SDK核心库"]
        RCSP["jl_rcsp<br/>RCSP基础协议"]
        BT_Connect["jl_bluetooth_connect<br/>蓝牙连接库"]
        OTA["jl_bt_ota<br/>OTA升级库"]
        Health_HTTP["jl_health_http<br/>健康服务器库"]
        WatchImpl["WatchOpImpl<br/>业务抽象基类"]
    end

    subgraph sg_Aux["辅助能力库"]
        Bmp["BmpConvert<br/>BMP/JPEG/PNG转换"]
        Gif["GifConvert<br/>GIF转换"]
        Audio["jl_audio_decode<br/>Opus/Speex解码"]
        Ali["ALi<br/>支付宝激活"]
        Decrypt["jldecryption<br/>加密解密"]
    end

    subgraph sg_Device["硬件设备层"]
        Dev_Watch["智能手表<br/>AC701N/AC707N/AC695N"]
        Dev_Band["健康手环等穿戴设备"]
    end

    App_YD --> JL_Watch
    App_Tool --> JL_Watch
    App_YD --> OTA
    App_Tool --> OTA
    JL_Watch --> WatchImpl
    JL_Watch --> RCSP
    RCSP --> BT_Connect
    JL_Watch --> Health_HTTP
    JL_Watch --> Bmp
    JL_Watch --> Gif
    JL_Watch --> Audio
    JL_Watch --> Ali
    JL_Watch --> Decrypt
    BT_Connect <-->|"BLE/SPP 透传"| Dev_Watch
    BT_Connect <-->|"BLE/SPP 透传"| Dev_Band

架构说明：

• 应用层：两个开源示例（宜动健康、手表测试工具）通过继承 WatchOpImpl 实现业务类（如 WatchManager），将蓝牙设备状态与接收数据"喂"给 SDK，同时重写 sendDataToDevice() 把 SDK 产出的数据包发回设备。这一层是客户二次开发的模板。
• SDK 核心层：JL_Watch 是功能总入口，依赖 jl_rcsp（协议编解码）、jl_bluetooth_connect（连接抽象）、jl_bt_ota（升级）、jl_health_http（云端服务）。
• 辅助库层：图像/音频/支付/加密等横向能力，按功能按需引入，降低主包体积。
• 设备层：支持 RCSP 功能的杰理芯片方案（AC701N、AC707N、AC695N 等），通信方式为 BLE（可切换 SPP）。

数据流（SDK 与应用的透传协作）

sequenceDiagram
    participant App as 应用 (WatchManager)
    participant SDK as JL_Watch SDK
    participant BT as 蓝牙连接库
    participant Dev as 穿戴设备

    App->>SDK: 创建 WatchManager(FUNC_WATCH)
    App->>BT: 扫描并连接设备 (BLE/SPP)
    BT-->>App: 连接状态回调
    App->>SDK: notifyBtDeviceConnection(device, CONNECTION_OK)
    SDK->>App: sendDataToDevice(device, data)
    App->>BT: 发送数据到设备
    BT-->>Dev: 透传数据包
    Dev-->>BT: 设备回复数据
    BT-->>App: 数据接收回调
    App->>SDK: notifyReceiveDeviceData(device, data)
    SDK-->>App: 解析为业务结果 (健康数据/命令应答)

设计意图：SDK 不直接持有蓝牙连接，而是通过 notifyBtDeviceConnection / notifyReceiveDeviceData 两个"输入口"和 sendDataToDevice 一个"输出口"与应用解耦。这样无论客户使用 BLE、SPP 还是私有连接方案，SDK 的业务逻辑都无需改动——连接层差异被完全隔离在应用侧。

核心能力详解

SDK 通过 JL_Watch 核心库暴露了完整的穿戴设备功能矩阵，涵盖设备管理、健康监测、数据同步与增值服务四大类：

来源：README.md

能力要点分析

• OTA 升级是平台级能力，支持固件空中升级、4G 模块 OTA（由 UpgradeViewModel 演示）与差分升级；版本 1.7.0 起兼容单备份 OTA 流程，1.13.0 增加 4G 模块 OTA 支持。
• 健康数据涵盖心率、血氧、血压、体温、睡眠等主流监测项，1.10.0 起支持连续心率测量并修复了下限值无效问题，1.8.0 修复了跌倒提醒中紧急联系人数据异常。
• 文件传输属于大文件通道（如音乐），1.9.0 增加取消传输接口，1.14.0 修复了大文件传输偶现失败问题——此类传输对 MTU 分包与队列式发数非常敏感。
• 表盘管理自 1.6.5 起提供表盘文件浏览/插入/删除/自定义背景，1.12.0 增加表盘拓展参数，1.13.0 完善 AI 表盘功能。
• 自定义命令是面向客户的扩展点，配合 CustomCommandDemo 示例实现私有协议指令，是 SDK 开放性的体现。

运行环境

来源：README.md

三个要点值得注意：

1. Android 5.1（API 22）起是基线，但这只是操作系统门槛；真正的硬件门槛是设备端芯片支持 RCSP 功能，SDK 无法脱离协议工作。
2. 官方在多个版本中持续做系统兼容：1.7.5 增加 Android 12 兼容、1.9.0 兼容 Android 13 BLE 广播格式、1.14.0 增加 Android 15 兼容处理——接入时应关注最新版本。
3. 语言支持 Java/Kotlin 双语言，示例应用（宜动健康）以 Java 为主，但接口设计不排斥 Kotlin 调用。

工程结构

Android-JL_Health/
├── apk/                                     # 测试APK文件夹
│   ├── app                                  # 宜动健康测试APK，建议在应用商店下载
│   └── tool                                 # 手表测试工具，用于测试手表功能
├── code/                                    # 参考源码工程文件夹
│   ├── app                                  # 宜动健康开放源码
│   └── tool                                 # 手表测试工具开放源码
├── doc/                                     # 开发文档文件夹
│   ├── 杰理健康SDK(Android)开发说明         # 杰理健康SDK开发说明文档
│   ├── 杰理OTA外接库(Android)开发文档       # OTA库的开发说明文档
│   └── 杰理连接库(Android)开发文档          # 蓝牙连接库开发说明文档
├── libs/                                    # 核心库文件夹
│   ├── ALi/                                 # 支付宝相关库
│   │   └── AliAgent-release-xxx.aar         # 支付宝激活库
│   ├── JL/ui/                               # UI组件库
│   │   ├── jl_dialog_Vxxx-debug.aar         # 杰理对话框样式
│   │   ├── jl_health_http_Vxxx-release.aar  # 杰理健康服务器相关
│   │   └── jl-component-lib_Vxxx-release.aar# 杰理工具类
│   ├── jldecryption_v0.4-release.aar        # 加密解密相关
│   ├── jl_bluetooth_connect_Vxxx-release.aar# 蓝牙连接相关
│   ├── jl_bt_ota_Vxxx-release.aar           # 杰理OTA相关
│   ├── jl_rcsp_Vxxx-release.aar             # 基础协议相关
│   ├── JL_Watch_Vxxx-release.aar            # 杰理健康SDK核心库
│   ├── BmpConvert_Vxxx-release.aar          # 图像转换(BMP/JPEG/PNG等)
│   ├── GifConvert_Vxxx-release.aar          # GIF动态图片转换
│   └── jl_audio_decode_Vxxx-release.aar     # Opus和Speex音频解码
├── Jieli_Health_SDK_Android_Releases.pdf    # SDK发布记录
└── ReadMe.txt                               # 说明文件

来源：README.md

目录角色解读

• apk/ 与 code/ 一一对应：app（宜动健康）展示完整的健康 SDK 功能，适合作为产品开发的起点；tool（手表测试工具）偏向功能验证，包含 BmpConvertDemo、CustomCommandDemo 等测试包示例，适合调试与协议验证。
• doc/ 是开发文档源目录，覆盖 SDK、OTA 外接库、连接库三份核心文档，与在线文档中心内容对应。
• libs/ 是能力仓库：JL_Watch 是功能主库，jl_rcsp/jl_bluetooth_connect/jl_bt_ota 是三大基础库，其余为横向辅助库。版本号以 xxx 占位，实际引入时需替换为发布版本。

接入流程

flowchart TD
    Start([开始接入]) --> Clone["克隆仓库 / 导入 code/ 工程"]
    Clone --> AddLib["添加 AAR 依赖库到 libs"]
    AddLib --> Gradle["build.gradle 声明依赖"]
    Gradle --> Perm["AndroidManifest 配置蓝牙/定位权限"]
    Perm --> Init["继承 WatchOpImpl 实现 WatchManager 单例"]
    Init --> Sync["notifyBtDeviceConnection + notifyReceiveDeviceData"]
    Sync --> Verify["运行示例 APK 验证功能"]
    Verify --> Q{"功能正常?"}
    Q -->|"是"| Done([完成接入])
    Q -->|"否"| Debug["Logcat 日志排查"]
    Debug --> Sync

接入的关键在初始化与数据透传闭环（详见下文「使用示例」），权限与依赖是前置条件，而 apk/ 中的现成测试包则提供了"先跑通、再开发"的快捷路径。

使用示例

以下示例均提取自仓库 README.md 的接入说明，展示了 SDK 接入的标准范式。

示例一：继承 WatchOpImpl 实现健康管理类

SDK 采用"模板方法 + 回调"设计：应用继承 WatchOpImpl 基类，重写两个核心钩子方法——getConnectedDevice()（提供当前设备）与 sendDataToDevice()（发送 SDK 产出的数据包）。注意 getInstance() 使用双重检查锁的单例模式，保证全局唯一的管理器实例。

//实现健康管理类
public class WatchManager extends WatchOpImpl{

   private BluetoothDevice mTargetDevice;

   public static WatchManager getInstance() {
       if (null == instance) {
           synchronized (WatchManager.class) {
              if (null == instance) {
                  instance = new WatchManager(FUNC_WATCH);
               }
            }
        }
        return instance;
   }

   //func FUNC_WATCH:手表功能
   //FUNC_RCSP：仅仅使用rcsp协议
   //FUNC_FILE_BROWSE：使用rcsp协议和目录浏览功能
    public WatchManager(int func) {
        super(func);
    }
     /**
      * 获取当前连接的设备，sdk的操作都是基于该设备
      * @return 目标设备
      */
    @Override
    public BluetoothDevice getConnectedDevice() {
        //TODO: 客户重写实现功能
         return mTargetDevice;
    }

    /**
     * SDK通知外部需要发送数据
     * @param device 蓝牙设备对象
     * @param data   数据包 byte数组
     * @return false：发送失败  true:发送成功
     */
    @Override
    public boolean sendDataToDevice(BluetoothDevice device, byte[] data) {
        //TODO: 客户重写实现功能
         return false;
    }
}

来源：README.md

设计意图：三个构造参数 FUNC_WATCH / FUNC_RCSP / FUNC_FILE_BROWSE 决定了 SDK 加载的能力集——纯协议（RCSP）、协议+文件浏览、还是完整手表功能。客户可根据产品形态按需裁剪，避免引入不需要的模块。

示例二：外部状态与数据同步（透传闭环）

SDK 与蓝牙连接层完全解耦，应用侧必须主动"喂"状态和数据：

WatchManager mWatchManager = WatchManager.getInstance();
//1. 通知SDK蓝牙设备状态
//targetDevice : 目标设备
//connection status : 连接状态
//注意：连接状态需要转换成StateCode的连接状态
mWatchManager.notifyBtDeviceConnection(targetDevice, StateCode.CONNECTION_OK);
//2. 通知SDK接收数据
//targetDevice： 目标设备
//data:byte数组， 接收到目标数据发送的数据
mWatchManager.notifyReceiveDeviceData(targetDevice,data);
//3. SDK通知外部需要发送数据（在子类重写方法实现）
//device: 目标设备
//data: 发送数据
sendDataToDevice(BluetoothDevice device, byte[] data);

来源：README.md

设计意图：notifyBtDeviceConnection 是 SDK 的"连接状态输入口"，notifyReceiveDeviceData 是"数据输入口"，sendDataToDevice 是"数据输出口"。应用只要实现这三个通道，SDK 内部的协议状态机与业务逻辑即可独立运转——这是 SDK 能适配任意蓝牙连接方案的根本原因。

示例三：依赖与权限配置

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

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

来源：README.md

<-- 使用蓝牙权限 --!>
<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>

<-- 定位权限，官方要求使用蓝牙或网络开发，需要位置信息 --!>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
        
<-- Android 12+ 需要增加蓝牙连接权限 --!>
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

来源：README.md

配置选项

SDK 的能力装配通过 WatchOpImpl 构造参数完成，这是最核心的"配置项"：

此外，Android 侧还有两类环境级配置：

• 权限：BLUETOOTH、BLUETOOTH_ADMIN、ACCESS_COARSE_LOCATION、ACCESS_FINE_LOCATION（Android 12+ 需追加 BLUETOOTH_CONNECT），缺少定位权限会导致 BLE 扫描异常。
• 连接状态映射：透传连接状态时必须转换为 SDK 定义的 StateCode 常量（如 CONNECTION_OK），不能直接透传系统蓝牙状态码。

API 参考（核心入口）

以下为 WatchOpImpl 派生类对外暴露的关键接口（签名以 WatchManager 示例为准）：

WatchManager(int func)

构造器，通过 super(func) 初始化 SDK 能力集。

参数：

• func（int）：能力开关，取 FUNC_WATCH / FUNC_RCSP / FUNC_FILE_BROWSE 之一。

static WatchManager getInstance()

获取全局单例。采用双重检查锁（DCL）保证线程安全。

返回： WatchManager 实例。

BluetoothDevice getConnectedDevice()

获取当前连接的设备——SDK 的所有操作都基于该设备。

返回： 目标 BluetoothDevice。客户需重写实现。

boolean sendDataToDevice(BluetoothDevice device, byte[] data)

SDK 通知外部发送数据到设备（SDK 侧回调，应用必须重写）。

参数：

• device（BluetoothDevice）：蓝牙设备对象
• data（byte[]）：SDK 编码后的数据包

返回： false 发送失败；true 发送成功。

void notifyBtDeviceConnection(BluetoothDevice device, StateCode status)

应用通知 SDK 蓝牙设备连接状态（应用侧主动调用）。

参数：

• device（BluetoothDevice）：目标设备
• status（StateCode）：连接状态，需转换为 SDK 定义的 StateCode（如 CONNECTION_OK）

void notifyReceiveDeviceData(BluetoothDevice device, byte[] data)

应用通知 SDK 已收到设备数据（应用侧主动调用）。

参数：

• device（BluetoothDevice）：目标设备
• data（byte[]）：设备发送的原始数据

来源：README.md

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

BLE 传输的两个经典陷阱

README 在接入说明中专门强调了 BLE 实现的注意事项，这是 SDK 接入中最常见的失败来源：

1. MTU 分包：BLE 连接会协商 MTU 值，超出 MTU 的数据包会被系统直接抛弃。发送数据长度超过 MTU 时，必须按 MTU 大小分包发送，否则数据静默丢失、SDK 协议状态机将长时间等待应答。
2. 队列式发数：BLE 并发式发送容易导致手机系统 BLE 底层协议栈卡住。官方建议在 BluetoothGattCallback#onCharacteristicWrite 回调确认后再发送下一包，即"队列式发数"。

来源：README.md

认证流程时序

若设备需要认证流程，必须在连接成功后完成设备认证，再回调成功状态给 SDK（notifyBtDeviceConnection(..., CONNECTION_OK)）。认证未完成即上报连接成功，会导致后续业务命令被设备拒绝。

并发与一致性

• WatchManager 采用双重检查锁单例，多线程并发获取实例是安全的；但数据透传通道（notifyReceiveDeviceData → 协议解析）在 BLE 高频率回调下仍建议在应用侧做好数据缓冲与顺序保障。
• SDK 的命令发送与 OTA 过程互斥（版本 1.8.0 修复了"OTA 过程中偶现其他命令异常"），接入时不要在升级期间发起业务命令。
• 大文件传输（音乐、表盘）对时序敏感：1.13.1 修复了"大文件传输中设备回复错误偏移导致闪退"，1.14.0 修复了"大文件传输偶现失败"——此类问题多与分包重传策略相关，应使用官方最新版本。

已知边界

• 多国语言兼容：1.9.0 修复了阿拉伯语等 RTL 语言导致闪退的问题，国际化产品需使用 ≥1.9.0 版本。
• Android 版本适配：1.10.0 起 Android 12+ 不再强制要求位置权限（蓝牙权限独立化）；1.14.0 增加 Android 15 兼容。老旧版本在新系统上存在兼容风险。
• 安全修复：1.10.0 修复了 unZipFolder 的安全漏洞，生产环境务必升级。

性能与运维注意事项

• 能力裁剪：通过 func 参数（FUNC_WATCH / FUNC_RCSP / FUNC_FILE_BROWSE）按需加载能力，纯协议场景不必引入文件浏览等重模块，可显著减小 APK 体积并降低内存占用。
• 辅助库按需引入：图像转换（BmpConvert/GifConvert）、音频解码（jl_audio_decode）、支付（ALi）等辅助库仅在使用对应功能时引入。
• 日志与调试：SDK 提供详细日志输出，可通过 Android Studio Logcat 查看蓝牙连接状态与健康数据交互；问题排查时优先参考 doc/ 下的开发说明与在线文档中心的调试说明。
• 快速验证：接入前先运行 apk/ 目录下的「宜动健康」与「手表测试工具」测试包，可快速区分"设备问题 / 连接问题 / SDK 调用问题"。
• 版本管理：SDK 版本演进较快（见版本历史），建议跟随 Jieli_Health_SDK_Android_Releases.pdf 发布记录评估升级；升级时同步更新所有 AAR，避免核心库与连接库版本错配。

核心类速查

宜动健康（code/app）

手表测试工具（code/tool）

来源：README.md

版本历史与演进方向

版本演进反映了平台能力的扩展脉络：

• 1.6.x（2022/02）：建立基础功能矩阵（表盘、大文件传输、健康/运动数据、天气、消息、闹钟、设备查找）
• 1.7.x（2022/07）：单备份 OTA 兼容、BLE 切 SPP 连接策略
• 1.8.x-1.9.x（2022-2023）：设备设置适配、ARGB 图像、取消大文件传输、错误码统一、Android 13 兼容
• 1.10.x（2023/06）：闹钟溢出处理、x86/x86_64 支持、安全漏洞修复
• 1.11.x-1.12.x（2023-2024）：AI 云服务、AI 表盘、Nand Flash 信息拓展
• 1.13.x（2024）：4G 模块 OTA、表盘拓展参数、AC707N 图像转码、图片验证码机制
• 1.14.0（2026/01）：FIND MY 设备回连、AC707N 图像压缩与 GIF 支持、复用空间特殊升级、Android 15 兼容

来源：README.md

整体趋势：从基础功能覆盖 → 云端能力（AI/4G）→ 新芯片方案适配 → 系统兼容与稳定性加固。接入方应关注每个版本对 Android 新版本的兼容处理与传输可靠性修复。

许可证

本项目采用 Apache License 2.0 开源协议，Copyright 2024 珠海市杰理科技股份有限公司。

来源：README.md

Related Links

• README.md（项目总览）
• README_en.md（英文版说明）
• 在线文档中心：杰理健康SDK开发文档
• 杰理科技官网
• 问题反馈：GitHub Issues
• 仓库内文档：doc/ 目录下的《杰理健康SDK(Android)开发说明》《杰理OTA外接库(Android)开发文档》《杰理连接库(Android)开发文档》