JL_BLEKit 蓝牙通信核心

JL_BLEKit 是杰理（JieLi）面向 iOS 平台发布的蓝牙通信 SDK 核心库，以 XCFramework 二进制形式分发，封装了从 BLE 扫描/连接、协议封装（RCSP）、设备管理（JL_EntityM / JL_ManagerM）到 TWS、翻译、穿戴健康、Auracast 等上百个功能模块的完整蓝牙通信链路。

Purpose and Scope

本页面围绕 JL_BLEKit 蓝牙通信核心 这一目录项，说明 SDK 的整体架构、模块组成、核心对象模型（JL_BLEMultiple / JL_EntityM / JL_ManagerM）、典型连接与命令控制流程，以及 Demo 工程中的真实用法。

本页面不深入以下主题（由同级目录页分别覆盖）：

具体业务功能管理器（如文件管理、TWS、翻译、EQ 调音）的内部实现细节——本文只说明它们在 SDK 中的位置与调用入口；
Demo App 的完整 UI 交互逻辑；
4G 升级、声卡等外围扩展能力的独立文档。

Overview

什么是 JL_BLEKit

JL_BLEKit 是杰理芯片（如 AC69 系列、TWS 耳机、穿戴手表、音箱等）在 iOS 端的官方蓝牙 SDK。它不是一个开源源码库，而是以 JL_BLEKit.xcframework 二进制分发的闭源库，工程通过引入 .framework/Headers/JL_BLEKit.h 单一头文件获得全部 API。

从主头文件可以看出，SDK 按职责被拆分为四类模块：

基础工具层：JL_Tools、JL_Handle、JL_BLEAction、JLTaskChain、JLEcTimerHelper、ECThreadHelper 等，负责线程调度、任务链、定时器与底层动作；
协议与命令层：JL_RCSP（RCSP 协议）、JL_OpCode（操作码）、JLCmdBasic（基础命令），负责命令字编解码；
数据模型层：JLModel_Device、JLModel_Headset、JLModel_EQ、JLModel_ANC、JLSportDataModel 等 40+ 个模型类，描述设备信息、状态与配置；
管理器层：核心管理器 JL_BLEMultiple（多连接管理）、JL_EntityM（设备实体）、JL_ManagerM（命令管理器），以及 JL_FileManager、JL_TwsManager、JLTranslationManager、JLWearable、JLAuracastManager 等功能管理器。

设计意图（WHY）

单一头文件聚合：JL_BLEKit.h 以约 130 个 #import 聚合全部子模块，开发者只需 import <JL_BLEKit/JL_BLEKit.h> 即可使用所有能力，降低集成成本；
实体 + 管理器分离：JL_EntityM 描述“一个具体的设备”（外设、RSSI、连接状态、命令管理器），JL_ManagerM 是“对这台设备发命令的通道”，JL_BLEMultiple 管理“多台设备的生命周期”。这种分层让多设备并发连接成为可能，也便于扩展新设备类型；
二进制分发 + 稳定头文件：闭源二进制保护协议实现细节，同时公开稳定的 Objective-C 头文件接口，便于 Demo 工程（JieLi_Home_Demo）与测试工具（SDKTestHelper）跨架构（真机 arm64 / 模拟器 arm64_x86_64）复用。

使用场景

杰理耳机/音箱/穿戴设备的扫描、配对、连接与断连管理；
通过 RCSP 协议下发控制命令（播放控制、EQ、ANC、闹钟、灯光等）；
文件系统操作（JL_FileManager）、Flash 读写（JL_FlashOperateManager）；
TWS 耳机状态同步（JL_TwsManager）、健康数据（JLWearable 及 JL_SDM_* 系列）；
翻译、语音（JLTranslationManager、JL_SpeechAIttsHandler）与 Auracast 广播（JLAuracastManager）。

Architecture

下图展示了 JL_BLEKit 在 iOS 工程中的分层架构，以及 Demo 工程如何通过单例封装与 SDK 交互：

flowchart TD
    subgraph sg_App["应用层 (JieLi_Home_Demo)"]
        AppDelegate["AppDelegate.m<br/>(NSNotification 监听)"]
        RunSDK["JL_RunSDK.m<br/>(SDK 单例封装)"]
        Preparation["JLPreparation.m<br/>(连接准备/命令下发)"]
    end

    subgraph sg_SDK["JL_BLEKit.xcframework"]
        subgraph sg_Core["核心管理器"]
            BLEMultiple["JL_BLEMultiple<br/>(多设备连接管理)"]
            EntityM["JL_EntityM<br/>(设备实体)"]
            ManagerM["JL_ManagerM<br/>(命令管理器)"]
            Assist["JL_Assist"]
        end
        subgraph sg_Proto["协议与基础"]
            RCSP["JL_RCSP 协议"]
            OpCode["JL_OpCode 操作码"]
            CmdBasic["JLCmdBasic 基础命令"]
            TaskChain["JLTaskChain 任务链"]
        end
        subgraph sg_Func["功能管理器"]
            FuncBase["JL_FunctionBaseManager"]
            FileMgr["JL_FileManager"]
            TwsMgr["JL_TwsManager"]
            TransMgr["JLTranslationManager"]
            Wearable["JLWearable"]
            AuracastMgr["JLAuracastManager"]
        end
        subgraph sg_Model["数据模型"]
            ModelDev["JLModel_Device"]
            ModelHeadset["JLModel_Headset"]
            ModelEQ["JLModel_EQ"]
            SportModel["JLSportDataModel"]
        end
    end

    subgraph sg_System["系统层"]
        CoreBluetooth["CoreBluetooth"]
        Device["杰理蓝牙设备"]
    end

    AppDelegate -->|"通知: note.object"| RunSDK
    RunSDK -->|"mBleEntityM / mBleMultiple"| BLEMultiple
    Preparation -->|"mCmdManager 发命令"| ManagerM
    BLEMultiple --> EntityM
    EntityM -->|"mCmdManager"| ManagerM
    ManagerM --> RCSP
    RCSP --> OpCode
    CmdBasic --> TaskChain
    ManagerM --> FuncBase
    FuncBase --> FileMgr
    FuncBase --> TwsMgr
    FuncBase --> TransMgr
    FuncBase --> Wearable
    FuncBase --> AuracastMgr
    EntityM --> ModelDev
    ManagerM --> ModelHeadset
    ManagerM --> ModelEQ
    Wearable --> SportModel
    BLEMultiple -->|"CBCentralManager"| CoreBluetooth
    CoreBluetooth -->|"BLE 链路"| Device

架构说明：

应用层通过 JL_RunSDK（单例）持有 SDK 的 JL_BLEMultiple 实例；AppDelegate 通过 NSNotificationCenter 接收设备状态变化，通知的 object 就是 JL_EntityM，可直接读取 mRSSI 等属性；
核心管理器是 SDK 的中枢：JL_BLEMultiple 负责扫描与多设备连接，JL_EntityM 代表单台设备（含 mCmdManager 命令通道），JL_ManagerM 把业务调用翻译成 RCSP 协议命令；
协议与基础层保证命令的可靠性：JL_RCSP 处理命令字封装，JL_OpCode 定义操作码，JLTaskChain 以任务链串行化命令，避免并发冲突；
功能管理器继承自 JL_FunctionBaseManager，全部挂在 JL_ManagerM 之下，按业务域（文件、TWS、翻译、穿戴、Auracast）横向扩展；
数据模型层是命令的“参数对象”，例如 JLModel_EQ 承载 EQ 参数、JLSportDataModel 承载运动数据，模型与命令一一对应。

再往下是全部功能管理器（文件、小文件、Flash、充电盒、通话、闹钟、灯效、TWS、翻译、声卡、歌词、Speex、语音、音乐控制、FM、系统 EQ/时间/音量、自定义、批量、日志、DHA 助听、ANC 自适配、设备配置、大数据、AI、穿戴、Auracast 等，JL_BLEKit.h#L52-L137）。头文件还导出了 JL_BLEKitVersionNumber / JL_BLEKitVersionString（JL_BLEKit.h#L12-L15）用于版本校验。

设计意图：头文件按“基础 → 模型 → 核心 → 功能”的顺序组织导入，既保证了编译顺序正确，也向集成者传递了依赖层级——功能管理器依赖核心管理器，核心管理器依赖协议与基础层。

JL_EntityM —— 设备实体

JL_EntityM 是 SDK 中“一台设备”的抽象。Demo 中通过 JL_RunSDK 单例持有当前设备实体（JL_RunSDK.m#L89-L91）：

-(JL_EntityM *)mBleEntityM{
    return _mBleEntityM;
}

Source: JL_RunSDK.m

实体上承载了设备的核心信息与命令通道：

成员	含义
`mPeripheral`	CoreBluetooth 的 `CBPeripheral`，对应 BLE 链路层外设
`mRSSI`	信号强度，用于扫描列表排序与断连判定
`mCmdManager`（`JL_ManagerM`）	向该设备下发命令的管理器
`mEntityStatus`（`JL_EntityM_Status`）	实体连接状态枚举（如 `JL_EntityM_StatusDisconnectOk`）

JL_ManagerM —— 命令管理器

JL_ManagerM 是命令下发的中枢，通过 entity.mCmdManager 获取。Demo 的 JLPreparation.m 展示了获取管理器后构造 JLTaskChain 任务链的典型用法（JLPreparation.m#L272-L274）：

JL_ManagerM *mgr = self.mBleEntityM.mCmdManager;
JLTaskChain *chain = [JLTaskChain new];

Source: JLPreparation.m

JLTaskChain 的存在说明 SDK 内部采用串行任务链机制：多条命令按顺序排队下发，避免 BLE 链路吞吐有限时命令交叉导致响应错乱。

JL_BLEMultiple —— 多设备连接管理

JL_BLEMultiple 负责扫描、连接与多设备维护。JL_RunSDK 中遍历已连接设备列表的代码（JL_RunSDK.m#L151-L153）：

NSMutableArray *mConnectArr = [self sharedMe].mBleMultiple.bleConnectedArr;
for (JL_EntityM *entity in mConnectArr) {
    NSString *inUnid = entity.mPeripheral.identifier.UUIDString;
    // 按 UUID 匹配已连接设备
}

Source: JL_RunSDK.m

断开连接使用异步回调返回状态（JLPreparation.m#L415-L417）：

[bleSDK.mBleMultiple disconnectEntity:self.mBleEntityM Result:^(JL_EntityM_Status status) {
    if (status == JL_EntityM_StatusDisconnectOk) {
        // 断开成功，更新 UI 状态
    }
}];

Source: JLPreparation.m

事件通知机制

SDK 通过 NSNotificationCenter 向外广播设备状态。AppDelegate.m 接收通知并取出实体（AppDelegate.m#L224-L226）：

-(void)noteBleStatusAlert:(NSNotification*)note{
    JL_EntityM *entity = note.object;
    NSNumber *rssi = entity.mRSSI;
    // 根据通知名与 entity 状态刷新界面
}

Source: AppDelegate.m

JL_RunSDK 还提供了状态枚举到文本的映射工具（JL_RunSDK.m#L166-L168）：

+(NSString *)textEntityStatus:(JL_EntityM_Status)status{
    if (status<0) return @"未知错误";
    // 按枚举值映射为可读文本
}

Source: JL_RunSDK.m

核心流程

设备连接与命令控制流程

sequenceDiagram
    participant App as 应用层 (JL_RunSDK)
    participant BM as JL_BLEMultiple
    participant CB as CoreBluetooth
    participant Dev as 杰理设备
    participant EM as JL_EntityM
    participant MM as JL_ManagerM

    App->>BM: 开始扫描 (scan)
    BM->>CB: CBCentralManager scanForPeripherals
    CB-->>BM: 发现外设 (RSSI/广播)
    BM-->>App: 回调设备列表 (JL_EntityM)
    App->>BM: connectEntity: 发起连接
    BM->>CB: connectPeripheral
    CB-->>BM: 连接成功回调
    BM->>EM: 创建/更新 JL_EntityM (mCmdManager)
    BM-->>App: 通知 (note.object = entity)
    App->>MM: entity.mCmdManager 下发命令
    MM->>Dev: RCSP 命令帧 (OpCode)
    Dev-->>MM: 应答帧
    MM-->>App: 命令结果回调
    App->>BM: disconnectEntity:Result:
    BM->>CB: cancelPeripheralConnection
    CB-->>BM: 断开回调
    BM-->>App: JL_EntityM_StatusDisconnectOk

流程说明：

扫描：JL_BLEMultiple 包装 CBCentralManager，把发现的外设包装为 JL_EntityM 列表返回；
连接：连接成功后实体被赋予 mCmdManager，此时实体才是“可用”状态；
命令：所有业务命令统一走 entity.mCmdManager，经 JL_RCSP + JL_OpCode 封装为协议帧下发，并通过 JLTaskChain 串行化；
事件：状态变化通过 NSNotification 广播，AppDelegate 等监听者从 note.object 取回 JL_EntityM 刷新 UI；
断开：disconnectEntity:Result: 异步回调 JL_EntityM_StatusDisconnectOk，业务层在此清理状态。

实体状态流转

stateDiagram-v2
    [*] --> 扫描中: startScan
    扫描中 --> 已发现: 发现外设
    已发现 --> 连接中: connectEntity
    连接中 --> 已连接: 连接成功 + mCmdManager 就绪
    连接中 --> 连接失败: 超时/拒绝
    已连接 --> 命令交互: mCmdManager 下发 RCSP
    命令交互 --> 已连接: 应答完成
    已连接 --> 断开中: disconnectEntity
    断开中 --> 已断开: JL_EntityM_StatusDisconnectOk
    连接失败 --> 扫描中: 重试
    已断开 --> 扫描中: 重新扫描

设计意图：状态机将“设备生命周期”显式化——业务层只需关注 JL_EntityM_Status 枚举（如 DisconnectOk），而把 BLE 层的异步细节（连接超时、断连重连）收敛在 JL_BLEMultiple 内部，这也是 textEntityStatus: 工具方法存在的意义：把枚举直接映射为用户可读文案。

集成方式

JL_BLEKit 以 XCFramework 形式集成，仓库内包含多份副本，供不同工程/架构使用：

位置	说明
`libs/JL_BLEKit.xcframework`	仓库根目录的 SDK 主副本
`code/JieLi_Home_Demo/Frameworks/JL_BLEKit.xcframework`	智能家居 Demo 工程引用副本
`code/JieLi_Home_Demo/NewJieliZhiNeng/JL_BLEKit.framework`	Demo 中旧式单 framework 副本
`code/SDKTestHelper/Code/SDKTestHelper/Frameworks/...`	SDK 测试工具引用副本
`code/SDKTestHelper/Libs/JL_BLEKit.xcframework`	SDK 测试工具备用库副本

XCFramework 内含两个 slice：

ios-arm64：真机（iPhone/iPad）架构；
ios-arm64_x86_64-simulator：模拟器架构（Apple Silicon 原生 arm64 模拟器 + Intel x86_64 模拟器均支持）。

集成时在 Xcode 的 General → Frameworks, Libraries, and Embedded Content 中导入 JL_BLEKit.xcframework，并在源码中 #import <JL_BLEKit/JL_BLEKit.h> 即可。

使用示例

示例 1：获取当前设备实体并判断 EDR 连接状态

JL_RunSDK 单例是 Demo 与 SDK 之间的适配层。isConnectedEdr: 类方法演示了如何基于 JL_EntityM 判断经典蓝牙（EDR）连接，这是 TWS/通话等特性生效的前提：

+(BOOL)isConnectedEdr:(JL_EntityM *)entity{
    // 通过实体内部状态判断 EDR 是否已连接
    return YES;
}

Source: JL_RunSDK.m

示例 2：通过实体命令管理器发起任务链

连接完成后，业务代码从实体取出 mCmdManager，用 JLTaskChain 组织一连串初始化命令（读设备信息、同步时间、配置等）。任务链保证命令按序执行，避免 BLE 小包链路上的乱序问题：

JL_ManagerM *mgr = self.mBleEntityM.mCmdManager;
JLTaskChain *chain = [JLTaskChain new];
// chain 中依次添加需要串行执行的命令任务

Source: JLPreparation.m

示例 3：监听蓝牙状态通知并读取信号强度

AppDelegate 注册通知，收到事件后从 note.object 取出 JL_EntityM，读取 mRSSI 用于信号显示或断连预警：

-(void)noteBleStatusAlert:(NSNotification*)note{
    JL_EntityM *entity = note.object;
    NSNumber *rssi = entity.mRSSI;
    // 刷新信号强度 UI / 触发弱信号告警
}

Source: AppDelegate.m

示例 4：遍历已连接设备列表

多设备场景（如同时连接耳机与音箱）下，通过 mBleMultiple.bleConnectedArr 获取所有已连接实体，按 mPeripheral.identifier.UUIDString 定位目标设备：

NSMutableArray *mConnectArr = [self sharedMe].mBleMultiple.bleConnectedArr;
for (JL_EntityM *entity in mConnectArr) {
    NSString *inUnid = entity.mPeripheral.identifier.UUIDString;
    // 按 UUID 匹配目标设备并操作
}

Source: JL_RunSDK.m

示例 5：断开连接并处理结果

断开是异步操作，结果通过 block 回调返回 JL_EntityM_Status：

[bleSDK.mBleMultiple disconnectEntity:self.mBleEntityM Result:^(JL_EntityM_Status status) {
    if (status == JL_EntityM_StatusDisconnectOk) {
        // 断开成功，回到扫描界面
    }
}];

Source: JLPreparation.m

配置选项

JL_BLEKit 作为二进制 SDK，其配置主要通过头文件常量、初始化参数与实体属性暴露，而非配置文件。从主头文件可见的配置面包括：

配置面	类型	说明
`JL_BLEKitVersionNumber` / `JL_BLEKitVersionString`	double / string	SDK 版本号，用于与固件/后台做版本匹配
`JL_EntityM.mRSSI`	NSNumber	信号强度阈值判断（弱信号告警/断连判定）
`JL_EntityM.mPeripheral`	CBPeripheral	底层外设引用，可读取广播数据/UUID
`JL_EntityM.mCmdManager`	JL_ManagerM	命令通道配置（超时、重试依赖其内部策略）
`JL_BLEMultiple.bleConnectedArr`	NSMutableArray	多连接管理，可查询/遍历已连接实体

说明：具体功能管理器（如 JL_SystemEQ、JL_SystemVolume、JLDeviceConfig）的配置项属于各自功能域，由对应子页或 SDK 头文件定义；SDK 二进制内的运行参数（扫描间隔、连接超时、命令重试次数等）未在公开头文件中暴露，如需调整请咨询杰理官方 SDK 支持。

API 参考（核心对象）

以下签名基于公开头文件导入关系与 Demo 实际调用整理；SDK 为闭源二进制，内部实现细节以官方头文件注释为准。

`JL_BLEMultiple`

多设备 BLE 连接管理器，SDK 的入口对象。

常用接口（Demo 已验证）：

方法	说明
`connectEntity:...`	连接指定 `JL_EntityM`
`disconnectEntity:Result:(void(^)(JL_EntityM_Status status))`	断开连接，异步回调状态
`bleConnectedArr`	已连接实体数组（可遍历）

`JL_EntityM`

单台设备的实体模型。

属性：

mPeripheral (CBPeripheral)：底层 BLE 外设；
mRSSI (NSNumber)：实时信号强度；
mCmdManager (JL_ManagerM)：该设备的命令管理器；
状态枚举 JL_EntityM_Status：定义连接生命周期（含 JL_EntityM_StatusDisconnectOk 等）。

Throws/回调：连接与命令均为异步回调模式，无异常抛出；错误通过状态枚举与通知携带。

`JL_ManagerM`

单设备命令管理器，所有业务命令的出口。

核心能力：

承载 JL_FunctionBaseManager 派生的各功能管理器（文件、TWS、翻译、穿戴等）；
通过 JL_RCSP 协议封装命令、以 JL_OpCode 区分命令字；
配合 JLTaskChain 串行执行命令队列。

连接中失败（超时、设备拒绝）时实体状态回到可重试状态，Demo 通过 textEntityStatus: 将状态映射为中文文案（如“未知错误”）提示用户；
断连后业务层须在 JL_EntityM_StatusDisconnectOk 回调中释放 mCmdManager 引用，避免悬挂指针。

多设备并发

JL_BLEMultiple 支持多实体并存，bleConnectedArr 中每个实体的 mCmdManager 相互独立；
多设备同时下发命令时，命令必须走各自实体的 mCmdManager，不可跨实体复用，否则会造成命令错乱；
单设备内命令并发通过 JLTaskChain 串行化——这是 SDK 明确的设计约束，业务层不应绕过任务链直接并发发命令。

RSSI 与弱信号

mRSSI 随广播/连接更新，弱信号下命令应答可能超时，SDK 内部按命令超时重试策略处理（未公开参数）；
Demo 中通知回调读取 mRSSI 用于 UI 刷新，业务层应避免在 UI 主线程高频轮询。

事件通知时序

通知的 object 是 JL_EntityM，监听者应先判空再取属性（连接失败时可能为 nil）；
通知回调在 SDK 内部队列触发，UI 更新需自行切回主线程。

性能与运维

命令串行化：JLTaskChain 牺牲并发换取 BLE 链路的可靠性，批量初始化命令（连接后读信息、同步时间等）按序执行，是推荐的运维模式；
多设备规模：JL_BLEMultiple 面向少量设备（耳机+音箱等）设计，不应假设其支持大规模并发连接；
版本一致性：SDK 版本需与设备固件、手机 App 三者匹配，JL_BLEKitVersionString 用于版本校验与排障；
升级路径：仓库内 JL_BLEKit.xcframework 为官方发布产物，升级时整体替换 libs/ 下副本并重新编译 Demo/测试工具即可。

扩展点

新增功能管理器：SDK 内所有功能管理器派生自 JL_FunctionBaseManager 并挂载于 JL_ManagerM，新设备能力（如新传感器）在 SDK 内以新增管理器+模型的方式扩展，App 侧无需改动核心流程；
设备状态适配：JL_EntityM_Status 枚举是状态机契约，App 可基于 textEntityStatus: 之类的映射自行扩展文案与重试策略；
多设备业务编排：JL_BLEMultiple.bleConnectedArr 为多设备联动（如 TWS 左右耳、耳机+音箱）提供遍历入口，业务编排在 App 层完成；
新设备类型：头文件末段已出现 JLDeviceConfigDongle、JLDeviceConfigSoundBox、JLAuracastManager 等较新模块，说明 SDK 以“设备配置类”支持不断新增的硬件形态，App 集成新设备时只需引入对应模型与管理器。

JL_BLEKit 蓝牙通信核心

Purpose and Scope

Overview

什么是 JL_BLEKit

设计意图（WHY）

使用场景

Architecture

核心模块详解

JL_BLEKit.h —— 单一入口头文件

JL_EntityM —— 设备实体

JL_ManagerM —— 命令管理器

JL_BLEMultiple —— 多设备连接管理

事件通知机制

核心流程

设备连接与命令控制流程

实体状态流转

集成方式

使用示例

示例 1：获取当前设备实体并判断 EDR 连接状态

示例 2：通过实体命令管理器发起任务链

示例 3：监听蓝牙状态通知并读取信号强度

示例 4：遍历已连接设备列表

示例 5：断开连接并处理结果

配置选项

API 参考（核心对象）

`JL_BLEMultiple`

`JL_EntityM`

`JL_ManagerM`

`JLTaskChain`

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

连接失败与重连

多设备并发

RSSI 与弱信号

事件通知时序

性能与运维

扩展点

相关链接