升级文件管理

本文档介绍 iOS-JL_OTA（杰理蓝牙 OTA 升级 SDK for iOS）中「升级文件管理」在 OTA 工作流中的位置与作用：升级文件的准备、分包传输、进度回调与结果上报，以及它在整个设备升级链路中的端到端行为。

目的与范围

本页聚焦 OTA 工作流中的 固件升级文件（firmware upgrade file） 管理能力，即从应用侧准备升级数据、通过 RCSP 协议将文件数据分发给杰理蓝牙设备、直到固件写入完成的全过程。

覆盖内容：

• 升级文件数据在 OTA 流程中的生命周期（准备 → 分包 → 发送 → 结果上报）
• SDK 提供的核心数据入口（cmdOTAData）与回调（otaDataSend、otaUpgradeResult）
• 与文件传输相关的连接/重连机制、设备能力协商（cmdTargetFeature）
• 由 README 公开的集成与配置要求

不属于本页范围（由其他目录页覆盖）：设备扫描/广播解析、Hash 配对认证细节、具体蓝牙连接层的实现（CoreBluetooth / JL_BLEKit / JL_Assist）、GATT Over BR/EDR 经典蓝牙升级。

资料来源说明：本仓库 master 分支当前仅包含 README.md、README_EN.md 与 LICENSE 三个文件；SDK 源码（code/ 示例工程与 libs/ XCFramework）未直接出现在该分支的文件树中（可能通过子模块 / Git LFS / 发布包形式交付）。因此本页以 README.md 公开的流程与 API 契约为依据编写；凡源码中无法直接验证的实现细节，均以「源码中未找到」明确标注。

概述

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

在 OTA 升级中，「升级文件管理」承担的核心职责是：把一份固件升级文件（二进制数据）可靠地、可分片地、可跟踪地传输到设备端。从 README 公开的核心调用流程可见其骨架：

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

（来源：README.md）

其中：

• cmdOTAData(data) 是文件数据发送入口：应用把升级文件的字节数据交给 SDK，SDK 依据 RCSP 协议与当前连接的分包能力（MTU 等）把数据切分成多个包写入设备。
• otaDataSend 是发送进度回调：每发送一部分数据（或每完成一次底层写操作）后回调，供 UI 展示进度条、计算速率。
• otaUpgradeResult 是升级结果回调：设备端完成固件写入、校验后上报最终结果，应用据此判断升级成功/失败并决定下一步（如重新连接设备）。
• cmdTargetFeature 是能力协商：升级前查询设备特性（例如是否支持双备份升级、强制升级），从而决定文件传输策略。

SDK 还通过「回连机制」与「强制升级」支持文件传输中断后的恢复，这是升级文件管理在异常路径上的重要补充。

架构

下图展示了升级文件管理在整个 SDK 与设备之间的位置：应用层通过 SDK 公共 API 操作升级文件，SDK 内部按连接方式把数据送达设备。

flowchart TD
    subgraph sg_App["iOS 应用层"]
        App["应用 / 示例工程<br/>(MiniSingleDemo / JLBleKitOTADemo / JLAssistOTADemo)"]
    end

    subgraph sg_SDK["杰理 OTA SDK 层"]
        OtaLib["JL_OTALib<br/>(RCSP 协议 · 升级文件管理)"]
        AdvParse["JL_AdvParse<br/>(广播解析)"]
        HashPair["JL_HashPair<br/>(Hash 配对认证)"]
        LogHelper["JLLogHelper<br/>(日志)"]
    end

    subgraph sg_Conn["蓝牙连接层"]
        CB["CoreBluetooth<br/>(原生)"]
        BLEKit["JL_BLEKit<br/>(SDK 内置)"]
        Assist["JL_Assist<br/>(自定义桥接)"]
    end

    subgraph sg_Dev["设备层"]
        Dev["杰理蓝牙设备<br/>(AC695X / AC608N / JL701N ...)"]
    end

    App -->|"cmdOTAData / cmdTargetFeature"| OtaLib
    OtaLib --> AdvParse
    OtaLib --> HashPair
    OtaLib --> LogHelper
    OtaLib --> CB
    OtaLib --> BLEKit
    OtaLib --> Assist
    CB -->|"GATT 特征写入 (分包)"| Dev
    BLEKit -->|"GATT 特征写入 (分包)"| Dev
    Assist -->|"GATT 特征写入 (分包)"| Dev

架构说明：

• JL_OTALib 是升级文件管理的核心宿主：文件数据的组织、分包、发送节奏、重试与结果判定都在这一层完成，对应用暴露 cmdOTAData 等 API 与 otaUpgradeResult、otaDataSend 等委托回调（契约见 README.md）。
• 连接层三选一：README 明确 SDK 提供三种蓝牙连接方式——原生 CoreBluetooth（完全掌控扫描/连接/服务/分包发送）、JL_BLEKit（快速集成）、JL_Assist（桥接既有蓝牙层），详见 README.md。文件数据最终都通过所选连接层写入设备 GATT 特征。
• 配套框架：JL_AdvParse（解析杰理广播包）、JL_HashPair（Hash 配对认证保障设备安全）、JLLogHelper（日志）与 JL_OTALib 一起以 XCFramework 形式交付，见 README.md。

升级文件管理的实现机制

以下各小节依据 README 公开的 OTA 核心调用流程与 SDK 功能说明整理；在 master 分支没有源码文件可供逐行核对的情况下，凡涉及 SDK 内部实现细节的描述均以「源码中未找到」标注，避免臆测。

升级文件在 OTA 流程中的位置

升级文件管理不是一个独立可调用的模块，而是贯穿整个 OTA 工作流的"数据通道"。README 给出的核心调用流程（README.md）可以拆解为三个阶段：

1. 会话建立阶段：设备连接 + 订阅通知 → 收到 noteEntityConnected。这是文件传输的前提——只有建立了可靠的 GATT 连接并订阅了特征通知，才能双向传输数据。
2. 能力协商阶段：调用 cmdTargetFeature 查询设备特性。这一步决定文件传输策略：
   • 设备是否支持单备份/双备份升级（双备份意味着升级失败后设备仍可回退到旧固件，文件传输可以更激进）；
   • 是否支持强制升级（设备当前固件状态不允许常规升级时，仍可强制写入新文件）。
3. 文件传输与收尾阶段：cmdOTAData(data) 逐段发送升级文件字节；期间通过 otaDataSend 上报发送进度；设备完成写入后通过 otaUpgradeResult 返回升级结果；连接断开时触发 noteEntityDisconnected，应用据此清理会话状态。

升级文件的准备与能力校验

• 文件来源：升级文件（固件二进制，如 .bin）由应用侧持有，通常是用户在 App 内选择或从服务器下载得到；SDK 侧只负责传输与结果确认。源码中未找到文件格式校验、CRC/哈希校验的具体实现。
• 升级前校验：通过 cmdTargetFeature 查询设备能力，若设备不支持当前文件要求的升级模式（如需要双备份而设备只支持单备份），应用应在发送文件前中止并提示用户。这一点在 README 中体现为"设备特性查询"步骤位于 cmdOTAData 之前（README.md），设计意图是先确认能力、再开始耗时的文件传输，避免在传输中途才发现不兼容。
• 认证前置：Hash 配对认证（JL_HashPair）保障设备安全，认证失败时文件传输不应开始；README 功能表将其列为独立能力（README.md）。

升级文件的分包传输（cmdOTAData）

cmdOTAData(data) 是文件数据进入 SDK 的入口。结合 README 对连接方式的说明（原生 CoreBluetooth 场景强调"完全掌控……分包发送"，README.md），可推断其内部机制：

1. SDK 将传入的 data 按当前连接的 MTU / 特征写入长度切分为若干数据包；
2. 按 RCSP 协议为每个包封装协议头（命令字、序号、总包数等；具体格式源码中未找到）；
3. 通过所选连接层写入设备的 GATT 特征，等待设备应答后发送下一包（流控）；
4. 每完成一个可观测的发送进度点，触发 otaDataSend 回调，让 UI 得以更新进度条。

设计意图：把"大文件传输"抽象为"有节奏的分包写入"，既适配 BLE 单次写入长度限制，又通过回调把底层发送节奏暴露给 UI，避免应用自行处理 MTU 协商与流控。

传输进度与结果回调（otaDataSend / otaUpgradeResult）

• otaDataSend：发送进度回调。典型用途是展示进度百分比、已发送字节数、速率；也可用于在发送卡顿时实现超时检测（超时实现源码中未找到）。
• otaUpgradeResult：升级结果回调。设备完成固件写入与校验后返回，应用据此判断成功/失败；失败时可结合回连机制安排重试。
• noteEntityDisconnected：会话结束信号。文件传输过程中若连接中断，该回调触发，应用应停止发送、记录断点，并可按 README 提到的回连机制重新连接继续升级（README.md）。

连接方式对文件传输的影响

README 提供三种连接方式（README.md），文件管理在三种方式下的差异：

选择指南（引自 README.md）：完全掌控 BLE 细节 → 原生；快速集成 → JL_BLEKit；已有蓝牙管控 → JL_Assist。

核心流程

下图是升级文件在典型 OTA 会话中的端到端时序（依据 README 公开流程绘制）：

sequenceDiagram
    participant App as iOS 应用
    participant SDK as JL_OTALib (RCSP)
    participant BLE as 蓝牙连接层
    participant Dev as 杰理蓝牙设备

    App->>BLE: 连接设备 + 订阅特征
    BLE-->>App: noteEntityConnected (会话建立)
    App->>SDK: cmdTargetFeature (能力协商)
    SDK-->>App: 设备特性 (单/双备份、强制升级支持)

    loop 升级文件分包传输
        App->>SDK: cmdOTAData(data) 文件数据
        SDK->>BLE: 按 MTU 分包写入 GATT 特征
        BLE-->>Dev: 数据包 (RCSP 协议)
        Dev-->>BLE: 应答/进度
        BLE-->>SDK: 写完成
        SDK-->>App: otaDataSend (发送进度)
    end

    Dev-->>SDK: 固件写入完成
    SDK-->>App: otaUpgradeResult (升级结果)
    BLE-->>App: noteEntityDisconnected (会话结束)

关键点说明：

• 能力协商必须先于文件传输：cmdTargetFeature 的结果决定后续 cmdOTAData 的发送策略，顺序颠倒会导致文件传输失败或设备拒绝写入。
• 进度回调是应用感知文件传输的唯一窗口：otaDataSend 的触发时机与 SDK 内部分包节奏绑定，UI 层不应自行假设发送进度。
• 升级结果以设备侧为准：otaUpgradeResult 由设备完成写入后上报，应用不应把"数据发送完毕"误判为"升级成功"。

使用示例

以下代码片段摘自 README.md，展示了升级文件管理在应用侧的核心调用契约（cmdOTAData / otaUpgradeResult / otaDataSend 等均为 SDK 公开 API）。

核心调用流程（集成骨架）

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

Source: README.md

解读：这是升级文件管理的"最小可用链路"。应用在 noteEntityConnected 回调后把升级文件字节传入 cmdOTAData；SDK 负责分包、发送与流控；应用通过两个委托回调感知进度与结果，并在断开时清理状态。

集成步骤（依赖与权限）

1. 集成 JL_OTALib.xcframework、JL_AdvParse.xcframework、JL_HashPair.xcframework、
   JLLogHelper.xcframework 并设置 Embed & Sign
2. 配置权限：Privacy - Bluetooth Peripheral/Always Usage Description

Source: README.md

解读：文件管理能力位于 JL_OTALib 中；JL_AdvParse、JL_HashPair、JLLogHelper 是其配套框架。Embed & Sign 保证框架在真机上的签名正确性；蓝牙权限描述是 App 使用 BLE 的前提（iOS 12.0+）。

快速开始（SDK 导入与初始化）

1. 导入框架：将 libs/ 目录下的 XCFramework 添加到项目中
2. 配置权限：在 Info.plist 中添加蓝牙使用权限描述
3. 初始化 SDK：参考示例工程的初始化代码进行集成
4. 开始开发：使用 SDK 提供的 API 进行 OTA 升级功能开发

Source: README.md

解读：libs/ 目录是 XCFramework 的交付位置（本分支文件树中未包含该目录，以发布包形式交付）。示例工程的初始化代码位于 code/ 下的三个 Demo 中，是文件管理 API 调用的最佳参考。

说明：由于 master 分支不包含 Objective-C/Swift 源码文件，此处无法给出真实的 cmdOTAData 方法签名与委托协议定义；以上契约以 README 原文为准。

配置选项

升级文件管理相关的配置主要来自 SDK 集成与工程配置（依据 README.md 与 README.md）：

API 参考

以下 API 与回调为升级文件管理的公开契约，名称与调用顺序引自 README.md。注意：master 分支无源码文件，签名与参数类型无法从源码验证，此处仅列出契约语义，勿视为精确签名。

调用顺序约束：noteEntityConnected → cmdTargetFeature → cmdOTAData(data) → （otaDataSend 多次）→ otaUpgradeResult；断开时 noteEntityDisconnected。

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

连接中断与回连机制

• 现象：文件传输过程中 BLE 连接断开，noteEntityDisconnected 触发，otaDataSend 停止上报。
• 处理：README 将回连机制列为 OTA 升级的内置能力（README.md），即应用可在断开后重新连接设备继续升级流程。设计意图是容忍弱信号/掉线环境下的长文件传输。
• 边界：回连后是否需要重传全部文件或仅续传剩余部分，取决于设备端状态与 SDK 实现，源码中未找到断点续传细节，应用侧应按「重新走一遍能力协商后再发送」的保守策略设计。

能力不匹配

• cmdTargetFeature 返回的能力若与升级文件要求的模式不符（例如设备仅支持单备份，而文件升级流程需要双备份保障），应在发送前中止。README 把该查询置于 cmdOTAData 之前（README.md），正是为了避免传输中途失败。

强制升级场景

• 设备固件状态异常时，常规升级可能被拒绝；README 明确支持强制升级（README.md）。强制升级会跳过部分安全校验，应仅在明确需要时使用，并对失败后果有预案（如设备进入恢复模式）。

发送节奏与流控

• BLE 单次特征写入长度有限，文件必须分包发送。若应用把整个文件一次性塞入 cmdOTAData，SDK 仍需按 MTU 分包；发送节奏过快可能触发设备端丢包/超时。README 在原生 CoreBluetooth 场景强调应用需"完全掌控分包发送"（README.md），提示分包与流控是文件传输正确性的关键。
• 进度回调（otaDataSend）不应作为并发安全的保证——UI 层更新进度时注意主线程同步；线程模型细节源码中未找到。

进度与结果的语义区分

• otaDataSend 只表示"数据已发出"，不代表设备固件写入成功；最终成功标志是 otaUpgradeResult。应用若把发送完成误判为升级完成，会在设备尚未重启/校验时过早收尾。这是升级文件管理中最容易出错的状态语义边界。

性能与运维说明

• 传输时长：固件文件可达数百 KB 至数 MB，BLE 吞吐受限（受 MTU、连接间隔、设备应答速度影响），升级可能持续数分钟。进度回调（otaDataSend）应被用于展示进度与预估剩余时间，避免用户误判卡死。
• 日志：JLLogHelper 提供日志能力（README.md），排查文件传输失败（超时、丢包、设备拒绝）时应开启日志并按序核对：连接建立 → 能力协商 → 分包发送 → 结果上报。
• 升级期间的应用行为：建议在文件传输期间阻止应用进入后台深度挂起（BLE 后台模式配置），并在 noteEntityDisconnected 时立即记录传输状态，以便回连后决策。
• 多设备/多任务：同一时间应只对一个设备执行文件传输；并发向多个设备发送会加剧 BLE 带宽竞争，README 未提供并发传输支持说明。

扩展点

• 连接层可替换性：SDK 通过三种连接方式（原生 CoreBluetooth / JL_BLEKit / JL_Assist）提供同一套文件传输能力，这是最核心的扩展点——已有蓝牙管控的应用可通过 JL_Assist 桥接，不必改造既有蓝牙栈（README.md）。
• 升级模式选择：单备份/双备份、强制升级由设备能力与业务需求共同决定，应用在 cmdTargetFeature 之后可自行决策发送策略。
• UI 进度呈现：otaDataSend 与 otaUpgradeResult 委托回调是应用自定义升级界面（进度条、结果弹窗）的挂钩点。

测试说明

• master 分支未包含测试源码，无法从源码确认单元测试/UI 测试覆盖范围。
• 可依据 README 的示例工程（code/MiniDemo/ 下三个 Demo 与 code/JL_OTA/ 完整示例，README.md）做真机验证：用数传设备（AC695X 等）实测完整升级流程，重点验证：正常升级成功、传输中断后回连继续、强制升级、升级失败后设备状态。
• 建议测试矩阵：不同固件大小 × 不同连接方式 × 强弱信号环境，观察 otaDataSend 进度连续性、otaUpgradeResult 正确性与断开恢复行为。

相关链接

• iOS-JL_OTA 仓库首页 / 快速开始 — 本页全部契约信息的来源
• README 工程结构 — code/、libs/ 目录布局与示例工程定位
• 杰理文档中心 · OTA iOS — 官方完整 API 文档（README 提供的外部链接）
• 目录内相关页面：OTA 工作流下的设备连接/广播解析、Hash 配对认证、GATT Over BR/EDR 升级等能力详见对应目录页