问题修复补丁

本页说明 fw-AW30N_BLE_SDK 仓库中“问题修复补丁”的交付机制与使用方式：该仓库不包含独立的补丁文件目录，问题修复以 SDK 版本迭代 + 配套 lib.a 库文件 + 版本历史说明 的形式发布，本文档介绍如何获取、应用与验证这些修复。

Purpose and Scope

本页面向使用 AW30N BLE SDK 的开发者，说明：

• SDK 中问题修复（bugfix）的发布形态：Release 版本代码 + 命名规则匹配的库文件（lib.a），以及版本历史记录；
• 如何获取与安装修复：升级 SDK 源码、匹配对应版本的库文件、重新编译；
• 官方提供的问题反馈渠道与常见问题（FAQ） 中沉淀的修复经验；
• 应用补丁后的验证与回归要点。

不在本页范围（由同目录下的兄弟页面覆盖）：

• 环境搭建与编译流程细节 → 见编译指南相关页面；
• 烧录与升级工具的使用 → 见烧录与升级相关页面；
• SDK 配置项说明 → 见配置说明相关页面。

说明：截至本页撰写时，仓库根目录仅含 LICENSE、README.md、README-en.md，未发现独立的 patch/ 或 bugfix/ 目录。因此本页以仓库中实际存在的版本发布机制（README 中的版本历史链接、常见问题章节、问题反馈入口）为事实依据，补丁的具体 diff 内容需以对应 Release 标签或版本历史 PDF 为准。

Overview

fw-AW30N_BLE_SDK 是杰理科技为 AW30N 系列芯片（带 BLE 5.4 功能的 32bit DSP MCU）提供的 BLE 通用 MCU SDK。其代码交付模式是：

本仓库包含 SDK Release 版本代码及示例工程，需配合对应命名规则的库文件 (lib.a) 进行编译。

这句话（见 README.md）是理解“问题修复补丁”机制的关键：SDK 的修复并不以零散的 .patch 文件分发，而是以整包 Release 版本的形式发布。每次修复对应：

1. 一个 Release 标签（tag，见 tags 页面），包含修复后的完整源码与示例工程；
2. 一份 版本历史说明（doc/AW30N_SDK_发布版本信息.pdf），逐版本记录修复/变更内容；
3. 一套 命名规则匹配的库文件（lib.a），必须与源码版本一一对应，否则会出现链接错误或行为不一致。

因此，“打补丁”对使用者而言就是：将工程切换到新的 Release 版本 → 替换匹配的 lib.a → 重新编译 → 回归验证。

核心概念

Architecture

问题修复从“报告”到“应用”的完整闭环如下：

flowchart TD
    subgraph sg_Report["问题报告层"]
        User["开发者/客户"]
        Issues["Gitee Issues 问题反馈"]
    end

    subgraph sg_Fix["官方修复层"]
        Maintainer["杰理维护团队"]
        Release["Release 版本标签<br/>(修复后源码+示例工程)"]
        Lib["匹配命名规则的 lib.a 库文件"]
        PDF["doc/AW30N_SDK_发布版本信息.pdf<br/>(版本历史/修复记录)"]
    end

    subgraph sg_Apply["补丁应用层"]
        Update["拉取/切换新版本源码"]
        Build["重新编译固件"]
        Verify["回归验证修复项"]
    end

    User -->|"提交问题"| Issues
    Issues -->|"评估与复现"| Maintainer
    Maintainer -->|"修复并发布"| Release
    Release --> Lib
    Release --> PDF
    User -->|"获取新版本"| Update
    Update --> Build
    Build --> Verify
    Lib -->|"替换旧库"| Build
    PDF -->|"核对修复项"| Verify

架构说明：

• 问题报告层：所有修复的起点。用户通过 Gitee Issues 提交问题（README 第十一章“社区与支持”中明确列出了问题反馈入口，见 README.md）。
• 官方修复层：维护团队复现、修复后，以 Release 标签发布完整源码，配套 lib.a 与版本历史 PDF。README 顶部提供了 SDK 版本历史 与 tags 下载入口。
• 补丁应用层：使用者侧的工作，即“应用补丁”= 更新源码 + 匹配库 + 重编译 + 回归验证。

为什么采用整包 Release 而非独立补丁文件？

从 SDK 交付结构可以推断其设计意图（设计意图分析，非代码事实）：

• SDK 源码与闭源库（lib.a）强耦合，独立补丁极易造成源码与库不匹配，导致链接错误或运行行为异常；
• 芯片固件开发中，问题往往牵涉编译器、启动代码、蓝牙协议栈等多层，整包发布能保证环境一致性；
• 便于维护团队做回归测试：每个 Release 都经过完整构建验证，而非仅验证被修改的模块。

补丁的获取与应用（Main Content）

1. 版本发布与版本历史

README 开篇即提供两条与补丁直接相关的入口（见 README.md）：

• SDK 版本历史：doc/AW30N_SDK_发布版本信息.pdf —— 这是查阅“修复了哪些问题”的权威来源，每次升级前应先核对此文档，确认目标版本包含自己所需的问题修复；
• tags 下载：通过 Gitee 的 Tags 页面获取各 Release 版本的源码包。

[English](https://gitee.com/Jieli-Tech/AW30N/blob/main/README-en.md) · [文档中心](https://doc.zh-jieli.com/AW30/zh-cn/master/index.html) · [SDK 版本历史](https://gitee.com/Jieli-Tech/AW30N/blob/main/doc/AW30N_SDK_%E5%8F%91%E5%B8%83%E7%89%88%E6%9C%AC%E4%BF%A1%E6%81%AF.pdf) · [报告问题](https://gitee.com/Jieli-Tech/AW30N/issues)

Source: README.md

这段 README 顶部横幅是补丁工作流的“导航页”：版本历史（查修复记录）、文档中心（查用法）、问题反馈（报新问题）三者构成闭环。

2. 升级步骤（应用补丁）

应用一次问题修复补丁的标准操作流程：

1. 确认修复版本：阅读 doc/AW30N_SDK_发布版本信息.pdf，找到包含目标问题修复的版本号；
2. 切换源码：将工程切换到对应 Release 标签（git checkout <tag> 或下载该版本源码包）；
3. 替换库文件：按版本命名规则获取并替换配套的 lib.a 库文件。README 明确指出“需配合对应命名规则的库文件 (lib.a) 进行编译”（见 README.md），库文件与源码版本必须一致；
4. 重新编译：使用杰理编译工具链（pi32/bin/clang）重新构建固件；
5. 回归验证：按版本历史 PDF 中记录的修复项逐一验证，并回归核心功能（蓝牙连接、OTA 升级、解码播放等）。

3. 问题反馈（补丁的来源）

修复需求的入口是 Gitee Issues。README 第十一章“社区与支持”以表格形式给出了支持渠道（见 README.md）：

Source: README.md

提交问题时建议包含：芯片型号、SDK 版本（含 lib.a 版本）、复现步骤、期望行为与实际行为、日志（UART 日志）等，便于维护团队复现与定位。

4. 常见问题（FAQ）中的修复经验

README 第十章“常见问题”（见 README.md）沉淀了开发者高频遇到的问题与规避方法。英文版 README 中对应章节还包含调试技巧（见 README-en.md）：

• UART 日志：通过 UART 输出调试日志，用于定位问题；
• BLE 抓包：使用 BLE Dongle 进行空中抓包分析，用于排查蓝牙连接类问题。

### 10.3 Debugging Tips

- **UART Logging**: Debug logs can be output via UART
- **BLE Sniffing**: Use a BLE Dongle for over-the-air packet capture and analysis

Source: README-en.md

这两条调试手段是问题修复验证阶段的重要工具：UART 日志用于确认固件运行路径，BLE 抓包用于确认协议栈行为是否符合预期。

Core Flow（补丁生命周期时序）

sequenceDiagram
    participant U as 开发者/客户
    participant I as Gitee Issues
    participant M as 杰理维护团队
    participant T as Release 标签
    participant P as 版本历史 PDF
    participant B as 编译工具链

    U->>I: 提交问题（芯片型号/SDK版本/复现步骤/日志）
    activate I
    I->>M: 分配并评估问题
    deactivate I
    M->>M: 复现、定位、修复、回归
    M->>T: 发布修复后源码与示例工程
    M->>P: 更新版本历史记录（修复内容）
    M-->>U: 在 Issues 中回复修复版本
    U->>T: 获取新版本源码（切换 tag）
    U->>B: 替换匹配命名规则的 lib.a 并重新编译
    B-->>U: 生成新固件
    U->>U: 按 PDF 修复项逐一回归验证
    U->>I: 验证通过后关闭/确认 Issue

时序要点：

1. 问题必须可复现才能进入修复管线，因此提交信息中“复现步骤 + SDK/lib 版本 + 日志”至关重要；
2. 修复以 Release 标签 + 版本历史 PDF 双通道交付：源码可从 tags 获取，修复清单从 PDF 获取；
3. 用户侧“应用补丁”只有三步：切换源码 → 换库编译 → 回归验证；
4. 验证通过后回填 Issue，形成闭环，供其他用户查阅。

Usage Examples

示例 1：验证编译工具链（升级/编译前置检查）

应用任何补丁前，先确认编译环境就绪。README 给出工具链验证命令（见 README.md）：

# 验证工具链是否安装成功
clang --version

Source: README.md

Linux 环境下要求 /opt/jieli/pi32/bin/clang 存在。若 clang --version 无法输出版本信息，说明工具链未安装或路径未配置，应重新安装杰理编译工具链后再继续编译。

示例 2：编译前的环境准备流程

README 第三章“环境搭建”给出了编译前置步骤（见 README.md）：

# Linux 用户可从此处下载工具链：pkgman.jieliapp.com
# 下载后解压到 /opt/jieli 目录
# 确保 /opt/jieli/pi32/bin/clang 存在

Source: README.md

为什么这属于补丁工作流的一部分：工具链版本差异可能掩盖或放大固件问题。升级 SDK 后若出现异常，先确认工具链与库版本匹配，再判断是否为 SDK 缺陷——这是常见问题排查的第一步。

示例 3：核对版本历史与报告问题（补丁决策依据）

[English](https://gitee.com/Jieli-Tech/AW30N/blob/main/README-en.md) · [文档中心](https://doc.zh-jieli.com/AW30/zh-cn/master/index.html) · [SDK 版本历史](https://gitee.com/Jieli-Tech/AW30N/blob/main/doc/AW30N_SDK_%E5%8F%91%E5%B8%83%E7%89%88%E6%9C%AC%E4%BF%A1%E6%81%AF.pdf) · [报告问题](https://gitee.com/Jieli-Tech/AW30N/issues)

Source: README.md

使用建议：升级前先读版本历史确认目标修复已包含；遇到新问题先查 FAQ，再决定是否通过 Issues 上报。

Configuration Options（配置与版本匹配约定）

本仓库的“补丁”不涉及运行时配置项，但存在一项必须遵守的版本匹配约定：

注：更多 SDK 运行配置请参见配置说明相关页面；此处仅列出与补丁应用直接相关的版本一致性约束。

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

以下为基于仓库事实推断的常见失败场景与规避建议：

边界情况：仓库 README 明确 Linux 环境“需要重写 download_sh.c 脚本适配 Linux 环境”（见 README.md），这意味着部分工具链配套脚本仅官方在 Windows 环境验证过；在 Linux 下应用补丁并烧录时，下载/烧录环节需自行适配。

Related Links

• README.md（主文档，含 FAQ 与支持渠道）
• README-en.md（英文版，含调试技巧 10.3）
• SDK 版本历史（发布版本信息 PDF）
• AW30N Release Tags
• 报告问题（Gitee Issues）
• AW30 文档中心
• 相关兄弟页面：配置说明（SDK 配置项）、烧录与升级（烧录工具使用）、编译指南（Code::Blocks / Makefile 构建）