快速开始

本文介绍如何从零开始获取、导入并运行 HarmonyOS-JL_OTA 参考 Demo，完成杰理 OTA SDK 的首次集成与固件升级验证。

Purpose and Scope

本页面向初次接触该仓库的开发者，说明在 DevEco Studio 中搭建并运行杰理 OTA 升级示例工程的完整步骤：克隆仓库、导入工程、引入 HAR 依赖、运行示例应用，以及理解参考 Demo 的工程结构与配置。相关主题如 SDK 各功能模块的详细实现（BLE 扫描、连接、OTA 升级流程、RCSP 协议处理等）属于对应功能页面，不在本页展开；本页只提供上手路径与工程级视角。

Overview

HarmonyOS-JL_OTA 是珠海市杰理科技股份有限公司为杰理蓝牙类产品（AC707N、AC703N、AC701N、AC697N、AC696N、AC695N 等）提供的 RCSP OTA 固件升级 SDK（HarmonyOS 版本）。SDK 以 har（Harmony Archive）形式发布，分为三个核心库：

• JL_Auth：杰理 RCSP 认证相关库；
• JL_OTA：OTA 升级核心库，包含升级流程控制；
• JL_RCSP：RCSP 协议相关库，包含 RCSP 协议处理。

参考 Demo 源码位于仓库 code/app/ 目录下，是一个完整的 HarmonyOS 工程（jl_ota_harmony），展示了 BLE/SPP 升级、自动回连等能力的实际接入方式。快速开始的关键路径为：获取代码 → 导入工程 → 配置依赖 → 构建运行 → 按使用流程验证升级。

flowchart TD
    Start([开始]) --> Clone["克隆仓库<br/>git clone"]
    Clone --> Import["DevEco Studio 打开工程<br/>code/app/ 目录"]
    Import --> Deps["配置依赖<br/>JL_Auth / JL_OTA / JL_RCSP HAR"]
    Deps --> Build["同步并构建工程<br/>compatibleSdkVersion 5.0.0(12)"]
    Build --> Run["运行示例应用<br/>授予蓝牙权限"]
    Run --> Flow["按使用流程体验 OTA 升级<br/>添加文件 → 连接设备 → 升级"]
    Flow --> End([完成])

Architecture

参考 Demo 是一个标准的 HarmonyOS Stage 模型工程。仓库以 code/ 存放参考源码，以 libs/ 存放（或通过 file: 依赖引用）核心 HAR 库；工程顶层通过 build-profile.json5 声明模块，模块间通过 oh-package.json5 声明依赖。

flowchart TD
    subgraph sg_Repo["仓库根目录"]
        README["README.md / README_en.md"]
        CODE["code/app/ 参考 Demo 工程"]
        LIBS["libs/ 核心 HAR 库<br/>JL_Auth / JL_OTA / JL_RCSP"]
    end

    subgraph sg_Project["HarmonyOS 工程 (jl_ota_harmony)"]
        APP["AppScope<br/>app.json5 / 应用级配置"]
        MOD_ENTRY["entry 模块<br/>主入口 (ArkTS)"]
        MOD_RCSP["lib_rcsp 模块<br/>RCSP 库模块"]
        BT["bluetooth/ble 等<br/>BLE 扫描/连接/发送处理"]
        MAIN["主页面 / OTA 升级流程<br/>调用 JL_OTA / JL_RCSP API"]
    end

    subgraph sg_SDK["SDK 依赖库"]
        H_AUTH["JL_Auth HAR<br/>RCSP 认证"]
        H_OTA["JL_OTA HAR<br/>升级流程控制"]
        H_RCSP["JL_RCSP HAR<br/>RCSP 协议处理"]
    end

    README --> CODE
    CODE --> APP
    APP --> MOD_ENTRY
    APP --> MOD_RCSP
    MOD_ENTRY --> BT
    BT --> MAIN
    MAIN --> H_AUTH
    MAIN --> H_OTA
    MAIN --> H_RCSP
    LIBS -. 发布/引用 .-> H_AUTH
    LIBS -. 发布/引用 .-> H_OTA
    LIBS -. 发布/引用 .-> H_RCSP

工程侧的关键事实（来源于实际配置文件）：

• 顶层 build-profile.json5 声明了 default 产品，compatibleSdkVersion 为 "5.0.0(12)"，runtimeOS 为 HarmonyOS；模块包含 entry 与 lib_rcsp 两个模块。
• entry/oh-package.json5 通过 "rcsp": "file:../lib_rcsp" 引用同工程内的 lib_rcsp 模块（注释中保留了 jl_bt_ota 的引用示例，说明本地库目录结构可按需调整）。

环境准备

在开始之前，请确认满足 README 中列出的运行环境要求：

环境信息来源于 README.md。

获取代码与导入工程

克隆仓库

使用 Git 克隆仓库并进入目录：

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

来源：README.md

导入项目到 DevEco Studio

1. 打开 DevEco Studio；
2. 选择 Open Project；
3. 导航到仓库中解压后的 code/ 目录；
4. 打开参考 Demo 源码工程中的项目文件（即 code/app/JL_OTA_Harmony_v1.0.0_sdk_v1.0.1/jl_ota_harmony/ 下的工程）。

来源：README.md

导入后，DevEco Studio 会依据顶层 build-profile.json5 识别 entry 与 lib_rcsp 两个模块。实际工程配置如下：

{
  "app": {
    "signingConfigs": [],
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.0(12)",
        "runtimeOS": "HarmonyOS",
      }
    ]
  },
  "modules": [
    {
      "name": "entry",
      "srcPath": "./entry",
      "targets": [
        {
          "name": "default",
          "applyToProducts": ["default"]
        }
      ]
    },
    {
      "name": "lib_rcsp",
      "srcPath": "./lib_rcsp",
    }
  ]
}

来源：build-profile.json5

entry 模块的依赖声明：

{
  "license": "",
  "devDependencies": {},
  "author": "",
  "name": "entry",
  "description": "Please describe the basic information.",
  "main": "",
  "version": "1.0.0",
  "dependencies": {
    //    "jl_bt_ota": "file:../jl_bt_ota",
    "rcsp": "file:../lib_rcsp"
  }
}

来源：oh-package.json5

设计意图说明：Demo 通过 file:../lib_rcsp 方式引用同工程内的 lib_rcsp 模块，而不是直接依赖 HAR 文件——这样做可以让 RCSP 相关源码在示例工程内保持可见、可调试；实际集成时，推荐按官方文档将 libs/ 目录下的 HAR 文件复制到工程 lib 目录，并在 oh-package.json5 中通过 file: 依赖引入（见下节）。

添加依赖库

在正式集成到自有工程时，需要引入三个 HAR 库：

• JL_Auth_vx.x.x-release.har：杰理 RCSP 认证相关库；
• JL_OTA_vx.x.x-release.har：OTA 升级核心库，包含升级流程控制；
• JL_RCSP_vx.x.x-release.har：RCSP 协议相关库，包含 RCSP 协议处理。

（xxx 为版本号。）将 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",
  }

来源：README.md

运行示例应用

完成依赖配置并同步构建成功后，即可运行示例应用。除了通过 DevEco Studio 直接运行 Demo 工程外，还可以在华为手机【应用市场】搜索「杰理OTA升级」安装官方发布的示例应用进行体验。

来源：README.md

使用流程

示例应用的核心使用流程（也是 OTA 升级能力的端到端验证路径）如下：

sequenceDiagram
    participant U as 用户
    participant App as Demo 应用
    participant BLE as 蓝牙设备
    participant OTA as JL_OTA / JL_RCSP SDK

    U->>App: 首次打开应用
    App->>App: 授予蓝牙等对应权限
    U->>App: 添加升级文件（本地文件复制到沙盒）
    U->>App: 搜索并连接目标蓝牙设备
    App->>BLE: BLE 扫描/连接
    U->>App: 选择升级文件，开始 OTA 升级
    App->>OTA: 发起 RCSP OTA 升级流程
    OTA->>BLE: 固件数据分包发送
    BLE-->>OTA: 升级进度/状态回调
    OTA-->>App: 升级结果
    App-->>U: 完成提示

使用流程依据 README「配置说明」章节整理：README.md

各步骤说明：

1. 打开 APP：初次打开应用需要授予蓝牙等对应权限，这是后续 BLE 扫描与连接的前提；
2. 添加升级文件：支持本地添加，选择手机本地的升级文件并复制到 App 沙盒中，SDK 从沙盒读取固件文件进行升级；
3. 连接目标设备：搜索并连接需要升级的蓝牙设备；
4. 开始 OTA 升级：选择目标升级文件，开始 OTA 升级；SDK 负责 RCSP 握手、固件分包传输、进度回调与结果上报。

工程结构

仓库根目录结构如下：

HarmonyOS-JL_OTA/
├── code/                                    # 参考源码工程文件夹
│   └── 参考Demo源码工程                  # OTA Demo项目源码
├── 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

参考 Demo 工程内部（code/app/JL_OTA_Harmony_v1.0.0_sdk_v1.0.1/jl_ota_harmony/jl_ota_harmony/）的源码组织包括：

• AppScope/：应用级配置（app.json5、资源与图标）；
• entry/：主模块，包含 build-profile.json5、oh-package.json5 与 src/main/ets/ 下的 ArkTS 源码；
• entry/src/main/ets/bluetooth/：蓝牙能力封装目录，其中 base/ 为通用基类（如 BaseSendDataHandler.ets、BluetoothDevice.ets、BluetoothErrorConstant.ets、BufferQueue.ets、IConnect.ets、IScan.ets），ble/ 为 BLE 通道实现（如 BleImpl.ets、BleDevice.ets、BleScanSettingConfigure.ets、BleConnectSettingConfigure.ets、BleSendDataHandler.ets 及 IBleScan.ets、IBleConnect.ets 接口）。

这个分层结构体现了 SDK 的通道抽象设计：IScan/IConnect 定义扫描与连接契约，BleImpl/BleDevice 提供 BLE 实现，BaseSendDataHandler 与 BleSendDataHandler 处理数据分包发送，BufferQueue 管理发送缓冲。快速开始阶段无需修改这些文件，直接运行工程即可。

调试技巧

• 日志输出：SDK 提供详细的日志输出，可通过日志查看 OTA 连接状态和数据交互；
• 设备调试：使用 DevEco Studio 的 Logcat 查看实时日志；
• 问题排查：SDK 相关问题参考测试调试 — 杰理OTA外接库开发文档(HarmonyOS)。

来源：README.md

常见问题与注意事项

• 权限：首次运行必须授予蓝牙权限，否则扫描与连接无法进行；
• 版本号：依赖声明中的 xxx 需替换为实际版本号（如 1.0.1），HAR 文件名需与 libs/ 目录下实际文件一致；
• SDK 版本：Demo 工程 compatibleSdkVersion 为 5.0.0(12)，若使用其他 HarmonyOS 版本需在 build-profile.json5 中调整；
• 签名配置：示例工程的 signingConfigs 为空，首次构建运行需在 DevEco Studio 中配置自动签名或导入签名证书；
• 芯片支持：固件升级目标设备必须是支持 RCSP OTA 功能的杰理 SDK 芯片（AC707N、AC703N、AC701N、AC697N、AC696N、AC695N 等）。

相关链接

• README.md（中文）
• README_en.md（English）
• 工程配置 build-profile.json5
• 模块依赖 oh-package.json5
• 杰理OTA外接库开发文档(HarmonyOS)
• 版本历史
• 问题反馈（GitHub Issues）