文档中心与 API 说明

本文介绍 iOS-JL_OTA 仓库（杰理蓝牙 OTA 升级 SDK）的文档中心结构与核心 API 说明，涵盖文档资源导航、JL_OTAManager 与 JLOTAFile 两大 API 体系、集成配置以及 OTA 升级的完整调用流程。

Purpose and Scope

本页作为「文档中心与 API 说明」的入口页，覆盖以下内容：

• 文档中心结构：README.md 入口文档、doc/ 目录下的 API 说明与版本文档、在线文档中心（doc.zh-jieli.com），以及 code/MiniDemo/ 下三个示例工程的开发文档。
• 核心 API 说明：OTA 升级管理对象 JL_OTAManager（初始化、枚举、属性、方法、回调协议）与 OTA 文件管理类 JLOTAFile（授权下载接口）。
• 集成与配置：必须/可选导入的 XCFramework、Info.plist 蓝牙权限、日志管理接口。
• 调用流程：从设备连接、特性查询到 OTA 升级、回调与断开的端到端流程。

以下主题属于兄弟页面，不在本页展开：三种连接方式（原生 CoreBluetooth、JL_BLEKit、JL_Assist）各自的实现细节与最佳实践，请分别参阅 code/MiniDemo/ 下对应的示例文档；SDK 各版本的更新明细，请参阅 README「版本历史」章节。

概述

iOS-JL_OTA 是珠海市杰理科技股份有限公司为杰理蓝牙设备提供的 OTA 升级开发平台，基于 RCSP 协议（远程控制系统协议），覆盖数传设备（AC695X、AC608N、AC897 等）、手表设备（AC695X、JL701N、AC707N）与音箱设备（JL701N、AC897、AD697N 等）的升级场景。仓库包含：

• SDK 框架库（libs/，XCFramework 格式）：JL_OTALib（OTA 升级业务库）、JL_AdvParse（广播包解析库）、JL_HashPair（设备认证库）、JL_BLEKit（蓝牙连接核心库，可选）、JLLogHelper（日志辅助库）。
• 示例工程（code/）：三种连接方式的迷你示例（MiniSingleDemo、JLBleKitOTADemo、JLAssistOTADemo）与包含完整 UI 的 JL_OTA 应用。
• 开发文档（doc/）：API 说明.md 与按版本归档的 HTML 文档（如 Release_V2.5.0/）。

文档中心的价值在于：开发者通过 README.md 即可了解 SDK 能力、运行环境与快速集成步骤；通过 API 说明.md 可查阅全部 OTA 接口的签名与语义；通过三个示例文档可对照具体连接方式落地实现。本页将这些资源串成一条可检索的索引，并对两大核心 API 做逐项解读。

架构

flowchart TD
    subgraph sg_DocCenter["文档中心资源"]
        README["README.md<br/>仓库入口文档（中文）"]
        README_EN["README_EN.md<br/>英文入口文档"]
        APIDOC["doc/API 说明.md<br/>SDK API 参考"]
        DEMO1["MiniSingleDemo 文档<br/>原生 CoreBluetooth 示例"]
        DEMO2["JLBleKitOTADemo 文档<br/>JL_BLEKit 示例"]
        DEMO3["JLAssistOTADemo 文档<br/>JL_Assist 示例"]
        ONLINE["在线文档中心<br/>doc.zh-jieli.com"]
    end

    subgraph sg_APICore["核心 API 层"]
        OTAMGR["JL_OTAManager<br/>OTA 升级管理对象"]
        OTAFILE["JLOTAFile<br/>OTA 文件下载"]
        DELEGATE["JL_OTAManagerDelegate<br/>回调协议"]
    end

    subgraph sg_SDKLibs["SDK 框架库（libs/，XCFramework）"]
        TOTALIB["JL_OTALib.xcframework"]
        ADVPARSE["JL_AdvParse.xcframework"]
        HASHPair["JL_HashPair.xcframework"]
        BLEKIT["JL_BLEKit.xcframework"]
        LOGHELPER["JLLogHelper.xcframework"]
    end

    README --> APIDOC
    README --> DEMO1
    README --> DEMO2
    README --> DEMO3
    README --> ONLINE
    APIDOC --> OTAMGR
    APIDOC --> OTAFILE
    OTAMGR -.实现.-> DELEGATE
    OTAMGR --> TOTALIB
    OTAMGR --> HASHPair
    OTAMGR --> ADVPARSE
    OTAMGR --> BLEKIT
    OTAMGR --> LOGHELPER
    OTAFILE --> TOTALIB

架构说明：文档中心由仓库内文档（README.md、doc/API 说明.md、三个示例文档）与在线文档中心共同构成，其中 README.md 是统一的入口，通过目录导航指向 API 说明与各示例文档。API 层以 JL_OTAManager 为升级流程的总控对象，通过 JL_OTAManagerDelegate 协议向业务层回调发送、特性与升级结果；JLOTAFile 独立负责从杰理服务器按授权 key/code 下载升级文件。二者都依赖 libs/ 下的 XCFramework 库：JL_OTALib 承载 OTA 业务逻辑，JL_HashPair 负责设备 Hash 配对认证，JL_AdvParse 负责广播包解析，JL_BLEKit 在选用 SDK 蓝牙连接时提供 BLE 栈，JLLogHelper 提供日志打印与收集能力。

文档中心结构

README.md：仓库入口

README.md 是文档中心的中文入口，采用九章节结构组织（README.md）：

英文读者可对照 README_EN.md。README 顶部还提供了在线文档中心（doc.zh-jieli.com/Apps/iOS/ota/zh-cn/master/index.html）的直链，作为仓库文档之外的权威在线资料（README.md）。

doc/ 目录：API 说明与版本文档

doc/ 目录存放两类文档资源（README.md）：

• API 说明.md：面向 JL_OTALib.framework 的 API 文档，覆盖 BLE 握手连接、设备信息获取与 OTA 升级全部接口（详见下文「核心 API 说明」）。
• Release_V2.5.0/：按 SDK 版本归档的 HTML 版本文档，随版本历史同步更新。

示例开发文档

code/MiniDemo/ 下三个示例工程各配一份开发文档，与三种连接方式一一对应（README.md）：

选择原则：需要完全掌控 BLE 细节选原生 CoreBluetooth；追求开发效率选 JL_BLEKit；已有自有蓝牙层时选 JL_Assist 桥接。

核心 API 说明：JL_OTAManager

JL_OTAManager 是 OTA 升级管理对象类，用于管理设备的整个升级过程（API 说明.md）。它通过丰富的功能接口与灵活的回调机制，为开发者提供高效、安全的设备固件升级支持。

classDiagram
    class JL_OTAManager {
        +mBLE_UUID: NSString*
        +mBLE_NAME: NSString*
        +bleOnly: BOOL
        +bleAddr: NSString*
        +mCmdSN: uint8_t
        +version: uint16_t
        +versionFirmware: NSString*
        +otaStatus: JL_OtaStatus
        +otaHeadset: JL_OtaHeadset
        +otaPartition: JL_Partition
        +otaLength: int64_t
        +otaSent: uint32_t
        +getOTAManager() JL_OTAManager*
        +noteEntityConnected() void
        +noteEntityDisconnected() void
        +cmdRebootDevice() void
        +cmdRebootForceDevice() void
        +cmdOTAData(data, result) void
        +cmdOTACancelResult(result) void
        +cmdOtaIsRelinking() BOOL
        +cmdTargetFeature() void
        +cmdSystemFunction() void
    }
    class JLOTAFile {
        +cmdGetOtaFileKey(key, code, result) void
        +cmdGetOtaFileKey(key, code, hash, result) void
    }
    class JL_OTAManagerDelegate {
        <<protocol>>
        +otaDataSend(data) void
        +otaFeatureResult(manager) void
        +otaUpgradeResult(result, progress) void
        +otaCancel() void
    }
    JL_OTAManager ..|> JL_OTAManagerDelegate : 实现回调

初始化（单例模式）

JL_OTAManager 采用单例获取方式，保证整个升级流程使用同一管理对象（API 说明.md）：

• + (JL_OTAManager *)getOTAManager：获取 OTA 升级管理对象，推荐使用。
• - (instancetype)init：初始化方法，已被标记为弃用；请改用 getOTAManager。

设计意图：OTA 升级涉及状态机、分包发送与回连逻辑，全局唯一实例可避免多对象并发操作同一设备导致的升级状态错乱（SDK v2.3.1 起还增加了 OTA 对象的对象管理容错）。

枚举类型

JL_OTAResult：升级结果状态

覆盖升级全过程的结果语义（API 说明.md）：

其余枚举

这些枚举构成升级决策的输入：otaStatus/otaHeadset/otaWatch 决定是否强制升级，otaPartition 决定单/双备份升级路径，JL_OTAReconnectType 决定单备份回连方式。

属性

mBLE_UUID/mBLE_NAME 需开发者主动填入，用于 SDK 在单备份回连场景下按 UUID 或名称重新发现设备；otaLength/otaSent 只读属性供进度展示使用。

方法：设备操作

设计意图：noteEntityConnected/noteEntityDisconnected 是 SDK 与业务蓝牙层的唯一耦合点——SDK 不直接持有 BLE 连接，而是由业务层在连接状态变化时主动通知，从而兼容原生 CoreBluetooth、JL_BLEKit、JL_Assist 三种连接方式。

方法：OTA 操作

方法：状态查询

回调协议 JL_OTAManagerDelegate

核心 API 说明：JLOTAFile

JLOTAFile 是 OTA 文件管理类，负责按授权信息从杰理服务器获取/下载升级文件（API 说明.md）。

枚举与回调类型

• JL_OTAUrlResult：文件获取结果。JL_OTAUrlResultSuccess（成功）、JL_OTAUrlResultFail（失败）、JL_OTAUrlResultDownloadFail（下载失败）。
• JL_OTA_URL 回调类型（API 说明.md）：

typedef void(^JL_OTA_URL)(JL_OTAUrlResult result,
                          NSString* __nullable version,
                          NSString* __nullable url,
                          NSString* __nullable explain);

回调参数：result 结果状态；version 文件版本（可空）；url 下载链接（可空）；explain 文件说明（可空）。

下载接口

设计意图：将「文件获取」从「升级执行」中解耦——先通过 JLOTAFile 凭授权换取合法升级文件，再通过 JL_OTAManager 完成升级，两条链路的失败可独立重试与诊断。

核心调用流程

README「快速集成步骤」给出了推荐的端到端调用顺序：设备连接+订阅 → noteEntityConnected → cmdTargetFeature → cmdOTAData(data) → 委托回调 otaUpgradeResult、otaDataSend → 断开时 noteEntityDisconnected（README.md）。

sequenceDiagram
    participant App as iOS 应用
    participant SDK as JL_OTAManager
    participant BLE as 杰理蓝牙设备

    App->>BLE: 设备连接 + 服务订阅
    App->>SDK: noteEntityConnected
    App->>SDK: cmdTargetFeature 查询 OTA 特性
    SDK-->>App: otaFeatureResult 设备状态回调
    App->>SDK: cmdOTAData(data, result) 发起升级
    SDK->>BLE: 分包发送升级数据
    BLE-->>SDK: 确认与进度
    SDK-->>App: otaDataSend 数据发送回调
    SDK-->>App: otaUpgradeResult 升级状态与进度
    App->>SDK: cmdOTACancelResult 可选取消
    BLE-->>App: 断开连接
    App->>SDK: noteEntityDisconnected

流程要点：

1. 连接与通知：业务层完成 BLE 连接与特征订阅后，必须调用 noteEntityConnected，否则 SDK 不认为设备在线。
2. 特性查询：cmdTargetFeature 应在连接后第一时间调用，用于确认设备支持的 OTA 能力（单/双备份、强制升级等），结果经 otaFeatureResult: 返回。
3. 发起升级：将 JLOTAFile 下载得到的文件数据（或本地导入的文件数据）经 cmdOTAData:Result: 提交；SDK 随后通过 otaDataSend: 回调向业务层请求发送分包数据，业务层写入蓝牙后继续，形成「请求-发送-确认」循环。
4. 进度与结果：otaUpgradeResult:Progress: 持续上报 JL_OTAResult 状态与浮点进度；成功进入重启阶段（JL_OTAResultReboot 或 JL_OTAResultReconnect），可调用 cmdRebootDevice/cmdRebootForceDevice。
5. 断开处理：连接断开时调用 noteEntityDisconnected，SDK 据此决定是否触发回连（单备份场景）或终止流程。

使用示例

示例一：OTA 升级文件下载（JLOTAFile）

以下代码摘自 API 说明文档，展示按授权 key/code 获取升级文件的完整用法（API 说明.md）：

JLOTAFile *otaFile = [[JLOTAFile alloc] init];
[otaFile cmdGetOtaFileKey:@"yourKey"
                     Code:@"yourCode"
                   Result:^(JL_OTAUrlResult result, NSString * _Nullable version, NSString * _Nullable url, NSString * _Nullable explain) {
    if (result == JL_OTAUrlResultSuccess) {
        NSLog(@"文件下载成功，版本：%@，链接：%@，说明：%@", version, url, explain);
    } else {
        NSLog(@"文件下载失败，状态：%d", result);
    }
}];

示例二：带 MD5 校验的文件下载

当需要校验文件完整性时，使用带 hash 参数的重载接口（API 说明.md）：

[otaFile cmdGetOtaFileKey:@"yourKey"
                     Code:@"yourCode"
                     hash:@"yourFileMD5"
                   Result:^(JL_OTAUrlResult result, NSString * _Nullable version, NSString * _Nullable url, NSString * _Nullable explain) {
    if (result == JL_OTAUrlResultSuccess) {
        NSLog(@"文件下载成功，版本：%@，链接：%@，说明：%@", version, url, explain);
    } else {
        NSLog(@"文件下载失败，状态：%d", result);
    }
}];

示例三：日志管理（JLLogHelper）

SDK 默认开启日志打印与存储，可通过 JLLogManager 控制（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")

调试建议：使用 Xcode Console 查看实时日志，可观测蓝牙连接状态与数据交互；问题排查可参考在线文档中心的 SDK 调试说明（README.md）。

配置选项

框架库导入配置

集成时需对以上库设置 Embed & Sign（README.md）。

Info.plist 权限配置

在 Info.plist 中添加蓝牙使用权限描述（README.md）：

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

JLLogManager 日志配置

API 参考汇总

JL_OTAManager

+ (JL_OTAManager *)getOTAManager 获取全局唯一的 OTA 升级管理对象（init 已弃用）。

- (void)noteEntityConnected / - (void)noteEntityDisconnected 通知 SDK 设备连接/断开。参数：无。返回：无。

- (void)cmdTargetFeature 查询设备 OTA 特性，连接后第一时间调用；结果经 otaFeatureResult: 回调。

- (void)cmdSystemFunction 查询设备系统状态（外置 Flash 场景）。

- (void)cmdOTAData:(NSData *)data Result:(JL_OTA_RT __nullable)result 发起 OTA 升级。参数：data（升级文件数据）、result（升级结果回调）。返回：无。

- (void)cmdOTACancelResult:(JL_OTA_RESULT __nullable)result 取消升级流程，触发 otaCancel 回调。

- (BOOL)cmdOtaIsRelinking 返回单备份是否正在回连。返回：BOOL。

- (void)cmdRebootDevice / - (void)cmdRebootForceDevice 请求设备重启 / 强制重启。

JL_OTAManagerDelegate（回调协议）

JLOTAFile

-(void)cmdGetOtaFileKey:(NSString*)key Code:(NSString*)code Result:(JL_OTA_URL __nullable)result 按授权 key/code 下载升级文件。参数：key（授权密钥）、code（授权码）、result（回调，含 JL_OTAUrlResult、version、url、explain）。

-(void)cmdGetOtaFileKey:(NSString*)key Code:(NSString*)code hash:(NSString*)hash Result:(JL_OTA_URL __nullable)result 同上，增加 hash（文件 MD5 值）做完整性校验。

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

• 结果码语义化：升级失败通过 JL_OTAResult 枚举细分（数据为空、指令失败、电压低、进入 OTA 模式失败、Uboot 不匹配、Flash 读写失败、指令超时、相同版本、SN 重复、TWS 未连接、耳机未在充电仓等 28 种），业务层应针对关键码（如 JL_OTAResultLowPower 提示充电、JL_OTAResultFailSameVersion 提示无需升级）做差异化提示。
• 多设备连接冲突：JL_OTAResultFailedConnectMore 表示当前固件多台设备连接，需提示用户手动断开其他设备，避免升级目标错乱。
• 单备份回连：JL_OTAResultReconnect（UUID 方式）与 JL_OTAResultReconnectWithMacAddr（MAC 方式）要求业务层按对应方式重连；cmdOtaIsRelinking 可查询回连状态，v2.4.0 起 SDK 支持内部自动回连。
• 回调参数可空：JL_OTA_URL 回调中的 version、url、explain 可能为空，使用前必须做有效性检查（API 说明.md）。
• 授权与校验：key/code 无效会导致下载失败（JL_OTAUrlResultFail）；使用 MD5 校验时必须正确传入 hash，否则文件完整性无法保障；建议失败时添加重试机制。
• 并发与单例：JL_OTAManager 为单例，业务层应串行驱动升级流程，避免并发调用 cmdOTAData: 与取消/重连接口造成状态机冲突；SDK 侧自 v2.3.1 起增加命令超时检测与对象管理容错，v2.4.0 优化超时处理并增加重复序列号容错。

性能与运维

• 日志开销：JLLogHelper 默认打印并存储日志，发布版本可关闭打印/存储以降低 I/O 开销（见「配置选项」）。
• 升级进度观测：通过 otaUpgradeResult:Progress: 的 progress（0~1）与只读属性 otaLength/otaSent 双通道展示进度；升级中设备不可断开，否则触发 JL_OTAResultDisconnect。
• 超时与重试：SDK 已内置命令超时检测（v2.3.1+）；文件下载侧建议业务层自行实现重试（失败时状态为 JL_OTAUrlResultDownloadFail）。
• 版本管理：升级包与 APP 需匹配 SDK 版本，SDK v2.5.0 起支持 GATT Over BR/EDR 经典蓝牙 OTA，新老版本能力差异以 README「版本历史」为准。

扩展点

• 连接方式可插拔：SDK 通过 noteEntityConnected/noteEntityDisconnected 与业务层解耦，支持原生 CoreBluetooth、JL_BLEKit、JL_Assist 三种接入方式，可自由扩展新的蓝牙桥接层（详见三个示例文档）。
• 回调协议定制：实现 JL_OTAManagerDelegate 即可接管数据发送（otaDataSend:）、特性结果（otaFeatureResult:）与升级结果（otaUpgradeResult:Progress:），UI 层据此实现自定义进度展示与业务逻辑。
• 升级决策枚举：通过 otaStatus（正常/强制）、otaHeadset、otaWatch、otaPartition 等属性，可针对不同产品形态（耳机、手表、音箱）定制升级策略。

测试与验证

仓库以三个可独立运行的示例工程作为集成验证载体（README.md）：

每个示例工程均配套开发文档，建议新接入方先运行对应 Demo 验证设备握手与升级，再移植到业务工程。

相关链接

• 仓库 README（中文入口）
• 仓库 README（英文入口）
• API 说明文档
• 在线文档中心
• 原生 CoreBluetooth 示例文档
• JL_BLEKit 示例文档
• JL_Assist 示例文档
• 问题反馈