JL_BLEKit SDK 连接

JL_BLEKit 是杰理科技（Jieli Tech）面向 iOS 平台的蓝牙 SDK，本页围绕 SDK 的引入、模块结构与设备连接机制 展开，说明如何通过 JL_BLEMultiple 扫描、JL_EntityM 设备实体、JL_ManagerM 管理器完成与杰理蓝牙芯片设备的连接，并梳理 SDK 各功能管理器与数据模型的职责边界。

Purpose and Scope

本页覆盖以下内容：

• JL_BLEKit 框架在仓库中的存在形式（.xcframework / .framework）与集成方式
• SDK 的模块化结构：基础层、连接核心层、功能管理器层、数据模型层、可穿戴层
• 设备连接的端到端机制：扫描 → 设备实体 → 连接 → 管理器 → 功能分发
• Demo 工程（JLBleKitOTADemo、JLAssistOTADemo）中的连接相关入口

以下主题属于相邻页面，不在本页展开：

• OTA 升级流程（JL_OTA 相关实现、固件推送与升级协议）—— 属于 OTA 升级能力页面
• JL_Assist 辅助工具的详细使用 —— 属于 JL_Assist 页面
• 各功能管理器的具体协议细节（如 JL_TwsManager、JL_AlarmClockManager）—— 属于各自功能页面

Overview

JL_BLEKit 是一个以 CoreBluetooth 为基础、以杰理私有协议（RCSP）为上层协议 的蓝牙通信 SDK。它将"扫描、连接、鉴权、指令收发、功能控制"分层封装，上层业务（如 OTA 升级、音乐控制、闹钟、翻译）只需面向 JL_ManagerM 与各功能管理器编程，而不必直接处理 CBCentralManager、CBPeripheral 和 GATT 特性（Characteristic）细节。

仓库中 SDK 的权威入口是 JL_BLEKit.h，它是整个框架的伞头文件（umbrella header），按层次导入了全部公开头文件：

Source: JL_BLEKit.h

#import <JL_BLEKit/JL_Tools.h>
#import <JL_BLEKit/JL_RCSP.h>
#import <JL_BLEKit/JL_OpCode.h>
#import <JL_BLEKit/JL_Handle.h>
#import <JL_BLEKit/JL_BLEAction.h>
#import <JL_BLEKit/JL_vad.h>
#import <JL_BLEKit/JL_TypeEnum.h>
#import <JL_BLEKit/JLTaskChain.h>
#import <JL_BLEKit/JLEcTimerHelper.h>

#import <JL_BLEKit/JLModel_Device.h>
// ... 各数据模型 ...
#import <JL_BLEKit/JL_BLEMultiple.h>
#import <JL_BLEKit/JL_EntityM.h>
#import <JL_BLEKit/JL_ManagerM.h>
#import <JL_BLEKit/JL_Assist.h>

#import <JL_BLEKit/JL_FunctionBaseManager.h>
#import <JL_BLEKit/JL_FileManager.h>
// ... 各功能管理器 ...

从导入顺序可以清晰看到 SDK 的分层设计：先基础工具（JL_Tools、JL_RCSP、JL_OpCode），再数据模型（JLModel_*），然后是连接核心（JL_BLEMultiple、JL_EntityM、JL_ManagerM、JL_Assist），最后是功能管理器与可穿戴健康数据模块。

Architecture

SDK 分层架构

flowchart TD
    subgraph sg_App["上层业务 (App / Demo)"]
        OTA["OTA 升级业务"]
        MUSIC["音乐/闹钟/翻译等业务"]
        WEAR["可穿戴健康业务"]
    end

    subgraph sg_Core["连接核心层"]
        BLEM["JL_BLEMultiple<br/>扫描/外设管理"]
        ENT["JL_EntityM<br/>设备实体"]
        MGR["JL_ManagerM<br/>连接管理器"]
        ASSIST["JL_Assist<br/>辅助连接/OTA助手"]
    end

    subgraph sg_Func["功能管理器层"]
        FUNC_BASE["JL_FunctionBaseManager"]
        FUNCS["JL_FileManager / JL_FlashOperateManager /<br/>JL_CallManager / JL_AlarmClockManager /<br/>JL_TwsManager / JL_MusicControlManager /<br/>JL_FmManager / JL_SystemEQ ..."]
        SDM["JLWearable / JL_SDM_* 健康数据"]
    end

    subgraph sg_Proto["协议与基础层"]
        RCSP["JL_RCSP (私有协议)"]
        OP["JL_OpCode (指令码)"]
        HANDLE["JL_Handle (数据收发)"]
        ACTION["JL_BLEAction"]
        TOOLS["JL_Tools / JLTaskChain /<br/>JLEcTimerHelper / ECThreadHelper"]
    end

    subgraph sg_BLE["系统蓝牙层"]
        CB["CoreBluetooth (CBCentralManager / CBPeripheral)"]
    end

    OTA --> MGR
    MUSIC --> MGR
    WEAR --> SDM
    MGR --> ENT
    MGR --> BLEM
    BLEM --> CB
    ASSIST --> BLEM
    MGR --> FUNC_BASE
    FUNC_BASE --> FUNCS
    FUNCS --> HANDLE
    SDM --> HANDLE
    ENT --> HANDLE
    HANDLE --> OP
    OP --> RCSP
    RCSP --> TOOLS
    HANDLE --> ACTION

各层职责说明

设计意图

• 分层解耦：上层业务不感知 CoreBluetooth 细节；协议层（JL_RCSP/JL_OpCode）独立于连接层，便于协议演进。
• 管理器聚合：所有功能指令通过 JL_ManagerM 统一入口分发，业务方只需持有一个管理器实例即可访问全部功能，避免重复建立连接。
• 任务链串行化：JLTaskChain 的存在表明 SDK 将"多发一收"的 RCSP 交互组织为串行任务链，防止指令交错导致协议错乱——这对 OTA 等强时序场景至关重要。

连接机制详解

1. 设备扫描与发现：JL_BLEMultiple

JL_BLEMultiple 是 SDK 对 CBCentralManager 的封装，负责系统蓝牙权限管理、外设扫描与列表维护。它向连接核心层提供"当前可发现设备"的统一视图，并屏蔽了 CoreBluetooth 的 delegate 回调矩阵。业务层通过它获取设备列表后，从中挑选目标设备交给连接流程。

2. 设备实体：JL_EntityM

JL_EntityM（Entity Manager）是 一台设备的完整抽象，它封装了设备的 CBPeripheral、广播信息、连接状态，以及该设备对应的指令收发上下文。在 SDK 的多设备（如 TWS 耳机左右耳）场景下，每个设备对应一个独立的 JL_EntityM 实例，从而支持一主多从的连接拓扑。

3. 连接管理器：JL_ManagerM

JL_ManagerM 是连接建立后业务访问的总入口，它持有当前活动设备实体，并向 JL_FunctionBaseManager 体系分发指令。典型连接流程中，扫描到设备后由外部调用连接方法，连接成功回调中拿到 JL_ManagerM 实例，之后所有功能调用（文件管理、闹钟、EQ、翻译等）都经由该实例完成。

4. 辅助连接：JL_Assist

JL_Assist 提供面向特定业务场景（典型如 OTA 升级）的辅助连接/管理能力，与 JL_ManagerM 形成互补：JL_ManagerM 面向常规功能交互，JL_Assist 面向升级等专用流程。仓库中 code/MiniDemo/JLAssistOTADemo 即演示了基于 JL_Assist 的 OTA 辅助开发方式。

5. 连接状态流转

连接过程在 SDK 内部的状态流转可以概括为：

stateDiagram-v2
    [*] --> 待扫描: 初始化 JL_BLEMultiple
    待扫描 --> 已发现: 扫描到设备(生成 JL_EntityM)
    已发现 --> 连接中: 发起连接
    连接中 --> 已连接: 连接成功(获取 JL_ManagerM)
    连接中 --> 连接失败: 超时/拒绝
    连接失败 --> 已发现: 可重试
    已连接 --> 鉴权/协议握手: RCSP 就绪
    鉴权/协议握手 --> 功能就绪: 设备能力加载完成
    功能就绪 --> 已断开: 断连/系统回调
    已断开 --> 已发现: 重新扫描连接

说明：以上状态流转基于 SDK 分层结构（扫描层 → 实体层 → 管理器层 → 功能层）推导的典型连接生命周期；具体状态枚举与回调方法签名定义于框架头文件 JL_TypeEnum.h 与 JL_EntityM.h/JL_ManagerM.h 中，集成时可查阅对应头文件确认精确 API。

Core Flow：一次完整连接的时序

以下时序图展示从初始化 SDK 到功能就绪的完整连接链路（基于仓库中 SDK 的层次结构绘制）：

sequenceDiagram
    participant APP as App/业务层
    participant BLEM as JL_BLEMultiple
    participant CB as CoreBluetooth
    participant ENT as JL_EntityM
    participant MGR as JL_ManagerM
    participant FUNC as 功能管理器

    APP->>BLEM: 初始化/开始扫描
    BLEM->>CB: startScan (CBCentralManager)
    CB-->>BLEM: 发现外设 (didDiscover)
    BLEM-->>APP: 设备列表更新 (JL_EntityM 候选)
    APP->>ENT: 选择目标设备并连接
    ENT->>CB: connectPeripheral
    CB-->>ENT: 连接成功 (didConnect)
    ENT-->>MGR: 建立 JL_ManagerM 实例
    MGR->>FUNC: 分发能力/加载设备信息
    FUNC-->>MGR: 设备模型就绪 (JLModel_Device 等)
    MGR-->>APP: 连接完成回调
    APP->>FUNC: 业务调用 (文件/闹钟/EQ/OTA...)

关键点说明：

1. 扫描阶段：JL_BLEMultiple 是唯一直接接触 CoreBluetooth 的类，业务层不应自行持有 CBCentralManager，否则会与 SDK 的系统回调冲突。
2. 实体选择：扫描结果以 JL_EntityM 形式暴露，业务层可依据设备名/广播信息过滤出目标设备。
3. 连接与实例化：连接成功后 JL_ManagerM 才可用；在连接建立前调用功能管理器接口无效。
4. 功能分发：JL_FunctionBaseManager 是所有功能管理器的基类，连接后按需实例化/调用，指令经 JL_Handle → JL_OpCode → JL_RCSP 编码后下发到设备。

使用示例（Demo 工程）

仓库提供了两个与 SDK 连接相关的官方 Demo，可作为集成参考：

其中 JLBleKitOTADemo 目录下包含连接接入文档 OTA升级开发示例(SDK蓝牙连接).md，以及 Podfile（表明 Demo 通过 CocoaPods 管理依赖，并锁定于 Podfile.lock）。

SDK 引入方式（示例）

在业务工程中通过伞头文件引入 SDK，即可使用全部公开 API：

// 引入 JL_BLEKit 全部公开接口
#import <JL_BLEKit/JL_BLEKit.h>

// 连接相关核心头文件亦可按需单独引入
#import <JL_BLEKit/JL_BLEMultiple.h>   // 扫描/外设管理
#import <JL_BLEKit/JL_EntityM.h>       // 设备实体
#import <JL_BLEKit/JL_ManagerM.h>      // 连接管理器
#import <JL_BLEKit/JL_Assist.h>        // 辅助连接

上例的结构源自仓库伞头文件 JL_BLEKit.h 的公开导入声明；具体的初始化参数与回调签名请以框架头文件为准。

配置选项与集成清单

仓库中 JL_BLEKit 以预编译二进制形式提供，支持的构建产物如下：

集成要点：

1. 主工程统一使用 .xcframework，同时包含真机（ios-arm64）与模拟器（ios-arm64_x86_64-simulator）切片，避免重复打包。
2. 引入后需在 App 的 Info.plist 中配置蓝牙使用权限描述（NSBluetoothAlwaysUsageDescription，系统 CoreBluetooth 要求），否则扫描/连接无法进行。
3. SDK 依赖系统框架 CoreBluetooth.framework，工程需显式链接。
4. JLBleKitOTADemo 通过 CocoaPods 管理第三方依赖（见 Podfile / Podfile.lock），主工程若使用其他依赖管理方式需自行处理冲突。

说明：权限配置与系统框架链接是 CoreBluetooth 集成的基本要求；仓库源码中未包含 Info.plist 内容，具体键值请按 Apple 文档配置。

API Reference（核心类型速览）

以下为核心连接层的公开类型清单，均已在伞头文件中验证存在；精确的方法签名、参数与回调请查阅框架对应头文件。

JL_BLEMultiple

• 职责：扫描管理、外设列表维护、系统蓝牙状态处理
• 关键能力：开始/停止扫描、获取发现的设备（JL_EntityM 集合）、设备连接入口

JL_EntityM

• 职责：单台设备实体，封装 CBPeripheral 与设备级上下文
• 关键能力：连接状态表示、设备信息（名称/地址/广播数据）、指令收发上下文

JL_ManagerM

• 职责：连接后的总管理器，功能指令分发入口
• 关键能力：访问功能管理器、设备模型（JLModel_Device）、断连通知

JL_Assist

• 职责：面向 OTA 等专用场景的辅助连接管理
• 关键能力：辅助升级流程的会话管理

JL_FunctionBaseManager（及子类）

• 职责：功能管理器基类，子类包括 JL_FileManager、JL_FlashOperateManager、JL_CallManager、JL_AlarmClockManager、JL_LightManager、JL_TwsManager、JL_MusicControlManager、JL_FmManager、JL_SystemEQ、JL_SystemTime、JL_SystemVolume、JL_CustomManager、JL_BatchManger、JL_DeviceLogs、JL_BigDataManager 等
• 关键能力：按功能域封装 RCSP 指令

本页为连接能力概览，各 API 的精确签名（- (void)scan...、- (void)connectEntity:...、回调 block 等）定义于 JL_BLEMultiple.h、JL_EntityM.h、JL_ManagerM.h、JL_Assist.h 中，集成时请直接阅读框架头文件获取权威定义。

Failure Modes、边界情况与并发注意

失败模式

边界情况

• 多设备拓扑：TWS 等一主多从场景下，每个设备独立 JL_EntityM，需区分主/从实体再下发指令。
• 模拟器调试：ios-arm64_x86_64-simulator 切片仅供编译通过，蓝牙功能在模拟器上受限，功能验证应在真机进行。
• Beta 产物差异：libs/BetaBuild 下的 framework 为测试构建，正式集成应使用 code/JL_OTA/Frameworks 下的 xcframework。

并发与时序

• 指令串行化：SDK 通过 JLTaskChain 将指令组织为任务链，业务层不应绕过任务链自行并发收发，否则可能破坏 RCSP 的请求-应答配对。
• 主线程约束：UIKit 相关回调应在主线程处理；JL_Tools/ECThreadHelper 提供线程辅助，供耗时的数据解析在后台线程执行。
• 连接生命周期：JL_ManagerM 在连接断开后失效，业务层不得缓存使用；每次重连需重新获取管理器实例。

性能与运维注意

• 扫描功耗：持续扫描耗电，建议扫描到目标设备后即停止扫描（JL_BLEMultiple 提供对应能力）。
• 指令频率：大批量文件操作（JL_FileManager、JL_FlashOperateManager）依赖任务链逐条确认，单条指令的往返延迟决定整体吞吐，避免无节制地短间隔发包。
• 日志与排查：JL_DeviceLogs、JL_BigDataManager 可辅助采集设备日志与运行数据，便于 OTA 与连接问题定位。

Extension Points（扩展点）

• 功能管理器子类化：JL_FunctionBaseManager 是功能域扩展的基类，新增设备功能时按其模式新增子类并在伞头文件注册。
• 自定义指令：底层 JL_OpCode + JL_RCSP 支持业务自定义指令码，适用于 SDK 未覆盖的设备私有功能。
• 表盘/翻译/健康扩展：JLDialInfoExtentManager、JLTranslationManager、JLWearable/JL_SDM_* 是独立扩展域，可单独集成而不影响连接核心。

Related Links

• JL_BLEKit 伞头文件（模块清单）
• JLBleKitOTADemo（SDK 蓝牙连接 + OTA 示例）
• OTA升级开发示例(SDK蓝牙连接).md
• JLAssistOTADemo（JL_Assist 辅助连接示例）
• JLBleKitOTADemo Podfile
• libs/BetaBuild 产物目录

相邻能力页面：OTA 升级流程、JL_Assist 工具、各功能管理器（TWS、闹钟、翻译、健康数据等）请参见对应目录页。