版本升级补丁链 (v1.1.0 → v1.4.0)

本页面向 AW30N BLE SDK 的用户完整介绍从 v1.1.0 到 v1.4.0 的版本升级补丁链：补丁包的目录组织、每个补丁的用途与内容、升级路径的衔接方式，以及如何将补丁正确合入 SDK 工程。

Purpose and Scope

本页面覆盖 fw-AW30N_BLE_SDK 仓库根目录下 补丁包/ 目录所承载的版本升级补丁链，即 SDK 从 v1.1.0 逐步升级到 v1.4.0 过程中官方提供的全部补丁包及其使用方式。内容包括：

• 补丁链的整体结构与各补丁包的定位（v1.2.0 裁剪补丁、v1.2.0→v1.3.0 蓝牙补丁、v1.3.4→v1.4.0 蓝牙相关补丁）；
• 补丁包与正式 SDK 源码（sdk/ 目录）之间的目录对应关系，以及补丁合并时的文件覆盖规则；
• 升级后的固件烧录/OTA 通道（U 盘、SD 卡、测试盒串口、测试盒蓝牙、手机 BLE OTA、手机 USB）与工具链要求；
• 补丁包内关键头文件（如 btctrler_task.h）中与版本上报、测试盒交互相关的接口定义。

以下内容属于兄弟页面，不在本页展开：SDK 整体架构与工程结构（见 SDK 工程结构页）、BLE 协议栈与 GATT 服务细节（见 BLE 协议栈页）、音频解码/编码与音效（见音频子系统页）。本页只关注"版本如何升级、补丁如何应用"这一条主线。

Overview

AW30N 系列是杰理科技面向 BLE 遥控器、BLE 对讲机、BLE Dongle、小音箱、语音玩具等场景推出的单模 BLE 5.4 32bit DSP MCU。SDK 以 Release 形态发布：仓库包含正式 SDK 源码（sdk/ 目录）与补丁包（补丁包/ 目录），正式源码配合按命名规则发布的 lib.a 库文件编译，而补丁包用于在已发布版本基础上进行定向修复或功能裁剪，无需等待下一个完整 Release。

补丁链存在的根本原因在于：BLE 协议栈与控制器相关的缺陷修复、功能增强（例如蓝牙连接稳定性、OTA 流程优化）往往以增量补丁形式先行交付，使已量产的客户可以在不改动整体 SDK 结构的前提下完成升级。同时，针对小容量 Flash 的芯片（如 256KB 限制场景），官方提供裁剪补丁，将 SDK 裁减到目标容量以内。

根据仓库中已验证的补丁包，本页涉及的补丁链为：

说明：仓库根目录另有 doc/AW30N_SDK_发布版本信息.pdf 作为官方版本发布记录的权威来源；本页描述的补丁链依据仓库目录结构与补丁包内文件核实，v1.1.0 与 v1.3.4 之间的中间衔接以各补丁包目录命名与 include_lib 目录结构为准。补丁包内文件为二进制库文件与头文件的混合，部分实现细节（如蓝牙协议栈内部行为）不在源码可见范围内。

Architecture

补丁链的整体架构如下：正式 SDK 源码与补丁包并存于同一仓库，补丁包通过"目录对齐 + 文件覆盖"的方式合入 SDK。

flowchart TD
    subgraph sg_Repo["fw-AW30N_BLE_SDK 仓库"]
        subgraph sg_Official["正式 Release 源码"]
            SDK_ROOT["sdk/ 目录<br/>（app / include_lib / 库文件 lib.a）"]
        end
        subgraph sg_Patches["补丁包/ 目录"]
            P12["AW30N_v1.2.0_SDK裁剪到256KB以内的补丁包<br/>_20240815"]
            P23["v1.2.0升级至v1.3.0蓝牙补丁"]
            P34["v1.3.4升级至v1.4.0蓝牙相关补丁"]
        end
        DOC["doc/AW30N_SDK_发布版本信息.pdf<br/>（版本发布记录）"]
    end

    P12 -->|"按目录对齐覆盖<br/>include_lib/bt_controller_include 等"| SDK_ROOT
    P23 -->|"按目录对齐覆盖<br/>include_lib/bt_controller_include 等"| SDK_ROOT
    P34 -->|"按目录对齐覆盖<br/>apps/include_lib/bt_controller_include 等"| SDK_ROOT
    DOC -.->|"权威版本历史"| P12
    DOC -.->|"权威版本历史"| P23
    DOC -.->|"权威版本历史"| P34
    SDK_ROOT -->|"编译 + 烧录/OTA 通道"| FW["固件（烧录/OTA 交付）"]

架构说明：

• sdk/ 正式源码是升级的"基准"，所有补丁都以某个已发布版本为基线制作，因此补丁目录名直接声明其基线版本（如 AW30N_v1.2.0_...）。
• 补丁包目录名即升级路径：v1.2.0升级至v1.3.0蓝牙补丁 明确表达"以 v1.2.0 为基线，升级到 v1.3.0 蓝牙功能"；v1.3.4升级至v1.4.0蓝牙相关补丁 同理。这构成了补丁链的"可追溯性"设计——每个补丁自描述其适用起点。
• 补丁通过目录对齐覆盖合入：补丁包内目录结构（如 include_lib/bt_controller_include/、apps/include_lib/bt_controller_include/）与 SDK 正式源码的目录结构保持一致，合入时直接按路径覆盖对应文件。这一设计避免了复杂的差异合并工具，任何支持文件覆盖的复制操作（如 Windows 资源管理器、cp -rf、Git 检出）即可完成打补丁。
• doc/ 下的版本信息 PDF 是补丁链的权威说明文档，仓库 README 在首屏即将其列为 SDK 版本历史的入口。

补丁包结构与关键文件

补丁包目录组织

仓库根目录 补丁包/ 下按"版本-用途-日期"的命名规范组织每个补丁包，形成一条可追踪的升级链：

命名规范解读（设计意图）：

• 版本前缀：AW30N_v1.2.0_ 表示该补丁面向 AW30N 系列、基线版本为 v1.2.0；
• 用途后缀：SDK裁剪到256KB以内 明确该补丁的容量目标；蓝牙补丁/蓝牙相关补丁 表明其作用域是蓝牙子系统；
• 日期后缀：_20240815 是补丁发布日期，用于区分同一版本多次发布的补丁（例如 v1.3.4 与 v1.4.0 之间的补丁可能多次迭代）。

补丁包内部结构与 SDK 的对应关系

以已验证的补丁包文件路径为证据，三个补丁包均包含与 SDK 正式源码对应的 include_lib/bt_controller_include/ 目录，而 v1.3.4→v1.4.0 补丁还使用了 apps/include_lib/bt_controller_include/ 这一更深的路径：

补丁包/
├── AW30N_v1.2.0_SDK裁剪到256KB以内的补丁包_20240815/
│   └── include_lib/
│       └── bt_controller_include/
│           └── btctrler_task.h          # 蓝牙控制器任务/测试盒信息接口头文件
├── v1.2.0升级至v1.3.0蓝牙补丁/
│   └── include_lib/
│       └── bt_controller_include/
│           └── btctrler_task.h
└── v1.3.4升级至v1.4.0蓝牙相关补丁/
    └── apps/
        └── include_lib/
            └── bt_controller_include/
                └── btctrler_task.h

说明：以上目录树依据 Grep 检索到的文件路径整理，补丁包内还包含对应的二进制库文件（lib.a 系列），受工具读取限制未逐一列出；apps/ 前缀的出现表明 v1.3.4→v1.4.0 补丁同时触及应用层（app 工程）与控制器层头文件，合入时需覆盖两处同名文件。

这一"路径对齐"设计的关键收益：

1. 合入零成本：补丁包内的每个文件在 SDK 中都有同名同路径的对应文件，使用 cp -rf 补丁包/... sdk/ 即可完成覆盖，不需要三方合并工具；
2. 可回溯：每个补丁包的目录名自带基线版本与目标版本，任何工程师拿到补丁包即可判断当前工程是否适用；
3. 可叠加：补丁按版本顺序应用（v1.2.0 裁剪 → v1.2.0→v1.3.0 → v1.3.4→v1.4.0），后一个补丁覆盖前一个补丁修改过的文件，形成线性升级链。

关键头文件：btctrler_task.h 与版本上报接口

btctrler_task.h 是蓝牙控制器任务接口头文件，位于蓝牙控制器层（bt_controller_include），同时出现在正式 SDK 与全部三个补丁包中，是补丁覆盖的核心文件之一。其中定义了测试盒（TestBox）与 SDK 交互的信息枚举，包含版本上报接口：

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

Source: btctrler_task.h（补丁包 v1.3.4→v1.4.0）

该枚举位于 TESTBOX_INFO 信息族中，紧随 TESTBOX_INFO_BURN_CODE（烧录码信息）之后，其回调签名 u8 *(*handle)(u8 *len) 表示：通过函数指针返回一段字节数据（固件版本字符串）及其长度。这是"测试盒蓝牙升级/串口升级"通道读取 SDK 版本、校验补丁与固件匹配度的底层依据。

设计意图：将版本信息作为测试盒可查询的标准信息项，使得产线工具（无线测试盒）在升级前即可读取目标固件版本，避免因补丁未合入、版本不匹配导致的升级失败；这也解释了为何每个补丁包都必须同步更新该头文件——版本字符串随 SDK 版本变化，接口枚举随之演进。

补丁内容对 SDK 版本上报的影响

三个补丁包都携带 btctrler_task.h，意味着每次升级都会修改蓝牙控制器层的测试盒信息接口。由于补丁是"文件级覆盖"，应用补丁后：

• 头文件中的 TESTBOX_INFO_SDK_VERSION 所对应的版本字符串（由配套库文件提供）变为新版本；
• 若工程仅更新了头文件而未更新配套的 lib.a 库文件，可能导致接口枚举与库内实现错位——这是补丁应用中最常见的失败模式（详见"Failure Modes"章节）。

升级路径与核心流程

补丁链的升级流程遵循"确认基线 → 按序合入 → 重编译 → 烧录/OTA"的线性模型：

flowchart LR
    A["确认当前 SDK 基线版本"] --> B{"基线 = v1.2.0?"}
    B -->|"是"| C["应用 v1.2.0 裁剪补丁<br/>（可选，小 Flash 场景）"]
    B -->|"否"| D["查找对应基线的补丁"]
    C --> E["应用 v1.2.0→v1.3.0 蓝牙补丁"]
    D --> E
    E --> F{"基线 = v1.3.4?"}
    F -->|"是"| G["应用 v1.3.4→v1.4.0 蓝牙相关补丁"]
    F -->|"否"| H["按版本链继续<br/>直到目标版本"]
    G --> I["重编译固件<br/>（Code::Blocks / Makefile）"]
    H --> I
    I --> J["烧录或 OTA 交付"]

流程要点：

1. 基线确认：先读取工程当前的 SDK 版本（可通过测试盒查询 TESTBOX_INFO_SDK_VERSION，或查看工程版本宏/发布记录 PDF），选择匹配的补丁；
2. 按序合入：补丁必须按版本顺序应用，不能跳级——v1.3.4→v1.4.0 补丁假定基线为 v1.3.4，若从 v1.2.0 直接应用会因中间文件差异导致编译失败或行为异常；
3. 重编译：合入补丁后必须重新编译（Windows 下 Code::Blocks IDE、Linux 下 Makefile 命令行，依赖 /opt/jieli/pi32/bin/clang 交叉工具链）；
4. 交付：编译产物通过 README 列出的升级通道交付——U 盘/SD 卡设备升级、测试盒串口升级、测试盒蓝牙升级、手机蓝牙 OTA 升级、手机 USB 升级。

升级执行时序

以下时序图描述一次完整的"应用补丁 → 编译 → 产线升级"过程，覆盖开发环境与产线测试盒两条路径：

sequenceDiagram
    participant Dev as 开发工程师
    participant SDK as SDK 工程 (sdk/)
    participant TC as 编译工具链 (clang)
    participant TB as 无线测试盒
    participant Dev2 as 目标设备 (AW30N)

    Dev->>SDK: 确认基线版本 (v1.2.0 / v1.3.4)
    Dev->>SDK: 按目录对齐覆盖补丁文件 (btctrler_task.h 等)
    SDK->>TC: 重新编译固件 (Code::Blocks / Makefile)
    TC-->>Dev: 生成新版本固件 (含新 TESTBOX_INFO_SDK_VERSION)
    Dev->>TB: 通过测试盒读取设备版本
    TB->>Dev2: 查询 TESTBOX_INFO_SDK_VERSION
    Dev2-->>TB: 返回版本字符串 + 长度 (u8 *len)
    TB-->>Dev: 显示当前固件版本
    Dev->>TB: 校验版本与补丁链匹配
    TB->>Dev2: 串口/蓝牙升级新固件
    Dev2-->>TB: 升级完成
    TB-->>Dev: 上报升级结果

时序中的关键交互点：

• 版本读取：测试盒通过 TESTBOX_INFO_SDK_VERSION 枚举对应的回调（u8 *(*handle)(u8 *len)）获取版本字符串及其长度，这是补丁链中"版本可验证性"的落地实现；
• 覆盖合入：开发工程师仅需将补丁包目录与 sdk/ 目录对齐后覆盖，无需手工编辑代码；
• 升级通道：README 声明 SDK 支持"测试盒串口升级、测试盒蓝牙升级、手机蓝牙 OTA、手机 USB、U 盘/SD 卡设备升级"五种通道，产线通常优先使用测试盒通道以兼顾版本校验与批量生产。

配置选项

补丁链本身不引入运行时配置项（补丁是编译期合入的源码/库文件），但与升级链相关的工具链与通道配置如下（依据 README.md 整理）：

工具链接与详细使用方法请直接查阅 README.md；download_sh.c 的 Linux 适配属于平台移植事项，不在补丁链范围内。

API Reference

补丁链直接暴露的编程接口集中在蓝牙控制器层头文件 btctrler_task.h，属于测试盒信息族枚举：

TESTBOX_INFO_SDK_VERSION

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

Source: btctrler_task.h

说明：TESTBOX_INFO 枚举族中的一个成员，位于 TESTBOX_INFO_BURN_CODE（烧录码）之后，是测试盒查询 SDK 版本的标准信息项。

回调签名：u8 *(*handle)(u8 *len)

参数：

• len（u8 *，出参）：回调写入的版本数据字节长度

返回：

• u8 *：指向版本字符串/版本数据缓冲区的指针

Throws：

• 无（C 语言枚举定义，不抛异常；但若头文件与库版本不匹配，运行期测试盒查询可能返回错误版本——见 Failure Modes）

设计意图：版本信息通过函数指针间接获取而非直接内嵌常量，使蓝牙控制器库（二进制 lib.a）可以独立演进——库内实现读取自身编译时的版本字符串，头文件只声明接口形状。这也意味着升级补丁必须同时更新头文件与库文件，二者版本必须严格配对。

Failure Modes、边界情况与并发注意事项

补丁应用失败模式

边界情况

• 裁剪与功能升级的叠加：v1.2.0 裁剪补丁与 v1.2.0→v1.3.0 蓝牙补丁基线相同但目标不同，二者可按序叠加（先裁剪、后升级），但顺序不可颠倒——蓝牙补丁假定的是"已裁剪或未裁剪的 v1.2.0"基线，具体以官方发布说明为准；
• v1.3.0 与 v1.3.4 之间的衔接：仓库中未单独发现 v1.3.0→v1.3.4 独立补丁包目录，v1.3.4 作为 v1.3.4升级至v1.4.0 补丁的基线存在；若工程处于 v1.3.0 且需要升级至 v1.4.0，需先确认官方是否提供了 v1.3.0→v1.3.4 的过渡补丁（可查阅 doc/AW30N_SDK_发布版本信息.pdf）；
• 二进制库文件的不可见性：补丁包内含 lib.a 二进制库，仓库工具无法解析其内部实现；蓝牙协议栈内部修复细节（如连接参数、OTA 时序）只能通过行为验证，无法从源码确认——本页对此保持诚实，未作推测。

并发与一致性注意事项

• 产线并发升级：多台测试盒同时升级同一批设备时，各设备独立烧录，无共享状态；但产线工具需保证"先校验版本、后烧录"的顺序，避免旧版本设备被误判；
• 版本一致性：TESTBOX_INFO_SDK_VERSION 由库文件提供，固件内任何其他位置若同时维护版本宏，需与补丁后的库版本保持一致，否则会出现"测试盒读到 A 版本、应用层显示 B 版本"的不一致现象。

性能与运维注意事项

• 编译时长：补丁合入后需要全量重编译，建议在 CI/本地流水线中保留干净的基线工程，便于快速生成对比固件；
• Flash 占用：256KB 裁剪补丁面向小容量芯片，应用后需通过编译器的 map 文件确认代码段/数据段占用未超出容量；若超出，需检查是否误合入了未裁剪功能的补丁；
• OTA 带宽：手机 BLE OTA 通道受 BLE 4.2/5.x 吞吐限制，大固件升级耗时较长；产线批量场景建议优先测试盒串口通道；
• 版本可追溯性：每个补丁包目录名自带"基线版本 + 目标版本 + 日期"，建议在工程内记录已应用的补丁清单（目录名+日期），与固件版本一同归档，便于售后问题定位。

扩展点

补丁链的扩展机制建立在"目录对齐覆盖"之上，开发者可基于同一模式扩展：

• 自定义补丁：在 补丁包/ 下按 {版本}_{用途}_{日期} 规范新建目录，目录结构与 sdk/ 对齐，即可复用现有的合入流程；
• 版本上报扩展：如需在测试盒信息中新增自定义信息项，可在 btctrler_task.h 的 TESTBOX_INFO 枚举后追加新枚举值，并在配套库中实现对应回调（需与杰理官方工具链配合）；
• 新升级通道：SDK 已支持五种升级通道，若需新增通道，可参考 download_sh.c 等烧录脚本的既有实现进行扩展（Linux 适配即为一个现成的扩展示例）。

测试情况

受仓库内容限制，补丁包内未发现独立的自动化测试套件。可依据的证据包括：

• 补丁包以"日期+用途"命名并随版本发布，表明补丁经过官方 Release 验证后发布（AW30N_v1.2.0_SDK裁剪到256KB以内的补丁包_20240815 的日期后缀即发布验证节点）；
• 测试盒信息接口（TESTBOX_INFO_SDK_VERSION）的存在表明产线测试工具是版本验证的主要手段——建议应用补丁后使用无线测试盒执行"读版本 → 校验 → 升级 → 再读版本"的回归流程；
• 若需更完整的测试覆盖（如各版本 OTA 兼容性矩阵），请参阅 AW30N_SDK_发布版本信息.pdf 及杰理官方文档中心（doc.zh-jieli.com/AW30）。

Related Links

• README.md（仓库总览与升级工具说明）
• SDK 发布版本信息（官方版本历史 PDF）
• 补丁包 v1.2.0 裁剪补丁 btctrler_task.h
• 补丁包 v1.2.0→v1.3.0 蓝牙补丁 btctrler_task.h
• 补丁包 v1.3.4→v1.4.0 蓝牙相关补丁 btctrler_task.h
• 兄弟页面：SDK 工程结构 / BLE 协议栈 / 音频子系统 / 烧录与 OTA（对应目录项另行展开）