SDK 框架组成

iOS-JL_OTA 是珠海杰理科技为杰理蓝牙设备提供的 OTA 升级开发平台。本页面系统梳理 SDK 的整体框架组成：核心 XCFramework 库、工具库、示例工程、第三方依赖以及它们之间如何协作完成一次完整的 OTA 升级。

Purpose and Scope

本页面从"框架组成"的视角说明 iOS-JL_OTA SDK 的模块划分与职责边界，包括：

• libs/ 目录下五个核心 XCFramework（JL_OTALib、JL_AdvParse、JL_HashPair、JL_BLEKit、JLLogHelper）各自的职责与依赖关系；
• code/JL_OTA/DFUnits.framework 通用工具库的组成；
• code/ 目录下三种连接方式的示例工程（MiniSingleDemo、JLBleKitOTADemo、JLAssistOTADemo）与完整示例工程 JL_OTA；
• Podfile 中的第三方依赖及其用途；
• RCSP 协议作为整个 SDK 的通信基础所处的位置。

与本页面相关的兄弟主题（如"OTA 升级流程""广播解析""设备认证""日志管理"等）属于各自的 catalog 页面，本页面只做框架层面的描述与交叉指引，不展开每个子系统的实现细节。

Overview

SDK 是什么

iOS-JL_OTA 是珠海市杰理科技股份有限公司为杰理蓝牙设备提供的 OTA 升级开发平台，基于 RCSP 协议（远程控制系统协议），提供完整的 OTA 升级功能，支持数传设备（AC695X、AC608N、AC897、AD697N、AD698N、AC630N、AC632N）、手表设备（AC695X、JL701N、AC707N）、音箱设备（JL701N、AC897、AD697N、AD698N、700N）等产品线。

SDK 的核心能力

框架组成的一览

整个仓库从架构上可分为四层：

1. 应用层：code/ 下的示例工程（含完整 UI 的 JL_OTA 应用与三个迷你示例），演示 SDK 的集成方式；
2. SDK 核心层：libs/ 下的 XCFramework 集合，封装 OTA 业务、广播解析、设备认证、日志与（可选的）蓝牙连接能力；
3. 工具层：DFUnits.framework，提供时间、文件、压缩、CRC、HTTP 等基础工具；
4. 协议与设备层：RCSP 协议承载 SDK 与杰理蓝牙设备之间的指令与数据交互。

运行环境要求：iOS 12.0+、Xcode 14.0+，语言支持 Objective-C / Swift。

Architecture

flowchart TD
    subgraph sg_App["应用层 (code/)"]
        App["iOS 应用 / 示例工程"]
        Bm["BleManager / BleByAssist / SDKBleManager"]
    end

    subgraph sg_SDK["核心 SDK 层 (libs/)"]
        OTA["JL_OTALib.xcframework<br/>OTA 升级业务库"]
        Adv["JL_AdvParse.xcframework<br/>广播包解析库"]
        Hash["JL_HashPair.xcframework<br/>设备认证库"]
        Log["JLLogHelper.xcframework<br/>日志辅助库"]
        BLE["JL_BLEKit.xcframework<br/>蓝牙连接核心库 (可选)"]
    end

    subgraph sg_Util["工具层 (code/JL_OTA/)"]
        DF["DFUnits.framework<br/>通用工具库"]
    end

    subgraph sg_Protocol["协议层"]
        RCSP["RCSP 协议<br/>远程控制系统协议"]
    end

    subgraph sg_Device["设备层"]
        Dev["杰理蓝牙设备<br/>AC695X / AC632N / JL701N 等"]
    end

    App --> OTA
    App --> Adv
    App --> Hash
    App --> Log
    App --> BLE
    App --> Bm
    Bm --> BLE
    OTA --> DF
    Adv --> DF
    Hash --> DF
    OTA --> RCSP
    Adv --> RCSP
    Hash --> RCSP
    BLE --> Dev
    RCSP --> Dev

架构说明

• JL_OTALib 是 OTA 升级的业务核心，负责固件数据下发、升级状态回调（otaUpgradeResult、otaDataSend）等，它依赖 DFUnits 提供的工具函数，并通过 RCSP 协议与设备通信；
• JL_AdvParse 解析杰理设备的广播包，帮助应用在扫描阶段识别设备并获取必要信息；
• JL_HashPair 完成 Hash 配对认证，是 OTA 升级前的安全前置步骤；
• JLLogHelper 贯穿所有业务库，提供日志打印、收集与落盘能力，用于问题排查；
• JL_BLEKit 是可选的蓝牙连接核心库：如果应用不使用原生 CoreBluetooth 或 JL_Assist 自定义连接，而是希望快速集成杰理封装好的蓝牙层，则导入该库；
• DFUnits 位于 code/JL_OTA/ 目录下，是杰理系列 SDK 通用的工具框架，为上层业务库提供与蓝牙无关的基础能力；
• 示例工程中的三个蓝牙管理器（BleManager、BleByAssist、SDKBleManager）分别对应三种连接方式，向业务层屏蔽底层差异。

核心 SDK 库（libs/）

libs/ 目录以 XCFramework 格式发布全部核心库，开发者将其拖入工程并设置为 Embed & Sign 即可使用。仓库 README 对工程结构的描述如下：

iOS-JL_OTA/
├── code/                           # 示例程序源码
│   ├── MiniDemo/                   # 迷你示例工程
│   │   ├── MiniSingleDemo/         #   原生 CoreBluetooth 连接示例
│   │   ├── JLBleKitOTADemo/        #   JL_BLEKit 连接示例
│   │   └── JLAssistOTADemo/        #   JL_Assist 自定义连接示例
│   └── JL_OTA/                     # 完整 OTA 应用示例
│       ├── BleManager/             #   自定义蓝牙连接实现
│       ├── BleByAssist/            #   JL_Assist 蓝牙连接实现
│       ├── SDKBleManager/          #   JL_BLEKit 蓝牙连接实现
│       └── Views/                  #   UI 视图
├── libs/                           # 核心 SDK 库 (XCFramework 格式)
│   ├── JL_OTALib.xcframework       #   OTA 升级业务库
│   ├── JL_AdvParse.xcframework     #   广播包解析库
│   ├── JL_HashPair.xcframework     #   设备认证库
│   ├── JL_BLEKit.xcframework       #   蓝牙连接核心库（可选）
│   └── JLLogHelper.xcframework     #   日志辅助库
└── doc/                            # 文档资源
    └── Release_V2.5.0/             #   最新版本文档

Source: README.md

JL_OTALib.xcframework — OTA 升级业务库

职责：OTA 升级流程的业务核心。应用完成设备连接与特征订阅后，SDK 通过 cmdTargetFeature 查询设备能力，再通过 cmdOTAData(data) 将固件分包下发，并通过委托回调 otaUpgradeResult、otaDataSend 向应用反馈升级进度与结果。

设计意图：将固件解析、分包策略、升级状态机等复杂逻辑封装在库内，应用只需关心"连接设备 → 发送数据 → 接收回调"三个动作，大幅降低集成门槛。

JL_AdvParse.xcframework — 广播包解析库

职责：解析杰理蓝牙设备的广播包，使应用能在扫描/连接阶段识别杰理设备并读取广播携带的设备信息。

设计意图：不同杰理芯片（AC695X、AC632N、JL701N 等）的广播格式统一由该库解析，避免各应用重复实现易错的位级解析逻辑。

JL_HashPair.xcframework — 设备认证库

职责：实现 Hash 配对认证。在 OTA 升级（尤其是强制升级）之前完成设备鉴权，保障升级链路安全。

设计意图：把安全相关的配对算法与业务解耦，单独成库便于杰理在认证策略升级时只替换该库，不影响 OTA 主流程。

JLLogHelper.xcframework — 日志辅助库

职责：日志打印、收集与落盘。默认开启日志打印和存储，可通过 JLLogManager 系列接口控制级别、时间戳、落盘与收集回调。

设计意图：OTA 升级属于长链路、低成功率敏感操作，完善的日志机制是现场问题排查的关键。日志库独立发布，使其可被其他杰理 SDK 复用。

JL_BLEKit.xcframework — 蓝牙连接核心库（可选）

职责：杰理封装好的蓝牙连接层，提供扫描、连接、服务发现、特征订阅与分包发送能力。

设计意图：作为可选依赖，它让"不想关心 CoreBluetooth 细节"的开发者快速接入；而希望完全掌控 BLE 行为的开发者可以不导入它，改用原生 CoreBluetooth 或 JL_Assist 桥接。这种"按需引入"的设计保持了框架组合的灵活性。

工具层：DFUnits.framework

code/JL_OTA/DFUnits.framework 是杰理系列 SDK 的通用工具框架，以二进制 framework 形式随示例工程发布。其公开头文件（Headers/ 目录）揭示了工具能力的覆盖面：

Source: DFUnits.framework 头文件目录

设计意图：把与业务无关的基础能力（时间、文件、校验、加密、网络、UI）抽离到独立 framework 中，供 JL_OTALib、JL_AdvParse、JL_HashPair 等业务库复用，避免每个业务库重复实现基础设施，也便于杰理其他产品线（如音频 SDK）共用同一工具底座。

示例工程（code/）

示例工程不仅是演示代码，更是 SDK 的"活文档"——它展示了三种连接方式的完整接线方式，是集成 SDK 时最重要的参考。

三种连接方式

选择指南（来自 README）：

• 完全掌控 BLE 扫描、连接、服务与分包发送 → 选择原生自定义连接；
• 快速集成、减少蓝牙细节处理 → 选择 SDK 蓝牙连接（JL_BLEKit）；
• 已有外部蓝牙管控或需桥接到既有蓝牙层 → 选择 JL_Assist 自定义连接。

设计意图：三种连接方式对应三种集成场景。SDK 业务层（JL_OTALib）对上层只暴露统一的 OTA 接口，蓝牙差异被隔离在管理器层，因此应用可以随时在三种方式之间切换而不影响 OTA 业务代码。

完整示例 JL_OTA

code/JL_OTA/ 是包含完整 UI（Views/）与三种蓝牙管理器（BleManager/、BleByAssist/、SDKBleManager/）的 OTA 应用示例，也是 DFUnits.framework 与 Podfile 所在工程。它演示了生产级集成：蓝牙权限配置、设备扫描列表、升级界面、日志查看等。

第三方依赖（Podfile）

code/JL_OTA/Podfile.lock 记录了完整示例工程的 CocoaPods 依赖：

Source: Podfile.lock

设计意图：这些依赖全部位于示例工程而非核心 SDK 内部，说明 SDK 核心库刻意保持零第三方依赖（仅依赖系统框架与 DFUnits 工具），把选择权交给集成方；示例工程使用这些库只是为了演示"一个真实 App 如何组织 UI 与网络层"。

协议层：RCSP

RCSP（远程控制系统协议）是杰理设备与 SDK 之间通信的基础协议，贯穿 OTA 升级、广播解析、设备认证三大业务库。SDK 侧发送的 cmdTargetFeature、cmdOTAData 等指令，最终都编码为 RCSP 报文通过蓝牙链路（BLE GATT 或 GATT Over BR/EDR）下发到设备；设备的应答与事件（如升级结果）也以 RCSP 报文形式回传并被 SDK 解析为业务回调。

设计意图：统一协议层使 SDK 能够跨芯片（AC695X、AC632N、JL701N、AD697N 等）复用同一套业务代码——设备差异被固件与协议版本隔离，SDK 只需针对协议版本做兼容。

Core Flow：一次 OTA 升级在框架间的流转

一次完整的 OTA 升级跨越了应用层、蓝牙层、OTA 业务库与设备层。以下时序图展示各框架组件如何协作：

sequenceDiagram
    participant App as iOS 应用 (示例工程)
    participant BM as 蓝牙管理器 (BleManager / SDKBleManager / BleByAssist)
    participant OTA as JL_OTALib
    participant Dev as 杰理设备

    App->>BM: 扫描并连接设备
    BM->>Dev: 连接 + 订阅 GATT 特征
    App->>OTA: 订阅 noteEntityConnected 通知
    Dev-->>OTA: noteEntityConnected (设备连接成功)
    OTA->>Dev: cmdTargetFeature 查询设备能力
    Dev-->>OTA: 设备能力应答
    App->>OTA: cmdOTAData(data) 下发固件数据
    OTA->>Dev: 按 RCSP 分包发送 OTA 数据
    Dev-->>OTA: otaDataSend 回调 (发送进度)
    OTA-->>App: 升级进度回调
    Dev-->>App: otaUpgradeResult 升级结果
    Dev-->>BM: 断开连接
    BM-->>App: noteEntityDisconnected

流程分步说明

1. 连接与订阅：应用通过蓝牙管理器（三种实现之一）完成设备连接与特征订阅；
2. 设备就绪通知：JL_OTALib 通过 noteEntityConnected 收到设备就绪事件——这是业务库开始工作的起点；
3. 能力查询：cmdTargetFeature 询问设备支持的升级特性（单/双备份、强制升级等），决定后续升级策略；
4. 数据下发：应用调用 cmdOTAData(data)，业务库内部按 RCSP 协议分包，通过蓝牙链路逐包发送；
5. 进度与结果回调：发送进度通过 otaDataSend 回报，最终升级结果通过 otaUpgradeResult 回调；
6. 断开处理：升级结束或异常断开时，noteEntityDisconnected 通知应用，进入回连或失败处理流程（SDK 支持回连机制）。

Usage Examples

集成核心库

集成 SDK 只需导入五个（或按需四个）XCFramework 并设置 Embed & Sign：

1. 集成 JL_OTALib.xcframework、JL_AdvParse.xcframework、JL_HashPair.xcframework、JLLogHelper.xcframework 并设置 Embed & Sign
2. 配置权限：Privacy - Bluetooth Peripheral/Always Usage Description
3. 核心调用流程：设备连接+订阅 → noteEntityConnected → cmdTargetFeature → cmdOTAData(data) → 委托回调 otaUpgradeResult、otaDataSend → 断开时 noteEntityDisconnected

Source: README.md

配置蓝牙权限

<key>NSBluetoothAlwaysUsageDescription</key>
<string>需要使用蓝牙功能连接杰理设备</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>需要作为蓝牙外设连接杰理设备</string>

Source: README.md

控制 JLLogHelper 日志（Objective-C）

// Objective-C
[JLLogManager clearLog]; // 清空日志
[JLLogManager setLog:false IsMore:false Level:JLLOG_COMPLETE]; // 关闭日志打印
[JLLogManager saveLogAsFile:false]; // 关闭日志存储
[JLLogManager logWithTimestamp:false]; // 关闭日志打印时间

Source: README.md

控制 JLLogHelper 日志（Swift）

// Swift
JLLogManager.saveLog(asFile: true)
JLLogManager.setLog(true, isMore: false, level: .COMPLETE)
JLLogManager.log(withTimestamp: true)
let path = NSSearchPathForDirectoriesInDomains(.documentDirectory, .userDomainMask, true).first! + "/abc.txt"
JLLogManager.redirectLogPath(path) // 重置保存路径
JLLogManager.clearLog()
JLLogManager.collectLog { str in
    print(str) // 回调所有的日志打印内容
}
JLLogManager.logSomething("abcd")

Source: README.md

设计意图：日志接口同时提供 ObjC 与 Swift 两种形式，覆盖两种主流开发语言；collectLog 回调让应用可以实时接管日志输出，redirectLogPath 允许把日志落盘到自定义路径——这为生产环境问题回溯提供了灵活性。

Configuration Options

库级配置：必选与可选

Source: README.md

Info.plist 权限配置

JLLogManager 日志配置

API Reference

本页面聚焦框架组成，这里仅列出示例工程与 README 中直接可见的、跨框架协作的关键接口；各库的完整 API 以 doc/Release_V2.5.0/ 下的开发文档为准。

JL_OTALib 关键接口

JLLogManager 接口签名（依据 README 示例归纳）

// Objective-C
+ (void)clearLog;
+ (void)setLog:(BOOL)isLog IsMore:(BOOL)isMore Level:(JLLogLevel)level;
+ (void)saveLogAsFile:(BOOL)isSave;
+ (void)logWithTimestamp:(BOOL)isTimestamp;

// Swift
JLLogManager.saveLog(asFile: Bool)
JLLogManager.setLog(Bool, isMore: Bool, level: JLLogLevel)
JLLogManager.log(withTimestamp: Bool)
JLLogManager.redirectLogPath(String)
JLLogManager.clearLog()
JLLogManager.collectLog((String) -> Void)
JLLogManager.logSomething(String)

Source: README.md

参数说明：

• level（JLLogLevel）：日志级别/详略模式，示例中使用 JLLOG_COMPLETE 表示完整输出；
• redirectLogPath(path:)：把日志文件重定向到指定路径（如应用 Documents 目录）；
• collectLog：每产生一条日志都会回调该闭包，可用于自定义转发或 UI 展示。

Throws / 失败行为： 日志接口均为非抛出型；若指定落盘路径不可写，日志收集会退化（README 未给出显式错误码，实际以设备端日志为准）。

Failure Modes、边界情况与并发

连接层失败

• 扫描/连接失败：三种连接方式（CoreBluetooth / JL_BLEKit / JL_Assist）在底层失败时的表现不同。原生 CoreBluetooth 方式下，应用需自行处理 didFailToConnect 等回调；JL_BLEKit 与 JL_Assist 方式则把连接状态收敛为统一回调，业务侧只需监听 noteEntityConnected / noteEntityDisconnected。
• 断线重连：SDK 的 OTA 升级支持回连机制。升级中途断开时，noteEntityDisconnected 触发应用侧回连逻辑；若设备处于强制升级模式，其广播/连接参数可能变化，广播解析库（JL_AdvParse）与回连策略必须协同才能找到设备。

认证失败

• Hash 配对认证（JL_HashPair）失败时，设备会拒绝后续 OTA 指令。典型原因是设备与 App 的配对密钥不一致，或设备处于未配对状态。此时应提示用户重新配对，而不是重试 cmdOTAData。

升级中断与一致性

• OTA 属于"长事务"操作：固件通常数 MB、按包发送数百至数千包。单包发送由 otaDataSend 逐包回报，业务库内部维护发送状态；若中间断连，固件与设备端升级状态可能不一致，需依赖设备端单/双备份机制恢复。
• 强制升级场景下设备可能不再响应普通业务指令，此时应用应只走 OTA 通道，避免其他指令干扰升级链路。

并发注意

• 蓝牙链路本质上是单通道串行的。示例工程中所有指令（能力查询、数据下发、认证）都通过同一 GATT 特征收发，应用不应在升级过程中并发发起其他写操作，否则会打乱 RCSP 分包顺序。
• 日志系统（JLLogHelper）在调试期间可能高频打印，collectLog 回调内不要做重操作（如网络上传），避免阻塞主线程或 BLE 发送线程。

Performance 与运维建议

• 分包与 MTU：升级吞吐取决于蓝牙 MTU 与分包策略。JL_OTALib 内部按 RCSP 分包发送；若使用原生 CoreBluetooth，可参考 MiniSingleDemo 中 BleManager 的实现协商更大 MTU 以提升传输速率。
• 日志策略：生产环境建议关闭 JLLOG_COMPLETE 级别的详细打印（或仅落盘不打印），降低日志对传输性能的影响；故障现场再通过 collectLog 或落盘文件回溯。
• 升级进度 UI：otaDataSend 回调频率较高，建议在 UI 层做节流（如每 N 包刷新一次进度条），避免频繁刷新导致掉帧。
• 版本管理：doc/Release_V2.5.0/ 存放各版本配套文档，升级 SDK 库时应同步查阅对应版本文档，避免业务库与工具库版本不匹配。

Extension Points

连接层可替换（最重要的扩展点）

框架将蓝牙差异隔离在管理器层，这是设计上最有意的扩展点：

• BleManager（原生 CoreBluetooth）：可扩展自定义扫描过滤、连接参数、MTU 协商；
• SDKBleManager（JL_BLEKit）：可扩展设备信息读取与连接策略；
• BleByAssist（JL_Assist）：可桥接到既有蓝牙层，适合已经有自己蓝牙栈的厂商 App。

应用可以新增自己的管理器实现（只要对齐 noteEntityConnected / cmdOTAData / otaUpgradeResult 等协作契约），即可在不修改 JL_OTALib 的前提下接入新的蓝牙方案。

日志通道可扩展

通过 collectLog 回调，应用可以把 SDK 日志接入自己的日志/上报体系（如 Bugly、自建日志平台），实现统一的运维观测。

工具库可复用

DFUnits.framework 与业务解耦，杰理其他 SDK 或应用自身可直接复用其时间、文件、CRC、加密、网络工具，减少重复造轮子。

Tests 与验证

仓库未在本次勘探范围内发现独立的单元测试工程；SDK 的验证主要依赖：

• 三个迷你示例工程（MiniSingleDemo、JLBleKitOTADemo、JLAssistOTADemo）各自作为"可运行的集成测试"，验证三种连接方式下 OTA 全流程；
• 完整示例 JL_OTA 覆盖了 UI 层与蓝牙管理层的生产级组合，可作为回归验证基线；
• 实际设备（AC695X、AC632N、JL701N 等）真机验证是 OTA 功能正确性的最终标准。

Related Links

• README.md（工程结构与集成指南）
• README_EN.md（英文版说明）
• code/JL_OTA/Podfile.lock（示例工程依赖清单）
• code/JL_OTA/DFUnits.framework/Headers（工具库头文件）
• 相关兄弟页面：OTA 升级流程、广播解析（JL_AdvParse）、设备认证（JL_HashPair）、日志管理（JLLogHelper）、三种连接方式详解