项目简介与核心能力

HarmonyOS-JL_OTA 是珠海市杰理科技股份有限公司（Jieli Tech）为杰理蓝牙类产品打造的 HarmonyOS 固件升级（OTA）集成 SDK 与参考 Demo 工程，基于 RCSP 协议提供 BLE、SPP 双通道的完整固件升级能力。

Purpose and Scope

本页面向初次接触该仓库的开发者，系统介绍 HarmonyOS-JL_OTA 项目的定位、核心能力、运行环境、工程结构、接入方式与使用流程，帮助读者快速建立对整套 OTA 升级能力的整体认知。

本页属于「项目概览」主题，覆盖以下内容：

• 项目的背景与定位（杰理 RCSP OTA 升级）
• 核心能力清单：BLE 升级、SPP 升级、自动回连
• 运行环境与硬件要求
• 仓库工程结构与依赖库说明
• 快速开始与使用流程
• 版本历史与社区支持

以下主题由仓库内其他页面/文档承载，本页不做展开：

• 各模块（BLE 连接、SPP 连接、数据收发）的详细实现与 API 签名，参见对应模块文档（如 bluetooth 模块 相关页面）。
• 杰理官方在线文档中心（杰理OTA外接库开发文档(HarmonyOS)）承载的协议细节与调试说明。

Overview

项目定位

HarmonyOS-JL_OTA 是杰理科技为 HarmonyOS 生态提供的 RCSP OTA 固件升级开发平台。RCSP（Remote Control Simple Protocol，杰理私有遥控/升级协议）是杰理蓝牙芯片系列用于设备控制与固件升级的标准协议。本 SDK 将该协议封装为可供 HarmonyOS 应用（ArkTS）直接调用的能力，覆盖"扫描设备 → 建立连接 → 传输固件 → 升级完成"的完整链路。

该仓库同时包含两类交付物（见 README.md 工程结构）：

1. 参考 Demo 源码工程（code/ 目录）：一个完整的 HarmonyOS 应用示例，展示如何集成 SDK、如何调用蓝牙扫描/连接/升级接口。
2. 核心库（.har 包，libs/ 目录）：以 Harmony Archive 形式分发的编译产物，包括认证库、OTA 核心库、RCSP 协议库。

核心能力一览

以上能力描述与功能表来自 README.md 概述章节。

Architecture

总体架构

flowchart TD
    subgraph sg_Demo["参考 Demo 工程（code/）"]
        UI["ArkTS UI 页面<br/>升级文件管理 / 设备列表 / 升级进度"]
        OTAManager["BluetoothOTAManager.ets<br/>OTA 业务调度"]
        BTManager["BluetoothManager.ets<br/>蓝牙统一入口"]
    end

    subgraph sg_Transport["传输层（entry/src/main/ets/bluetooth/）"]
        BLE["ble/ 子模块<br/>BleImpl / BleDevice / BleSendDataHandler"]
        SPP["spp/ 子模块<br/>SppImpl / SppDevice / SppConnectSettingConfigure"]
        BASE["base/ 公共基类<br/>IConnect / IScan / BufferQueue / BaseSendDataHandler"]
    end

    subgraph sg_Sdk["SDK 依赖库（libs/ 目录 .har）"]
        AUTH["JL_Auth_vx.x.x-release.har<br/>RCSP 认证"]
        OTA["JL_OTA_vx.x.x-release.har<br/>升级流程控制"]
        RCSP["JL_RCSP_vx.x.x-release.har<br/>RCSP 协议处理"]
    end

    subgraph sg_Device["杰理蓝牙设备"]
        DEV["AC707N / AC703N / AC701N<br/>AC697N / AC696N / AC695N 等"]
    end

    UI --> OTAManager
    OTAManager --> BTManager
    BTManager --> BLE
    BTManager --> SPP
    BLE --> BASE
    SPP --> BASE
    BLE -->|"BLE 空中链路"| DEV
    SPP -->|"经典蓝牙 SPP 链路"| DEV
    OTAManager --> AUTH
    OTAManager --> OTA
    OTAManager --> RCSP
    OTA --> RCSP

架构说明：

• UI 层（Demo 工程）：负责蓝牙权限申请、升级文件选择、设备列表展示与升级进度呈现，是 SDK 能力的调用方。
• 业务调度层：BluetoothOTAManager.ets 作为 OTA 升级流程的编排入口，BluetoothManager.ets 提供蓝牙能力统一入口，向下分发到具体传输实现。
• 传输层：bluetooth/ 目录按 ble/、spp/、base/ 三个子模块组织。base/ 提供连接（IConnect）、扫描（IScan）、发送处理器（BaseSendDataHandler）、环形缓冲（BufferQueue）等抽象与工具，BLE 与 SPP 各自实现这些抽象，形成策略模式——上层业务无需关心底层通道差异。
• SDK 库层：三个 .har 分别承担认证、升级流程、协议编解码职责。Demo 工程通过 oh-package.json5 以 file: 方式依赖本地 libs/ 目录中的产物。
• 设备层：支持 RCSP OTA 的杰理芯片方案（AC70xN / AC69xN 系列）。

仓库目录结构

HarmonyOS-JL_OTA/
├── code/                                    # 参考源码工程文件夹
│   └── JL_OTA_Harmony_v1.0.0_sdk_v1.0.1/    # OTA Demo 项目源码（含 entry 与 lib_rcsp 模块）
├── 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_en.md                             # 英文说明文件
└── LICENSE                                  # Apache License 2.0

Demo 工程内部（code/app/.../jl_ota_harmony/）主要包含：

• entry/：HarmonyOS 应用主模块，其中 entry/src/main/ets/bluetooth/ 为蓝牙与 OTA 业务代码，按 base/、ble/、spp/ 分层组织。
• lib_rcsp/：RCSP 相关资源/逻辑的独立模块（含多语言资源 zh_CN、en_US）。

核心能力详解

BLE 升级（低功耗蓝牙通道）

BLE 通道是 HarmonyOS 5.0+ 设备最常用的升级路径。Demo 工程在 bluetooth/ble/ 子模块中实现了 BLE 专属能力：

• BleImpl.ets：BLE 扫描与连接的实现类，对应 IBleScan / IBleConnect 接口。
• BleDevice.ets：BLE 设备封装（地址、名称、广播数据等）。
• BleSendDataHandler.ets：继承 base/BaseSendDataHandler.ets，负责 BLE 通道上的分包发送与流控。
• BleScanSettingConfigure.ets / BleConnectSettingConfigure.ets：扫描与连接的参数配置（如 UUID、连接参数）。

设计意图：BLE 是穿戴设备与低功耗外设的事实标准。将扫描、连接、数据发送各自抽象为接口（IScan、IConnect、BaseSendDataHandler），使 OTA 上层逻辑与底层链路解耦——同一套升级流程代码既能跑在 BLE 上，也能跑在 SPP 上。

SPP 升级（经典蓝牙通道）

SPP（Serial Port Profile）面向经典蓝牙产品。bluetooth/spp/ 子模块提供：

• SppImpl.ets：SPP 扫描与连接实现，对应 ISppScan / ISppConnect 接口。
• SppDevice.ets：SPP 设备封装。
• SppConnectSettingConfigure.ets：SPP 连接参数配置。

SPP 支持在 V1.0.1 版本中新增（版本历史："兼容支持SPP升级方式"）。对于仅支持经典蓝牙的存量产品，SPP 通道是唯一可行的升级路径，因此 SDK 必须同时维护两套传输实现。

自动回连（单备份 OTA）

单备份升级场景下，设备在写入固件后会重启。应用侧的自动回连能力会在设备重启完成后自动重新建立 BLE 连接，避免用户手动重新配对。这是提升 OTA 升级体验的关键环节——升级中断后能否无缝恢复，直接决定用户是否感知到升级成功。

运行环境

来源：README.md 运行环境。

使用流程（端到端）

flowchart TD
    Start([打开 APP]) --> P1["授予蓝牙等权限"]
    P1 --> P2{"添加升级文件"}
    P2 -->|"本地添加"| P3["选择手机本地升级文件<br/>复制到 App 沙盒"]
    P3 --> P4["搜索目标蓝牙设备"]
    P4 --> P5["连接目标设备"]
    P5 --> P6["选择升级文件"]
    P6 --> P7["开始 OTA 升级"]
    P7 --> P8{"升级通道"}
    P8 -->|"BLE"| B["BLE 链路传输固件"]
    P8 -->|"SPP"| S["SPP 链路传输固件"]
    B --> Done([升级完成/自动回连])
    S --> Done

流程步骤来源：README.md 配置说明-使用流程。

快速开始与接入方式

1. 克隆仓库

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

来源：README.md 快速开始。

2. 导入工程

使用 DevEco Studio 选择 "Open Project"，导航到 code/ 目录下的参考 Demo 源码工程打开即可。

3. 添加依赖库

将 libs/ 目录下的 .har 文件放入项目的 lib 目录，并在 oh-package.json5 中声明依赖（xxx 为版本号）：

{
  "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 添加依赖库。

三个依赖库的职责边界（设计意图）：认证（jl-auth）、升级流程（jl-ota）、协议（jl-rcsp）分离，使各库可独立演进。认证库负责设备鉴权与安全握手，协议库负责 RCSP 报文编解码，OTA 库只关心升级状态机与固件分发，职责单一、便于测试与复用。

4. 运行示例应用

可在华为手机【应用市场】搜索 "杰理OTA升级" 直接体验已发布的示例应用。

配置选项

依赖库配置来源：README.md 添加依赖库；传输参数配置类位于 bluetooth 模块 的 ble/ 与 spp/ 子目录。

代码入口参考

Demo 工程中与 OTA 升级直接相关的核心代码入口（位于 entry/src/main/ets/bluetooth/）：

注意：上述文件的详细方法签名与参数以实际源码为准，各模块的接口级文档请参见对应模块页面与杰理官方文档中心。

失败模式、边界情况与调试

权限与系统限制

• 首次打开应用必须授予蓝牙等系统权限；HarmonyOS 5.0+ 的蓝牙权限模型要求应用在扫描前完成动态授权，否则扫描接口会直接失败。
• 运行环境要求 HarmonyOS 5.0+，低版本系统无法使用 BLE 能力。

升级中断与恢复

• 单备份 OTA 场景依赖自动回连能力：设备升级重启后应用需自动恢复连接，若回连失败，用户需手动重新连接。
• 固件传输中断（如蓝牙断开、设备移动出范围）属于典型失败场景，SDK 日志是定位传输断点的主要手段。

调试手段

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

调试建议来源：README.md 调试技巧。

边界情况

• 升级文件来源：当前版本支持"本地添加"（选择手机本地升级文件复制到 App 沙盒），不支持从云端直接拉取，文件管理需自行保证沙盒空间充足。
• 多设备场景：Demo 按"搜索 → 连接 → 升级"的串行流程设计，同一时刻以单一目标设备为准。

版本历史

来源：README.md 版本历史。

社区与支持

Related Links

• README（中文） — 项目完整说明文档
• README_en.md（English） — English version of project README
• bluetooth 模块源码目录 — BLE/SPP 传输层实现
• 杰理OTA外接库开发文档(HarmonyOS) — 官方在线文档中心
• 版本发布记录 — SDK 发布记录
• LICENSE — Apache License 2.0