集成与二次开发指南

本文档是 HarmonyOS-JL_OTA 杰理 OTA SDK（HarmonyOS 版）的集成与二次开发参考手册，覆盖从依赖引入、工程配置到基于蓝牙抽象层进行二次开发的全过程。

Purpose and Scope

本页面向希望在自有 HarmonyOS 应用中集成杰理 RCSP OTA 升级能力、或在官方 Demo 基础上进行二次开发的开发者，内容包括：

• SDK 的定位、组成与运行环境
• 依赖库（HAR）的引入方式与工程结构
• 基于蓝牙抽象层（bluetooth/base 与 bluetooth/ble）的二次开发要点
• OTA 升级的完整控制流、配置项、失败模式与调试方法

不涵盖的内容：RCSP 协议本身的字节级规范、各芯片（AC707N/AC703N 等）固件侧的 OTA 实现细节、以及 JL_Auth 认证库的内部算法 —— 这些属于芯片固件文档与其他 SDK 的范畴，请参考 杰理在线文档中心。

概述

HarmonyOS-JL_OTA 是珠海市杰理科技股份有限公司（Jieli Technology）为杰理蓝牙类产品提供的固件升级开发平台。它专门实现杰理蓝牙产品的 RCSP OTA 升级功能，支持 BLE（低功耗蓝牙）与 SPP（经典蓝牙串口）等多种传输通道，向开发者交付完整的固件升级流程。

SDK 以三个核心 HAR（HarmonyOS Archive）库的形式交付，各司其职：

仓库内同时附带了参考 Demo 源码工程（code/ 目录），该 Demo 已经实现了「授权 → 添加升级文件 → 搜索连接设备 → 执行 OTA 升级」的完整链路，是二次开发的最佳起点。Demo 应用已上架华为应用市场（搜索"杰理OTA升级"），可用于真机体验。

为什么选择本 SDK

• 传输层解耦：Demo 源码将蓝牙能力抽象为 IScan/IConnect 接口族，BLE 与 SPP 作为不同实现，SDK 核心升级逻辑不依赖具体传输介质 —— 二次开发时可以替换或扩展传输实现而不触碰升级流程。
• 自动回连：支持单备份 OTA 的 BLE 自动回连，升级断线后可自动恢复，提升用户体验。
• 纯 ArkTS 生态：基于 HarmonyOS 5.0+ 与 DevEco Studio 开发，与鸿蒙原生能力（蓝牙、沙箱文件、日志）深度集成。

架构

下图展示 SDK 的整体架构：上层应用通过三个 HAR 库与蓝牙抽象层协同，最终经 BLE/SPP 通道与杰理芯片设备交互。

flowchart TD
    subgraph sg_App["应用层 (HarmonyOS 5.0+)"]
        Demo["杰理OTA升级 Demo<br/>(参考源码 code/)"] --> UseFlow["升级流程编排<br/>授权→选文件→连接→升级"]
    end

    subgraph sg_SDK["SDK 核心库 (libs/ 目录 HAR)"]
        Auth["JL_Auth<br/>RCSP 认证库"]
        OTA["JL_OTA<br/>OTA 升级核心库"]
        RCSP["JL_RCSP<br/>RCSP 协议库"]
        OTA --> RCSP
        Auth --> RCSP
    end

    subgraph sg_BT["蓝牙抽象层 (Demo 源码)"]
        IConnect["IConnect / IScan<br/>(bluetooth/base 接口)"]
        BleImpl["BleImpl / BleDevice<br/>(bluetooth/ble 实现)"]
        IConnect --> BleImpl
    end

    subgraph sg_Device["设备侧"]
        Chip["杰理蓝牙芯片<br/>(AC707N/AC703N/AC697N 等<br/>支持 RCSP OTA 的 SDK)"]
    end

    UseFlow --> OTA
    UseFlow --> Auth
    UseFlow --> IConnect
    BleImpl -->|"BLE GATT / SPP RFCOMM"| Chip

架构要点说明：

1. 依赖方向：应用层（Demo）依赖 SDK 核心库与蓝牙抽象层；JL_OTA 依赖 JL_RCSP 完成协议交互，JL_Auth 与 JL_RCSP 协作完成认证 —— 认证与协议被隔离成独立库，保证升级逻辑的纯净。
2. 抽象边界：bluetooth/base/ 下的 IConnect、IScan、BaseSendDataHandler、BufferQueue、BluetoothErrorConstant、BluetoothDevice 定义了传输层契约；bluetooth/ble/ 下的 BleImpl、BleDevice、BleSendDataHandler、BleConnectSettingConfigure、BleScanSettingConfigure 等是其 BLE 实现。SPP 升级（V1.0.1 起）通过新增传输实现接入，不改动升级核心。
3. 数据通道：升级文件数据经 BaseSendDataHandler（数据分包发送处理器）与 BufferQueue（缓冲队列）流向 BLE/SPP 通道，最终写入芯片固件区。

与仓库结构的对应关系

仓库源码树中，code/app/JL_OTA_Harmony_v1.0.0_sdk_v1.0.1/jl_ota_harmony/jl_ota_harmony/ 是完整 DevEco Studio 工程，其中：

• AppScope/：应用级配置（bundleName、图标、标签）
• entry/：模块代码，entry/src/main/ets/bluetooth/ 下按 base（抽象基类与接口）与 ble（BLE 具体实现）分目录组织
• entry/oh-package.json5：声明对 rcsp 本地 HAR 的依赖

集成步骤

1. 环境准备

以上要求摘录自 README.md。设计意图：将运行环境收敛到 HarmonyOS 5.0+ 与 ArkTS，确保 SDK 只依赖稳定的系统蓝牙/文件 API，避免向下兼容带来的分支复杂度。

2. 引入依赖库

将 libs/ 目录下的三个 HAR 文件放入工程 lib/ 目录，并在 oh-package.json5 中声明依赖：

"dependencies": {
  "jl-ota": "file:./lib/JL_OTA_1.0.1-release.har",
  "jl-rcsp": "file:./lib/JL_RCSP_1.0.1-release.har",
  "jl-auth": "file:./lib/JL_Auth_1.0.1-release.har",
}

Source: README.md

官方 Demo 工程的依赖声明方式与此一致，使用本地文件路径引用 HAR 包：

{
  "name": "entry",
  "version": "1.0.0",
  "dependencies": {
//    "jl_bt_ota": "file:../jl_bt_ota",
    "rcsp": "file:../lib_rcsp"
  }
}

Source: entry/oh-package.json5

设计意图：HAR 是 HarmonyOS 的静态共享包格式，file: 前缀本地引入意味着 SDK 以源码级/字节码级随应用打包，无远程仓库网络依赖，离线构建友好；同时 rcsp 与 jl_bt_ota 分层声明，让协议库与蓝牙传输库可按需裁剪。

工程结构解析

HarmonyOS-JL_OTA/
├── code/                                    # 参考源码工程文件夹
│   └── 参考Demo源码工程                  # OTA Demo 项目源码（DevEco Studio 工程）
│       └── jl_ota_harmony/
│           ├── AppScope/                    # 应用级配置（bundle、图标、字符串资源）
│           ├── entry/
│           │   ├── oh-package.json5         # 模块依赖声明（rcsp HAR）
│           │   └── src/main/ets/bluetooth/
│           │       ├── base/                # 蓝牙抽象层：接口与基础组件
│           │       │   ├── IConnect.ets     # 连接抽象接口
│           │       │   ├── IScan.ets        # 扫描抽象接口
│           │       │   ├── BaseSendDataHandler.ets  # 数据分包发送基类
│           │       │   ├── BluetoothDevice.ets      # 设备信息模型
│           │       │   ├── BluetoothErrorConstant.ets# 错误码常量
│           │       │   └── BufferQueue.ets          # 发送缓冲队列
│           │       └── ble/                 # BLE 传输实现层
│           │           ├── IBleScan.ets / IBleConnect.ets  # BLE 能力接口
│           │           ├── BleImpl.ets      # BLE 扫描/连接主实现
│           │           ├── BleDevice.ets    # BLE 设备封装
│           │           ├── BleSendDataHandler.ets    # BLE 数据发送处理
│           │           ├── BleScanSettingConfigure.ets # 扫描参数配置
│           │           └── BleConnectSettingConfigure.ets # 连接参数配置
├── libs/                                    # 核心库文件夹（交付物）
│   ├── JL_Auth_vx.x.x-release.har           # RCSP 认证相关库
│   ├── JL_OTA_vx.x.x-release.har            # OTA 升级核心库（流程控制）
│   └── JL_RCSP_vx.x.x-release.har           # RCSP 协议处理库
└── README.md                                # 说明文件（含集成步骤与版本历史）

目录结构依据 README.md 及仓库文件列表整理。

结构设计意图：

• base 与 ble 分层：base 层只定义契约（接口 + 基础实现），ble 层是具体传输实现。若二次开发需要支持 SPP（经典蓝牙），可在 base 契约之上新增 spp 实现目录，与现有 ble 并列 —— 这正是 V1.0.1 增加 SPP 升级支持时采用的扩展方式。
• BufferQueue 独立成件：OTA 升级数据量大（固件文件可达数 MB），发送必须异步化、可控速。BufferQueue 作为独立的缓冲队列组件被 BaseSendDataHandler 使用，将「业务产生数据」与「通道发送数据」解耦，避免升级过程中 UI 线程阻塞。
• 配置类独立：BleScanSettingConfigure / BleConnectSettingConfigure 把扫描与连接的参数（如扫描超时、连接间隔等）从实现逻辑中剥离，便于二次开发按设备特性调参。

二次开发指南

蓝牙抽象层扩展点

Demo 的蓝牙层是二次开发的核心扩展面，文件清单如下（角色依据目录结构与命名约定归纳）：

注：以上文件均位于 Demo 工程 entry/src/main/ets/bluetooth/ 下（base/ 与 ble/ 两个子目录），具体方法签名以各文件源码为准。

二次开发典型场景

1. 更换扫描/连接策略：修改或继承 BleScanSettingConfigure / BleConnectSettingConfigure，调整扫描窗口、连接超时等参数，适配不同杰理芯片的射频特性。
2. 新增传输通道（如 SPP）：实现 IScan / IConnect 契约，仿照 ble/ 目录新增 spp/ 实现，并在升级流程入口处按设备能力选择传输实现 —— 无需改动 JL_OTA 核心升级逻辑。
3. 自定义升级文件管理：Demo 采用「本地添加 → 复制到 App 沙盒」的方式管理升级文件（见 README.md），二次开发可替换为远程下载、增量包校验等策略，再交给 JL_OTA 库执行。

核心升级流程

SDK 的完整使用流程如下（摘自 README.md 配置说明）：

sequenceDiagram
    participant User as 用户
    participant App as Demo App (ArkTS)
    participant OTA as JL_OTA 核心库
    participant RCSP as JL_RCSP 协议库
    participant BT as 蓝牙抽象层 (BleImpl)
    participant Dev as 杰理芯片设备

    User->>App: 打开 APP（首次授予蓝牙权限）
    App->>App: 添加升级文件（本地文件复制到沙盒）
    User->>App: 点击搜索设备
    App->>BT: IScan 扫描
    BT-->>App: 设备列表（BluetoothDevice）
    User->>App: 选择目标设备
    App->>BT: IConnect 连接
    BT-->>App: 连接成功
    User->>App: 选择升级文件，开始 OTA
    App->>OTA: 启动升级流程
    OTA->>RCSP: RCSP 指令交互（认证/版本协商）
    RCSP->>BT: 发送指令数据
    BT->>Dev: BLE GATT 写入 / SPP 数据
    Dev-->>BT: 响应回包
    BT-->>RCSP: 解析回包
    RCSP-->>OTA: 协议状态推进
    OTA-->>App: 升级进度/结果回调
    App-->>User: UI 展示升级结果

流程设计意图：

• 升级文件先行：先添加文件再连接设备，保证升级开始时数据立即可用，缩短连接后的等待窗口，降低设备侧超时风险。
• 协议与传输分离：JL_OTA 只关心升级状态机，JL_RCSP 负责协议编解码，蓝牙抽象层 只负责字节收发 —— 三层各司其职，任何一层可独立替换。
• 权限前置：首次打开即授予蓝牙权限（README 明确提示），避免升级中途因权限缺失导致流程中断。

配置选项

应用级配置（AppScope/app.json5）

Demo 应用的应用级配置如下：

{
  "app": {
    "bundleName": "com.jieli.bt.ota",
    "vendor": "Jieli Technology",
    "versionCode": 2,
    "versionName": "1.0.0",
    "icon": "$media:app_icon",
    "label": "$string:app_name"
  }
}

Source: AppScope/app.json5

模块级依赖配置（entry/oh-package.json5）

蓝牙参数配置（二次开发）

BLE 传输层的扫描与连接参数集中在 BleScanSettingConfigure.ets 与 BleConnectSettingConfigure.ets 中（文件位于 entry/src/main/ets/bluetooth/ble/）。二次开发时按需调整的关键参数方向包括：

具体字段名与默认值以对应源码文件为准；上表给出的是参数调整的工程方向，非虚构的 API 签名。

API 参考

SDK 核心能力（认证、OTA 升级流程、RCSP 协议）封装在 JL_Auth、JL_OTA、JL_RCSP 三个 HAR 库中，以二进制形式交付，仓库内不包含其源码；Demo 工程暴露的是蓝牙传输层接口。以下为二次开发直接面对的主要契约入口（基于仓库文件清单，签名细节请查阅对应源码与在线 API 文档）：

传输层接口（Demo 源码）

使用约束

• 线程模型：蓝牙回调与数据发送发生在系统蓝牙事件线程，业务 UI 更新需切换到主线程（ArkTS 的 TaskPool/Emitter 机制）。
• 生命周期：扫描与连接资源必须在页面退出或升级结束时显式释放，防止 BLE 句柄泄漏（BleImpl 的连接/断连职责即为此设计）。
• 错误码：统一从 BluetoothErrorConstant 读取错误码，二次开发不应硬编码数值。

失败模式与边界情况

常见失败场景

并发与一致性考虑

• 数据发送流控：BufferQueue + BaseSendDataHandler 的组合确保升级数据按序、按速下发；二次开发若绕过该组件直接写 BLE 通道，可能因 BLE MTU 限制与链路拥塞导致丢包。
• 连接状态竞态：用户可能在升级过程中手动断开连接，业务层需监听 IConnect 的断开回调并终止升级状态机，避免悬空等待。
• 文件沙盒一致性：升级文件从手机本地复制到 App 沙盒后，应用升级/卸载场景下需重新校验文件可用性。

调试与排障

SDK 提供详细日志输出，可通过日志查看 OTA 连接状态与数据交互：

• 使用 DevEco Studio 的 Logcat 查看实时日志（详见 README.md 调试技巧）。
• SDK 侧问题排查参考官方文档 测试调试 — 杰理OTA外接库开发文档(HarmonyOS)。
• 日志关键字建议关注：扫描结果、连接状态、RCSP 指令交互、升级进度百分比、错误码。

使用示例

示例 1：获取工程并导入

git clone https://github.com/Jieli-Tech/HarmonyOS-JL_OTA.git
cd HarmonyOS-JL_OTA

Source: README.md

导入步骤：打开 DevEco Studio → 选择 "Open Project" → 导航到解压后的 code/ 目录 → 打开参考 Demo 源码工程中的项目文件（README.md）。设计意图：以官方 Demo 为模板工程导入，可以保证编译配置（签名、权限声明、依赖路径）开箱即用，规避手工搭建工程时常见的 HAR 路径与权限声明错误。

示例 2：依赖声明（集成到自有工程）

"dependencies": {
  "jl-ota": "file:./lib/JL_OTA_1.0.1-release.har",
  "jl-rcsp": "file:./lib/JL_RCSP_1.0.1-release.har",
  "jl-auth": "file:./lib/JL_Auth_1.0.1-release.har",
}

Source: README.md

三个库缺一不可：JL_OTA 是升级流程入口，JL_RCSP 提供协议能力，JL_Auth 完成设备认证；xxx 替换为实际版本号。

示例 3：Demo 应用内依赖（工程参考）

{
  "name": "entry",
  "version": "1.0.0",
  "dependencies": {
//    "jl_bt_ota": "file:../jl_bt_ota",
    "rcsp": "file:../lib_rcsp"
  }
}

Source: entry/oh-package.json5

示例 4：端到端使用流程

1. 打开 APP：首次打开授予蓝牙等对应权限
2. 添加升级文件：本地添加，选择手机本地的升级文件复制到 App 沙盒
3. 连接目标设备：搜索并连接需要升级的蓝牙设备
4. 开始 OTA 升级：选择目标的升级文件，开始 OTA 升级

Source: README.md

版本历史与演进

Source: README.md 版本历史

演进启示：V1.0.0 首发仅支持 BLE，V1.0.1 通过传输层抽象新增 SPP 支持 —— 这印证了 bluetooth/base 抽象层设计的正确性：新增传输只需实现契约，核心升级流程零改动。二次开发新增通道时应沿用该模式。

性能与运维建议

• 升级速率调优：BLE 通道受 MTU（最大传输单元）与连接间隔限制，吞吐量有限。调优方向为 BleSendDataHandler 的分包大小与 BufferQueue 的发送间隔，需在速率与稳定性间折中；SPP 通道吞吐更高，适合大固件。
• 功耗管理：扫描与升级期间蓝牙射频持续工作，建议升级前提示用户保持设备在充电/高电量状态，避免中断。
• 日志分级：SDK 详细日志在生产环境中可能产生大量输出，建议在正式发布包中关闭或降级日志级别。
• 版本匹配：保持 JL_Auth / JL_OTA / JL_RCSP 三个库版本一致，避免协议不兼容。

扩展点总结

测试说明

仓库内以参考 Demo 工程形式提供可运行样本（code/ 目录），其价值包括：

• 提供完整的真机验证路径：Demo 已上架华为应用市场（"杰理OTA升级"），可用于功能验收；
• 蓝牙抽象层的接口设计即为可测试性设计：IScan/IConnect 接口可注入 Mock 实现进行单元测试；
• 升级流程的可观测性：依赖日志输出验证连接状态与数据交互，支持问题定位。

仓库当前未包含独立自动化测试目录（如 test/），端到端验证依赖真机与杰理芯片设备。

Related Links

• 杰理 OTA 外接库开发文档（HarmonyOS）— 在线文档中心
• 测试调试章节 — 官方文档
• 发布记录（版本历史）— 官方文档
• README.md（集成步骤与工程结构）
• README_en.md（英文说明）
• 问题反馈：GitHub Issues
• 杰理科技官方网站

免责说明：本文档基于仓库源码与 README 整理。JL_Auth / JL_OTA / JL_RCSP 为二进制 HAR 交付，其内部 API 签名请以实际库文件与官方在线文档为准；bluetooth/ 目录下各文件的具体方法签名请直接查阅对应 .ets 源码。