调试技巧与问题排查

本文介绍杰理健康 SDK（Android-JL_Health）开发调试的完整方法论：如何利用 SDK 内置日志输出监控蓝牙连接与健康数据交互、如何借助 Android Studio Logcat 与配套测试工具定位问题，以及官方提供的排查路径。

目的与范围

本页面向使用 Android-JL_Health SDK 开发蓝牙穿戴类应用（智能手表、健康手环等）的开发者，覆盖以下内容：

• SDK 日志输出机制与 Logcat 实时日志查看方法
• 设备调试流程（编译 → 部署 → 连接 → 观察日志）
• 官方问题排查资源（SDK 调试指南、HealthAide 测试 APK、WatchTestTool 测试工具）
• 调试相关的工程组件与 AAR 依赖变体（release/debug）
• 常见故障场景与排查思路

以下内容属于兄弟页面，不在本页展开：

• 快速开始与工程导入：见 README「三、快速开始」与「四、工程结构」
• 参数配置与初始化：见 README「五、配置说明」
• 各功能模块（OTA、表盘、健康数据、消息同步等）：见对应功能文档

说明：本页基于仓库 README 与示例工程结构撰写；SDK 内部实现以 AAR 二进制形式发布，具体日志接口签名与协议字段请以官方 SDK 调试指南为准（该链接由 README_en.md 提供）。

概述

Android-JL_Health 是珠海市杰理科技股份有限公司为蓝牙穿戴类产品提供的健康数据与设备管理开发平台，基于 RCSP 协议（远程控制系统协议） 通过 BLE 与穿戴设备交互，支持 OTA 升级、表盘管理、健康数据、运动数据、消息同步、天气、联系人、闹钟、文件传输等能力（见 README.md）。

BLE + RCSP 的调试链路比普通 App 更复杂，问题可能出现在多个环节：

1. 协议层：RCSP 指令封装与解析是否正确
2. 传输层：BLE 连接稳定性、MTU、分包与粘包
3. 业务层：健康数据（心率/血氧/睡眠等）的请求与回调时序
4. 设备侧：固件版本是否支持对应指令（AC701N、AC707N、AC695N 等）

因此，杰理 SDK 的设计理念是把日志作为第一调试手段：SDK 提供详细的日志输出，可通过日志查看蓝牙连接状态和健康数据交互；配合 Android Studio 的 Logcat 实现实时监控（见 README.md）。

架构

下图展示了调试视角下的完整链路：开发环境、示例工程、SDK 组件、硬件设备与测试工具之间的关系。

flowchart TD
    subgraph sg_Dev["开发环境"]
        AS["Android Studio"]
        LC["Logcat 日志窗口"]
    end

    subgraph sg_App["示例工程 HealthAide"]
        APP["HealthAide APP"]
        SAMPLE["com.jieli.healthaide<br/>data(dao/db/entity/vo) 分层"]
    end

    subgraph sg_SDK["杰理健康SDK AAR 库"]
        CORE["JL_Watch Vxxx-release.aar"]
        BLE["jl_bluetooth_connect Vxxx-release.aar"]
        OTA["jl_bt_ota Vxxx-release.aar"]
        RCSP["jl_rcsp Vxxx-release.aar"]
        HTTP["jl_health_http Vxxx-release.aar"]
    end

    subgraph sg_Device["硬件设备"]
        WATCH["RCSP 蓝牙穿戴设备<br/>(AC701N/AC707N/AC695N)"]
    end

    subgraph sg_Tools["调试工具"]
        WT["WatchTestTool 测试工具"]
        APK["HealthAide 测试 APK<br/>(apk/ 目录)"]
    end

    AS --> APP
    APP --> CORE
    CORE --> BLE
    CORE --> OTA
    CORE --> RCSP
    CORE --> HTTP
    BLE -->|"BLE 连接与 RCSP 数据交互"| WATCH
    APP -->|"日志输出"| LC
    WT -->|"协议联调/固件验证"| WATCH
    APK -->|"现场复现问题"| WATCH

架构说明：

• HealthAide 示例工程（code/app/HealthAide_V1.1.0_SDK_V1.14.0）是官方提供的最小可运行示例，数据层按 data.dao（Room DAO）、data.db（数据库与辅助类）、data.entity（实体）、data.vo（视图对象）分层组织，是验证 SDK 集成是否正确的参照实现。
• SDK AAR 组件按职责拆分为核心库（JL_Watch）、蓝牙连接、OTA、RCSP 协议、健康服务器等，调试时可根据问题现象缩小到具体库。
• 测试工具（WatchTestTool、HealthAide 测试 APK）用于绕过 App 层直接与设备联调，或在实际设备上复现问题，是问题归属判断（App 问题还是协议/固件问题）的关键手段。

核心流程：一次典型的问题定位过程

从"编译运行"到"定位问题"的完整时序如下：

sequenceDiagram
    participant Dev as 开发者
    participant Studio as Android Studio
    participant App as HealthAide 示例APP
    participant SDK as 杰理健康SDK
    participant Device as RCSP 穿戴设备
    participant LC as Logcat

    Dev->>Studio: 打开工程并编译安装
    Studio->>App: 部署 APK 到手机
    App->>SDK: 初始化 SDK / 发起 BLE 扫描与连接
    SDK->>Device: BLE 连接与 RCSP 指令交互
    Device-->>SDK: 健康数据 / 协议应答
    SDK-->>App: 业务回调
    App-->>LC: 输出连接状态与数据交互日志
    LC-->>Dev: 按进程/标签筛选实时查看
    Dev->>Dev: 依据日志判断问题归属<br/>(App / SDK / 协议 / 固件)
    Dev->>WT: 必要时使用测试工具复现验证

流程要点：

1. 复现：使用 HealthAide 示例工程或测试 APK 在真实设备上复现问题，排除业务代码干扰。
2. 观察：在 Android Studio Logcat 中按进程名（如 com.jieli.healthaide）过滤，实时查看蓝牙连接状态与健康数据交互日志。
3. 归属判断：日志能覆盖到哪一层，问题就大概率出在该层或以下——日志缺失点即为断点。
4. 工具验证：若怀疑协议或固件问题，改用 WatchTestTool 直接与设备联调；若怀疑 SDK 行为，查阅官方调试指南。

日志输出机制

SDK 内置日志

杰理健康 SDK 提供详细的日志输出，覆盖蓝牙连接状态与健康数据交互两大核心链路（见 README.md）：

• 日志输出：SDK提供详细的日志输出，可通过日志查看蓝牙连接状态和健康数据交互
• 设备调试：使用Android Studio的Logcat查看实时日志

英文版 README 的对应描述为："The SDK provides detailed log output for monitoring Bluetooth connection status and health data interactions"（见 README_en.md）。

设计意图：BLE 通道上 RCSP 指令的收发是异步的，回调结果与指令发送顺序并不总是严格对应。把连接状态和每次数据交互都落成日志，能让开发者重建完整的时序，这是定位"指令未响应""数据未同步"类问题的最直接手段。

Logcat 使用建议

• 在 Android Studio 的 Logcat 面板中，优先按包名/进程名过滤，避免被系统日志淹没。
• 连接类问题关注：扫描结果、连接建立/断开、MTU 协商、服务发现（GATT）等日志。
• 数据类问题关注：指令发送、ACK 应答、数据分片与解析完成日志。
• 可结合日志时间戳与设备端操作（如按表盘上的按键）对照，判断事件先后。

注：SDK 日志的具体 TAG、级别与开关接口属于 AAR 内部实现，本仓库未包含其源码；如需自定义日志级别或回调，请查阅官方 SDK 调试指南。

设备调试流程

1. 准备工程：克隆仓库并导入 code/ 目录下的示例项目（详见 README.md）。
2. 确认依赖：将 libs/ 下的 AAR 放入模块 libs 目录并在 build.gradle 声明依赖（详见下文「使用示例」）。
3. 连接设备：手机开启 BLE，穿戴设备进入可连接状态，App 发起扫描与连接。
4. 复现操作：在 App 中触发目标功能（同步健康数据、OTA 等），同时保持 Logcat 运行。
5. 定位问题：按上文归属判断法逐层排查；若确认 SDK/固件行为异常，收集日志与复现步骤，通过 Issues 反馈。

问题排查指南

官方资源

README 提供两条官方排查路径（见 README_en.md）：

中文文档可通过文档中心访问（见 README.md）。

常见故障场景与排查思路

以下排查思路基于 README 的调试指引与 BLE/RCSP 开发的一般规律，具体错误码语义请以官方调试指南为准：

问题归属判断法

• App 层问题：日志显示 SDK 回调正常但界面/数据异常 → 检查业务代码与数据层（DAO/Entity/VO）。
• 协议层问题：指令已发出但无应答或应答异常 → 用 WatchTestTool 直接联调验证。
• 固件问题：测试工具也无法复现预期行为 → 确认设备固件版本与 SDK 版本兼容性。

调试相关工程组件

示例工程 HealthAide

示例工程位于 code/app/HealthAide_V1.1.0_SDK_V1.14.0/，其数据层是调试数据链路时的参照实现：

• data/dao/：Room DAO（HealthDao、UserDao、SportRecordDao、LocationDao、AICloudMessageDao 等）
• data/db/：HealthDatabase（数据库定义）、HealthDataDbHelper（数据辅助）、VirtualDataHelper（虚拟数据辅助，可用于构造模拟健康数据验证数据链路，具体实现请阅读 VirtualDataHelper.java）
• data/entity/：持久化实体（HealthEntity、SportRecord、User 等）
• data/vo/：业务视图对象（BaseVo、BaseParseVo、BaseLiveDataVo，以及按健康指标拆分的 blood_oxygen、心率等子包）

调试提示：对照示例工程的 VO 解析链（BaseParseVo → 各指标 VO）可以快速确认"设备回传数据 → SDK 解析 → App 展示"每一环的格式约定。

AAR 依赖变体（release / debug）

工程依赖以 AAR 形式提供，大部分为 release 变体；UI 组件库中存在 debug 变体（见 README.md）：

jl_dialog_Vxxx-debug.aar   # 杰理对话框样式（debug 变体）

设计意图：debug/release 变体并存是为了在开发阶段获得更完整的日志与断言，而在发布阶段获得优化与裁剪。调试时如怀疑 UI 组件问题，应优先确认引入的是 debug 变体。

使用示例

示例一：克隆仓库并导入工程

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

Source: README.md

克隆后打开 Android Studio，选择 "Open an existing project"，导航到 code/ 目录并打开对应示例项目（见 README.md）。

示例二：在 build.gradle 中声明 AAR 依赖

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

Source: README.md

示例三：确认日志链路（阅读顺序）

以"连接后数据不同步"为例，按以下顺序核对日志（伪流程，源自 SDK 调试指南与 README 指引，TAG 以实际 SDK 输出为准）：

1. BLE 连接成功日志 → 确认传输层正常
2. RCSP 握手/指令发送日志 → 确认协议层正常
3. 健康数据解析完成日志 → 确认业务层正常
4. App 回调与数据库写入日志 → 确认应用层正常

任一步骤日志缺失，即该层为问题断点。

配置选项

SDK AAR 依赖清单

以下为调试链路涉及的全部 AAR 依赖及其职责（见 README.md，xxx 为版本号）：

运行环境要求

（见 README.md）

调试时请先核对运行环境：低于 Android 5.1 或设备固件不支持 RCSP，会导致连接与日志链路本身不可用，容易误判为 SDK 问题。

故障模式、边界情况与并发

故障模式

1. BLE 连接失败/中断：表现为扫描不到设备或连接后立即断开。此类问题的日志特征为连接层日志缺失，应优先使用 WatchTestTool 交叉验证，排除 App 层干扰。
2. 健康数据静默丢失：指令发送成功但无数据回传。可能涉及设备端数据为空、命令与固件版本不匹配、回调未注册等，需结合数据交互日志逐层核对。
3. OTA 中断：大文件传输受 BLE 链路质量影响大，中断后固件可能处于半更新状态，应严格按照 OTA 功能文档的流程重试。
4. 日志缺失：使用 release 变体或日志被系统回收时看不到 SDK 日志，可改用 debug 变体（如 jl_dialog_Vxxx-debug.aar 所示模式）并确认过滤条件。

边界情况

• 异步回调时序：RCSP 交互为异步模型，回调顺序不等同于指令发送顺序。调试时应以日志时间戳重建时序，而非假设"先发先回"。
• 大文件分包：文件传输（如音乐）与 OTA 涉及分包，边界处（最后一个分包、跨 MTU 边界）最易出错，日志中的分片序号是排查关键。
• 设备重启/重连：设备重启后需要重新走连接与初始化流程，期间发起的指令可能无响应，需在 App 层做好状态机处理。

并发与一致性

• 多条健康指令同时下发时，SDK 内部按队列串行处理（依据 RCSP 协议一般实现，具体以 SDK 行为为准）；调试时避免在回调中再次同步调用阻塞操作。
• 数据入库（Room DAO）与 UI 刷新（LiveData/VO）之间的线程切换，可通过 BaseLiveDataVo 与 BaseParseVo 的层次观察（见示例工程 data/vo 包）；若出现界面与数据不一致，优先检查是否在工作线程直接更新 UI。

性能与运维注意事项

• Logcat 过滤：长时间运行时开启日志会产生 IO 开销，正式联调阶段建议仅保留本进程日志（按包名过滤），发布前移除调试代码。
• 版本一致性：SDK 各 AAR 应使用同一版本号（Vxxx），混用不同版本的 jl_rcsp 与 JL_Watch 可能导致协议不匹配的隐蔽问题。
• 日志留存：现场问题建议先导出 Logcat 文件（adb logcat -d > log.txt 为通用 Android 工具用法，非仓库代码）再分析，便于与厂商/官方沟通时附带完整证据链。
• 渠道与支持：问题确认后可通过 GitHub Issues 反馈，附上 SDK 版本、固件版本、复现步骤与日志（见 README.md）。

扩展点

自定义命令（协议扩展）

SDK 支持自定义命令以便客户拓展功能（见 README.md）。调试自定义命令时，应先在 WatchTestTool 中验证指令格式，再接入 App，从而将"指令错误"与"业务代码错误"分离。

虚拟数据辅助

示例工程的 data/db/VirtualDataHelper 提供了构造模拟健康数据的辅助能力（依据文件名与包结构推断，具体 API 请阅读 VirtualDataHelper.java）。在没有真实设备或需要构造边界数据（如心率越界值）时，这是验证 App 数据链路的高效手段。

测试 APK 与独立测试工具

• HealthAide 测试 APK：位于仓库 apk/ 目录（见 README_en.md），用于在真机环境快速复现 SDK 行为。
• WatchTestTool：位于 code/tool/WatchTestTool_V0.9.0_SDK_V1.14.0/，配套独立文档 手表测试工具说明文档.md，适合协议联调与固件验证场景。

相关链接

• README.md（中文总览，含调试技巧章节）
• README_en.md（英文版 Debugging Tips）
• 官方 SDK 调试指南（英文）
• 官方文档中心（中文）
• WatchTestTool 测试工具说明文档
• HealthAide 示例工程数据层（HealthDatabase.java）
• 报告问题（GitHub Issues）

提示：本页为开发指南（10-developer-guide）下的调试主题页；功能模块的使用细节（OTA、表盘、健康数据等）请查看对应功能文档，避免在本页重复展开。