广播包解析与设备认证

本文档介绍 iOS-JL_Health SDK 中蓝牙设备广播包（Advertisement）解析与设备认证（Device Authentication）能力的定位、端到端流程、集成配置与依赖关系。该能力由 JL_BLEKit.xcframework 提供，是整个 SDK"扫描 → 连接 → 协议交互 → 功能调用"链路的入口环节。

Purpose and Scope

本页覆盖以下内容：

• 广播包解析与设备认证在 JL_Health SDK 中的角色与位置（属于蓝牙连接模块 JL_BLEKit.xcframework，README 将其职责明确为"设备扫描与连接、基础协议交互"）；
• 从 App 扫描设备到建立可靠连接的端到端流程：广播接收 → 解析 → 认证/协议握手 → 连接成功 → 功能数据交互；
• 接入本能力所需的运行环境、框架集成与权限配置；
• 该能力与 OTA、表盘、健康数据等上层功能模块的依赖关系。

以下内容不属于本页范围，由各自目录页覆盖：OTA 升级流程（JL_OTALib.xcframework）、表盘管理（JLDialUnit.xcframework）、音频编解码（JLAudioUnitKit.xcframework）、图像转码（JLBmpConvertKit.xcframework）与资源打包（JLPackageResKit.xcframework）。

关于源码可得性的诚实说明：本仓库以预编译 XCFramework 形式分发 SDK，广播包解析与设备认证的内部实现（解析算法、认证报文、错误码）不在仓库源码中。本文全部结论均基于仓库内可读的集成文档（README 的概述、运行环境、功能模块与快速集成章节）与可见的工程结构；对二进制 SDK 内部实现的描述仅给出其对外可观察的流程与约束。

Overview

背景

杰理科技为蓝牙穿戴类产品（智能手表、健康手环、智能徽章、智能戒指等）提供健康 SDK。硬件侧要求设备"支持杰理 RCSP 协议"，典型芯片型号为 AC701N、AC707N、AC695N 等（见 README.md 运行环境）。

为什么需要广播包解析与设备认证

BLE 设备通过广播包（Advertisement）对外宣告自身存在。在杰理生态中，广播包不仅是"我在这里"的信标，还承载了厂商自定义数据——设备类型、协议能力、固件版本等信息。App 端必须：

1. 解析广播包：从原始广播数据中识别出杰理设备及其型号/能力，从而决定是否展示在设备列表中、后续走哪条交互路径；
2. 认证设备：在连接建立前后与设备完成协议握手，确认设备身份与固件能力，保证后续健康数据、OTA、表盘等指令的安全可靠交互。

这两步合在一起构成了 SDK 核心调用流程的起点——README 给出的标准链路是：

设备连接 → 协议交互 → 功能调用 → 数据回调

（见 README.md 快速集成步骤）

关键概念

Architecture

下图展示广播解析与设备认证在整个 JL_Health SDK 中的位置及其与上层功能模块的关系（依据 README 功能模块表绘制）：

flowchart TD
    subgraph sg_App["App 业务层 (示例工程)"]
        AppDelegate["AppDelegate / 业务入口"]
        FeatureUI["功能界面 (健康/OTA/表盘/音乐...)"]
    end

    subgraph sg_SDK["JL_Health SDK"]
        BLEKit["JL_BLEKit.xcframework<br/>设备扫描 · 广播解析 · 认证 · 连接"]
        subgraph sg_Features["上层功能框架"]
            OTALib["JL_OTALib.xcframework"]
            DialUnit["JLDialUnit.xcframework"]
            AudioUnit["JLAudioUnitKit.xcframework"]
        end
    end

    subgraph sg_Device["杰理穿戴设备"]
        Device["AC701N / AC707N / AC695N<br/>RCSP 协议固件"]
    end

    AppDelegate -->|"初始化/扫描"| BLEKit
    BLEKit -->|"BLE 广播 (Advertisement)"| Device
    BLEKit -->|"认证/协议握手 (RCSP)"| Device
    BLEKit -->|"连接建立后基础协议交互"| Device
    FeatureUI -->|"调用功能接口"| OTALib
    FeatureUI -->|"调用功能接口"| DialUnit
    FeatureUI -->|"调用功能接口"| AudioUnit
    OTALib --> BLEKit
    DialUnit --> BLEKit
    AudioUnit --> BLEKit

架构要点：

• JL_BLEKit.xcframework 是唯一与设备直接交互的框架。README 功能模块表将其职责定义为"设备扫描与连接、基础协议交互"（见 README.md 功能实现指南），因此广播包解析与设备认证都发生在这个框架内部。
• 上层功能框架不直接访问 BLE 栈。OTA、表盘、音频等模块都建立在 BLEKit 建立的连接与协议通道之上，这保证了"一次认证、多次复用"的会话模型——认证只需在连接阶段完成一次，之后所有功能模块共享同一条可靠协议链路。
• 设备侧以 RCSP 协议固件为边界。广播解析的识别对象、认证的握手对象都是支持 RCSP 协议的杰理设备；非 RCSP 设备在扫描阶段即可被过滤掉，这是 README 硬件要求（L70-L77）隐含的设计意图——在入口处就用广播内容做协议能力过滤，避免把资源浪费在无法交互的设备上。

广播包解析：扫描、识别与过滤

解析发生的位置

广播解析发生在 JL_BLEKit.xcframework 内部，对 App 呈现为"扫描到设备并回调设备实体"的可观察行为。App 侧只负责发起扫描与接收回调，解析细节（厂商自定义数据段偏移、字段含义、协议版本判定）被封装在二进制 SDK 中，对外不可见——这是本 SDK 的设计意图：把杰理私有协议知识收敛进框架，业务层只需面向设备实体编程。

解析驱动的三类决策

基于 README 对产品与硬件约束的描述，可以确认广播解析结果至少驱动以下三类决策：

1. 设备识别：判定扫描到的外设是否是杰理穿戴设备（通过厂商自定义广播数据中的设备标识）。
2. 能力过滤：判定设备是否支持 RCSP 协议——这是 README 硬件要求"支持杰理 RCSP 协议的 SDK（AC701N、AC707N、AC695N等）"（README.md L70-L77）在扫描阶段的体现：不满足协议能力的设备不会进入认证与连接流程。
3. 产品分流：儿童手表、成人手表、健康手环、智能徽章、智能戒指等产品形态不同（README.md 概述），广播包中的产品类型字段用于让 SDK 走对应的交互路径（例如表盘能力仅对带屏设备开放）。

与上层模块的衔接

广播解析成功后，设备实体被交付给上层模块使用。README 的功能模块表展示了这一衔接关系——所有功能模块都挂在"蓝牙连接"（JL_BLEKit）之下：

（见 README.md 功能实现指南）

设备认证：连接阶段的协议握手

认证的目的

设备认证发生在连接建立前后，是"设备连接 → 协议交互 → 功能调用 → 数据回调"（README.md L115）标准链路中的第二步。其目的可以归纳为：

• 身份确认：验证对端确实是与广播包标识一致的杰理设备，避免连接到仿冒或无关设备；
• 能力协商：确认固件支持的 RCSP 协议版本与功能子集，决定后续可用指令集；
• 会话建立：为后续健康数据、OTA、表盘、消息同步等功能调用建立安全可靠的协议会话。

认证在流程中的位置

认证不是独立步骤，而是连接建立过程的一部分。它紧跟在 GATT 连接之后、功能调用之前，且全 SDK 仅执行一次——后续所有功能框架（OTALib、DialUnit、AudioUnit 等）复用 BLEKit 已认证的协议通道，这就是架构图中"上层功能框架依赖 BLEKit"这一连线存在的原因。

Core Flow：从广播到功能数据的端到端时序

sequenceDiagram
    participant App as App 业务层
    participant SDK as JL_BLEKit
    participant BLE as 系统 BLE 栈 (CoreBluetooth)
    participant Dev as 杰理穿戴设备 (RCSP)

    App->>SDK: 发起设备扫描
    SDK->>BLE: 开始扫描 (CBCentralManager)
    BLE->>Dev: 监听广播
    Dev-->>BLE: BLE 广播包 (含厂商自定义数据)
    BLE-->>SDK: 广播数据回调
    SDK->>SDK: 解析广播包 (设备识别/能力过滤)
    SDK-->>App: 回调设备实体 (可连接)
    App->>SDK: 选择设备并连接
    SDK->>BLE: 发起 GATT 连接
    BLE->>Dev: 建立连接
    Dev-->>BLE: 连接成功
    BLE-->>SDK: 连接建立事件
    SDK->>Dev: 设备认证/协议握手 (RCSP)
    Dev-->>SDK: 认证结果
    SDK-->>App: 连接与认证成功回调
    App->>SDK: 功能调用 (健康/OTA/表盘/消息...)
    SDK->>Dev: RCSP 指令/数据交互
    Dev-->>SDK: 数据响应
    SDK-->>App: 数据回调

流程要点逐段说明：

1. 扫描与广播回调：App 调用扫描接口后，SDK 经由系统 BLE 栈监听广播。杰理设备的广播包中包含厂商自定义数据，这是后续解析的输入。
2. 解析与过滤：SDK 在内部完成广播包解析，识别设备类型与协议能力；非 RCSP 设备在此阶段即被过滤，不会出现在设备列表中——这是"硬件要求 RCSP 协议"（README.md L76）在运行时最直接的体现。
3. 连接与认证：App 选择设备后，SDK 完成 GATT 连接并立即执行设备认证/协议握手。只有认证成功才向 App 抛出"连接成功"，保证 App 收到的每个设备都处于可交互状态。
4. 功能数据交互：连接成功后，所有功能模块（健康数据、OTA、表盘等）复用同一条认证过的协议通道进行指令与数据交互，最终以回调形式把数据交还 App（"数据回调"）。

Usage Examples

以下示例全部提取自仓库内可读文档（README），展示接入"广播解析 + 设备认证"链路所需的集成步骤与配置。

示例 1：获取仓库并进入工程

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

Source: README.md

示例 2：集成对应功能框架

广播解析与设备认证位于"蓝牙连接"模块，集成 JL_BLEKit.xcframework 并按功能需要追加上层框架：

| 功能模块 | 参考库 | 说明 |
|---------|--------|------|
| 蓝牙连接 | JL_BLEKit.xcframework | 设备扫描与连接、基础协议交互 |
| 健康数据 | JL_BLEKit.xcframework | 运动健康数据模型、睡眠监测 |
| OTA 升级 | JL_OTALib.xcframework | 固件升级流程控制、资源文件传输 |

Source: README.md

示例 3：配置蓝牙权限（Info.plist）

README 要求配置 Privacy - Bluetooth Peripheral/Always Usage Description 权限（README.md L114），在 Info.plist 中对应标准的蓝牙权限键：

<key>NSBluetoothAlwaysUsageDescription</key>
<string>需要蓝牙权限以扫描并连接杰理健康设备</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>需要蓝牙权限以扫描并连接杰理健康设备</string>

说明：README 以 prose 形式给出权限要求（"Privacy - Bluetooth Peripheral/Always Usage Description"），上表键名是 iOS 标准权限键的对应形式。

示例 4：核心调用流程

设备连接 → 协议交互 → 功能调用 → 数据回调

Source: README.md

这是整个 SDK（包括广播解析与设备认证）的标准时序骨架：先完成扫描-连接-认证（前三步的前置部分），再进入功能调用与数据回调阶段。

Configuration Options

以下为接入广播解析与设备认证链路时必须满足的环境与配置要求（全部来自 README.md 运行环境 与快速集成）：

API Reference

诚实说明：JL_BLEKit.xcframework 以预编译二进制形式分发，仓库中不包含其头文件源码，因此本页无法给出经源码验证的方法签名。公开 API 的权威来源是：

• 集成后 SDK 框架自带的头文件（JL_BLEKit.xcframework 的 Headers 目录）；
• 官方文档中心：iOS 健康 SDK 文档。

仓库内可见的头文件目录示例：code/JL_Health/AIKIT.framework/Headers/（含 AiHandle.h、AiHelper.h、AIKIT.h 等）——这些属于 AI 云服务/AI 表盘模块，与广播解析无直接关系，仅用于佐证本仓库以"二进制框架 + 头文件"方式分发 SDK 的工程结构。

Failure Modes, Edge Cases & Concurrency

以下条目分为两类：已由仓库文档确认的约束与基于集成流程的合理推断（推断项已明确标注）。

已确认的约束（来自 README）

• 缺少蓝牙权限：未配置 Privacy - Bluetooth Peripheral/Always Usage Description（README.md L114）时，系统不会向 App 提供扫描结果，广播解析链路在第一步即不可用。
• 非 RCSP 设备：硬件要求"支持杰理 RCSP 协议的 SDK"（README.md L76）。扫描到不满足协议能力的设备时，广播解析无法识别为可交互的杰理设备。
• 低版本系统：iOS 低于 10.0 不在支持范围内，BLE 能力与权限模型可能不完整。

推断项（基于集成流程）

• 认证失败/超时（推断）：若设备在认证/协议握手阶段无响应或固件版本过旧，连接流程将失败；App 应回退到重新扫描或提示用户。具体错误码定义在二进制 SDK 内，仓库未提供。
• 扫描与连接的并发（推断）：扫描回调与连接建立事件可能并发到达；SDK 内部对设备实体做状态管理，App 侧应避免在回调中做耗时操作。
• 广播丢包（推断）：BLE 广播本身不可靠，可能需多次广播周期才能解析完整；这是 BLE 协议固有特性，SDK 通常会在扫描持续期间累积解析。

Performance & Operational Considerations

• 按需扫描：扫描是耗电且干扰连接的 BLE 操作。建议 App 在进入设备列表页时开始扫描、离开时停止，避免长时间后台扫描。
• 认证前置：设备认证在连接阶段一次性完成，后续所有功能模块复用同一协议通道（见架构图），这是 SDK 保证性能的关键设计——避免了每个功能调用重复握手的开销。
• 权限提示时机：蓝牙权限申请应放在首次扫描之前，权限被拒后系统不会再次弹窗，需引导用户到系统设置开启。

Extension Points

• 自定义命令：README 功能列表包含"自定义命令：支持客户拓展功能"（README.md L63）。在广播解析识别出设备、认证建立协议通道之后，客户可通过自定义命令在 RCSP 协议之上扩展私有功能——这是本能力最重要的扩展点。
• 功能模块扩展：健康数据、消息同步、天气、联系人、闹钟等上层功能均在认证后的协议通道上叠加（README.md 功能列表），新增产品形态时只需复用既有解析/认证链路。

Related Links

• README.md（项目总览与快速开始）
• README_EN.md（英文版说明）
• 官方文档中心：iOS 健康 SDK
• 相关目录页：OTA 升级（JL_OTALib）、表盘管理（JLDialUnit）、健康数据同步、音频编解码（JLAudioUnitKit）——这些能力均建立在本文所述"广播解析 → 认证 → 连接"链路之上。