WatchTestTool 测试工具

WatchTestTool（com.jieli.watchtesttool）是杰理科技（Jieli）面向 JL 智能手表 的 Android 端综合测试工具示例应用，用于验证蓝牙连接、RCSP 协议、OTA 升级、表盘推送、音乐传输、联系人同步、传感器数据、天气与消息通知等一整套手表功能。

Purpose and Scope

本文档介绍 code/tool/WatchTestTool_V0.9.0_SDK_V1.14.0 目录下的 WatchTestTool 示例应用，涵盖：

• 应用整体架构与入口（AndroidManifest.xml、MainActivity、ContentActivity）
• 功能开关与常量配置（WatchTestConstant）
• 蓝牙连接 / RCSP / OTA 等 SDK 依赖（本地 AAR 库）
• 本地数据层（Room 数据库：消息、传感器、天气）与数据模型（Bean）
• 构建产物与打包规则

本页面聚焦"测试工具应用"本身；JL 手表 SDK（JL_Watch_V1.14.0、jl_rcsp、jl_bluetooth_connect 等）的内部实现属于 SDK 二进制库范畴，不在本页面展开。仓库中其他示例应用（如 App、SdkDemo 等）请参见对应 catalog 页面。

Overview

WatchTestTool 是一个 演示 + 验证 性质的原生 Android 应用（Java），以 singleTask 竖屏的 MainActivity 作为唯一入口，通过 ContentActivity 承载各功能页面。它的设计目标是为手表方案的研发/测试人员提供一个开箱即用的验证平台：

• 连接层：封装 BLE 扫描、连接、MTU 协商（默认 PROTOCOL_TYPE_BLE + BLE_MTU_MAX）；
• 功能层：通过功能开关常量逐个启用/停用待测功能（文件传输、表盘操作、OTA、录音、文件浏览等）；
• 数据层：使用 Room 持久化设备消息、传感器与天气数据，资产目录（assets/）提供测试用的音乐、联系人等素材；
• SDK 层：全部核心能力以本地 AAR 形式集成，业务代码只做编排与 UI 展示。

应用版本号 0.9.0、版本码 619，minSdk 21、targetSdk 34、compileSdk 36，产物命名规则为 WatchTestTool_V{versionName}_{versionCode}_{yyyyMMdd}。

Architecture

flowchart TD
    subgraph sg_Entry["入口层 (Entry)"]
        MainActivity["MainActivity<br/>(singleTask, 竖屏)"]
        ContentActivity["ContentActivity<br/>(功能承载页)"]
        WatchApplication["WatchApplication"]
    end

    subgraph sg_UI["UI / ViewModel 层"]
        BluetoothViewModel["BluetoothViewModel"]
        HomeUI["首页功能列表"]
    end

    subgraph sg_Tool["工具层 (tool)"]
        BluetoothHelper["BluetoothHelper"]
        BluetoothEventListener["BluetoothEventListener"]
    end

    subgraph sg_SDK["SDK 层 (本地 AAR)"]
        JL_Watch["JL_Watch_V1.14.0"]
        Rcsp["jl_rcsp_V0.8.0"]
        BtConnect["jl_bluetooth_connect_V2.0.0"]
        Ota["jl_bt_ota_V1.11.0"]
        BmpConv["BmpConvert_V1.6.0"]
        AudioDec["jl_audio_decode_V2.1.0"]
        JlDialog["jl_dialog_V1.3.0"]
        JlComp["jl-component-lib_V1.4.0"]
        JlDecrypt["jldecryption_v0.4"]
    end

    subgraph sg_Data["数据层 (data)"]
        Beans["Bean 模型<br/>WatchInfo/ScanDevice/SettingItem/..."]
        RoomDB["Room 数据库<br/>Message/Sensor/Weather DAO"]
        Assets["assets/ 测试素材<br/>music / contacts"]
    end

    MainActivity --> ContentActivity
    WatchApplication --> MainActivity
    HomeUI --> MainActivity
    ContentActivity --> BluetoothViewModel
    BluetoothViewModel --> BluetoothHelper
    BluetoothHelper --> BluetoothEventListener
    BluetoothHelper --> BtConnect
    BluetoothHelper --> JL_Watch
    Rcsp --> JL_Watch
    Ota --> JL_Watch
    JL_Watch --> BtConnect
    BmpConv --> JL_Watch
    AudioDec --> JL_Watch
    JlDialog --> ContentActivity
    JlComp --> ContentActivity
    JlDecrypt --> JL_Watch
    ContentActivity --> Beans
    BluetoothViewModel --> RoomDB
    RoomDB --> Assets

架构说明：上层 UI（MainActivity/ContentActivity + ViewModel）只负责编排；所有手表协议、OTA、资源转换能力都封装在本地 AAR 中，通过 app/libs/ 以 implementation fileTree 方式引入；业务层通过 WatchTestConstant 的布尔开关控制测试范围，避免为每个功能维护独立入口。数据层与素材目录解耦——Room 负责结构化数据，assets/ 提供二进制测试素材，二者互不依赖。

应用入口与生命周期

AndroidManifest.xml 定义了应用的全部入口与权限模型：

• 权限：除常规网络/存储权限外，声明了 Android 12+ 的 BLUETOOTH_CONNECT（蓝牙连接）与 BLUETOOTH_SCAN（蓝牙搜索），以及定位权限（用于 BLE 扫描）、前台服务权限；
• Application：WatchApplication 负责全局初始化；
• Activity：MainActivity 为 LAUNCHER 入口（singleTask + 竖屏），ContentActivity 承载功能页面并处理大量 configChanges（旋转、键盘、语言、密度等），避免配置变化导致页面重建；
• FileProvider：${applicationId}.provider 用于跨应用共享测试文件（如 OTA 升级包）。

Source: AndroidManifest.xml

功能开关与常量配置（WatchTestConstant）

WatchTestConstant 是整个测试工具的"总控台"：通过一组 public final static 常量集中管理连接方式、MTU、设备过滤、认证以及各功能模块的启停，测试人员修改一处即可改变应用行为，而无需改动业务代码。

/*功能配置区*/
//默认连接方式
public final static int DEFAULT_CONNECT_WAY = BluetoothConstant.PROTOCOL_TYPE_BLE;
//默认BLE的MTU
public final static int DEFAULT_BLE_MTU = BluetoothConstant.BLE_MTU_MAX;
//是否过滤设备
public final static boolean FILTER_DEVICE = true;
//是否使用设备认证
public final static boolean USE_DEVICE_AUTH = true;
//是否禁止自动测试功能
public final static boolean BAN_AUTO_TEST = true;
//测试大文件传输功能
public final static boolean TEST_FILE_TRANSFER = true;
//测试文件浏览
public final static boolean TEST_FILE_BROWSE = false;
//测试表盘操作功能
public final static boolean TEST_WATCH_OP = true;
//测试OTA相关功能
public final static boolean TEST_OTA_FUNC = true;
//测试小文件传输功能
public final static boolean TEST_SMALL_FILE_TRANSFER = false;
//测试录音功能
public final static boolean TEST_RECORD = false;

Source: WatchTestConstant.java

设计意图：常量集中化让"测试矩阵"一目了然——例如 BAN_AUTO_TEST = true 表示禁止自动化测试、TEST_FILE_TRANSFER = true 而 TEST_SMALL_FILE_TRANSFER = false 表示只验证大文件通道。DEFAULT_CONNECT_WAY 与 BluetoothConstant 对齐，保证连接参数与 SDK 版本匹配；USE_DEVICE_AUTH 开启设备认证流程以模拟量产环境。

目录与版本常量

public final static String DIR_WATCH = "watch";        //表盘测试文件夹
public final static String DIR_WATCH_BG = "watch_bg";  //表盘自定义背景测试文件夹
public final static String DIR_MUSIC = "music";        //音乐文件测试文件夹
public final static String DIR_CONTACTS = "contacts";  //联系人测试文件夹
public final static String DIR_UPDATE = "upgrade";     //升级文件
public final static String DIR_RECORD = "record";      //录音文件
public final static String DIR_MESSAGE = "message";    //设备信息

public final static String DIR_BR23 = "BR23";          //BR23资源文件夹
public final static String DIR_BR28 = "BR28";          //BR28资源文件夹
public final static String DIR_BR35 = "BR35";          //BR35资源文件夹
public final static String DIR_NETWORK = "network";    //网络升级文件夹

public final static String VERSION_W001 = "W001";      //版本1
public final static String VERSION_W002 = "W002";      //版本2

public final static String KEY_FORCED_UPDATE_FLAG = "forced_update_flag_1";  //强制更新资源标志

Source: WatchTestConstant.java

这些常量按 功能目录（表盘/音乐/联系人/升级/录音/消息）、芯片平台目录（BR23/BR28/BR35）、资源版本（W001/W002） 三个维度组织，为文件传输、OTA 资源推送等模块提供统一的资源定位规则；KEY_FORCED_UPDATE_FLAG 用于记录"强制更新资源"状态，配合网络升级文件夹实现资源强制刷新。

构建系统与 SDK 依赖

应用通过 build.gradle 将全部杰理 SDK 以本地 AAR 形式集成（fileTree 引入 libs/ 下所有 .jar/.aar），并启用 dataBinding、viewBinding 与 buildConfig：

plugins {
    id 'com.android.application'
}

android {
    namespace "com.jieli.watchtesttool"
    compileSdk 36
    buildToolsVersion = "36.0.0"

    defaultConfig {
        applicationId "com.jieli.watchtesttool"
        minSdk 21
        targetSdk 34
        versionCode 619
        versionName "0.9.0"
        archivesBaseName = getAppName("WatchTestTool", versionName, versionCode)
        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
        //指定room.schemaLocation生成的文件路径
        javaCompileOptions {
            annotationProcessorOptions {
                arguments = ["room.schemaLocation": "$projectDir/schemas".toString()]
            }
        }
    }

    buildTypes {
        release {
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
    }
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    buildFeatures {
        dataBinding = true
        viewBinding = true
        buildConfig = true
    }
    ...
}

static def getAppName(String prefix, String versionName, int versionCode) {
    return "${prefix}_V${versionName}_${versionCode}_${getSystemTime()}"
}

Source: build.gradle

依赖清单（app/libs/）：

Source: build.gradle dependencies

第三方库方面，Room 2.3.0 负责持久化（schema 输出到 $projectDir/schemas），Gson 2.13.1 负责 JSON 序列化，permissionsdispatcher 4.9.2 用注解生成权限申请代码，BaseRecyclerViewAdapterHelper 3.0.4 与 SwipeDelMenuLayout V1.2.5 提供列表与侧滑菜单 UI 能力。minifyEnabled false 说明测试工具默认关闭混淆，便于调试与抓取日志。

数据层与数据模型

应用按 data 包组织数据能力，包含三类元素：

• Bean 模型（data/bean/）：WatchInfo（手表信息）、ScanDevice（扫描到的设备）、DeviceConnectionData（连接状态数据）、SettingItem（设置项）、SportRecord（运动记录）、WatchOpData（表盘操作数据）、SdkMapInfo（SDK 映射信息）、CalendarUtil（日历工具）、CompatRes（兼容资源）；
• Room 数据库（data/db/）：SensorDbBase 为数据库基类，下辖 MessageDao/MessageEntity（设备消息）、SensorDao/SensorEntity（传感器数据，含 SensorDataListener 监听器）、WeatherDao/WeatherEntity（天气数据）三组 DAO/Entity；
• 测试素材（assets/）：contacts/call.txt（联系人）、music/*.mp3（多首中文测试歌曲），供联系人同步与音乐传输测试使用。

flowchart LR
    subgraph sg_Beans["data/bean"]
        WatchInfo["WatchInfo"]
        ScanDevice["ScanDevice"]
        DeviceConnectionData["DeviceConnectionData"]
        SettingItem["SettingItem"]
        SportRecord["SportRecord"]
        WatchOpData["WatchOpData"]
    end

    subgraph sg_DB["data/db (Room)"]
        SensorDbBase["SensorDbBase"]
        MessageDao["MessageDao / MessageEntity"]
        SensorDao["SensorDao / SensorEntity<br/>+ SensorDataListener"]
        WeatherDao["WeatherDao / WeatherEntity"]
    end

    subgraph sg_Assets["assets"]
        CallTxt["contacts/call.txt"]
        Music["music/*.mp3"]
    end

    BluetoothViewModel --> ScanDevice
    BluetoothViewModel --> WatchInfo
    BluetoothViewModel --> DeviceConnectionData
    BluetoothViewModel --> SensorDbBase
    SensorDbBase --> MessageDao
    SensorDbBase --> SensorDao
    SensorDbBase --> WeatherDao
    MainActivity --> SettingItem
    ContentActivity --> SportRecord
    ContentActivity --> WatchOpData
    ContentActivity --> CallTxt
    ContentActivity --> Music

设计意图：Bean 与 Entity 分离——Bean 用于 UI/蓝牙层的数据交换（轻量、可序列化），Room Entity 用于本地持久化（传感器上报、消息记录、天气缓存），SensorDataListener 提供传感器数据的实时回调接口，避免轮询。

核心流程：从扫描到功能测试

工具的核心工作流为"扫描设备 → 连接 → 功能测试 → 数据落库"，由 MainActivity 启动、BluetoothViewModel 驱动、BluetoothHelper/BluetoothEventListener 承接 SDK 回调：

sequenceDiagram
    participant U as 测试人员
    participant M as MainActivity
    participant VM as BluetoothViewModel
    participant H as BluetoothHelper
    participant SDK as jl_bluetooth_connect<br/>+ JL_Watch SDK
    participant D as Room DB

    U->>M: 打开应用(授予权限)
    M->>VM: 初始化 ViewModel
    VM->>H: 注册 BluetoothEventListener
    U->>M: 点击扫描
    M->>VM: startScan()
    VM->>H: scan(BLE, MTU=BLE_MTU_MAX)
    H->>SDK: 启动 BLE 扫描
    SDK-->>H: 设备回调(onDeviceFound)
    H-->>VM: 更新 ScanDevice 列表
    U->>M: 选择设备并连接
    VM->>H: connect(device)
    H->>SDK: 发起连接(认证: USE_DEVICE_AUTH)
    SDK-->>H: 连接成功回调
    H-->>VM: DeviceConnectionData 更新
    VM-->>M: 进入功能页(ContentActivity)
    U->>M: 选择测试项(如 OTA/表盘/音乐)
    M->>VM: 执行测试命令
    VM->>SDK: 调用对应 SDK 能力
    SDK-->>VM: 结果/数据回调
    VM->>D: 写入消息/传感器/天气数据

流程要点：

1. 权限前置：AndroidManifest 声明 BLUETOOTH_SCAN/BLUETOOTH_CONNECT/定位权限，运行时由 permissionsdispatcher 注解生成申请逻辑；
2. 连接参数：DEFAULT_CONNECT_WAY = PROTOCOL_TYPE_BLE、DEFAULT_BLE_MTU = BLE_MTU_MAX，FILTER_DEVICE = true 时仅展示符合过滤规则的设备，USE_DEVICE_AUTH = true 时连接阶段执行设备认证；
3. 事件驱动：BluetoothEventListener 是 SDK 与业务层之间的桥，扫描/连接/数据事件都经它回调到 BluetoothViewModel，再以 LiveData 驱动 UI；
4. 功能分流：连接成功后在 ContentActivity 中按 WatchTestConstant 开关显示可测功能，测试结果（消息、传感器、天气）写入 Room。

使用示例

示例一：修改功能测试范围

测试某批次手表的 OTA 与表盘能力时，只需调整常量区：

// 只保留需要的测试项
public final static boolean TEST_FILE_TRANSFER = true;   // 大文件传输
public final static boolean TEST_WATCH_OP = true;        // 表盘操作
public final static boolean TEST_OTA_FUNC = true;        // OTA
public final static boolean TEST_RECORD = false;         // 录音暂不测
public final static boolean TEST_SMALL_FILE_TRANSFER = false;

Source: WatchTestConstant.java

示例二：更换默认连接方式与 MTU

将连接方式改为 SPP 或调整 MTU（需与 SDK BluetoothConstant 定义对齐）：

//默认连接方式
public final static int DEFAULT_CONNECT_WAY = BluetoothConstant.PROTOCOL_TYPE_BLE;
//默认BLE的MTU
public final static int DEFAULT_BLE_MTU = BluetoothConstant.BLE_MTU_MAX;

Source: WatchTestConstant.java

示例三：新增测试素材

在 assets/ 对应目录放置素材即可参与对应功能测试（目录名与 WatchTestConstant 中 DIR_* 常量一一对应）：music/*.mp3 用于音乐传输，contacts/call.txt 用于联系人同步，upgrade/ 用于 OTA 升级包，watch/、watch_bg/ 用于表盘推送。

配置选项

构建期配置（build.gradle）：applicationId=com.jieli.watchtesttool、minSdk=21、targetSdk=34、compileSdk=36、versionCode=619、versionName=0.9.0、minifyEnabled=false（release 不混淆）。

API 参考（核心常量类）

WatchTestConstant

功能配置常量（见上方代码），全部为 public final static，应用启动后由各模块直接读取：

• 连接相关：DEFAULT_CONNECT_WAY、DEFAULT_BLE_MTU、FILTER_DEVICE、USE_DEVICE_AUTH
• 测试开关：BAN_AUTO_TEST、TEST_FILE_TRANSFER、TEST_FILE_BROWSE、TEST_WATCH_OP、TEST_OTA_FUNC、TEST_SMALL_FILE_TRANSFER、TEST_RECORD
• 素材目录：DIR_WATCH、DIR_WATCH_BG、DIR_MUSIC、DIR_CONTACTS、DIR_UPDATE、DIR_RECORD、DIR_MESSAGE、DIR_BR23、DIR_BR28、DIR_BR35、DIR_NETWORK
• 版本与标志：VERSION_W001、VERSION_W002、KEY_FORCED_UPDATE_FLAG

无方法级 API；SDK 能力（连接、OTA、表盘推送等）由 AAR 库内部暴露，业务侧通过 BluetoothHelper 与 BluetoothEventListener 交互。

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

蓝牙连接失败 / 设备不可达

• 表现：扫描无结果或连接超时。原因多为权限未授予（BLUETOOTH_SCAN/定位）、设备处于不可发现状态、MTU 协商失败。
• 应对：FILTER_DEVICE = true 时列表已过滤，减少误选；USE_DEVICE_AUTH = true 时认证失败会中断连接，需保证设备固件与 SDK 版本匹配（本工具固定配套 JL_Watch_V1.14.0）。

权限边界（Android 12+）

• 工具依赖 BLUETOOTH_CONNECT/BLUETOOTH_SCAN 与位置权限；targetSdk 34 下运行时权限必须动态申请，permissionsdispatcher 注解处理器会在编译期生成对应逻辑。用户拒绝权限后扫描/连接功能不可用，UI 需给出提示。

OTA / 资源升级异常

• TEST_OTA_FUNC = true 时升级包路径为 assets/upgrade 或 DIR_UPDATE；KEY_FORCED_UPDATE_FLAG 控制强制更新标志。升级中断（电量不足、蓝牙断开）可能造成设备侧资源损坏，测试时应保证设备电量与连接稳定；jldecryption 库负责加密升级包解密，密钥不匹配会导致升级失败。

并发与数据一致性

• 传感器数据经 SensorDataListener 实时回调写入 Room（SensorDao），回调线程与 UI 线程分离，写入通过 DAO 串行化；MessageDao/WeatherDao 同理。多测试项同时执行时，蓝牙通道为单连接串行复用，SDK 内部负责命令排队，业务层不应并发下发互斥命令。
• 大文件传输（TEST_FILE_TRANSFER = true）与小文件传输通道独立（后者默认关闭），避免同时开启造成带宽抢占；文件传输中断时 SDK 通过回调上报进度/错误，业务层应清理半成品文件。

生命周期边界

• MainActivity 为 singleTask，重复启动不会新建实例；ContentActivity 声明大量 configChanges，旋转/语言/密度变化不重建页面，但蓝牙状态（断开）需要通过 DeviceConnectionData 通知 UI 刷新。

性能与运维注意事项

• 调试优先：release 构建 minifyEnabled false，便于直接抓取日志与断点调试；测试工具不面向生产发布。
• 素材体积：assets/music 内置多首 MP3，APK 体积随素材增大；仓库内对应 APK 产物为 apk/tool/WatchTestTool_V0.9.0_619_20260202-debug.apk。
• Room schema 管理：room.schemaLocation 指向 $projectDir/schemas，升级数据库结构时应提交 schema 变更并走 Migration，否则升级后查询可能失败。
• 蓝牙功耗：扫描/连接/文件传输均为高功耗操作，长时间测试建议连接电源；BluetoothHelper 应在上层退出时释放监听与连接资源。

扩展点

1. 新增测试功能模块：仿照现有开关模式，在 WatchTestConstant 增加 TEST_XXX 开关与 DIR_XXX 素材目录，并在 ContentActivity 中注册对应页面与 SDK 调用；
2. 替换/升级 SDK：替换 app/libs/ 下同名 AAR 并同步 WatchTestConstant 中的 BluetoothConstant 常量（如 MTU、协议类型），注意 SDK 间版本配套关系；
3. 扩展持久化：在 data/db 下新增 Entity/DAO 并注册到 SensorDbBase，复用现有 Room 架构与 SensorDataListener 模式；
4. 自动化测试：BAN_AUTO_TEST 默认为 true 表示默认关闭自动化测试入口，开启后可按既有工具链接入仪器测试（androidTest 下已有 ExampleInstrumentedTest 骨架）。

测试覆盖

• 单元测试：依赖 junit:junit:4.+，testImplementation 已配置；
• 仪器测试：androidTest 提供 ExampleInstrumentedTest.java（Espresso + AndroidJUnitRunner）骨架，用于真机/模拟器上的 UI 与蓝牙流程冒烟验证；
• 手工测试：核心验证依赖真机 + 杰理手表硬件，测试矩阵由 WatchTestConstant 开关组合定义（连接 → 各功能项 → 数据落库校验）。

Related Links

• WatchTestConstant.java — 功能开关与目录常量定义
• AndroidManifest.xml — 入口与权限声明
• app/build.gradle — 构建配置与依赖
• 蓝牙工具层：code/tool/WatchTestTool_V0.9.0_SDK_V1.14.0/app/src/main/java/com/jieli/watchtesttool/tool/bluetooth/BluetoothHelper.java、BluetoothEventListener.java、BluetoothViewModel.java
• 数据层：data/db/SensorDbBase.java 及 message/sensor/weather 三组 DAO/Entity
• 预编译 APK：apk/tool/WatchTestTool_V0.9.0_619_20260202-debug.apk