项目概述与功能特性

iOS-JL_OTA 是珠海市杰理科技股份有限公司为杰理蓝牙设备提供的 iOS 端 OTA（Over-The-Air，空中升级）SDK 与示例工程仓库，基于 RCSP（远程控制系统协议）实现完整的固件空中升级能力。

Purpose and Scope

本文档是 iOS-JL_OTA 仓库的项目级概述页，面向需要快速了解该 SDK 定位、能力边界、架构组成与技术特性的开发者、架构师与产品经理。本页覆盖以下内容：

• 项目的定位、应用场景与支持的设备类型
• SDK 框架库（libs/）组成与各自职责
• 核心功能特性（OTA 升级、设备认证、广播解析、多种连接方式、GATT Over BR/EDR）
• 示例工程（code/）结构与三种蓝牙连接方式的选择指南
• 核心 OTA 升级调用流程
• 集成配置（权限、依赖库、日志管理）、版本历史与许可证

不覆盖的内容（由同仓库其他专题页承担）：具体 API 的逐方法签名说明、各示例工程的逐文件实现细节、RCSP 协议报文格式、以及后端/固件侧的升级逻辑。如需这些内容，请参阅「SDK 接入文档」「示例工程说明」「RCSP 协议说明」等兄弟页面。

概述

iOS-JL_OTA 是杰理科技官方发布的 iOS OTA 升级开发平台。SDK 基于 RCSP 协议（Remote Control System Protocol，远程控制系统协议），提供完整的 BLE（低功耗蓝牙）与经典蓝牙（BR/EDR）固件升级功能，帮助开发者将杰理蓝牙设备的固件升级能力快速集成进 iOS 应用。

该仓库本身包含三大部分：

从架构演进上看，SDK 经历了「单体 → 模块化拆分」的过程：自 v2.1.0 起将 OTA 模块、设备认证配对业务、广播包解析模块拆分为独立运行库，v2.3.1 又将日志打印库分离为独立模块。这种拆分让宿主 App 可以按需引入依赖，降低集成体积与耦合度。

核心调用链路（最快上手路径）：设备连接 + 订阅 → noteEntityConnected → cmdTargetFeature → cmdOTAData(data) → 委托回调 otaUpgradeResult、otaDataSend → 断开时 noteEntityDisconnected。详见下文「核心升级流程」。

架构

下图展示 iOS-JL_OTA 的整体架构：上层示例工程 / 宿主 App 通过 JL_OTALib 编排升级流程，框架层各库各司其职，蓝牙连接层提供三种可选的数据通道，最终与运行 RCSP 协议固件的杰理设备通信。

flowchart TD
    subgraph sg_App["iOS 应用层 (code/)"]
        Demo["示例工程<br/>MiniDemo / JL_OTA"]
        Host["宿主 App"]
    end

    subgraph sg_SDK["SDK 框架层 (libs/)"]
        OTA["JL_OTALib<br/>OTA 升级业务库"]
        Adv["JL_AdvParse<br/>广播包解析库"]
        Hash["JL_HashPair<br/>设备认证库"]
        Log["JLLogHelper<br/>日志辅助库"]
        BLEKit["JL_BLEKit<br/>蓝牙连接核心库 (可选)"]
    end

    subgraph sg_Conn["蓝牙连接层"]
        CB["原生 CoreBluetooth"]
        Assist["JL_Assist 桥接"]
    end

    subgraph sg_Device["设备层"]
        FW["杰理蓝牙设备<br/>(RCSP 协议固件)"]
    end

    Host --> OTA
    Demo --> OTA
    OTA --> Adv
    OTA --> Hash
    OTA --> Log
    OTA --> BLEKit
    BLEKit --> CB
    Demo --> CB
    Demo --> Assist
    CB -->|"BLE GATT 数据通道"| FW
    BLEKit -->|"BLE GATT 数据通道"| FW
    Assist -->|"外部蓝牙桥接"| FW

架构分层说明

SDK 框架层（libs/） 是升级能力的核心，各库职责如下：

蓝牙连接层 是架构中最值得关注的设计点：SDK 刻意把「蓝牙数据通道」与「OTA 升级业务」解耦，允许开发者按自身蓝牙栈情况选择三种连接方式之一（详见「连接方式选择」小节）。OTA 业务库只依赖一个抽象的数据收发通道，无论底层是系统 CoreBluetooth、杰理自研 BLEKit 还是外部蓝牙管理模块，升级流程保持一致。

核心功能特性

OTA 升级

OTA 升级是 SDK 的核心能力，覆盖完整的产品级升级场景：

• BLE 单备份 / 双备份升级：支持单备份（Single Backup）与双备份（Dual Backup）两种固件升级策略。双备份模式下设备具备回滚能力，升级失败时可回退到旧固件，降低升级风险。
• 强制升级：当设备固件存在严重缺陷或升级为强约束场景时，可发起强制升级流程。
• 回连机制：升级过程中设备可能因固件切换而断开，SDK 提供自动回连能力。v2.4.0 增加了单备份场景下 SDK 内部的自动回连接口，v2.5.0 修复了 OTA 回连超时问题。
• 特殊空间复用升级：v2.4.0 起支持特殊存储空间复用的升级场景。
• GATT Over BR/EDR：v2.5.0 起支持通过经典蓝牙（BR/EDR）承载 GATT 进行 OTA 升级，扩展了仅支持经典蓝牙的设备的升级能力。

设备认证（Hash 配对）

JL_HashPair.xcframework 提供基于 Hash 的配对认证机制。在建立升级会话前对设备进行身份认证，防止非授权设备或伪造设备接入升级流程，保障设备与固件的安全。该模块自 v2.1.0 起从主 SDK 中拆分为独立库。

广播包解析

JL_AdvParse.xcframework 自动解析杰理蓝牙设备的广播包（Advertisement Packet），帮助 App 在扫描阶段识别杰理设备并提取设备信息（如设备类型、固件版本相关字段等），从而在连接前即可进行设备识别与过滤。自 v2.0.0 起支持可选开启 BLE 广播包过滤。

多种连接方式

SDK 提供三种蓝牙连接方式，适应不同集成场景：

选择指南：

• 完全掌控 BLE 扫描、连接、服务与分包发送 → 选择原生自定义连接
• 快速集成、减少蓝牙细节处理 → 选择 SDK 蓝牙连接（JL_BLEKit）
• 已有外部蓝牙管控或需桥接到既有蓝牙层 → 选择 JL_Assist 自定义连接

flowchart TD
    Start([选择连接方式]) --> Q{"需要完全掌控蓝牙<br/>扫描/连接/分包细节?"}
    Q -->|"是"| CB["原生 CoreBluetooth<br/>MiniSingleDemo"]
    Q -->|"否"| Q2{"已有外部蓝牙管控<br/>或桥接需求?"}
    Q2 -->|"否"| JK["JL_BLEKit<br/>JLBleKitOTADemo"]
    Q2 -->|"是"| JA["JL_Assist 自定义连接<br/>JLAssistOTADemo"]

日志管理

JLLogHelper.xcframework 默认开启日志打印与存储，并暴露完整的日志控制接口（Objective-C 与 Swift 双语言），支持清空日志、关闭打印/存储、重定向保存路径、实时收集日志内容等，是排查蓝牙连接与升级问题的重要工具。

应用场景与设备支持

SDK 面向三类典型应用场景，覆盖杰理主流芯片平台：

运行环境要求：

工程结构

仓库目录按「示例源码 / SDK 库 / 文档」三块组织：

iOS-JL_OTA/
├── code/                           # 示例程序源码
│   ├── MiniDemo/                   # 迷你示例工程
│   │   ├── MiniSingleDemo/         #   原生 CoreBluetooth 连接示例
│   │   ├── JLBleKitOTADemo/        #   JL_BLEKit 连接示例
│   │   └── JLAssistOTADemo/        #   JL_Assist 自定义连接示例
│   └── JL_OTA/                     # 完整 OTA 应用示例
│       ├── BleManager/             #   自定义蓝牙连接实现
│       ├── BleByAssist/            #   JL_Assist 蓝牙连接实现
│       ├── SDKBleManager/          #   JL_BLEKit 蓝牙连接实现
│       └── Views/                  #   UI 视图
├── libs/                           # 核心 SDK 库 (XCFramework 格式)
│   ├── JL_OTALib.xcframework       #   OTA 升级业务库
│   ├── JL_AdvParse.xcframework     #   广播包解析库
│   ├── JL_HashPair.xcframework     #   设备认证库
│   ├── JL_BLEKit.xcframework       #   蓝牙连接核心库（可选）
│   └── JLLogHelper.xcframework     #   日志辅助库
└── doc/                            # 文档资源
    └── Release_V2.5.0/             #   最新版本文档

关键目录说明：

核心升级流程

SDK 的 OTA 升级遵循「连接 → 能力查询 → 数据下发 → 结果回调 → 断开处理」的固定链路。README 给出的核心调用流程为：设备连接 + 订阅 → noteEntityConnected → cmdTargetFeature → cmdOTAData(data) → 委托回调 otaUpgradeResult、otaDataSend → 断开时 noteEntityDisconnected。

sequenceDiagram
    participant App as iOS 应用 (示例工程)
    participant OTA as JL_OTALib
    participant BLE as 蓝牙连接层<br/>(CoreBluetooth / JL_BLEKit / JL_Assist)
    participant Dev as 杰理蓝牙设备

    App->>BLE: 扫描、连接设备并订阅通知
    BLE-->>App: 连接成功
    App->>OTA: noteEntityConnected(设备信息)
    OTA->>OTA: 初始化 OTA 会话
    App->>OTA: cmdTargetFeature(查询设备特征)
    OTA->>Dev: 下发特征查询命令
    Dev-->>OTA: 返回设备特征 (升级能力)
    App->>OTA: cmdOTAData(升级文件数据)
    loop 分包发送与进度
        OTA->>Dev: 发送数据包
        Dev-->>OTA: 应答
        OTA-->>App: otaDataSend (发送进度回调)
    end
    OTA-->>App: otaUpgradeResult (升级结果)
    Dev-->>BLE: 断开连接
    BLE-->>App: noteEntityDisconnected

各步骤的设计意图：

1. 设备连接 + 订阅：先建立 GATT 连接并订阅特征通知，保证后续命令有可用的双向数据通道。
2. noteEntityConnected：通知 OTA 模块设备已就绪，SDK 内部初始化升级会话上下文。
3. cmdTargetFeature：升级前向设备查询目标特征（如固件版本、存储空间、升级能力），据此决定升级策略（单备份/双备份、是否强制升级等），避免盲目下发。
4. cmdOTAData(data)：将升级文件数据交给 SDK，SDK 按协议分包发送；otaDataSend 回调持续反馈发送进度。
5. otaUpgradeResult：升级流程结束后回调结果，App 据此展示成功/失败状态。
6. noteEntityDisconnected：设备断开（升级完成后固件重启或异常掉线）时通知 SDK 清理会话；配合 SDK 的回连机制可自动恢复连接并继续/完成升级。

使用示例

以下代码摘自仓库 README，展示集成与调试阶段最常用的配置方式。

蓝牙权限配置（Info.plist）

集成 SDK 后必须在 Info.plist 中声明蓝牙使用权限，否则 iOS 系统会直接拒绝蓝牙访问：

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

Source: README.md

日志管理（Objective-C）

JLLogHelper 默认开启日志打印和存储，生产环境可通过以下接口控制：

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

Source: README.md

日志管理（Swift）

Swift 侧还支持日志路径重定向与实时收集，便于将 SDK 日志接入自有日志系统：

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

Source: README.md

快速集成步骤

1. 集成 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
4. 详细实现与最佳实践请参考对应的示例文档

Source: README.md

配置选项

依赖库配置

权限配置（Info.plist）

日志开关（JLLogHelper）

可靠性设计与边界情况

SDK 的可靠性能力主要体现在超时处理与容错机制上，这些能力随版本逐步增强：

• 命令超时检测（v2.3.1+）：为所有命令增加超时检测，避免设备无响应时流程永久挂起；OTA 升级增加错误回调，App 可捕获失败原因并做相应 UI 提示。
• OTA 超时处理优化（v2.4.0）：细化升级过程中的超时处理逻辑，缩短异常场景的等待时间。
• 重复序列号容错（v2.4.0）：对蓝牙链路中可能出现的重复数据包序列号做容错处理，防止重复包导致协议状态错乱——这是 BLE 丢包重传场景下的典型边界问题。
• 回连超时修复（v2.5.0）：修复 OTA 回连超时问题，保证升级中断线重连的可靠性。
• 对象管理容错（v2.3.1）：增加 OTA 对象的对象管理容错，避免并发/重复初始化场景下的对象状态异常。

说明：以上可靠性项的证据来源于 README.md 版本历史；更细粒度的异常枚举与错误码请以 SDK 头文件与文档中心为准。

版本历史

SDK 版本

APP 示例版本

Source: README.md

调试与支持

• 日志输出：SDK 提供详细日志输出，可通过日志查看蓝牙连接状态与数据交互；使用 Xcode 的 Console 查看器查看实时日志。
• 问题排查：SDK 调试方法参考文档中心 SDK 调试说明；杰理 OTA APP 的打印日志导出方法参考同一页面的相关章节。
• 资源链接：
  • 📖 在线文档中心：https://doc.zh-jieli.com/
  • 📄 SDK 接入文档：https://doc.zh-jieli.com/Apps/iOS/ota/zh-cn/master/index.html
  • 🌐 官方网站：https://www.zh-jieli.com/
  • 🐛 问题反馈：GitHub Issues

许可证

本项目采用 Apache License 2.0 开源协议。

Source: README.md

相关链接

• SDK 接入文档（文档中心） — 完整的集成、API 与调试说明
• README.md（仓库首页） — 项目原始说明（中文）
• README_EN.md（英文说明） — 项目原始说明（英文）
• LICENSE（Apache 2.0） — 开源许可证全文
• 兄弟页面指引：连接方式接入细节见「连接方式与示例工程」；SDK API 签名与回调说明见「API 参考」；升级策略与协议细节见「RCSP 协议与升级机制」。