RCSP 认证库（jl_auth）

jl_auth 是杰理（Jieli）OTA SDK 中负责 RCSP 认证握手的核心库，以编译产物（jl_auth_x.x.x.js + jl_auth_x.x.x.d.ts）形式随 SDK 分发，在 BLE 连接建立后、OTA 升级开始前完成设备安全认证与 RCSP 初始化前置校验。

Purpose and Scope

本页面说明 jl_auth（RCSP 认证库）在杰理微信小程序 OTA SDK 中的职责边界、集成方式、配置开关与失败行为。内容基于本仓库 README.md 中可验证的集成契约与调用示例。

页面边界说明：

本仓库是 SDK 的集成说明/示例仓库，jl_auth 的实现源码不在本仓库内，它作为预编译库随 SDK 发布包（libs/ 目录）分发。因此本页面重点记录其外部契约（交付形态、配置项、调用流程、失败语义），而非内部算法。
同属一个 SDK 生态的兄弟能力请参见对应页面：
- jl_ota（OTA 流程库）：负责升级流程编排、回连逻辑与进度回调，是认证库的主要调用方。
- jl_rcsp_ota（RCSP-OTA 协议库）：负责 RCSP 协议报文编解码与 BLE 数据透传，认证握手报文经此层收发。
- 蓝牙连接/扫描/数据收发属于上层业务（Demo）职责，不在本页面范围。

若需要认证库的完整 API 签名，请以 SDK 发布包中随附的 jl_auth_x.x.x.d.ts 声明文件及官方文档中心为准。

RCSP（杰理私有实时控制与流传输协议，Real-time Control and Streaming Protocol）是杰理蓝牙 SoC（AC707N、AC703N、AC701N、AC697N、AC696N、AC695N 等）与上位机之间进行控制交互的私有协议。在 OTA 场景中，小程序连接设备后必须先完成 RCSP 认证，才能建立可信的通讯上下文、执行 RCSP 初始化并进入固件升级流程。

jl_auth 正是这一认证环节的载体：它接收 OTAWrapper 的认证触发信号，协调 RCSP 协议层向设备发起认证指令、校验应答，并将认证结果反馈给上层。

为什么需要单独的认证库

从 README.md 的工程结构可以看出，SDK 被刻意拆分为三个独立库（jl_auth、jl_ota、jl_rcsp_ota）。这种拆分的设计意图是：

关注点分离：认证（安全握手）、流程（OTA 编排）、协议（报文编解码）各自独立演进与发版；
可裁剪性：如果上层业务（如 App 或其它小程序）已经在自己的链路中完成了 RCSP 认证，可以跳过认证库的认证步骤，避免重复认证；
版本独立性：每个库都有独立版本号（x.x.x），升级其中一个库不必连带升级其它库。

认证在整体 OTA 流程中的位置

认证发生在设备连接成功之后、RCSP 初始化与 OTA 升级开始之前，是设备通讯的"门禁"步骤：

flowchart TD
    subgraph sg_MiniProgram["微信小程序（上层业务）"]
        App["业务层 / Demo"]
        OTAWrapper["OTAWrapper（jl_ota 流程库）"]
    end

    subgraph sg_Libs["SDK 核心库（libs/ 目录）"]
        Auth["jl_auth 认证库"]
        RCSP["jl_rcsp_ota 协议库"]
    end

    subgraph sg_BLE["蓝牙通道"]
        BLE["微信 BLE API"]
        Device["杰理蓝牙设备<br/>（AC6xxx 系列）"]
    end

    App -->|"初始化 OTAWrapper"| OTAWrapper
    OTAWrapper -->|"连接成功后触发"| Auth
    Auth -->|"认证握手报文"| RCSP
    RCSP -->|"BLE 透传"| BLE
    BLE <-->|"GATT 特性读写"| Device

各节点的职责：

节点	职责	归属
业务层 / Demo	实现蓝牙扫描、连接、收发与权限申请，初始化 OTAWrapper	上层（本仓库 Demo）
OTAWrapper（jl_ota）	编排认证 → RCSP 初始化 → OTA 升级流程；按 `isUseAuth` 决定是否调用认证	jl_ota 库
jl_auth 认证库	执行 RCSP 认证握手，返回认证结果；是本文档主题	jl_auth 库
jl_rcsp_ota 协议库	RCSP 报文编解码、BLE 数据透传通道	jl_rcsp_ota 库
杰理蓝牙设备	RCSP 服务端，校验认证指令并应答	硬件（杰理 SDK）

架构说明：认证库不是独立与设备通讯的，它通过协议库复用同一条 BLE 透传通道；而是否触发认证则由流程库（OTAWrapper）依据配置决定。三者之间是"配置驱动 → 流程编排 → 协议执行"的依赖链。

认证机制与设计意图

交付形态与接入方式

jl_auth 以两个文件随 SDK 发布（见 README.md 3.3 添加依赖库）：

jl_auth_x.x.x.d.ts — TypeScript 声明文件，提供认证库的类型信息与 API 签名（供微信开发者工具智能提示）；
jl_auth_x.x.x.js — 认证库运行时代码（压缩后的 ES5 产物，兼容小程序环境）。

接入时，将 libs/ 目录下的 js 与声明文件放入工程 lib 文件夹，xxx 为版本号。由于是预编译产物，本仓库不包含其源码；声明文件是了解其公开 API 的最直接依据。

认证触发的设计：isUseAuth 开关

认证库是否参与连接流程，由上层通过 OTAWrapperOption.isUseAuth 决定。这是 SDK 提供的最核心认证相关配置，其设计意图是避免重复认证：

isUseAuth 返回 true（默认场景）：上层未做过认证，OTAWrapper 在连接设备后主动触发 RCSP 认证；
isUseAuth 返回 false：上层（如 App 或其它业务）已经完成 RCSP 认证，SDK 跳过认证步骤直接进行 RCSP 初始化，节省一次握手往返。

对应 README 中的初始化示例（README.md#L134-L138）：

const otaWrapperOption: OTAWrapperOption = {
    /**是否需要认证。 在上层已经认证过，就不需要认证。**/
    isUseAuth: () => {
        return this._BluetoothConfigure.isUseAuth
    },

设计意图：认证是安全敏感操作，SDK 将"是否认证"决策权交给上层，既保证默认安全（默认认证），又允许信任链更长的宿主（例如已与设备做过认证的 App）跳过冗余握手。

认证失败的处理语义

README 明确规定了认证失败的行为（README.md#L227-L233）：

连接设备时，会进行 RCSP 的认证和 RCSP 的初始化。当认证失败或者初始化失败时，SDK 会主动断开设备（OTAWrapperOption.disconnectDevice）。

这一语义的设计意图是快速失败（fail fast）：认证失败意味着设备通讯上下文不可信，继续停留在连接态没有意义，还可能阻塞后续扫描与重试。SDK 通过回调上层提供的 disconnectDevice 主动断开，把"善后"工作交还给上层业务（如提示用户、更新 UI 状态）。

认证状态的上报与查询

上层需要感知认证/初始化结果时，SDK 提供两条途径：

回调注册：在 OTAWrapper 上注册 RCSP 回调（OTAWrapper.registerRcspCallback），接收设备初始化状态事件；
状态查询：调用 IOTAWrapper.isRCSPInit 判断设备是否已完成 RCSP 初始化，返回 true 表示认证与初始化均成功、可安全开始 OTA。

这两条途径分别对应"事件驱动"与"轮询/事后判断"两种使用习惯，保证上层在异步 BLE 通讯环境下有确定的方式获取认证结果。

核心流程

认证与初始化时序

下图展示从设备连接成功到 OTA 可开始之间的完整时序（依据 README.md#L174-L192 的回调同步契约与 README.md#L227-L233 的认证流程说明）：

sequenceDiagram
    participant App as 小程序业务层
    participant W as OTAWrapper（jl_ota）
    participant A as jl_auth 认证库
    participant R as jl_rcsp_ota 协议库
    participant D as 杰理蓝牙设备

    App->>W: onConnectStateSuccess(dev)
    activate W
    W->>W: 读取 isUseAuth()
    W->>A: 触发 RCSP 认证
    activate A
    A->>R: 构造认证指令
    R->>D: BLE 透传认证请求
    D-->>R: 认证应答
    R-->>A: 解析认证结果
    A-->>W: 认证成功
    deactivate A

    alt 认证/初始化成功
        W->>R: RCSP 初始化
        R-->>W: 初始化完成
        W-->>App: registerRcspCallback 上报<br/>isRCSPInit() = true
        App->>W: startOTA(device, otaConfig, callback)
    else 认证失败或初始化失败
        W->>App: disconnectDevice(dev) 主动断开
        App-->>D: 断开 BLE 连接
    end
    deactivate W

认证决策分支

isUseAuth 的取值决定了认证步骤是否执行，完整的决策流程如下：

flowchart TD
    Start(["BLE 连接成功"]) --> Check{"OTAWrapperOption<br/>isUseAuth() ?"}
    Check -->|"true（默认，需认证）"| Auth["jl_auth 执行 RCSP 认证握手"]
    Check -->|"false（上层已认证）"| Init["跳过认证，直接 RCSP 初始化"]
    Auth --> Result{"认证成功 ?"}
    Result -->|"成功"| Init
    Result -->|"失败"| Disconnect["disconnectDevice(dev)<br/>主动断开连接"]
    Init --> InitResult{"RCSP 初始化成功 ?"}
    InitResult -->|"成功"| Ready["isRCSPInit() = true<br/>可调用 startOTA"]
    InitResult -->|"失败"| Disconnect
    Disconnect --> End(["流程终止，等待重新连接"])
    Ready --> End

关键点：

两个失败出口：认证失败与 RCSP 初始化失败都会触发主动断开，语义一致；
两个成功前置条件：isRCSPInit() 为 true 之前，不应调用 startOTA；
开关只影响认证步骤：isUseAuth = false 只是跳过握手，RCSP 初始化仍然是必需的。

使用示例

以下示例均提取自仓库 README.md，展示认证库在真实集成中的接入方式。

示例一：通过 OTAWrapperOption 配置认证开关

认证库本身无需直接实例化——它的启用与否由 OTAWrapperOption.isUseAuth 控制，这是推荐用法（README.md#L132-L170）：

//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)

说明：isUseAuth 在此被实现为读取 _BluetoothConfigure.isUseAuth 的闭包，意味着认证开关可以在运行时动态决定，而不必在初始化时写死——这是设计上为"上层已认证"场景预留的扩展口。

示例二：同步蓝牙连接状态，触发认证

认证由 OTAWrapper 在收到连接成功事件后自动触发，上层只需将蓝牙连接状态转发给 OTAWrapper（README.md#L174-L192）：

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)
    }
})

设计意图：认证流程完全封装在 OTAWrapper 内部，上层只需把"连接成功"这个事实同步进来，认证的触发、执行、结果判断均无需业务感知。这也是 README 强调"通常只需要使用 OTAWrapper 即可完成 OTA 功能"的原因。

示例三：认证通过后开始 OTA

认证与 RCSP 初始化成功（isRCSPInit() 为 true）后，方可发起升级（README.md#L237-L272）：

/*--- 开始执行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)

配置选项

认证相关配置通过 OTAWrapperOption 传入 OTAWrapper，其中直接影响认证库行为的关键项如下：

选项	类型	默认行为	说明
`isUseAuth`	`() => boolean`	需显式实现	返回 `true` 时连接后执行 RCSP 认证；返回 `false` 表示上层已认证，跳过认证直接初始化
`disconnectDevice`	`(device: BluetoothDevice) => void`	需显式实现	认证失败或 RCSP 初始化失败时，SDK 主动断开设备所调用的回调
`sendData`	`(device: BluetoothDevice, data: Uint8Array) => void`	非必须	当内部创建并管理 `RCSPImpl`（未实现 `getRCSPImpl`）且需要认证时（`isUseAuth` 返回 `true`），必须实现，用于 BLE 发数
`getRCSPImpl`	`(device) => RCSPProtocol.RcspImpl \| undefined`	非必须	上层自行管理 `RCSPImpl` 时（如使用 jl-rcsp-op）实现；不实现则由内部创建管理

其中 sendData 与 isUseAuth 存在联动约束（README.md#L155-L162）：只要认证步骤需要执行且 RCSPImpl 由 SDK 内部管理，就必须提供 sendData——因为认证握手报文需要通过上层实现的 BLE 发送通道下行。

API 契约（认证相关）

以下为 README 中明确提到的认证相关 API/类型，完整签名请以 SDK 附带的 jl_auth_x.x.x.d.ts 与 jl_ota_x.x.x.d.ts 为准：

API / 类型	所在库	语义
`OTAWrapperOption.isUseAuth(): boolean`	jl_ota（配置项）	是否需要执行 RCSP 认证
`OTAWrapper.onConnectStateSuccess(dev)`	jl_ota	连接成功入口，触发认证流程
`OTAWrapper.registerRcspCallback(callback)`	jl_ota	注册 RCSP 回调，接收设备初始化状态
`IOTAWrapper.isRCSPInit(): boolean`	jl_ota	查询设备是否已完成 RCSP 初始化（认证+初始化成功）
`OTAWrapper.startOTA(device, otaConfig, onUpgradeCallback)`	jl_ota	认证就绪后开始 OTA 升级
`OTAWrapperOption.disconnectDevice(device)`	jl_ota（配置项）	认证/初始化失败时 SDK 主动断开的回调

诚实声明：jl_auth 库自身的内部 API（如认证握手函数、结果回调类型）未在本仓库源码中公开，以上契约均为 README 中可验证的外部接口。如需认证库的完整函数签名，请查阅 SDK 发布包中的 jl_auth_x.x.x.d.ts 声明文件。

失败模式、边界情况与并发注意

基于 README 可验证的语义，认证环节存在以下需要关注的行为：

场景	行为	建议
认证失败	OTAWrapper 调用 `disconnectDevice` 主动断开	上层在断开回调中提示用户"认证失败"，并复位 `isRCSPInit` 状态
RCSP 初始化失败	与认证失败同等处理，主动断开	与认证失败共用同一失败出口，按业务统一处理
上层已认证（`isUseAuth=false`）	跳过认证，直接初始化	确保上层确实完成过同一设备的认证，否则设备可能拒绝后续指令
`sendData` 未实现且需要认证	认证报文无法下发，流程无法推进	按 README 约束实现 `sendData`，或通过 `getRCSPImpl` 让上层管理 `RCSPImpl`
并发/时序	BLE 数据到达是异步事件；认证握手、初始化、数据收发共享同一条透传通道	认证未完成前不应调用 `startOTA`；依赖 `isRCSPInit()` 或 RCSP 回调作为就绪信号，避免竞态
断连重连	每次新连接都会重新走认证/初始化判定	重连成功后需再次同步 `onConnectStateSuccess`，并重新确认 `isRCSPInit()`

性能与运维注意

握手开销：认证 + 初始化是 BLE 链路上的一次性握手，isUseAuth=false 可省去认证往返，缩短连接到可升级的耗时——对连接频繁的应用是有效的优化手段，但需以安全性为前提。
日志排查：README 调试章节（README.md#L288-L293）指出 SDK 提供详细日志输出，可通过日志查看 OTA 连接状态与数据交互；认证失败排查时可结合 vConsole 观察连接阶段日志，定位是认证报文未下发还是应答校验失败。
版本配套：三个库独立发版，升级 jl_auth 时建议同步核对 jl_ota / jl_rcsp_ota 的兼容版本（见 README 版本历史，如 V2.1.1 修复 iOS16 单备份回连与 AC695 升级问题）。

扩展点

认证开关动态化：isUseAuth 是闭包而非常量，上层可在运行时根据设备型号、业务策略或安全等级动态返回，实现认证策略的灵活控制。
RCSPImpl 托管切换：通过 getRCSPImpl 可以让上层接管 RCSPImpl 生命周期（如复用 jl-rcsp-op 的既有实例），认证与后续指令可复用同一会话，避免重复建链。
断开策略定制：认证失败后的"善后"（提示文案、重试逻辑、UI 状态）全部通过 disconnectDevice 回调交由上层实现，SDK 不绑定任何具体交互。

源码可用性说明

需要特别说明的是：本仓库（WeChat-Mini-Program-OTA）是 SDK 的集成说明/示例仓库，不包含 jl_auth 的实现源码。仓库根目录仅包含 README.md、README_en.md 与 LICENSE；README 中描述的 code/（参考 Demo 源码工程）与 libs/（核心库）目录属于 SDK 发布包结构，并未提交到本仓库。

因此，本页面记录的均为外部可验证契约（交付形态、集成方式、配置项、时序与失败语义），而非内部实现细节。若需要：

认证库源码/完整 API：请获取 SDK 发布包（tag 发布版本），查阅 libs/ 下的 jl_auth_x.x.x.js 与 jl_auth_x.x.x.d.ts；
更深入的协议说明：请参见杰理 OTA SDK 官方文档中心与 SDK 调试说明；
问题反馈：通过 GitHub Issues 提交。

README.md（中文，本页主要依据）
README_en.md（英文版）
LICENSE（Apache 2.0）
兄弟能力页面：jl_ota（OTA 流程库）、jl_rcsp_ota（RCSP-OTA 协议库） —— 认证库与二者共同构成杰理 OTA SDK 的三层核心库
杰理 OTA SDK 文档中心
SDK 调试说明
版本历史（发布记录）