快速开始

本文档介绍如何从零开始使用杰理 OTA SDK（微信小程序版）：包括环境准备、克隆仓库、导入微信开发者工具、添加依赖库、运行示例工程，以及如何在 Demo 中完成 OTAWrapper 的初始化与首次 OTA 升级。

Purpose and Scope

本页覆盖 首次跑通 SDK 的全部必要步骤：

• 运行环境与硬件前置条件
• 仓库克隆与工程结构概览
• 微信开发者工具导入与依赖库（libs/）配置
• 示例工程（code/JLOTA）的结构说明
• OTAWrapper 六步接入流程与首个 OTA 升级示例
• 端侧用户使用流程与常见问题排查

以下主题属于其他页面，本页不做展开：

• OTAWrapper / OTA 库 / RCSP 协议库 / 认证库 的完整 API 参考 —— 参见对应的 API 参考页面
• 配置项详解与调试技巧 —— 参见"配置说明""调试技巧"页面
• SDK 版本历史与许可证 —— 参见 README 末尾的版本历史章节

概述

WeChat-Mini-Program-OTA 是珠海市杰理科技股份有限公司为杰理蓝牙类产品提供的固件升级开发平台，专门实现基于 RCSP OTA 协议的固件升级功能，传输方式为 BLE。SDK 提供完整的升级流程，并支持自动回连（单备份 OTA 自动回连 BLE，提升用户体验）。

整个 SDK 采用分层设计（见 code/JLOTA/docs/readMe.md）：

整个OTA项目的架构: OTA流程库基于RCSP协议库实现，所以需要先实现RCSP协议库

即：OTA 流程库（jl_ota）→ RCSP 协议库（jl_rcsp_ota）→ 认证库（jl_auth） 逐层依赖。快速开始的目标，就是让开发者先把这一整套依赖在微信开发者工具中跑起来。

核心概念：

架构

flowchart TD
    subgraph sg_Demo["示例工程 code/JLOTA"]
        Pages["页面与组件<br/>otaProgressView / timesSelectView / waittingView"]
        BT["上层蓝牙模块<br/>扫描 / 连接 / 收发数据"]
        Wrapper["OTAWrapper 封装层"]
    end

    subgraph sg_SDK["SDK 核心库 libs/"]
        OtaLib["jl_ota（OTA 流程库）"]
        RcspLib["jl_rcsp_ota（RCSP-OTA 协议库）"]
        AuthLib["jl_auth（RCSP 认证库）"]
    end

    subgraph sg_WX["微信小程序平台"]
        WxAPI["wx.* BLE API"]
    end

    subgraph sg_Device["杰理蓝牙设备"]
        Chip["支持 RCSP OTA 的芯片<br/>AC707N / AC703N / AC701N / AC697N / AC696N / AC695N"]
    end

    Pages --> Wrapper
    Wrapper --> OtaLib
    OtaLib --> RcspLib
    RcspLib --> AuthLib
    BT --> WxAPI
    Wrapper -.->|"sendData / 连接 / 断开 回调"| BT
    WxAPI <-->|"BLE 通道 ATT_MTU"| Chip

架构要点：

• 上层蓝牙模块与 SDK 解耦：自 V2.0.0 起，SDK 抽离了蓝牙连接和蓝牙收发数据部分。扫描、连接、断开、发数等操作由上层（Demo）通过 OTAWrapperOption 注入，SDK 不再直接持有微信 BLE API。
• OTAWrapper 是唯一入口：常规场景下无需直接调用 OTA 库接口，只需实现 OTAWrapperOption 中的回调并把蓝牙事件同步给 OTAWrapper。
• 协议分层：jl_ota 依赖 jl_rcsp_ota，认证过程依赖 jl_auth；三层库的 .js 与 .d.ts 文件都需要放入工程 lib/ 目录。

运行环境与前置条件

来源：README.md 运行环境章节

设计意图：BLE 能力与 RCSP 协议栈是硬性依赖，因此在快速开始前需确认目标芯片 SDK 已开启 RCSP OTA 功能，且微信客户端版本满足要求，否则会出现扫描不到设备或连接后无法认证的问题。

快速开始步骤

步骤 1：克隆仓库

git clone https://github.com/Jieli-Tech/WeChat-Mini-Program-OTA.git
cd WeChat-Mini-Program-OTA

来源：README.md

步骤 2：导入项目到微信开发者工具

1. 打开微信开发者工具
2. 选择"导入"
3. 导航到解压后的 code/ 目录
4. 打开参考 Demo 源码工程中的项目文件（即 code/JLOTA 工程）

步骤 3：添加依赖库

将 libs/ 目录下的以下文件放入工程目录中的 lib/ 文件夹（xxx 为版本号）：

来源：README.md 添加依赖库章节

设计意图：.d.ts 声明文件用于 TypeScript 工程的类型提示与编译检查，.js 为运行时实现。两者必须成对放入，缺声明文件会导致 TS 编译报错，缺 js 文件会导致运行时报"模块不存在"。

步骤 4：运行示例应用

编译运行后，可在微信中搜索小程序 "杰理OTA升级" 体验 SDK 功能与使用方法（选择聊天文件作为升级固件来源、连接设备并执行升级）。

工程结构说明

WeChat-Mini-Program-OTA/
├── code/       # 参考源码工程文件夹（OTA Demo 项目源码，含 code/JLOTA）
├── libs/       # 核心库文件夹（auth / ota / rcsp_ota 的 js 与 d.ts）
└── ReadMe.txt  # 说明文件

来源：README.md 工程结构章节

示例工程 code/JLOTA 的关键目录：

接入 OTAWrapper：六步完成首次 OTA

在示例工程中，OTA 能力通过 OTAWrapper 暴露给业务层。完整接入分为六步，前四步是"把蓝牙事件同步给 OTAWrapper"，后两步是连接与升级。

第一步：初始化 OTAWrapper

//OTAWrapper 初始化
const otaWrapperOption: OTAWrapperOption = {
    /**是否需要认证。 在上层已经认证过，就不需要认证。**/
    isUseAuth: () => {
        return this._BluetoothConfigure.isUseAuth
    },
    /**是否需要回连。 在上层进行回连，就不需要内部回连。**/
    isInnerReconnect: () => {
        return true
    },
    /**扫描设备**/
    sanDevice: () => {
        //todo 实现蓝牙扫描操作
    },
    /**连接设备**/
    connectDevice: (device: BluetoothDevice) => {
        //todo 实现蓝牙连接操作
    },
    /**断开设备**/
    disconnectDevice: (device: BluetoothDevice) => {
        //todo 实现蓝牙断开操作
    },
    /**发送数据(非必须实现)，
    * 必须实现的情况：
    * - 1.内部创建并管理RCSPImpl, 即OTAWrapperOption.getRCSPImpl未实现
    * - 2.需要进行认证, 即OTAWrapperOption.isUseAuth返回false
    * **/
    sendData: (device: BluetoothDevice, data: Uint8Array) => {
       //todo 实现蓝牙发数操作
    }
    /**获取RCSPImpl(非必须实现)。
    * - 上层管理RCSPImpl则需要实现,如使用jl-rcsp-op时需要实现。
    * - 上层不管理RCSPImpl则不需要实现，由内部创建并管理RCSPImpl
    *  **/
    //getRCSPImpl?(device: BluetoothDevice): RCSPProtocol.RcspImpl | undefined
}
this._OTAWrapper = new OTAWrapper(otaWrapperOption)

来源：README.md

设计要点：

• isUseAuth 控制是否执行 RCSP 认证。若上层已在更早阶段完成认证，可返回 false 跳过，减少一次握手开销。
• isInnerReconnect 控制单备份升级后的回连是否由 SDK 内部完成；若上层自行实现回连，返回 false。
• sendData 的必选条件：当 SDK 内部创建并管理 RCSPImpl（未实现 getRCSPImpl）或需要认证（isUseAuth 返回 false）时，必须实现蓝牙发数；否则 SDK 通过 getRCSPImpl 获取上层管理的数据通道。
• getRCSPImpl 用于复用上层已管理的 RCSP 实例（例如同时使用 jl-rcsp-op 业务库时）。

第二步：监听蓝牙连接状态并同步 OTAWrapper

this._bluetoothInstance.addConnectCallback({
    onMTUChange: (dev: any, mtu) => {
        BleSendDataHandler.setMtu(dev.deviceId, mtu)
        this._onConnectStateMTUChange(dev, mtu)
    }, onConnectSuccess: (dev: any) => {
        // 通知 OTAWrapper 蓝牙连接成功
        this._OTAWrapper.onConnectStateSuccess(dev)
        this._onConnectStateSuccess(dev)
    }, onConnectFailed: (dev: any, _err) => {
        // 通知 OTAWrapper 蓝牙连接失败
        this._OTAWrapper.onConnectStateFailed(dev)
        this._onConnectStateFailed(dev)
    }, onConnectDisconnect: (dev: any) => {
        // 通知 OTAWrapper 蓝牙连接断开
        this._OTAWrapper.onConnectStateDisconnect(dev)
        this._onConnectStateDisconnect(dev)
    }
})

来源：README.md

设计意图：OTAWrapper 依赖连接状态机推进 OTA 流程（连接成功后才发起认证与 RCSP 初始化，断开后触发回连逻辑），因此上层必须在连接状态变化的同一时机把事件透传给 OTAWrapper，顺序不可颠倒。MTU 变化时还需同步 BleSendDataHandler.setMtu，供发数模块按新 MTU 分包。

第三步：监听蓝牙扫描状态并同步 OTAWrapper

this._bluetoothInstance.addScanCallback({
    onFound: (devs: BTBean.BluetoothDevice[]) => {
        // 通知 OTAWrapper 发现设备
        this._OTAWrapper.onScanFound(devs)
        this._onScanFound(devs)
    }, onScanStart: () => {
        this._onScanStart()
    }, onScanFailed: (err: BTBean.BluetoothError) => {
        this._onScanFailed(err)
    }, onScanFinish: () => {
        // 通知 OTAWrapper 扫描设备停止
        this._OTAWrapper.onSanDeviceStop()
        this._onScanFinish()
    }
})

来源：README.md

第四步：监听蓝牙数据推送并同步 OTAWrapper

const bleDataCallback: BleDataCallback = {
    onReceiveData: (res: WechatMiniprogram.OnBLECharacteristicValueChangeCallbackResult) => {
        // 通知 OTAWrapper 收到数据
        this._OTAWrapper.onReceiveData(this._toDevice(res.deviceId), res.value)
    }
}
BleDataHandler.addCallbacks(bleDataCallback)

来源：README.md

注意：数据回调中需将微信的 deviceId 映射为 SDK 的 BluetoothDevice 对象（this._toDevice(...)），且数据需是 Uint8Array/ArrayBuffer 字节流——RCSP 协议包解析依赖完整的字节序。

第五步：连接设备（触发认证与 RCSP 初始化）

连接设备时，SDK 会自动执行 RCSP 认证与 RCSP 初始化；当认证失败或初始化失败时，SDK 会主动调用 OTAWrapperOption.disconnectDevice 断开设备。

• 若需监听设备初始化状态，可注册 RCSP 回调：OTAWrapper.registerRcspCallback
• 若需判断设备是否初始化成功，可调用 IOTAWrapper.isRCSPInit

第六步：开始 OTA 升级

/*--- 开始执行OTA升级 ---*/
//创建OTA配置项
const otaConfig: OTAConfig = new OTAConfig()
//是否支持新的回连方式
otaConfig.isSupportNewRebootWay = true
//固件升级文件数据
otaConfig.updateFileData = this.upgradeData
//升级目标设备
const device = connectedDevices[0]
const onUgradeCallback: OnUpgradeCallback = {
    onStartOTA: () => {
    // 开始升级
    },
    onNeedReconnect: (reConnectMsg: ReConnectMsg) => {
    // 正在回连
    },
    onProgress: (type: UpgradeType, progress: number) => {
    // 升级进度回调
     if (type == UpgradeType.UPGRADE_TYPE_CHECK_FILE) {
      // 校验文件（传输BootLoader）
      } else if (type == UpgradeType.UPGRADE_TYPE_FIRMWARE) {
      // 传输升级内容
      }
    },
    onStopOTA: () => {
    // 升级结束
    },
    onCancelOTA: () => {
    // 升级取消
    },
    onError: (error: number, message: string) => {
    // 升级失败
    },
}
this._OTAWrapper.startOTA(device, otaConfig, onUgradeCallback)

来源：README.md

关键点：

• OTAConfig.updateFileData 必须填充完整的固件二进制数据（Demo 中从聊天文件选择获取）。
• onProgress 通过 UpgradeType 区分 UPGRADE_TYPE_CHECK_FILE（校验文件/传输 BootLoader） 与 UPGRADE_TYPE_FIRMWARE（传输升级内容） 两个阶段，UI 可据此展示不同提示。
• onError(error, message) 为升级失败的唯一出口，建议在此展示错误码并引导用户重试。

核心流程

sequenceDiagram
    participant Dev as 业务层页面
    participant W as OTAWrapper
    participant Ota as jl_ota 流程库
    participant Rcsp as jl_rcsp_ota 协议库
    participant Auth as jl_auth 认证库
    participant BT as 上层蓝牙模块 (wx BLE)
    participant Chip as 杰理设备

    Dev->>W: new OTAWrapper(option)
    Dev->>W: 同步 onConnectStateSuccess / onScanFound / onReceiveData
    Dev->>W: startOTA(device, otaConfig, callback)
    W->>Ota: 启动升级流程
    Ota->>Rcsp: 生成 RCSP 升级命令
    Rcsp->>Auth: 认证握手（按 isUseAuth）
    Rcsp->>BT: sendData(device, data)
    BT->>Chip: 写入特征值（按 MTU 分包）
    Chip-->>BT: 特征值变化通知
    BT-->>W: onReceiveData(device, bytes)
    W-->>Dev: onProgress(type, progress)
    W-->>Dev: onStopOTA / onError / onNeedReconnect

端侧用户视角的使用流程（与代码流程对应）：

1. 打开小程序 —— 初次打开需授予蓝牙等对应权限
2. 添加升级文件 —— 支持选择聊天文件
3. 连接目标设备 —— 搜索并连接需要升级的蓝牙设备
4. 开始 OTA 升级 —— 选择目标升级文件，开始 OTA 升级

来源：README.md 使用流程章节

常见问题与故障排查

首次接入最容易踩坑的点集中在 MTU、微信 API 兼容性、权限与认证 四个方面。以下内容整理自示例工程的 code/JLOTA/docs/readMe.md，建议在开始联调前通读。

已知微信 API bug（基础库 2.24.6）

1. wx.setBLEMTU 的 fail 属性不会返回最终协商 MTU —— 解决方式：fail 时调用 wx.getBLEMTU 获取最终协商 MTU。
2. wx.onBLEMTUChange 不触发 —— 需自行处理 MTU 变化监听的不确定性。
3. iOS 端部分微信版本不支持获取 MTU，会直接导致每包只能以 20 Byte 发送，最终影响设备升级失败。可参考的处理方案：通过自定义命令的方式从设备端获取 MTU。

问题 1：MTU 引起的发送数据异常

常见现象：小机（设备）在 OTA 时频繁请求同一段数据。

原因分析：

• 小程序中 MTU 为 ATT_MTU，包含 Op-Code 和 Attribute Handle 的长度，实际可传输的数据长度为 ATT_MTU - 3。iOS 系统中 MTU 为固定值；Android 系统中 MTU 会在系统协商成功后发生改变，建议使用 wx.onBLEMTUChange 监听。
• MTU 大小不足且没有做分包发送会导致丢数据。示例：MTU 只有 23，实际可用大小为 20，发送数据 40 Byte，设备真正收到的只有前 20 Byte。

处理建议：按 ATT_MTU - 3 计算每包载荷，分包发送；并参考第一、二、四步中的 BleSendDataHandler.setMtu 同步最新 MTU。

问题 2：小程序调整 MTU 失败

常见现象：调用 wx.setBLEMTU 回调 fail。

原因分析：

• 可调节的 MTU 大小要小于设备端设置的 MTU，否则调整失败，且 fail 中不携带最终协商 MTU（当前微信 API 的 bug）。
• iOS 手机不支持调整 MTU，需要通过 wx.getBLEMTU() 获取，且 writeType 要指明为 writeNoResponse。

问题 3：提审时 wx.getLocation 暂未开通

处理方式：先到「设置 - 基本设置 - 服务类目」将小程序的类目设置成对应类目，再到「开发 - 开发管理 - 接口设置」中自助开通该接口权限。只有部分类目可以开通，具体以官方介绍为准。

问题 4：旧 JS 项目使用 TS 出现白屏（部分 UI 显示不正常）

处理方式：在 project.config.json 的 setting 下将 uglifyFileName 改为 false（关闭上传时代码保护），可解决基于 TypeScript/less 开发的小程序真机预览白屏、babel 报错问题。

问题 5：OTA 升级失败，等待回复命令超时

可能原因与处理：

• MTU 太小，频繁调用 wx.writeBLECharacteristicValue 会偶现写入成功回调延时严重。处理方法：当 wx.writeBLECharacteristicValue 回调 complete 时，再调用下一次。
• MTU 太小，单个协议包数据太大，完整发出前设备端已超时。处理方法：调大 MTU。

问题 6：出现认证失败

可能原因：上一次通过认证的蓝牙连接断开和本次连接时间间隔很短，蓝牙底层并未真正断开。

处理办法：

1. 避免频繁断连设备；
2. 若必须频繁断连，推荐小程序端不走认证，并同时关闭设备端的认证（对应 OTAWrapperOption.isUseAuth 返回 false 的场景）。

调试技巧速览

• 日志输出：SDK 提供详细日志，可通过日志查看 OTA 连接状态与数据交互。
• 设备调试：使用 vConsole 查看实时日志。
• 问题排查：SDK 侧问题可参考 SDK 调试说明。

相关链接

• README.md（仓库主文档，含配置说明、版本历史）
• README_en.md（英文版说明）
• code/JLOTA/docs/readMe.md（架构说明与微信 API bug / 常见问题）
• 杰理 OTA SDK 在线文档中心
• 版本历史（README 第八章）
• Apache License 2.0