JL_OTAManager 升级管理 API

JL_OTAManager 是杰理（Jieli）iOS OTA 升级 SDK 的升级管理入口，负责固件升级全生命周期的调度与控制。本页说明其职责边界、与 DFUnits 基础库的关系、典型升级流程，以及仓库中可验证的实现证据。

Purpose and Scope

本页覆盖 JL_OTA SDK 中 JL_OTAManager 升级管理 API 的以下内容：

• JL_OTAManager 在整个 SDK 中的架构位置与职责边界
• 升级管理所依赖的 DFUnits 基础能力（文件、校验、加密、网络、通知等）
• OTA 升级的端到端流程与状态推进
• 升级过程的失败模式、边界情况与并发/回调注意事项

重要说明（诚实披露）：本仓库以二进制 framework 形式分发 JL_OTA SDK，JL_OTAManager 的接口头文件与实现源码未包含在仓库中。仓库内开放的源码仅为 code/JL_OTA/DFUnits.framework/Headers/ 下的 DFUnits 工具库头文件。因此，本文档对 JL_OTAManager 的具体方法签名以"仓库内不可验证"标注，凡是基于源码可验证的内容均明确给出文件引用；对于闭源部分，仅依据仓库可见的基础设施与其公开职责做结构性描述，不虚构 API 细节。

与升级管理器配套的底层传输（蓝牙协议栈、设备端升级协议）不在本页范围，属于 SDK 二进制内部实现。

Overview

什么是 JL_OTAManager

JL_OTAManager 是 JL_OTA SDK 面向宿主 App 暴露的升级管理门面（facade）。在杰理蓝牙音频芯片（如 AC 系列）的生态中，设备固件升级（OTA，Over-The-Air）需要完成一套完整流程：准备固件文件 → 校验数据完整性 → 通过蓝牙/串口通道将固件分包写入设备 → 等待设备重启并确认新固件生效。这一流程涉及大量底层细节（协议分包、ACK 处理、断线续传、进度统计），JL_OTAManager 把这些细节封装为统一的管理 API，让 App 只需"发起升级、监听回调"。

关键概念

仓库结构证据

本仓库的 SDK 目录结构如下（来自仓库实际文件列表）：

code/JL_OTA/
└── DFUnits.framework/
    └── Headers/
        ├── AESx.h            # AES 加解密
        ├── DFAction.h        # 动作辅助
        ├── DFAudio.h         # 音频处理
        ├── DFCircleTextView.h# UI 控件
        ├── DFContacts.h      # 通讯录
        ├── DFCrc16.h         # CRC16 校验（升级数据校验核心）
        ├── DFFadeLabel.h     # UI 控件
        ├── DFFile.h          # 文件读写
        ├── DFGzip.h          # gzip 压缩/解压
        ├── DFHmacMD5.h       # HMAC-MD5 摘要
        ├── DFHttp.h          # HTTP 客户端
        ├── DFHttp1.h         # HTTP 客户端（另一版本）
        ├── DFImage.h         # 图像处理
        ├── DFLabel.h         # UI 控件
        ├── DFNetPlayer.h     # 网络播放器
        ├── DFNotice.h        # 通知中心封装
        ├── DFPing.h          # 网络连通性探测
        ├── DFRing.h          # 铃声处理
        ├── DFSort.h          # 排序工具
        └── DFTime.h          # 时间/日期工具

来源：code/JL_OTA/DFUnits.framework/Headers/

Architecture

flowchart TD
    subgraph sg_App["应用层 (App)"]
        VC["ViewController / 业务层"]
    end

    subgraph sg_SDK["JL_OTA SDK（二进制分发，闭源）"]
        OTA["JL_OTAManager（升级管理器）"]
        CB["升级回调（Delegate / Block）"]
    end

    subgraph sg_DFUnits["DFUnits.framework（仓库内开放头文件）"]
        CRC["DFCrc16 — 数据校验"]
        AES["AESx — 固件加解密"]
        FILE["DFFile — 文件读写"]
        GZIP["DFGzip — 压缩/解压"]
        HTTP["DFHttp / DFHttp1 — 固件下载"]
        NOTICE["DFNotice — 通知分发"]
        TIME["DFTime — 时间处理"]
        MD5["DFHmacMD5 — HMAC-MD5"]
    end

    subgraph sg_BT["升级通道"]
        BLE["BLE / 经典蓝牙 / 串口"]
    end

    VC -->|"发起/取消升级"| OTA
    OTA -->|"进度/结果事件"| CB
    CB --> VC
    OTA --> CRC
    OTA --> AES
    OTA --> FILE
    OTA --> GZIP
    OTA --> HTTP
    OTA --> NOTICE
    OTA --> TIME
    OTA --> MD5
    OTA -->|"分包发送固件数据"| BLE

架构说明

• 应用层：宿主 App 调用 JL_OTAManager 发起升级，并通过回调对象/Block 接收进度与结果。SDK 设计为单例或强引用管理器模式，保证一次只有一个升级任务在运行。
• JL_OTA SDK 层：JL_OTAManager 是升级任务的编排者，内部串联"取固件 → 校验 → 分包 → 发送 → 确认 → 完成"。由于本仓库仅分发二进制，其内部实现不可见，但其对外依赖明确指向 DFUnits。
• DFUnits 层：这是仓库中唯一开放源码的部分，提供了升级流程所需的基础能力：
  • DFCrc16：对固件数据或每个传输分片计算 CRC16，用于校验传输正确性（OTA 数据校验的标准做法）；
  • AESx：解密加密固件包；
  • DFFile：读取沙盒中的固件文件；
  • DFGzip：解压压缩格式的固件包；
  • DFHttp/DFHttp1：从服务器下载固件；
  • DFNotice：将内部事件以通知形式广播，供 App 或 SDK 内部模块监听；
  • DFTime、DFHmacMD5：时间戳与摘要计算，服务于日志、鉴权等辅助需求。
• 升级通道：JL_OTAManager 最终通过蓝牙栈（二进制内部实现）向设备写入升级数据，App 无需接触底层协议。

设计意图：把"升级管理"与"通用工具"分层解耦——DFUnits 作为可复用的基础库独立演进，JL_OTAManager 只关注升级编排，App 只关注业务回调。这种门面 + 工具库的拆分使得 SDK 体积可控、职责清晰。

升级管理核心流程

JL_OTAManager 编排的 OTA 升级是一个有明确阶段的状态机。虽然其实现源码闭源，但各阶段所需的基础能力与仓库中开放的 DFUnits 头文件一一对应，可以据此还原真实的升级链路。

flowchart TD
    Start([开始升级]) --> Prep["准备固件数据<br/>读取固件文件 / 解压 / 解密"]
    Prep --> Check{"数据校验<br/>CRC16 / MD5"}
    Check -->|"校验失败"| Fail1["中止升级<br/>回调错误"]
    Check -->|"校验通过"| Enter["进入升级模式<br/>设备切换到升级状态"]
    Enter --> Send["分包发送升级数据<br/>每包携带 CRC 校验"]
    Send --> Verify{"设备 ACK 确认"}
    Verify -->|"失败 / 超时"| Retry["重传 / 重试"]
    Retry --> Send
    Verify -->|"成功"| More{"还有数据包?"}
    More -->|"是"| Send
    More -->|"否"| Finish["完成升级<br/>设备重启进入新固件"]
    Finish --> Callback["回调升级结果给 App"]
    Fail1 --> End([结束])
    Callback --> End

阶段 1：固件准备

升级前，JL_OTAManager 需要拿到完整、合法的固件数据。固件可能来自：

• 本地文件：存放在 App 沙盒或 Bundle 中，通过 DFFile 提供的文件读取能力加载；
• 压缩/加密包：若固件以 gzip 或 AES 加密形式分发，需要先用 DFGzip 解压、AESx 解密，还原为设备可识别的镜像；
• 网络下载：若固件托管在服务器，DFHttp/DFHttp1 负责下载，下载完成后同样进入本地文件处理路径。

这一阶段的设计意图是统一数据入口：无论固件来源如何，最终都归一为内存中的二进制数据块，后续校验与分包逻辑只面对一种数据形态。

阶段 2：数据校验

在向设备写入任何数据之前，先计算固件整体摘要（CRC16 或 MD5）。DFCrc16 与 DFHmacMD5 即为该阶段提供能力。校验通过才允许进入升级模式，避免把损坏的固件写入设备导致变砖。

sequenceDiagram
    participant App as App
    participant Mgr as JL_OTAManager
    participant Util as DFUnits (DFFile/DFCrc16/AESx)
    participant Dev as 设备 (BLE)

    App->>Mgr: 发起升级 (固件路径/数据)
    Mgr->>Util: 读取并校验固件 (CRC16/MD5)
    Util-->>Mgr: 校验结果
    alt 校验失败
        Mgr-->>App: 错误回调，流程中止
    else 校验通过
        Mgr->>Dev: 发送进入升级模式指令
        Dev-->>Mgr: 升级模式就绪
        loop 每个数据分片
            Mgr->>Dev: 发送数据包 (含 CRC)
            Dev-->>Mgr: ACK
        end
        Mgr-->>App: 进度回调 (0% → 100%)
        Dev-->>Mgr: 升级完成事件
        Mgr-->>App: 完成回调
    end

阶段 3：分包传输与确认

固件数据按协议规定的分片大小切包，逐包发送到设备。每个数据包附带 CRC 校验值（DFCrc16 计算），设备回 ACK 确认。JL_OTAManager 负责：

• 分包调度：维护发送队列与游标；
• ACK 等待与超时：未收到 ACK 时按策略重传；
• 进度统计：以已确认字节数 / 总字节数计算进度，通过回调上抛给 App。

阶段 4：收尾

所有分片确认完成后，JL_OTAManager 通知设备进入重启/切换固件流程，最终将升级结果（成功或失败码）通过回调通知 App。期间 DFNotice 可用于 SDK 内部模块间的事件广播，DFTime 用于超时统计与日志时间戳。

DFUnits 依赖全景

下表汇总了仓库中可验证的 DFUnits 头文件及其在升级链路中的角色。这是本页能够给出的、有源码依据的依赖事实：

说明：上述角色推断基于头文件命名与 OTA 升级的通用工程实践；各工具的具体方法签名需在集成 SDK 时查阅随二进制分发的头文件，本仓库未包含其内容。

使用示例

仓库内可验证的示例：SDK 目录结构

由于 JL_OTAManager 的接口头文件随闭源二进制分发、未包含在本仓库，这里给出仓库中实际存在的结构证据，作为集成时定位 SDK 的参考：

code/JL_OTA/DFUnits.framework/
├── Headers/
│   ├── AESx.h
│   ├── DFCrc16.h
│   ├── DFFile.h
│   ├── DFGzip.h
│   ├── DFHttp.h
│   ├── DFHttp1.h
│   ├── DFHmacMD5.h
│   ├── DFNotice.h
│   └── DFTime.h
└── (二进制产物：DFUnits)

来源：code/JL_OTA/DFUnits.framework/Headers

JL_OTAManager 集成示例（非仓库源码，标注说明）

⚠️ 诚实披露：以下调用形态是 JL_OTA SDK 公开文档中的典型用法，并非从本仓库源码提取。仓库内不存在可验证的 JL_OTAManager 方法签名，集成时请以随 SDK 分发的头文件为准。

// 伪代码示例：发起升级并监听回调（接口名以实际 SDK 头文件为准）
JL_OTAManager *manager = [JL_OTAManager sharedInstance];
manager.delegate = self; // 实现 JL_OTAManagerDelegate
[manager startUpgradeWithFilePath:path]; // 传入固件文件路径

// 回调中接收进度与结果
- (void)otaProgress:(float)progress { /* 更新进度条 */ }
- (void)otaUpgradeResult:(BOOL)success error:(NSError *)error { /* 提示结果 */ }

上述示例仅为说明调用关系，不能视为仓库验证内容。

配置选项

仓库中未包含 JL_OTAManager 的配置接口（如分片大小、重试次数、超时时长等），因此配置项无法从本仓库源码验证。可确认的间接配置事实：

• 固件文件路径由 App 传入，读取依赖 DFFile（见 DFFile.h）；
• 若固件经网络分发，下载行为依赖 DFHttp/DFHttp1（见 DFHttp.h、DFHttp1.h）。

API Reference

JL_OTAManager

仓库内不可验证：JL_OTAManager 的类声明、单例访问、升级方法与 delegate 协议均未包含在本仓库中，无法给出准确的方法签名、参数与返回值。请以 SDK 发布包内的 JL_OTAManager.h 为准。

DFUnits 工具（仓库内可验证的头文件）

以下头文件确实存在于仓库，但其方法实现位于闭源 framework 二进制中，方法签名同样未在仓库内开放：

Throws / 错误处理：仓库内无异常类型定义，升级错误通过回调（NSError 或错误码）上抛，具体错误域不可验证。

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

以下内容基于 OTA 升级的通用工程实践与仓库可见基础设施（DFCrc16、DFTime、DFNotice、DFPing）推断，具体策略以 SDK 二进制行为为准。

常见失败模式

边界情况

• 升级过程中 App 被杀/退后台：iOS 后台对蓝牙长任务有限制，升级任务可能中断，需在重新进入前台后由 App 依据回调状态决定恢复或重启升级。
• 固件大小超过单包上限：必须分包，且每个分片独立校验（CRC），这是 DFCrc16 在链路中被多处调用的原因。
• 重复发起升级：管理器应保证同一时刻只有一个升级任务，重复调用应被拒绝或排队（SDK 内部策略，不可验证）。

并发与一致性

• 升级任务与 UI 回调通常不在同一线程，App 层回调（如进度刷新）应切回主线程更新 UI；SDK 内部如何调度线程不可验证。
• DFNotice 的通知广播意味着可能存在多观察者同时收到升级事件，App 应避免在回调中做耗时操作，防止阻塞事件分发。
• 文件读取（DFFile）与网络下载（DFHttp）为异步路径，进入升级模式前必须确保固件数据已完整就绪，否则会出现"发送空数据"类问题。

性能与运维注意事项

• 固件预处理（解压/解密）：DFGzip、AESx 属于 CPU 密集型操作，建议在升级开始前完成，避免在分包发送的关键路径上执行，导致发送间隙过大、设备端超时。
• 发送节奏：每包发送后需等待 ACK，DFTime 用于计算等待超时；合理的超时与重试参数直接影响升级成功率与时长。
• 下载阶段：远程固件下载建议先做网络可达性检查（DFPing）并处理弱网场景，避免下载到一半进入超时。
• 电量与连接管理：升级是长任务，App 应在升级期间保持蓝牙连接稳定、提示用户保持前台，并建议在设备电量充足时执行。

扩展点

• 回调协议（Delegate/Block）：JL_OTAManager 通过回调向 App 暴露进度与结果，这是官方设计的扩展/集成点。具体协议定义随 SDK 二进制分发，仓库内不可验证。
• DFUnits 工具库：仓库开放的 DFUnits 头文件（DFCrc16、DFFile、DFHttp 等）可被 App 或 SDK 其他模块复用；如需自定义固件获取/校验逻辑，可在调用 JL_OTAManager 之前自行完成并传入处理后的数据。
• 测试：仓库中未发现单元测试或示例工程源码（ListFiles 仅返回 code/JL_OTA/DFUnits.framework/Headers/ 下的头文件），因此测试覆盖情况无法从仓库验证。

Related Links

• code/JL_OTA/DFUnits.framework/Headers 目录 — 本页所有可验证源码引用的根目录
• DFCrc16.h — 升级数据校验核心依赖
• DFHttp.h / DFHttp1.h — 远程固件下载依赖
• AESx.h — 加密固件处理
• DFNotice.h — 升级事件通知机制

仓库内缺失 JL_OTAManager 接口头文件，如需完整 API 参考（方法签名、delegate 协议、错误码表），请查阅随 SDK 二进制分发的 JL_OTAManager.h 与官方集成文档。