SDK 集成步骤

本文档介绍如何将杰理 iOS OTA SDK（XCFramework 格式）集成到你的 iOS 应用中，涵盖环境要求、框架导入、权限配置、连接方式选择、核心调用流程、日志管理及常见问题排查。

Purpose and Scope

本页面向需要把杰理蓝牙 OTA 升级能力接入自有 iOS App 的开发者，说明从零开始的完整集成路径：获取 SDK → 导入框架 → 配置权限 → 选择蓝牙连接方式 → 实现核心 OTA 调用流程 → 日志调试。

本页聚焦"集成"这一动作本身。以下内容属于兄弟页面，不在本页展开：

• 三种连接方式的具体 API 用法与最佳实践，请参考各自的示例文档（code/MiniDemo/ 下三个独立示例工程）。
• 广播包解析、设备 Hash 认证、OTA 升级的内部协议细节，请参考 SDK 文档中心与 doc/Release_V2.5.0/。
• 调试技巧与日志导出，请参考官方调试说明文档。

Overview

杰理 OTA SDK 提供完整的蓝牙 OTA 升级能力封装，支持 BLE 单备份/双备份升级、强制升级、回连机制、Hash 配对认证、广播包解析，以及 GATT Over BR/EDR 经典蓝牙升级。仓库以 XCFramework 格式分发二进制库，同时附带三个迷你示例工程（MiniSingleDemo、JLBleKitOTADemo、JLAssistOTADemo）与一个完整 OTA 应用示例（code/JL_OTA/）。

核心设计意图：把"OTA 升级业务"与"蓝牙连接细节"解耦。开发者可以完全使用 SDK 自带的蓝牙层（JL_BLEKit）快速集成，也可以基于原生 CoreBluetooth 或外部蓝牙层（JL_Assist）自行管理连接，只把 OTA 业务交给 JL_OTALib。因此集成的第一步不是写代码，而是先决定连接方式。

flowchart TD
    A["下载/克隆仓库"] --> B["导入 XCFramework<br/>并设置 Embed & Sign"]
    B --> C["配置 Info.plist 蓝牙权限"]
    C --> D{"选择连接方式"}
    D -->|"原生 CoreBluetooth"| E["MiniSingleDemo 模式"]
    D -->|"JL_BLEKit"| F["JLBleKitOTADemo 模式"]
    D -->|"JL_Assist 自定义"| G["JLAssistOTADemo 模式"]
    E --> H["初始化 SDK 并实现核心流程"]
    F --> H
    G --> H
    H --> I["编译运行，开始 OTA 升级开发"]

Architecture

SDK 采用分层设计，iOS App 通过四至五个 XCFramework 组合获得完整 OTA 能力：

flowchart TD
    subgraph sg_App["iOS 应用层"]
        App["你的 iOS App"]
        Demo["示例工程 code/MiniDemo"]
    end

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

    subgraph sg_Device["设备层"]
        FW["杰理蓝牙设备<br/>（支持 RCSP 协议的固件）"]
    end

    App --> OTA
    OTA --> Adv
    OTA --> Hash
    OTA --> Log
    OTA --> BLE
    BLE -->|"BLE GATT / GATT Over BR/EDR"| FW

各库职责（依据 README.md）：

这种拆分源于版本演进：v2.1.0 起将 OTA 模块、设备认证、广播解析从单一库中分离为独立模块，使开发者可以按需裁剪依赖，同时保持升级业务与连接层解耦。

集成前置条件（运行环境）

在开始集成前，请确认工程满足以下要求（来源：README.md）：

支持的设备平台示例：数传设备（AC695X、AC608N、AC897、AD697N、AD698N、AC630N、AC632N）、手表设备（AC695X、JL701N、AC707N）、音箱设备（JL701N、AC897、AD697N、AD698N、700N）。

获取 SDK 与工程结构

通过 Git 克隆仓库获取 SDK 二进制与示例源码（来源：README.md）：

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

仓库目录结构（来源：README.md）：

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

集成时只需从 libs/ 拷贝所需 XCFramework 到自己的工程；code/MiniDemo/ 中的三个工程是不同连接方式的最小可运行参考，code/JL_OTA/ 是带完整 UI 与蓝牙管理的综合示例。

第一步：导入框架

将 libs/ 目录下的 XCFramework 添加到 Xcode 工程中，并设置 Embed & Sign（来源：README.md）：

1. 集成 JL_OTALib.xcframework、JL_AdvParse.xcframework、JL_HashPair.xcframework、JLLogHelper.xcframework，并在 General → Frameworks, Libraries, and Embedded Content 中设为 Embed & Sign。
2. 若选择 SDK 蓝牙连接方式，额外导入 JL_BLEKit.xcframework。

为什么必须 Embed & Sign：XCFramework 是动态链接的二进制包，必须嵌入 App 包内并在签名时一并处理，否则真机运行时会出现动态库加载失败（dyld: Library not loaded）问题。

第二步：配置蓝牙权限

在 Info.plist 中添加蓝牙使用权限描述，否则系统会拒绝 App 访问蓝牙（来源：README.md）：

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

• NSBluetoothAlwaysUsageDescription：iOS 13+ 访问蓝牙必须声明的权限。
• NSBluetoothPeripheralUsageDescription：iOS 12 及更早版本的兼容声明。

第三步：选择蓝牙连接方式

SDK 提供三种蓝牙连接方式，选择决定了后续初始化代码的形态（来源：README.md）：

选择指南：

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

第四步：核心调用流程

无论选择哪种连接方式，OTA 升级的业务调用骨架是一致的（来源：README.md）：

设备连接+订阅 → noteEntityConnected → cmdTargetFeature → cmdOTAData(data) → 委托回调 otaUpgradeResult、otaDataSend → 断开时 noteEntityDisconnected

sequenceDiagram
    participant App as iOS App
    participant SDK as JL_OTALib
    participant BLE as 蓝牙连接层
    participant Dev as 杰理设备

    App->>BLE: 设备连接 + 订阅通知
    BLE-->>SDK: noteEntityConnected（连接成功通知）
    SDK->>Dev: cmdTargetFeature（查询设备升级能力）
    Dev-->>SDK: 能力信息回调
    App->>SDK: cmdOTAData(data) 发送升级数据
    SDK->>Dev: 分包发送 OTA 数据
    SDK-->>App: 委托回调 otaUpgradeResult / otaDataSend
    BLE-->>SDK: noteEntityDisconnected（断开通知）

各环节的设计意图：

1. 设备连接 + 订阅：先建立 BLE 连接并订阅设备的通知特征，确保能收到设备上报的数据。
2. noteEntityConnected：SDK 收到连接事件后开始管理该设备的 OTA 会话状态；这是 SDK 判定"设备在线"的锚点。
3. cmdTargetFeature：升级前向设备查询能力（如是否支持双备份、当前固件版本等），用于决定升级策略与 UI 展示。
4. cmdOTAData(data)：将升级文件数据交给 SDK，由 SDK 负责分包、校验与发送；调用方无需关心分帧细节。
5. 委托回调：otaUpgradeResult 回报升级结果（成功/失败及错误码），otaDataSend 回报发送进度，用于驱动进度条与结果页。
6. noteEntityDisconnected：设备断开时 SDK 清理会话，App 可在此触发重连或回连逻辑。

日志管理（JLLogHelper）

JLLogHelper 默认开启日志打印和存储，可在初始化后按需调整（来源：README.md）：

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

// 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")

调试时建议保持日志开启；collectLog 可将 SDK 内部日志实时转发到你的日志系统，便于与业务日志关联分析。日志详细排查方法参见官方 SDK 调试说明。

配置选项

API 参考（集成阶段常用接口）

以下接口名称与调用顺序来自 README.md 快速集成步骤 与示例工程。完整的协议级 API 请以 doc/Release_V2.5.0/ 与在线文档中心为准。

cmdTargetFeature

查询设备 OTA 升级能力（固件版本、备份方式等），在连接建立后、发送升级数据前调用。

调用时机：noteEntityConnected 之后、cmdOTAData 之前。

cmdOTAData(data)

将 OTA 升级文件数据交给 SDK 发送。

参数：

• data：升级文件的数据（NSData/Data），通常来自固件文件读取或浏览器/第三方软件导入的升级包。

说明：SDK 内部负责分包、发送节奏控制与数据校验，调用方只需在收到 otaDataSend 进度回调后继续驱动流程。

委托回调

JLLogManager（日志辅助库）

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

依据 README.md 版本历史，SDK 在以下场景有明确的容错与错误处理设计，集成时应加以利用：

• OTA 超时：v2.3.1 起所有命令增加超时检测，v2.4.0 优化超时处理逻辑。升级中途卡死时会通过 otaUpgradeResult 错误回调上报，App 应据此展示失败状态并提示重试。
• OTA 回连超时：v2.5.0 修复回连超时问题；v2.4.0 增加单备份 SDK 内部自动回连接口。升级完成后设备可能短暂断开重连，App 不应立即判定失败。
• 重复序列号容错：v2.4.0 增加对重复序列号的容错处理，避免设备与 SDK 因丢包重发导致的状态错乱。
• 特殊空间复用升级：v2.4.0 增加特殊空间复用的升级支持。
• 对象管理容错：v2.3.1 增加 OTA 对象的对象管理容错，防止异常释放导致崩溃。
• 升级错误回调：v2.3.1 起 otaUpgradeResult 提供错误码，建议在集成期打印完整错误码并对照 SDK 文档排查。
• 并发注意：一次升级会话对应一台设备，App 应在收到 noteEntityDisconnected 前避免重复发起 cmdOTAData；多个设备并行升级场景需按设备实例分别管理委托回调。

调试与验证清单

集成完成后，建议按以下顺序自检（来源：README.md 调试技巧）：

1. Xcode Console 中能看到 SDK 的蓝牙连接状态日志与数据交互日志；
2. Info.plist 权限已生效（首次触发蓝牙时系统弹出权限对话框）；
3. 设备扫描/连接成功，noteEntityConnected 被触发；
4. cmdTargetFeature 能返回设备能力；
5. cmdOTAData 后 otaDataSend 进度递增，最终收到 otaUpgradeResult 成功回调；
6. 断连场景下 noteEntityDisconnected 被触发，回连/重试逻辑正常。

若日志无法定位问题，可导出 App 沙盒中的日志文件，参考官方 杰理 OTA 导出打印日志说明。

Related Links

• README.md（集成总览）
• 在线文档中心
• SDK 接入文档
• SDK 调试说明
• 示例工程：code/MiniDemo/MiniSingleDemo/（原生 CoreBluetooth）、code/MiniDemo/JLBleKitOTADemo/（JL_BLEKit）、code/MiniDemo/JLAssistOTADemo/（JL_Assist 自定义）
• 完整示例：code/JL_OTA/