版本补丁与兼容性修复

本页介绍 AW31N BLE SDK 的版本补丁发布机制与兼容性修复体系，包括 patch_release/ 补丁目录结构、补丁应用方式、SDK 版本标识（SDK_VERSION_CFG_DEFINE）、RCSP 协议版本属性、TestBox 版本信息以及 PNP 设备版本号等与版本管理、跨版本兼容相关的实现细节。

Purpose and Scope

本页覆盖 AW31N BLE SDK 中与版本补丁和兼容性修复相关的完整机制：

• patch_release/ 补丁发布目录的组织方式与命名规范（主题 + 日期 + 版本号）；
• 补丁包如何以「SDK 目录树覆盖」形式应用到工程中；
• SDK 在启动、RCSP 协议、TestBox 测试盒、BLE HID PNP 服务等处的版本标识实现；
• 与版本/兼容性相关的典型修复方向（开机、低功耗、VM 兼容性）。

不在本页范围：具体功能模块（如低功耗管理、VM 存储、开机流程）的实现细节属于各自模块页面；SDK 版本历史发布记录由官方文档中心维护（见 Related Links）。

Overview

嵌入式 BLE SDK 的固件发布天然具有「多客户、多方案、多版本并存」的特点：同一 SDK 主分支下可能有大量量产项目，每个项目锁定在不同版本上。当上游修复了某个问题（如低功耗异常、VM 数据不兼容、开机时序问题）后，无法要求所有客户立即升级到最新主线，因此 SDK 采用增量补丁（update patch）机制：官方按「修复主题 + 发布日期」组织补丁包，补丁包内以完整 SDK 目录树镜像的方式给出需要替换/新增的文件，客户通过文件级覆盖即可将修复合入自己的工程，而不必整体迁移版本。

同时，SDK 内部布设了多层版本标识与兼容性探测通道：

1. 启动日志：init.c 打印 SDK_VERSION_CFG_DEFINE 与 SDK_VERSION_DATE_DEFINE，用于确认固件实际编译的 SDK 版本；
2. RCSP 协议：rcsp_bluetooth.c 定义 ATTR_TYPE_PROTOCOL_VERSION、ATTR_TYPE_DEV_VERSION、ATTR_TYPE_UBOOT_VERSION、ATTR_TYPE_DOUBLE_PARITION 等属性，使 App/上位机可以读取设备端 SDK/协议/uboot 版本并据此做兼容分支；
3. TestBox：btctrler_task.h 中的 TESTBOX_INFO_SDK_VERSION 允许产测工具读取 SDK 版本；
4. BLE PNP 服务：HID 例程通过 PNP_PID_VERSION 上报设备固件版本号。

这些通道共同构成「补丁发布 → 版本识别 → 兼容分支处理」的完整闭环。

Architecture

flowchart TD
    subgraph sg_Upstream["官方补丁发布侧"]
        PATCH["patch_release/<br/>AW31N_主题_日期/"]
        PATCH --> PKG["AW31N_sdk_v1.1.0_update_patch/<br/>sdk/ 目录树镜像"]
        PKG --> F1["rcsp_bluetooth.c"]
        PKG --> F2["init.c"]
        PKG --> F3["ble_hogp.c"]
    end

    subgraph sg_Customer["客户工程侧"]
        APP["apps/app/bsp/..."]
        APP -->|"文件级覆盖合并"| F1
        APP -->|"文件级覆盖合并"| F2
        APP -->|"文件级覆盖合并"| F3
    end

    subgraph sg_Identify["版本标识与兼容性通道"]
        LOG["init.c 启动日志<br/>SDK_VERSION_CFG_DEFINE"]
        RCSP["RCSP 属性<br/>PROTOCOL/DEV/UBOOT/DOUBLE_PARITION"]
        TB["TestBox<br/>TESTBOX_INFO_SDK_VERSION"]
        PNP["PNP 服务<br/>PNP_PID_VERSION"]
    end

    APP --> LOG
    APP --> RCSP
    APP --> TB
    APP --> PNP

架构说明：补丁发布侧以「主题 + 日期」命名目录（本仓库示例为 AW31N_开机&低功耗&VM兼容性修复说明_20250102），其内部 sdk/ 镜像与主线 SDK 相同目录结构（apps/app/bsp/...），客户只需将补丁中列出的文件覆盖到同名路径即可合入修复。合入后，固件内的四类版本标识通道（启动日志、RCSP、TestBox、PNP）使外部工具与 App 能够识别固件版本，从而在协议协商、产测校验、设备发现等场景执行兼容性分支。

本页补丁目录结构证据来自 patch_release 目录，镜像文件与主线对应关系见后续章节。

补丁发布机制详解

补丁目录结构与命名规范

仓库根目录下的 patch_release/ 是官方补丁的唯一发布入口。当前仓库中可确认的补丁示例为：

patch_release/
└── AW31N_开机&低功耗&VM兼容性修复说明_20250102/
    └── AW31N_sdk_v1.1.0_update_patch/
        └── sdk/
            ├── apps/app/bsp/common/third_party_profile/jieli/JL_rcsp/rcsp_bluetooth.c
            ├── apps/app/bsp/start/init.c
            └── apps/demo/hid/modules/bt/ble_hogp.c

目录命名遵循三段式约定，语义自解释：

内层目录 AW31N_sdk_v1.1.0_update_patch 进一步标明了补丁基准版本（v1.1.0）与补丁类型（update_patch），即该补丁是基于 v1.1.0 SDK 的增量修复。

补丁应用方式：目录树覆盖

补丁包内 sdk/ 子树与主线 SDK 的目录结构完全一致（这是设计意图：让客户无需理解依赖关系，直接按路径覆盖即可）：

• sdk/apps/app/bsp/start/init.c ↔ 主线 apps/app/bsp/start/init.c
• sdk/apps/app/bsp/common/third_party_profile/jieli/JL_rcsp/rcsp_bluetooth.c ↔ 主线 apps/app/bsp/common/third_party_profile/jieli/JL_rcsp/rcsp_bluetooth.c
• sdk/apps/demo/hid/modules/bt/ble_hogp.c ↔ 主线 apps/demo/hid/modules/bt/ble_hogp.c

应用流程：将补丁内文件复制到客户工程的同名相对路径，替换原文件后重新编译即可。由于是文件级覆盖，客户工程中未涉及的文件保持不变，降低了整体迁移风险——这正是「补丁」而非「升级」的核心取舍：以文件粒度合入修复，而非以版本粒度整体迁移。

版本标识实现剖析

启动日志中的 SDK 版本

apps/app/bsp/start/init.c 在系统初始化早期打印 SDK 版本信息，是定位「固件到底跑在哪个版本」的第一现场：

log_info(">>>AW31N_SDK INFO: %x,%d,time:%s,%s<<<", SDK_VERSION_CFG_DEFINE, SDK_VERSION_DATE_DEFINE,
         __DATE__, __TIME__);

Source: init.c

设计意图：

• SDK_VERSION_CFG_DEFINE 以十六进制打印编译期配置的 SDK 版本号（%x），用于精确区分小版本；
• SDK_VERSION_DATE_DEFINE 以十进制打印版本日期；
• __DATE__ / __TIME__ 是编译器内置宏，记录实际编译时刻。

四者配合可以快速回答两个关键问题：固件基于哪个 SDK 版本编译？编译于何时？ 当客户上报问题时，该日志是官方判断「是否已合入某补丁」的直接依据。

RCSP 协议版本属性

apps/app/bsp/common/third_party_profile/jieli/JL_rcsp/rcsp_bluetooth.c 定义了 RCSP（杰理私有控制协议）的属性类型枚举，其中多个属性专门用于版本与兼容性协商：

#define ATTR_TYPE_PROTOCOL_VERSION	0
#define ATTR_TYPE_SYS_INFO			1
#define ATTR_TYPE_FUNCTION_INFO		4
#define ATTR_TYPE_DEV_VERSION		5
#define ATTR_TYPE_SDK_TYPE			6
#define ATTR_TYPE_UBOOT_VERSION		7
#define ATTR_TYPE_DOUBLE_PARITION	8

Source: rcsp_bluetooth.c

各属性在兼容性场景中的作用：

设计意图：RCSP 是设备与 App/上位机之间的控制通道，新旧固件混用时协议行为可能变化，因此协议层把「版本」作为一等属性暴露，让对端在发起任何可能不兼容的操作前先读取版本并走兼容分支。

TestBox 测试盒版本信息

apps/include_lib/bt_controller_include/btctrler_task.h 的 TestBox 信息枚举中包含 SDK 版本项：

TESTBOX_INFO_SDK_VERSION,		//(u8 *(*handle)(u8 *len))

Source: btctrler_task.h

该枚举位于 TESTBOX_INFO_BURN_CODE 之后，注释表明其 handler 形态为 u8 *(*handle)(u8 *len)——即返回一个长度前缀的字节串。产测（生产测试）工具通过 TestBox 通道读取 SDK 版本，用于产线版本校验：确保烧录的固件版本与工单一致，防止错版出货。

BLE PNP 服务版本号

HID 例程（apps/demo/hid/modules/bt/ble_hogp.c）在 PNP（Device Identification Profile）服务中上报产品 ID 与版本：

#define  PNP_PID          0x022C //
#define  PNP_PID_VERSION  0x011b //1.1.11

Source: ble_hogp.c

PNP_PID_VERSION 注释 1.1.11 表明版本编码方式为 BCD 风格（0x011b → 1.1.11）。PC/手机操作系统与驱动会读取 PNP 信息识别设备，固件版本号在此暴露，便于驱动侧做兼容分支；同时该值也用于设备管理类工具显示「固件版本」。

核心流程

补丁生命周期

flowchart LR
    A["上游发现缺陷<br/>（低功耗/VM/开机）"] --> B["修复并验证"]
    B --> C["按主题+日期组织补丁包<br/>patch_release/AW31N_主题_日期/"]
    C --> D["客户下载补丁"]
    D --> E["按 sdk/ 镜像路径覆盖文件"]
    E --> F["重新编译烧录"]
    F --> G["init.c 打印新 SDK 版本"]
    G --> H{"版本核对"}
    H -->|"日志版本正确"| I["量产/发布"]
    H -->|"版本不符"| J["检查覆盖路径是否遗漏"]
    J --> E

版本识别与兼容分支时序

以「App 连接设备后先协商再执行操作」为例，展示四条版本通道的协作时序：

sequenceDiagram
    participant APP as App/上位机
    participant DEV as 设备(固件)
    participant RCSP as RCSP 协议层
    participant LOG as 启动日志
    participant TB as TestBox 通道

    Note over DEV: 上电
    DEV->>LOG: log_info(SDK_VERSION_CFG_DEFINE, ...)
    Note over LOG: 产线/研发核对版本

    APP->>RCSP: 读取 ATTR_TYPE_PROTOCOL_VERSION
    RCSP-->>APP: 协议版本号
    APP->>RCSP: 读取 ATTR_TYPE_DEV_VERSION / UBOOT_VERSION
    RCSP-->>APP: 设备/uboot 版本号
    Note over APP,RCSP: App 依据版本走兼容分支

    TB->>DEV: 产测请求 TESTBOX_INFO_SDK_VERSION
    DEV-->>TB: SDK 版本字节串
    Note over TB: 产线版本校验

兼容性修复方向（以 v1.1.0 补丁为例）

本仓库 patch_release/ 中可确认的补丁覆盖三个问题域，其兼容性风险点如下：

1. 开机（Boot）兼容性：不同批次 Flash/PMU 方案对初始化时序敏感。补丁通过调整 init.c 等启动路径上的初始化顺序/等待条件，保证旧方案硬件在新固件下正常启动——风险在于改动启动时序可能影响低功耗唤醒路径，因此该补丁将「开机」与「低功耗」打包发布，说明两者在实现上耦合（唤醒即启动的一种形态）。
2. 低功耗（Low Power）兼容性：BLE 广播/连接间隔与休眠策略的配合。修复目标通常是在不破坏连接稳定性的前提下降低功耗，涉及 rcsp_bluetooth.c 所在协议栈与系统电源管理的交互。
3. VM 兼容性：VM（虚拟内存/参数存储）的数据布局在版本间变更时，旧版本写入的参数区可能无法被新版本解析。这是最容易引发量产事故的一类兼容性问题（升级后参数丢失或错位），补丁需保证读写侧对旧布局的容忍或提供迁移逻辑。

说明：以上三个方向依据补丁目录名 AW31N_开机&低功耗&VM兼容性修复说明_20250102 归纳；各方向内部的具体代码改动细节未在本仓库主线中展开（补丁以覆盖文件形式发布），如需精确 diff，请对比补丁包内 sdk/ 文件与主线同名文件。

使用示例

核对固件 SDK 版本（研发/FAE 侧）

固件上电后从串口日志中搜索：

>>>AW31N_SDK INFO: <SDK_VERSION_CFG_DEFINE十六进制>,<SDK_VERSION_DATE_DEFINE十进制>,time:<编译日期>,<编译时间><<<

将十六进制版本号与补丁说明中标注的基准版本（如 v1.1.0）比对，即可确认当前固件是否已合入对应补丁。日志打印逻辑见 init.c。

应用补丁（客户侧）

1. 解压 AW31N_sdk_v1.1.0_update_patch；
2. 将 sdk/ 下的文件逐个覆盖到客户工程同名路径：
   • apps/app/bsp/start/init.c
   • apps/app/bsp/common/third_party_profile/jieli/JL_rcsp/rcsp_bluetooth.c
   • apps/demo/hid/modules/bt/ble_hogp.c
3. 全量重编译，确认启动日志中 SDK_VERSION_CFG_DEFINE 与补丁基准版本一致；
4. 执行开机、低功耗、VM 读写回归测试。

扩展：新增一个版本相关 RCSP 属性

在 rcsp_bluetooth.c 的属性枚举中追加：

#define	ATTR_TYPE_APP_VERSION		9	// 新增：App 版本协商

并仿照现有属性的 handler 注册方式实现读取/设置回调，即可让对端通过 RCSP 读取该版本信息。注意：新增属性属于协议扩展，需要与 App 端同步发布，否则旧 App 无法识别该属性号——这是协议兼容性的经典约束。

配置选项

版本标识通道相关的可配置项（均为编译期宏，由 SDK 构建配置注入）：

注意：PNP_PID / PNP_PID_VERSION 位于 HID 例程 ble_hogp.c，量产项目需按实际产品分配值，且版本号应在每次发布补丁时递增，否则无法区分是否已合入修复。

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

补丁覆盖遗漏

• 症状：固件行为与补丁说明不符，启动日志版本号与补丁基准版本不一致。
• 根因：补丁包内文件未全部覆盖（尤其客户工程做了本地修改时，diff 合并易遗漏）。
• 规避：以启动日志中的 SDK_VERSION_CFG_DEFINE 为「是否合入」的判定依据，而不是凭记忆。

VM 兼容性破坏（最高风险）

• 场景：旧版本固件写入的 VM 参数区布局，与新版本解析逻辑不兼容。
• 后果：升级后参数丢失、错位，甚至读取越界导致异常复位。
• 规避：补丁必须自带旧布局的读写兼容（按版本号分支解析）或迁移逻辑；量产前必须做「旧版本写入 → 新版本读取」的专项回归。

RCSP 协议版本协商失败

• 场景：设备固件为旧版，App 为新版（或反之）。
• 后果：App 按新协议发送指令，设备无法解析，出现无响应或误操作。
• 规避：App 连接后先读 ATTR_TYPE_PROTOCOL_VERSION，严格按协议版本走分支；协议层新增属性（如示例中的 ATTR_TYPE_APP_VERSION）必须新旧共存。

开机与低功耗的耦合

• 场景：补丁调整开机初始化时序，间接改变休眠唤醒路径的时序。
• 后果：低功耗唤醒异常、RTC 漂移等偶发问题。
• 规避：本补丁将「开机」与「低功耗」同包发布正因二者耦合；客户验证时需覆盖「开机 → 休眠 → 唤醒」全链路。

并发/时序注意

嵌入式固件中版本读取路径多为「查询-应答」式（RCSP/TestBox），一般不存在多线程竞争；但要注意：

• 启动日志打印发生在 init.c 早期，此时部分外设/协议栈尚未就绪，不要在版本打印处挂接依赖协议栈的逻辑；
• TestBox 与 RCSP 可能同时被产测工具访问，若同一版本缓冲区被两个通道共享，需按现有框架的互斥约定使用，避免交叉改写。

性能与运维注意事项

• 日志开销：init.c 的版本打印仅启动时一次，成本可忽略，建议保留；量产固件如需裁剪日志，可通过日志等级开关关闭，但会失去线上版本追溯能力。
• 版本号维护纪律：每次发布补丁必须同步递增相关版本标识（SDK 版本宏、PNP_PID_VERSION、RCSP 设备版本），这是多客户并行维护的基础设施。
• 补丁留存：patch_release/ 目录按日期归档，建议客户建立「已应用补丁清单」，与工程代码一同入库，便于后续 FAE 定位问题。

扩展点

1. 新增版本协商属性：在 rcsp_bluetooth.c 的 ATTR_TYPE_* 枚举中追加属性号并注册 handler，实现自定义版本/能力协商（见上文示例）。
2. 自定义 TestBox 版本指令：仿照 TESTBOX_INFO_SDK_VERSION 在 TestBox 信息枚举中扩展产测需要的版本类信息（如 uboot 版本、SDK 类型）。
3. VM 迁移钩子：若 SDK 提供 VM 版本字段，可在补丁中加入「检测旧版本号 → 迁移数据 → 更新版本号」的迁移逻辑，这是 VM 兼容性修复的推荐模式。
4. 补丁基准版本声明：补丁目录名（如 AW31N_sdk_v1.1.0_update_patch）即扩展契约——后续自动化脚本可解析该命名，校验客户工程版本与补丁基准是否匹配。

Related Links

• SDK 版本历史（官方文档中心） — 官方维护的版本发布记录，README 中也引用了该链接（见 README.md）
• init.c — SDK 版本日志
• rcsp_bluetooth.c — RCSP 版本属性定义
• btctrler_task.h — TestBox SDK 版本信息
• ble_hogp.c — PNP 设备版本号
• 补丁包镜像对照：patch_release/AW31N_开机&低功耗&VM兼容性修复说明_20250102/AW31N_sdk_v1.1.0_update_patch/sdk/apps/app/bsp/start/init.c（链接）

相关模块页面提示：开机流程、低功耗管理与 VM 存储的实现细节请参阅各自模块文档；本页仅从「版本补丁与兼容性修复」视角描述其发布与标识机制。