SDK 版本与构建产物

本文档系统梳理 iOS-JL_OTA 杰理蓝牙 OTA 升级 SDK 的版本体系（SDK 版本与示例 APP 版本）、版本演进历史、版本对应关系，以及仓库内提供的构建产物（XCFramework / framework 格式的 SDK 库）的组成与集成方式。

Purpose and Scope

本页面向需要选型、升级、排查版本兼容问题的集成开发者，覆盖以下内容：

• SDK 版本（v2.x）与示例 APP 版本（v3.x）的版本历史与演进脉络
• SDK 版本与 APP 版本、固件能力之间的对应关系
• libs/ 目录下构建产物的完整清单、格式（XCFramework / framework）与发布渠道（正式版 / BetaBuild）
• 构建产物的集成方式（导入、Embed & Sign、权限配置）与版本选择建议

不在本页范围内（由兄弟页面覆盖）：

• OTA 升级的具体业务流程（设备连接、订阅、cmdTargetFeature、cmdOTAData 分包发送等）→ 参见 OTA 升级机制相关页面
• 三种蓝牙连接方式（原生 CoreBluetooth / JL_BLEKit / JL_Assist）的实现细节 → 参见连接方式相关页面
• SDK 各业务库的完整 API 参考 → 参见各库 API 参考页面

Overview

iOS-JL_OTA 是珠海市杰理科技股份有限公司为杰理蓝牙设备（AC695X、AC697N、JL701N、AD697N/AD698N、AC630N/AC632N 等）提供的 OTA 升级开发平台，基于 RCSP 协议（远程控制系统协议） 实现。仓库同时承载三类交付物：

1. 核心 SDK 库（libs/ 目录）：以 XCFramework 格式发布的正式构建产物，包括 OTA 升级业务库 JL_OTALib、广播包解析库 JL_AdvParse、设备认证库 JL_HashPair、日志辅助库 JLLogHelper，以及可选的蓝牙连接核心库 JL_BLEKit；另含 BetaBuild/iOSOnlyBuild/ 下的 framework 格式测试构建。
2. 示例工程源码（code/ 目录）：迷你示例（三种连接方式）与完整 OTA 应用 JL_OTA（依赖 DFUnits.framework 工具库）。
3. 开发文档（doc/ 目录）：随版本发布的 HTML 文档，如 Release_V2.5.0/。

SDK 的版本演进遵循"功能模块化拆分 → 独立库发布 → 稳定性修复"的路线：从 v2.0.0 单一能力起步，经 v2.1.0 拆分独立模块、v2.3.1 分离日志库并引入超时检测，到 v2.4.0/v2.5.0 增强容错与新增 GATT Over BR/EDR 支持。版本号语义上，v2.x.y 为 SDK 主版本线，v3.x.y 为示例 APP 版本线，两者通过"APP 适配 SDK"的关系联动发布（详见 版本历史）。

Architecture

下图展示了仓库中与"版本与构建产物"相关的完整生态：发布渠道、SDK 库构成、示例工程依赖关系，以及各库之间的依赖边界。

flowchart TD
    subgraph sg_Repo["iOS-JL_OTA 仓库"]
        subgraph sg_Libs["libs/ — SDK 构建产物"]
            OTA["JL_OTALib.xcframework<br/>OTA 升级业务库"]
            ADV["JL_AdvParse.xcframework<br/>广播包解析库"]
            HASH["JL_HashPair.xcframework<br/>设备认证库"]
            BLE["JL_BLEKit.xcframework<br/>蓝牙连接核心库（可选）"]
            LOG["JLLogHelper.xcframework<br/>日志辅助库"]
            BETA["BetaBuild/iOSOnlyBuild/<br/>framework 格式测试构建"]
        end

        subgraph sg_Code["code/ — 示例工程"]
            MINI["MiniDemo<br/>三种连接方式迷你示例"]
            FULL["JL_OTA<br/>完整 OTA 应用"]
            DFU["DFUnits.framework<br/>通用工具库"]
        end

        subgraph sg_Doc["doc/ — 发布文档"]
            DOC["Release_V2.5.0/<br/>版本文档"]
        end
    end

    MINI --> OTA
    MINI --> ADV
    MINI --> HASH
    MINI --> LOG
    FULL --> OTA
    FULL --> DFU
    BETA -.->|"测试渠道（非正式发布）"| ADV
    BETA -.->|"测试渠道（非正式发布）"| BLE

架构说明：

• libs/ 是正式构建产物的唯一来源。集成时必须导入 JL_OTALib、JL_AdvParse、JL_HashPair、JLLogHelper 四个库并设置 Embed & Sign；JL_BLEKit 仅在需要使用杰理集成蓝牙库时导入（见 README.md）。
• BetaBuild/iOSOnlyBuild/ 是测试渠道产物。该目录下为 framework 格式（而非 XCFramework），包含 JL_AdvParse.framework、JL_BLEKit.framework 等，供内部/灰度验证使用，不建议正式发布集成。
• 示例工程与 SDK 库解耦：code/ 下三个迷你示例分别演示三种连接方式，完整示例 JL_OTA 额外依赖 DFUnits.framework（通用工具库，提供 AES、CRC16、Gzip、Http 等能力），说明 SDK 本身不依赖 DFUnits，仅示例工程使用。
• 文档随版本发布：doc/ 目录按版本号组织（当前为 Release_V2.5.0），与 SDK 版本一一对应。

版本与构建产物的生命周期关系可用下图概括：

flowchart LR
    DEV["开发迭代"] --> TAG["打 Tag 发布版本<br/>v2.x.y（SDK）/ v3.x.y（APP）"]
    TAG --> BUILD["构建产物生成"]
    BUILD --> XC["XCFramework 正式产物<br/>libs/ 目录"]
    BUILD --> FB["framework 测试产物<br/>libs/BetaBuild/iOSOnlyBuild/"]
    XC --> DOC["同步更新 doc/ 版本文档"]
    XC --> DEMO["示例工程同步适配"]
    DEMO --> REL["开发者集成选型"]
    DOC --> REL

版本历史

版本历史是本文档的核心内容，数据直接来源于仓库 README 的版本历史章节。

SDK 版本（v2.x 线）

来源：README.md 版本历史 SDK 表

APP 版本（v3.x 线）

来源：README.md 版本历史 APP 表

版本对应关系

SDK 与示例 APP 采用"APP 适配 SDK"的联动发布策略：每次 SDK 发版后，示例 APP 随即跟进适配并修复已知问题。对应关系如下：

选型建议：新项目直接采用当前最新版本（SDK v2.5.0 + APP v3.5.2）；存量项目升级时，务必同时升级 SDK 与示例工程对应版本，并参考 doc/Release_V2.5.0/ 文档核对 API 变更。

版本演进脉络分析

flowchart TD
    V200["v2.0.0 (2021/10)<br/>BLE 单/双备份升级<br/>广播过滤、握手连接"]
    V210["v2.1.0 (2023/03)<br/>模块化拆分：OTA / 认证 / 广播解析<br/>独立库发布，性能优化"]
    V231["v2.3.1 (2024/12)<br/>分离日志库 JLLogHelper<br/>全命令超时检测、错误回调"]
    V240["v2.4.0 (2025/10)<br/>超时逻辑优化<br/>重复序列号容错、空间复用升级"]
    V250["v2.5.0 (2026/02)<br/>GATT Over BR/EDR 支持<br/>修复回连超时"]

    V200 --> V210 --> V231 --> V240 --> V250

设计意图解读：

1. 模块化拆分是主线（v2.1.0、v2.3.1）：OTA 业务、设备认证、广播解析、日志逐步拆分为独立 XCFramework。这样做的目的是：① 减小业务主库体积，日志库按需加载；② 各模块独立演进、独立修复，降低耦合；③ 让集成方只需导入实际用到的库。
2. 容错与超时是稳定性的重点（v2.3.1 → v2.4.0 → v2.5.0）：从"增加所有命令的超时检测"到"OTA 超时处理逻辑优化"，再到"修复 OTA 回连超时问题"，说明蓝牙链路的不确定性（丢包、断连、回连）是 OTA 场景最主要的稳定性风险，版本迭代持续在此投入。
3. 能力边界持续扩展（v2.0.0 → v2.5.0）：从 BLE 单/双备份，到特殊空间复用升级、单备份内部自动回连，再到 GATT Over BR/EDR 经典蓝牙升级，覆盖了从 TWS 耳机到音箱、手表的全产品线升级诉求。

构建产物详解

libs/ 目录结构与发布渠道

仓库通过 libs/ 目录统一承载 SDK 构建产物，分为两条渠道（见 README.md 工程结构 与仓库实际目录）：

libs/
├── JL_OTALib.xcframework       # OTA 升级业务库（正式）
├── JL_AdvParse.xcframework     # 广播包解析库（正式）
├── JL_HashPair.xcframework     # 设备认证库（正式）
├── JL_BLEKit.xcframework       # 蓝牙连接核心库（正式，可选）
├── JLLogHelper.xcframework     # 日志辅助库（正式）
└── BetaBuild/
    └── iOSOnlyBuild/           # 测试渠道产物（framework 格式）
        ├── JL_AdvParse.framework/
        │   ├── Headers/JL_AdvParse.h, JLAdvParse.h,
        │   │         JLChargingBoxAdv.h, JLDevicesAdv.h,
        │   │         JLEarphoneAdv.h, JLOtaAdv.h,
        │   │         JLSoundBoxAdv.h, JLSoundCardAdv.h,
        │   │         JLTwsAdv.h, JLWatchAdv.h
        │   ├── Info.plist
        │   ├── Modules/module.modulemap
        │   └── JL_AdvParse                 # 二进制主文件
        └── JL_BLEKit.framework/            # 蓝牙连接库（测试渠道）
            └── Headers/ECBDTManager.h, ECBDTObjc.h ...

来源：README.md 工程结构；BetaBuild 目录结构为仓库实际内容。

库清单（构建产物组成）

XCFramework 与 framework 两种格式的设计考量

• 正式发布产物采用 XCFramework：XCFramework 是 Apple 推荐的跨平台/跨架构二进制打包格式，一个 .xcframework 内可同时包含模拟器与真机 slice（ios-arm64、ios-arm64_x86_64-simulator 等），集成时通过 Embed & Sign 自动选择合适 slice，无需手动剥离架构——这是 SDK 面向不同开发者环境（Intel Mac + 模拟器 / Apple Silicon / 真机）的关键设计。
• 测试渠道产物采用 framework 格式（libs/BetaBuild/iOSOnlyBuild/）：目录名 iOSOnlyBuild 表明其仅面向 iOS 真机构建，便于内部快速验证新特性或修复，不承诺跨架构兼容性，不建议正式发布集成。

构建产物的版本一致性要求

集成时需保证四个必选库来自同一 SDK 版本（当前 v2.5.0），避免因跨版本混用导致协议不匹配。判断方法：

1. 核对 libs/ 目录中库的二进制构建时间/版本，与 doc/Release_<版本号>/ 文档对应；
2. 在示例工程 code/ 中核对 SDK 适配版本（当前 APP v3.5.2 适配 SDK v2.5.0）；
3. 参考 README 徽章中的最新 Tag（github.com/Jieli-Tech/iOS-JL_OTA/tags）确认最新发布版本。

说明：仓库 Tag 与徽章信息位于 README.md 顶部，实际 Tag 列表以 GitHub Releases/Tags 页为准。

核心流程：从版本选择到构建产物集成

版本选择与集成决策流程

flowchart TD
    Start([开始集成]) --> Q1{"新项目 or 存量升级?"}
    Q1 -->|"新项目"| LATEST["选用最新版本<br/>SDK v2.5.0 + APP v3.5.2"]
    Q1 -->|"存量升级"| CUR{"当前 SDK 版本?"}
    CUR -->|"低于 v2.4.0"| UPGRADE["升级到 v2.5.0<br/>注意 v2.3.1 日志库拆分等破坏性变更"]
    CUR -->|"v2.4.0+"| PATCH["小版本升级 v2.5.0<br/>新增 BR/EDR 能力，修复回连超时"]
    LATEST --> INTEG["从 libs/ 导入 4 个必选 XCFramework"]
    UPGRADE --> INTEG
    PATCH --> INTEG
    INTEG --> EMBED["设置 Embed & Sign"]
    EMBED --> PERM["Info.plist 配置蓝牙权限"]
    PERM --> OPT{"需要杰理蓝牙栈?"}
    OPT -->|"是"| BLE["额外导入 JL_BLEKit.xcframework"]
    OPT -->|"否"| SKIP["使用原生 CoreBluetooth 或 JL_Assist"]
    BLE --> CODE["编写业务代码"]
    SKIP --> CODE
    CODE --> TEST["真机验证 OTA 升级"]
    TEST --> END([完成])

集成步骤（来自 README 快速开始）

仓库 README 给出的标准集成流程如下：

1. 将 libs/ 目录下的 JL_OTALib.xcframework、JL_AdvParse.xcframework、JL_HashPair.xcframework、JLLogHelper.xcframework 添加到项目并设置 Embed & Sign；
2. 配置权限：Privacy - Bluetooth Peripheral/Always Usage Description；
3. 核心调用流程：设备连接+订阅 → noteEntityConnected → cmdTargetFeature → cmdOTAData(data) → 委托回调 otaUpgradeResult、otaDataSend → 断开时 noteEntityDisconnected。

来源：README.md 快速集成步骤

构建产物导入后的权限配置示例

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

来源：README.md 权限配置

使用示例

示例一：日志库（JLLogHelper）运行控制

v2.3.1 起 JLLogHelper 作为独立构建产物交付，默认开启日志打印与存储，可通过以下接口控制（Objective-C）：

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

来源：README.md 日志管理（OC）

Swift 侧等价接口（含日志重定向与收集回调）：

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

来源：README.md 日志管理（Swift）

设计意图：日志库独立后，生产环境可通过 setLog:false 与 saveLogAsFile:false 关闭日志以降低性能开销；调试期可通过 redirectLogPath 将日志重定向到指定文件、用 collectLog 实时收集日志——这套能力与 v2.3.1 引入的"全命令超时检测 + 错误回调"配合，是排查蓝牙链路问题（断连、回连超时）的核心手段。

示例二：广播解析库（JL_AdvParse）的头文件入口

测试渠道产物 libs/BetaBuild/iOSOnlyBuild/JL_AdvParse.framework 的公开头文件体现了广播解析库的能力边界（按设备类型划分解析器）：

• JL_AdvParse.h / JLAdvParse.h — 库主入口
• JLOtaAdv.h — OTA 广播包解析
• JLEarphoneAdv.h / JLTwsAdv.h — 耳机 / TWS 设备广播
• JLWatchAdv.h — 手表设备广播
• JLSoundBoxAdv.h / JLSoundCardAdv.h / JLChargingBoxAdv.h / JLDevicesAdv.h — 音箱、声卡、充电盒、通用设备广播

来源：libs/BetaBuild/iOSOnlyBuild/JL_AdvParse.framework 目录

这组头文件是 v2.1.0"分离广播包解析模块为独立库"的直接产物：将原先内嵌于 OTA 主库的广播解析逻辑按设备品类拆分为独立类，使集成方可以只依赖 JL_AdvParse 完成设备发现/过滤，而无需引入完整 OTA 业务。

配置选项

构建产物导入配置

日志运行配置（JLLogHelper）

故障模式、边界情况与并发

以下内容基于版本历史中明确记录的修复项与 SDK 设计特征整理：

已知故障模式与修复记录

边界情况与并发注意事项

• 单备份升级的断连风险：单备份升级过程中若蓝牙断连，固件可能处于半升级状态。v2.4.0 起提供"单备份 SDK 内部自动回连接口"，建议升级前通过 noteEntityDisconnected 回调感知断连，并主动触发回连。
• 广播包过滤与握手连接：v2.0.0 起支持"可选择 BLE 广播包过滤"与"可选择 BLE 握手连接"，在多设备并存环境中需合理配置过滤条件，避免错误设备抢占升级链路。
• 模块独立运行带来的线程边界：v2.1.0 起 OTA 模块为独立运行模块，日志、认证、广播解析均在各库内部线程处理；多库同时回调时，业务层应避免在委托回调中执行耗时操作，防止阻塞蓝牙链路。
• 版本混用风险：四个必选库必须同版本。跨版本混用（如 v2.5.0 的 JL_OTALib + v2.3.1 的 JL_AdvParse）可能导致广播解析与 OTA 业务协议不匹配。

性能与运维注意事项

• 模块化减小主库体积：v2.1.0 分离认证、广播解析，v2.3.1 分离日志库，集成方可按需裁剪，生产包仅保留 OTA 业务必需库，日志库可在发布前关闭打印与存储以降低运行时开销。
• 日志是运维抓手：JLLogHelper 支持文件落盘与 collectLog 实时收集，配合版本号（SDK v2.5.0 / APP v3.5.2）上报，是定位线上蓝牙问题的主要手段。
• 真机验证必要性：BetaBuild 渠道的 iOSOnlyBuild 产物仅面向真机；模拟器调试请使用 XCFramework 正式产物，且最终 OTA 流程务必在真机验证（蓝牙外设行为与模拟器存在差异）。
• 升级节奏建议：跟随 SDK 主版本（v2.x 末尾版本）升级而非每个小版本，重点吸收超时/容错类修复（v2.3.1 起持续增强）。

扩展点

1. 连接方式三选一：原生 CoreBluetooth（完全掌控扫描/连接/分包）、JL_BLEKit（快速集成）、JL_Assist（桥接既有蓝牙层）。连接层与 OTA 业务层解耦，可在不改动 OTA 逻辑的前提下替换连接实现。
2. 可选导入 JL_BLEKit：不使用杰理蓝牙栈时可省略该库，降低体积；使用自定义蓝牙层（JL_Assist）时也无需导入。
3. 日志模块可编程控制：JLLogHelper 提供完整的运行期开关（打印、落盘、时间戳、路径重定向），可接入自定义日志上报体系。
4. 广播解析按品类扩展：JL_AdvParse 头文件按设备类型（TWS、手表、音箱、声卡、充电盒）组织，新设备品类可在此基础上扩展解析器。

Related Links

• README.md（仓库主文档，含完整版本历史与集成说明）
• README_EN.md（英文版说明）
• LICENSE（Apache License 2.0）
• libs/BetaBuild/iOSOnlyBuild/JL_AdvParse.framework（测试渠道构建产物示例）
• 在线文档中心：https://doc.zh-jieli.com/Apps/iOS/ota/zh-cn/master/index.html
• 版本 Tag 列表：https://github.com/Jieli-Tech/iOS-JL_OTA/tags

本文档所有版本号、发布日期与功能描述均以仓库 README 版本历史章节为准；构建产物目录结构以仓库 libs/ 实际内容为准。