文档中心与 JL_OTALib API 说明

本文档面向 iOS 开发者，完整说明 JL_OTALib.framework（杰理科技 OTA 升级库）的 API 体系与使用方式，涵盖 OTA 升级管理对象 JL_OTAManager、授权文件下载类 JLOTAFile、全部枚举/回调/属性/协议定义，以及从 BLE 握手、设备信息获取到固件传输与回连的端到端升级流程。

Purpose and Scope

本页是仓库 文档中心 中关于 JL_OTALib.framework 的权威参考页，内容基于仓库内 docs/JL_OTALib.framework API 说明.md 与框架公开头文件（JL_OTAManager.h、JLOTAFile.h、JLOtaReConnectOption.h、JLOtaCustom.h、jl_ufw.h）整理而成。

本页覆盖：

• JL_OTAManager 的初始化方式、类型定义（枚举）、属性、方法与回调协议；
• JLOTAFile 基于授权 key/code 的固件文件下载机制；
• OTA 升级的完整控制流（连接 → 查询特性 → 握手 → 传输 → 回连 → 重启）；
• 失败模式、错误码语义、回连策略与扩展点。

以下相关内容属于兄弟页面/其他框架，本页仅作指向、不展开：

• BLE 连接核心库 JL_BLEKit.xcframework：负责设备扫描、连接与数据通道（见仓库根 README.md 中的框架目录结构）；
• 表盘处理库 JLDialUnit.xcframework、哈希配对库 JL_HashPair、翻译传输功能（见 翻译传输功能说明.md）；
• SDK 测试工程 SDKTestHelper 中的自定义命令使用说明（见 APP说明书.md 第 1.27 节 "OTA 库自定义命令（Otalib Custom Cmd）"）。

Overview

什么是 JL_OTALib

JL_OTALib.framework 是杰理科技为 iOS 平台提供的 OTA（Over-The-Air）固件升级库。官方文档将其定位为"包含了 OTA 升级的所有 API，用于实现 OTA 升级的过程，包括 BLE 设备握手连接、获取设备信息、OTA 升级功能等"。仓库根目录将它与 JL_BLEKit（蓝牙连接核心库）、JLDialUnit（表盘处理库）并列为 SDK 框架栈中的独立组件：

├── JL_BLEKit.xcframework           # 蓝牙连接核心库
├── JL_OTALib.xcframework           # OTA 升级库
├── JLDialUnit.xcframework          # 表盘处理库

Source: README.md

核心设计意图

• 单例管理升级过程：JL_OTAManager 通过 getOTAManager 提供全局唯一的升级管理对象，init 已被标记为废弃，强制开发者走单例路径，避免多个升级状态机互相干扰。
• 回连策略内部化：cmdUpgrade:Option:Result: 接口"免去了公版 OTA 的外边回连策略，内部实现回连"，即库内部自行处理设备从普通模式切换到 OTA 模式后的重连，并以 Result 回调替代 delegate 回调。
• 授权文件下载：JLOTAFile 使用授权 key 与 code 从杰理服务器下载升级文件，保证固件分发的安全性与可追溯性。
• 强状态反馈：JL_OTAResult 枚举以 0x00~0x11、0xe0~0xfe 的编码体系区分成功、进行中、需重连/重启、以及各类校验/硬件/协议失败，使上层 App 可以精确驱动 UI 状态机。

典型使用场景

• 蓝牙耳机/音箱固件升级（单备份、双备份 JL_Partition）；
• TWS 耳机升级（需检查 JL_OTAResultFailTWSDisconnect、充电仓状态 JL_OTAResultFailNotInBin）；
• 手表资源升级（JL_OtaWatch / JLOtaSourcesExtendMode 资源升级模式）；
• BootLoader 下载（JL_BootLoader）；
• 强制升级（JL_OtaStatusForce、JL_OtaHeadsetYES）。

Architecture

flowchart TD
    subgraph sg_App["iOS 应用层 (App)"]
        App["开发者 App"]
    end

    subgraph sg_OTALib["JL_OTALib.framework"]
        OTAManager["JL_OTAManager<br/>OTA 升级管理对象"]
        OTAFile["JLOTAFile<br/>授权文件下载"]
        ReConnect["JLOtaReConnectOption<br/>回连参数"]
        Custom["JLOtaCustom<br/>自定义命令"]
        UFW["jl_ufw<br/>固件格式解析"]
    end

    subgraph sg_BLE["蓝牙系统层"]
        BLEKit["JL_BLEKit<br/>蓝牙连接核心库"]
        CoreBluetooth["CoreBluetooth"]
    end

    subgraph sg_External["外部"]
        Device["杰理蓝牙设备"]
        Server["杰理 OTA 服务器"]
    end

    App -->|"import JL_OTALib"| OTAManager
    App -->|"cmdGetOtaFileKey:Code:"| OTAFile
    OTAFile -->|"HTTPS 下载"| Server
    OTAManager -->|"发送/接收数据"| BLEKit
    BLEKit --> CoreBluetooth
    CoreBluetooth -->|"BLE 链路"| Device
    OTAManager --> ReConnect
    OTAManager --> Custom
    OTAManager --> UFW

架构说明：

• JL_OTAManager 是升级流程的中枢：持有设备标识（mBLE_UUID、mBLE_NAME、bleAddr）、设备能力（otaStatus、otaPartition、bootloaderType）、传输进度（只读 otaLength/otaSent），并通过 JL_OTAManagerDelegate 把数据发送、特性结果、升级状态与进度回调给上层；
• JLOTAFile 独立于升级流程之外，负责从杰理服务器按授权 key/code 拉取固件文件，返回 url/version/explain 供下载使用；
• JLOtaReConnectOption / JLOtaCustom / jl_ufw 是 JL_OTAManager 的辅助模块：前者承载 cmdUpgrade:Option: 的回连参数，后者提供自定义指令通道与 UFW 固件格式解析能力；
• JL_BLEKit + CoreBluetooth 构成数据通道：JL_OTALib 本身不直接操作 CoreBluetooth 的 GATT 细节，而是依赖 JL_BLEKit 完成设备连接，再通过 noteEntityConnected / noteEntityDisconnected 把连接状态"告知"OTA 库。

核心实现：JL_OTAManager

JL_OTAManager 是杰理科技开发的"专业 OTA 升级管理工具类"，为开发者提供高效、安全的设备固件升级支持，通过丰富的功能接口和灵活的回调机制帮助开发者轻松实现设备升级管理（官方文档原述）。

单例与生命周期

/// 获取 OTA 升级对象
+ (JL_OTAManager *)getOTAManager;

/// 不建议使用自行初始化
/// 推荐获取 getOTAManager
- (instancetype)init __attribute__((deprecated("Please use getOTAManager instead.")));

Source: JL_OTAManager.h

设计意图：升级过程涉及跨多次 BLE 交互的状态机（握手、传输、回连），必须全局唯一，因此 init 被显式废弃，统一走 getOTAManager 单例。

类型定义：枚举体系

JL_OTAResult（升级结果，UInt16）

这是整个库最核心的错误/状态码枚举，头文件中以 NS_ENUM(UInt16, JL_OTAResult) 定义，官方文档给出了完整的语义表：

头文件中的原始定义片段：

typedef NS_ENUM(UInt16, JL_OTAResult) {
    /// OTA升级成功
    JL_OTAResultSuccess = 0x00,
    /// OTA升级失败
    JL_OTAResultFail = 0x01,
    /// OTA升级数据为空
    JL_OTAResultDataIsNull = 0x02,
    // ...（0x03 ~ 0xfb 见上表）
    /// OTA需重连设备(更新资源)
    JL_OTAResultReconnectUpdateSource = 0xfe,
    /// OTA未知错误
    JL_OTAResultUnknown
};

Source: JL_OTAManager.h

编码区间设计意图：0x00~0x11 为流程状态（成功/进行中/需重连/需重启/准备中），0xe0~0xe1 为数据/取消类，0xf1~0xfb 为校验与硬件类失败，0xfc~0xfe 为重连/断开类——上层 App 可根据区间快速决定 UI 分支（如 0x09/0xfc 触发重连流程、0x0a 提示用户重启设备、0x06 提示充电）。

其他配置型枚举

Source: JL_OTAManager.h

属性一览

Source: JL_OTAManager.h

设计意图：mBLE_UUID/mBLE_NAME/bleAddr 是 OTA 回连时定位设备的输入参数，必须在连接阶段由开发者填充；otaLength/otaSent 只读，由库内部依据设备通知与传输计数维护，供进度条计算（progress = otaSent / otaLength）。

方法

设备操作

/// 当BLE连接上时告知SDK
- (void)noteEntityConnected;
/// 当BLE断开时告知SDK
- (void)noteEntityDisconnected;
/// 请求设备重启
- (void)cmdRebootDevice;
/// 强制请求设备重启
- (void)cmdRebootForceDevice;

noteEntityConnected / noteEntityDisconnected 是连接事件注入点：JL_OTALib 不主动扫描连接，而是由上层（基于 JL_BLEKit）在 BLE 连接/断开时通知 OTA 库，使其内部的回连与重连状态机得以推进。

OTA 操作

/// 发起 OTA 升级请求
- (void)cmdOTAData:(NSData *)data Result:(JL_OTA_RT __nullable)result;
/// 取消当前 OTA 升级流程
- (void)cmdOTACancelResult:(JL_OTA_RESULT __nullable)result;
/// 内部实现回连的升级接口（免去公版 OTA 的外边回连策略）
- (void)cmdUpgrade:(NSData *)data
            Option:(JLOtaReConnectOption *_Nullable)option
            Result:(JL_OTA_RT _Nonnull)result;
/// 检查当前 OTA 单备份是否正在回连
- (BOOL)cmdOtaIsRelinking;

Source: JL_OTAManager.h（方法名与回调类型见官方文档 docs/JL_OTALib.framework API 说明.md）

⚠️ 官方文档特别提示：使用 cmdUpgrade:Option:Result: 时不可使用 delegate 的回调信息，必须使用 Result 块回调，因为该接口内部已接管回连流程。

状态查询与调优

/// 查询设备支持的 OTA 特性（建议连接设备后第一时间调用）
- (void)cmdTargetFeature;
/// 查询设备系统状态（主要用于外置 Flash 场景）
- (void)cmdSystemFunction;
/// 打印 OTA 发送的数据内容
- (void)logSendData:(BOOL)status;
/// 设置最大丢包次数（default: 10）
- (void)maxLostCount:(int)count;
/// 设置超时时间（default: 5 秒）
- (void)cmdTimeOut:(int)timeOut;

回调协议 JL_OTAManagerDelegate

/// OTA 升级管理对象回调
@protocol JL_OTAManagerDelegate <NSObject>

/// 即将被发送的数据
/// @param data 数据内容
- (void)otaDataSend:(NSData *_Nonnull)data;

@optional
/// 回调设备状态信息
/// @param manager 对象状态
- (void)otaFeatureResult:(JL_OTAManager *_Nonnull)manager;

/// 回调升级状态以及进度等
/// @param result 状态以及进度信息
/// @param progress 进度信息
- (void)otaUpgradeResult:(JL_OTAResult)result Progress:(float)progress;

/// 取消OTA升级
- (void)otaCancel;

@end

Source: JL_OTAManager.h

otaDataSend 为 @required：上层必须实现，把即将发送的数据写入 BLE 通道；otaFeatureResult 在 cmdTargetFeature 查询完成后回调，此时可读取 manager 的 otaStatus/otaPartition/bootloaderType/otaSourceMode 等能力字段；otaUpgradeResult:Progress: 是升级全程的状态机驱动源。

回调类型

typedef void (^JL_OTA_RT)(JL_OTAResult result, float progress);
typedef void (^JL_OTA_RESULT)(uint8_t status, uint8_t sn, NSData *__nullable data);

Source: JL_OTAManager.h

JL_OTA_RT 携带 JL_OTAResult 与 0.0~1.0 的 progress，是 cmdOTAData:Result: / cmdUpgrade:Option:Result: 的进度回调；JL_OTA_RESULT 返回指令级 status/sn/data，用于 cmdOTACancelResult: 等指令确认场景。

核心流程：OTA 升级端到端控制流

sequenceDiagram
    participant App as 开发者 App
    participant Mgr as JL_OTAManager
    participant BLE as JL_BLEKit / CoreBluetooth
    participant Dev as 杰理设备
    participant Svr as 杰理 OTA 服务器

    App->>Svr: JLOTAFile cmdGetOtaFileKey:Code: 拉取固件
    Svr-->>App: JL_OTA_URL(url, version, explain)
    App->>Mgr: getOTAManager 获取单例
    App->>Mgr: 填充 mBLE_UUID / mBLE_NAME / delegate
    App->>BLE: 连接设备
    BLE-->>App: 连接成功
    App->>Mgr: noteEntityConnected
    App->>Mgr: cmdTargetFeature 查询 OTA 特性
    Mgr-->>App: otaFeatureResult 回调（读能力字段）
    App->>Mgr: cmdUpgrade:data Option:Result: 发起升级
    Mgr->>Dev: 握手 / 进入 OTA 模式
    Dev-->>Mgr: JL_OTAResultPreparing / Prepared
    Mgr->>Dev: 分包传输固件（otaDataSend 注入 BLE 通道）
    Dev-->>Mgr: ACK + 传输计数
    Mgr-->>App: otaUpgradeResult:Progress: 进度回调
    alt 单备份需回连
        Mgr-->>App: JL_OTAResultReconnect / ReconnectWithMacAddr
        Mgr->>BLE: 按 UUID/MAC 回连设备
    end
    Mgr-->>App: JL_OTAResultSuccess
    App->>Mgr: cmdRebootDevice 请求设备重启

流程要点：

1. 授权取包：先通过 JLOTAFile 的 cmdGetOtaFileKey:Code:Result: 从服务器换取固件下载地址（JL_OTA_URL 回调返回 url/version/explain）；
2. 连接与告知：App 基于 JL_BLEKit 建立 BLE 连接后，必须调用 noteEntityConnected 让 OTA 库感知连接就绪；
3. 特性查询：cmdTargetFeature 应在连接后第一时间调用，其 otaFeatureResult 回调会填充 JL_OTAManager 的能力属性（单/双备份、是否强制、是否需要 BootLoader、资源升级模式等），这些字段决定了后续传输策略；
4. 发起升级：cmdUpgrade:Option:Result:（推荐）或 cmdOTAData:Result: 携带固件数据启动升级，库内部完成握手、进入 OTA 模式、状态机推进；
5. 传输与进度：库把待发送数据通过 delegate 的 otaDataSend: 交还上层写入 BLE，同时用 otaUpgradeResult:Progress: 上报状态与 0~1 进度；
6. 回连处理：单备份设备在进入 OTA 模式后链路会断开，库按 otaReconnectType（UUID/MAC）自动回连，期间返回 JL_OTAResultReconnect / JL_OTAResultReconnectWithMacAddr；
7. 收尾：升级成功后上层调用 cmdRebootDevice 让设备重启进入新固件。

JLOTAFile：授权固件文件下载

JLOTAFile 是杰理科技提供的 OTA 文件管理类，主要用于支持 OTA 升级文件的下载和管理功能，通过简单的接口调用，开发者可以轻松获取固件文件并实现相关业务逻辑。

结果枚举

回调类型

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

Source: docs/JL_OTALib.framework API 说明.md

回调参数说明：

• result：结果状态，对应 JL_OTAUrlResult 枚举值；
• version：文件版本信息，可能为空（nullable）；
• url：下载链接地址，可能为空；
• explain：文件说明信息，可能为空。

文件下载方法

-(void)cmdGetOtaFileKey:(NSString*)key
                   Code:(NSString*)code
                 Result:(JL_OTA_URL __nullable)result

Source: docs/JL_OTALib.framework API 说明.md

描述：根据授权 key 和 code，下载指定的 OTA 升级文件。

参数：

• key：授权的密钥；
• code：授权码；
• result：下载结果回调，返回文件信息和状态。

设计意图：key/code 授权机制保证只有合法渠道（如与杰理签约的 App）才能获取固件包，url 与下载动作分离——JLOTAFile 只负责换取下载地址与元信息，实际的文件传输可由 App 使用任意下载框架完成，避免在库内重复实现下载器。

使用示例

以下示例均取自仓库内可验证的 API 定义与文档，展示典型接入代码结构。

示例 1：获取单例并配置设备信息

// 获取 OTA 升级管理对象（单例）
JL_OTAManager *otaManager = [JL_OTAManager getOTAManager];

// 填入设备信息（BLE 连接后从 JL_BLEKit 回调中获得）
otaManager.mBLE_UUID  = deviceUUID;   // 设备 UUID
otaManager.mBLE_NAME  = deviceName;   // 设备名称
otaManager.bleAddr    = deviceAddr;   // 蓝牙地址
otaManager.delegate   = self;         // 实现 JL_OTAManagerDelegate
otaManager.otaReconnectType = JL_OTAReconnectTypeUUID; // 回连方式

Source: JL_OTAManager.h（属性与方法定义）；docs/JL_OTALib.framework API 说明.md

示例 2：实现升级回调协议

@interface ViewController () <JL_OTAManagerDelegate>
@end

// @required：即将发送的数据，写入 BLE 通道
- (void)otaDataSend:(NSData *)data {
    // 通过 JL_BLEKit 的发送接口把 data 发往设备
    [self.bleManager sendData:data];
}

// @optional：特性查询结果
- (void)otaFeatureResult:(JL_OTAManager *)manager {
    // 读取 manager.otaStatus / otaPartition / bootloaderType 等能力
    self.isForceUpdate = (manager.otaStatus == JL_OtaStatusForce);
}

// @optional：升级状态与进度
- (void)otaUpgradeResult:(JL_OTAResult)result Progress:(float)progress {
    // 驱动 UI 进度条与状态文案
    [self.progressView setProgress:progress animated:YES];
    if (result == JL_OTAResultSuccess) {
        [self showTip:@"升级成功，设备即将重启"];
    }
}

// @optional：取消升级
- (void)otaCancel {
    [self showTip:@"升级已取消"];
}

Source: JL_OTAManager.h

示例 3：发起升级（内部回连方式）

// 推荐方式：内部实现回连，使用 Result 回调而非 delegate
[otaManager cmdUpgrade:otaData
                Option:nil                    // 或传入 JLOtaReConnectOption
                Result:^(JL_OTAResult result, float progress) {
    // 升级状态与进度统一在此回调处理
    if (result == JL_OTAResultSuccess) {
        // 成功后请求设备重启
        [otaManager cmdRebootDevice];
    } else if (result == JL_OTAResultFailCmdTimeout) {
        // 指令超时处理
    }
}];

Source: docs/JL_OTALib.framework API 说明.md

示例 4：授权下载固件文件

JLOTAFile *otaFile = [[JLOTAFile alloc] init]; // 或按 SDK 方式获取实例

[otaFile cmdGetOtaFileKey:@"YOUR_AUTH_KEY"
                     Code:@"YOUR_AUTH_CODE"
                   Result:^(JL_OTAUrlResult result,
                            NSString *version,
                            NSString *url,
                            NSString *explain) {
    if (result == JL_OTAUrlResultSuccess) {
        // 使用 url 下载固件，version 可做版本比对
        [self downloadFirmwareFromURL:url];
    } else if (result == JL_OTAUrlResultDownloadFail) {
        // 下载失败处理
    }
}];

Source: docs/JL_OTALib.framework API 说明.md

示例 5：连接事件注入与参数调优

// BLE 连接成功时告知 OTA 库
[otaManager noteEntityConnected];

// 连接后第一时间查询 OTA 特性
[otaManager cmdTargetFeature];

// 调优传输参数（默认值：超时 5 秒、最大丢包 10 次）
[otaManager cmdTimeOut:5];
[otaManager maxLostCount:10];

// 调试：打印 OTA 发送的数据内容
[otaManager logSendData:YES];

// BLE 断开时告知 OTA 库
[otaManager noteEntityDisconnected];

Source: JL_OTAManager.h；docs/JL_OTALib.framework API 说明.md

配置选项

JL_OTAManager 的配置通过公开属性与方法完成，无独立配置文件；以下为完整配置项清单：

Source: JL_OTAManager.h

API 参考

JL_OTAManager

+ (JL_OTAManager *)getOTAManager

获取 OTA 升级管理对象（单例）。init 已废弃，禁止自行初始化。

• 返回：全局唯一的 JL_OTAManager 实例。

- (void)noteEntityConnected / - (void)noteEntityDisconnected

向 OTA 库注入 BLE 连接/断开事件，驱动内部回连状态机。

- (void)cmdTargetFeature

查询设备支持的 OTA 特性，建议连接设备后第一时间调用；结果经 otaFeatureResult: 回调返回。

- (void)cmdSystemFunction

查询设备系统状态，主要用于外置 Flash 场景。

- (void)cmdOTAData:(NSData *)data Result:(JL_OTA_RT __nullable)result

发起 OTA 升级请求。

• 参数 data：升级文件数据；
• 参数 result：升级结果回调 JL_OTA_RT(JL_OTAResult result, float progress)。

- (void)cmdUpgrade:(NSData *)data Option:(JLOtaReConnectOption *_Nullable)option Result:(JL_OTA_RT _Nonnull)result

内部实现回连的升级接口，免去公版 OTA 的外边回连策略。

• ⚠️ 使用此方法时不可使用 delegate 回调，必须使用 Result 回调；
• 参数 option：回连选项（JLOtaReConnectOption，可为 nil）。

- (void)cmdOTACancelResult:(JL_OTA_RESULT __nullable)result

取消当前 OTA 升级流程；完成时触发 otaCancel delegate 回调。

- (BOOL)cmdOtaIsRelinking

检查当前 OTA 单备份是否正在回连。

• 返回：正在回连返回 YES。

- (void)cmdRebootDevice / - (void)cmdRebootForceDevice

请求设备重启 / 强制请求设备重启（升级成功后的收尾动作）。

- (void)logSendData:(BOOL)status / - (void)maxLostCount:(int)count / - (void)cmdTimeOut:(int)timeOut

调试打印开关 / 设置最大丢包次数（默认 10）/ 设置指令超时（默认 5 秒）。

JLOTAFile

- (void)cmdGetOtaFileKey:(NSString *)key Code:(NSString *)code Result:(JL_OTA_URL __nullable)result

根据授权 key 与 code 获取 OTA 升级文件信息。

• 参数 key：授权密钥；
• 参数 code：授权码；
• 参数 result：JL_OTA_URL 回调（result/version/url/explain）；
• 结果状态：JL_OTAUrlResultSuccess / JL_OTAUrlResultFail / JL_OTAUrlResultDownloadFail。

回调协议 JL_OTAManagerDelegate

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

错误码驱动的失败处理

升级失败统一通过 JL_OTAResult 编码，常见分支建议：

• 低电量 JL_OTAResultLowPower：提示用户充电后重试（升级中设备断电会变砖风险最高）；
• 未能进入 OTA 模式 JL_OTAResultEnterFail / 指令失败 JL_OTAResultCommandFail：检查设备是否处于可升级状态、mBLE_UUID/mBLE_NAME 是否填写正确；
• 校验类失败 JL_OTAResultFailVerification / JL_OTAResultFailKey / JL_OTAResultFailErrorFile / JL_OTAResultFailSameSN：多为固件文件不匹配或授权问题，应重新获取固件；
• 硬件类失败 JL_OTAResultFailFlash / JL_OTAResultFailUboot / JL_OTAResultFailLenght：设备侧异常，需联系固件团队；
• TWS/充电仓约束 JL_OTAResultFailTWSDisconnect / JL_OTAResultFailNotInBin：耳机类设备升级前的环境约束检查失败；
• 相同版本 JL_OTAResultFailSameVersion：应先比对 version/versionFirmware 再做升级。

重连边界

• 单备份设备升级需先断开再重连，库返回 JL_OTAResultReconnect（UUID）或 JL_OTAResultReconnectWithMacAddr（MAC）；otaReconnectType 决定回连方式，MAC 方式依赖 bleAddr 已正确填充；
• cmdOtaIsRelinking 可轮询回连状态，回连期间不应重复发起升级；
• JL_OTAResultFailedConnectMore 表示当前固件同时连接了多台设备，必须由用户手动断开其他设备后再试——这是用户交互类错误，不能自动重试。

并发与线程注意

• JL_OTAManager 为单例，多个页面/业务同时持有引用时，升级状态机是共享的，应在 App 层做"仅一个升级会话"的互斥控制；
• delegate 为 weak 引用，持有 delegate 的对象（如 VC）必须在升级期间保持存活，否则回调静默丢失；
• otaDataSend: 在库内部按传输节奏调用，上层写 BLE 通道时应保持顺序写入，避免并发写导致丢包（配合 maxLostCount: 重传机制兜底）。

性能与运维

• 传输性能：升级采用分包 + ACK + 重传机制，maxLostCount:（默认 10）控制容忍丢包上限，cmdTimeOut:（默认 5 秒）控制单条指令超时；弱信号环境下可适当调大超时；
• 进度观测：只读属性 otaLength/otaSent 与 otaUpgradeResult:Progress: 回调提供双重进度来源，可交叉校验；
• 调试手段：logSendData: 可打印发送内容，配合 SDKTestHelper 工程（APP说明书.md 第 1.27 节）中的自定义命令工具可定位协议层问题；
• 升级安全：升级期间禁止断开 App/设备（杀进程、退后台被系统挂起）——OTA 传输基于 BLE 长连接，中断后需依赖库的重连机制恢复。

扩展点

• 自定义命令：JLOtaCustom（头文件 JLOtaCustom.h）提供 OTA 库自定义命令通道，可在标准升级流程之外向设备下发私有指令（详见 SDKTestHelper 文档第 1.27 节）；
• 资源升级模式：JLOtaSourcesExtendMode 支持"仅资源 / 仅固件 / 普通"三种扩展模式，配合 isSupportExpand/isSupportReuseSpaceOTA 适配不同设备的存储策略；
• 回连定制：JLOtaReConnectOption 允许在 cmdUpgrade:Option: 中定制回连参数；
• 固件格式解析：jl_ufw.h 提供 UFW 固件格式解析能力，可用于升级前校验固件头信息。

测试与示例工程

• 仓库根 README.md 说明了 SDK 框架栈组成，JL_OTALib.xcframework 同时提供 ios-arm64（真机）与 ios-arm64_x86_64-simulator（模拟器）切片；
• code/SDKTestHelper/README.md 展示了测试工程内 JL_OTALib.xcframework 的引用方式；
• 翻译传输功能说明.md 展示了 import JL_OTALib 的 Swift 集成方式及与 JL_HashPair 的联合使用；
• APP说明书.md 第 1.27 节给出 OTA 库自定义命令的测试入口。

Related Links

• JL_OTALib.framework API 说明（官方 API 文档）
• JL_OTAManager.h（头文件）
• JLOTAFile.h（文件下载头文件）
• JLOtaReConnectOption.h（回连选项头文件）
• JLOtaCustom.h（自定义命令头文件）
• jl_ufw.h（UFW 固件格式头文件）
• 仓库根 README.md（框架结构总览）
• 翻译传输功能说明.md（JL_OTALib 与 JL_HashPair 联合使用）
• APP说明书.md（OTA 库自定义命令测试章节）

注：本页为文档中心内 JL_OTALib 专属 API 页；蓝牙连接与扫描细节请参考 JL_BLEKit 相关文档，表盘与翻译功能请参考 JLDialUnit / JL_HashPair 相关页面。