项目概述

WeChat-Mini-Program-OTA 是珠海市杰理科技股份有限公司为杰理蓝牙类产品提供的固件升级（OTA）微信小程序开发平台，通过 BLE 通道实现 RCSP OTA 升级流程，并附带完整的参考 Demo 工程。

Purpose and Scope

本页面从宏观角度介绍该仓库的整体定位、组成结构、运行环境与快速上手方式，帮助读者建立对项目的整体认知，并定位后续深入阅读的入口。

本页面覆盖以下内容：

仓库整体结构与各目录职责
核心 SDK 依赖库（libs/）的组成
参考 Demo 工程（code/JLOTA）的页面结构与全局初始化流程
运行环境要求与快速开始步骤
全局配置项与存储键说明

以下主题属于后续专项页面，不在本页展开：

BLE 连接流程与设备发现 → 参见「连接模块」相关页面
OTA 升级流程与协议细节 → 参见「升级流程」相关页面
设置页与自定义指令（BLE 数据透传、自定义命令）→ 参见「设置模块」相关页面
各 SDK 库的 API 细节 → 参见「SDK 库参考」相关页面

Overview

WeChat-Mini-Program-OTA 定位为杰理 OTA SDK（WeiXin），即专为杰理蓝牙类产品提供固件升级功能的集成 SDK。它面向微信小程序环境，核心能力包括：

功能	说明
BLE 升级	通过 BLE（低功耗蓝牙）通道进行固件升级
自动回连	单备份 OTA 自动回连 BLE 功能，提升用户体验
RCSP 协议	基于杰理私有 RCSP 协议实现完整升级流程

仓库同时提供一套完整的参考 Demo 小程序（工程位于 code/ 目录下），该 Demo 即为微信上可搜索到的「杰理OTA升级」小程序，用于演示 SDK 的功能与使用方法，可作为集成方二次开发的起点。

仓库由三大部分组成：

code/：参考 Demo 源码工程（微信小程序项目，使用 TypeScript + less + wxml 编写）；
libs/：核心依赖库（RCSP 认证库 jl_auth、OTA 流程库 jl_ota、RCSP-OTA 协议库 jl_rcsp_ota）；
README.md / README_en.md：中英文说明文档与文档中心入口。

Architecture

下图展示了仓库的整体架构：Demo 工程在运行时加载三个核心 SDK 库，通过 BluetoothOTAManager 统一管理蓝牙连接与升级流程，最终通过微信 BLE API 与杰理蓝牙芯片（如 AC695N 等系列）通信。

flowchart TD
    subgraph sg_Repo["WeChat-Mini-Program-OTA 仓库"]
        subgraph sg_Demo["code/JLOTA Demo 工程"]
            App["app.ts 全局入口<br/>(BluetoothOTAManager 初始化)"]
            Pages["页面层<br/>pageConnect / pageUpdate / pageSetting"]
            Components["自定义组件<br/>otaProgressView / timesSelectView / waittingView"]
            TabBar["custom-tab-bar<br/>自定义 TabBar"]
            App --> Pages
            Pages --> Components
            Pages --> TabBar
        end

        subgraph sg_Libs["libs/ 核心依赖库"]
            AuthLib["jl_auth (RCSP 认证库)"]
            OtaLib["jl_ota (OTA 流程库)"]
            RcspOtaLib["jl_rcsp_ota (RCSP-OTA 协议库)"]
        end

        subgraph sg_WeChat["微信小程序环境"]
            WxAPI["wx BLE API<br/>(openBluetoothAdapter 等)"]
            BluetoothManager["BluetoothOTAManager<br/>(code 工程 lib 层)"]
        end
    end

    Pages --> AuthLib
    Pages --> OtaLib
    Pages --> RcspOtaLib
    AuthLib --> RcspOtaLib
    OtaLib --> RcspOtaLib
    BluetoothManager --> WxAPI
    WxAPI <-->|"BLE 通信"| Device["杰理蓝牙芯片<br/>(AC707N/AC697N/AC696N 等)"]

架构说明：

页面层是 Demo 的入口载体：pageConnect（连接）、pageUpdate（升级）、pageSetting（设置）三个 Tab 页，以及设置页下的 pageBLEDataSet（BLE 数据透传）与 pageCustomCmd（自定义指令）子页面；
SDK 库层是核心能力所在：jl_rcsp_ota 实现 RCSP 协议编解码，jl_ota 在上层编排升级流程，jl_auth 提供 RCSP 认证握手能力；
BluetoothOTAManager（Demo 工程 lib 层）封装了蓝牙设备管理，将 SDK 与微信 BLE API 桥接，是全局唯一的蓝牙管理器实例（在 app.ts 的 onLaunch 中创建）。

仓库结构详解

仓库根目录的布局（来自 README.md）：

WeChat-Mini-Program-OTA/
├── code/                                    # 参考源码工程文件夹
│   └── JLOTA/miniprogram/                   # OTA Demo 小程序项目源码
├── libs/                                    # 核心库文件夹（SDK 依赖）
├── README.md                                # 中文说明文档
├── README_en.md                             # 英文说明文档
└── LICENSE                                  # 许可证

Source: README.md

`libs/` 核心依赖库

libs/ 目录存放集成所需的三个 SDK 库（含 JS 实现与声明文件），当前仓库内的版本为：

库文件	作用	版本
`jl_auth_2.0.0.js`（及 `.d.ts`）	RCSP 认证库：完成设备认证/握手	2.0.0
`jl_ota_2.1.1.js`（及 `.d.ts`）	OTA 流程库：编排固件升级流程	2.1.1
`jl_rcsp_ota_2.1.1.js`（及 `.d.ts`）	RCSP-OTA 协议库：RCSP 协议报文编解码	2.1.1

集成时需将 libs/ 下的 JS 与声明文件一并复制到工程目录的 lib 文件夹下（参见 README.md）。Demo 工程中这些库位于 code/JLOTA/miniprogram/lib/jl_lib/ 下，属于本地依赖的示例放置方式。

`code/JLOTA` 参考 Demo 工程

Demo 是一个标准的微信小程序项目，其页面与全局配置定义在 app.json 中：

5 个页面：pageConnect、pageUpdate、pageSetting 三个 Tab 主页面，以及设置页下的 pageBLEDataSet、pageCustomCmd 两个子页面；
自定义 TabBar：custom: true，共「连接」「升级」「设置」三个 Tab，选中色为 #398BFF；
窗口配置：导航栏标题为「杰理OTA升级」；
权限声明：申请 scope.userLocation 定位权限，用于发现蓝牙设备（小程序定位权限与 BLE 扫描相关）；
样式体系采用 style: "v2"。

Demo 工程还包含若干自定义组件：otaProgressView（升级进度视图）、timesSelectView（次数选择视图）、waittingView（等待视图），以及 custom-tab-bar（自定义 TabBar 实现）。

全局初始化流程

Demo 的入口为 app.ts，它在 App() 生命周期中完成全局数据初始化、日志系统装配与蓝牙管理器创建。核心逻辑如下（节选）：

// app.ts

import { BluetoothOTAManager } from "./lib/bluetoothOTAManager";
import { setLogger as setOTALogger, setLogGrade as setOTALoggerGrade } from "./lib/jl_lib/jl_ota_2.1.1";
import { setLogger as setRCSPLogger, setLogGrade as setRCSPLoggerGrade } from "./lib/jl_lib/jl_rcsp_ota_2.1.1";
import { setLogger as setAppLogger, setLogGrade as setAppLoggerGrade } from "./lib/log";
import { getLogger, setLogEnable, setLogGrade as setLogManagerGrade } from "./lib/logger";

App<IAppOption>({
  globalData: {
    gbIsHandshake: true,
    gbIsAutoTest: false,
    gbTestNum: 1,
    gbMtuNum: 512,
    gbDevelop: false,
    gbEnableDebug: false,
    bluetoothManager: <any>null,
  },
  onLaunch() {
    // 开发者模式
    const developMode = wx.getStorageSync("DevelopMode")
    if (developMode != "") {
      this.globalData.gbDevelop = developMode
    }
    //小程序开发调试(打印)
    const cacheIsEnableDebug = wx.getStorageSync("IsEnableDebug")
    if (cacheIsEnableDebug != "") {
      this.globalData.gbEnableDebug = cacheIsEnableDebug
      setLogEnable(cacheIsEnableDebug)
    }
    //打印设置
    {
      const logger = getLogger()
      setOTALogger(logger)
      setRCSPLogger(logger)
      setAppLogger(logger)
      const logGrade = wx.getStorageSync("LogGrade")
      if (logGrade != "") {
        setLogManagerGrade(logGrade)
      }
    }
    const cacheIsHandshake = wx.getStorageSync("IsHandshake")
    if (cacheIsHandshake != "") {
      this.globalData.gbIsHandshake = cacheIsHandshake
    }
    // ...（AutoTest / TestNum / MtuNum 等存储键读取）
    const sysinfo = wx.getSystemInfoSync()
    this.globalData.bluetoothManager = new BluetoothOTAManager(sysinfo.platform);
    const configure = this.globalData.bluetoothManager.getConfigure()
    configure.isUseAuth = this.globalData.gbIsHandshake
    configure.changeMTU = this.globalData.gbMtuNum
    //todo 目前未实现自动化测试OTA
    configure.isAutoTestOTA = false;
    configure.autoTestOTACount = 20;
  },
});

Source: app.ts

这段初始化逻辑的设计意图在于：

持久化优先：所有可调参数（握手开关、MTU 大小、日志等级、开发者模式等）都先从 wx.getStorageSync 读取缓存值，再覆盖到 globalData，保证用户在设置页修改的配置在重启小程序后依然生效；
日志统一注入：通过 setLogger / setLogGrade 把统一的日志管理器注入 OTA 库、RCSP 库和应用日志模块，避免三方库各自打印、无法统一控制；
单例蓝牙管理器：BluetoothOTAManager 在启动时按平台创建一次并存入 globalData，后续所有页面通过全局数据共享同一蓝牙连接与升级状态；
默认值保守：默认 gbIsHandshake = true（启用认证握手）、gbMtuNum = 512、gbIsAutoTest = false，其中自动化测试 OTA 尚未实现（代码中留有 //todo 注释）。

核心流程：小程序启动

下图描述了 Demo 小程序从冷启动到进入首页的完整时序：

sequenceDiagram
    participant U as 用户
    participant WX as 微信客户端
    participant App as app.ts onLaunch
    participant Store as 本地存储 wx Storage
    participant Logger as logger 日志管理器
    participant BTM as BluetoothOTAManager
    participant SDK as jl_ota / jl_rcsp_ota

    U->>WX: 打开「杰理OTA升级」小程序
    WX->>App: 触发 onLaunch
    App->>Store: 读取 DevelopMode / IsEnableDebug / LogGrade / IsHandshake / MtuNum 等
    Store-->>App: 返回缓存配置（若无则保持默认值）
    App->>App: 合并到 globalData
    App->>Logger: getLogger()
    App->>SDK: setLogger(logger) / setLogGrade(grade)
    App->>BTM: new BluetoothOTAManager(sysinfo.platform)
    App->>BTM: getConfigure() 并写入 isUseAuth / changeMTU / isAutoTestOTA
    WX->>App: onLaunch 完成，加载首页 pageConnect
    Note over BTM,SDK: 连接页后续通过蓝牙管理器<br/>发现设备、握手认证、执行 OTA

该流程的关键决策点：所有运行参数优先取自本地存储，存储中没有对应键时才使用 app.ts 中声明的默认值。这种「存储优先、默认兜底」的策略既保证了开箱即用，又保证了可配置性。

使用示例

示例一：页面与 TabBar 声明

小程序注册了 5 个页面并启用自定义 TabBar，这是理解 Demo 功能入口（连接 → 升级 → 设置）的第一步：

{
  "pages": [
    "pages/pageConnect/pageConnect",
    "pages/pageUpdate/pageUpdate",
    "pages/pageSetting/pageSetting",
    "pages/pageSetting/pageBLEDataSet/pageBLEDataSet",
    "pages/pageSetting/pageCustomCmd/pageCustomCmd"
  ],
  "tabBar": {
    "custom": true,
    "color": "#808080",
    "selectedColor": "#398BFF",
    "list": [
      { "pagePath": "pages/pageConnect/pageConnect", "text": "连接" },
      { "pagePath": "pages/pageUpdate/pageUpdate", "text": "升级" },
      { "pagePath": "pages/pageSetting/pageSetting", "text": "设置" }
    ]
  }
}

Source: app.json

示例二：蓝牙权限声明

由于 BLE 设备扫描在小程序侧与定位权限绑定，app.json 中声明了定位权限及用途说明：

"permission": {
  "scope.userLocation": {
    "desc": "你的位置信息将用于发现蓝牙设备"
  }
}

Source: app.json

配置选项

全局运行参数（`app.ts` globalData）

参数	类型	默认值	说明
`gbIsHandshake`	boolean	`true`	是否启用 RCSP 认证握手，可从存储键 `IsHandshake` 覆盖
`gbIsAutoTest`	boolean	`false`	是否启用自动化测试 OTA（当前未实现）
`gbTestNum`	number	`1`	测试次数，可从存储键 `TestNum` 覆盖
`gbMtuNum`	number	`512`	请求的 MTU 大小，可从存储键 `MtuNum` 覆盖
`gbDevelop`	boolean	`false`	开发者模式开关，可从存储键 `DevelopMode` 覆盖
`gbEnableDebug`	boolean	`false`	调试打印开关，可从存储键 `IsEnableDebug` 覆盖并同步到日志管理器
`bluetoothManager`	BluetoothOTAManager	`null`	全局唯一的蓝牙管理器实例，启动时创建

本地存储键（`wx.getStorageSync`）

存储键	影响配置	说明
`DevelopMode`	`gbDevelop`	开发者模式
`IsEnableDebug`	`gbEnableDebug` / 日志使能	是否启用调试打印
`LogGrade`	日志等级	控制 SDK 与应用日志输出级别
`IsHandshake`	`gbIsHandshake`	是否执行握手认证
`IsAutoTest`	`gbIsAutoTest`	自动化测试开关（未实现）
`TestNum`	`gbTestNum`	测试次数
`MtuNum`	`gbMtuNum`	MTU 大小
`ServiceUUID` / `NotifyCharacteristicUUID` / `WriteCharacteristicUUID`	蓝牙服务与特征值	自定义 BLE 服务/特征 UUID（由设置页维护）

Source: app.ts

失败模式与边界情况

基于对入口代码与 README 的分析，该项目在集成与运行时有以下已知边界与失败模式：

硬件不兼容：BLE 升级能力依赖芯片固件支持 RCSP OTA。README 明确列出支持的芯片系列（AC707N、AC703N、AC701N、AC697N、AC696N、AC695N 等），在不支持 RCSP OTA 的杰理 SDK 上调用升级将失败，集成前需先确认固件能力。
微信客户端版本过低：BLE 功能要求微信客户端 iOS 6.5.6 以上、Android 6.5.7 以上；旧版本客户端可能无法初始化蓝牙适配器。
定位权限缺失：小程序 BLE 扫描依赖 scope.userLocation 定位权限。用户在设置中关闭定位授权后，设备发现可能失败——这是 app.json 中声明该权限的原因，Demo 应处理权限拒绝回调。
配置持久化依赖本地存储：所有运行参数通过 wx.getStorageSync 读取。若存储中残留过期或非法值（例如过大的 MtuNum），会直接覆盖默认值并影响连接行为；Demo 未在读取处做值域校验，属于集成方需要注意的边界。
自动化测试 OTA 未实现：app.ts 中 configure.isAutoTestOTA 被硬编码为 false，源码注释 //todo 目前未实现自动化测试OTA 表明该能力尚未落地，相关开关（gbIsAutoTest、autoTestOTACount）当前不会产生实际升级行为。
单例状态共享：BluetoothOTAManager 作为全局单例存放于 globalData，页面间共享连接与升级状态。若页面生命周期管理不当（如页面销毁后回调仍触发），可能产生状态错乱，集成方应关注页面的 onUnload 清理逻辑。

性能与运维注意事项

日志分级控制：项目将 OTA 库、RCSP 库与应用日志统一注入同一 logger，可通过 LogGrade 存储键控制输出级别。生产环境建议调低日志级别以减少 console 输出对 BLE 时序的影响。
MTU 协商：默认 gbMtuNum = 512，实际 MTU 由 BluetoothOTAManager 与设备协商，过大的 MTU 请求可能被设备拒绝，过小则降低传输吞吐。升级耗时对 MTU 敏感，可在设置页调整。
升级传输通道：升级数据经 BLE 通道传输，数据分片与应答间隔直接影响升级时长与稳定性；Demo 使用自定义进度组件（otaProgressView）向用户呈现传输进度。

扩展点

页面扩展：在 app.json 的 pages 数组中追加页面即可扩展功能入口；设置页已演示了 pageBLEDataSet（BLE 数据透传）与 pageCustomCmd（自定义指令）两种扩展形态，可作为新增调试/量产功能的模板。
SDK 替换：libs/ 中三个库均有版本号（如 jl_ota_2.1.1），升级 SDK 时替换对应 JS 与 .d.ts 文件即可，API 兼容性以各版本声明文件为准。
自定义 TabBar：Demo 使用 custom: true 的自定义 TabBar，集成方可按需调整 Tab 样式与行为，而不受微信默认 TabBar 的视觉约束。

README.md（中文说明）
README_en.md（English）
app.json（页面与 TabBar 配置）
app.ts（全局初始化入口）
文档中心（官方）：https://doc.zh-jieli.com/Apps/Wechat/ota/zh-cn/master/index.html
相关页面：连接模块、升级流程、设置模块、SDK 库参考（本目录下对应目录项）