SDK 版本与发布信息
fw-AW30N_BLE_SDK 是杰理科技 AW30N 系列 BLE 通用 MCU SDK 的发布仓库。本页说明该 SDK 的版本管理机制、发布产物构成、配套文档版本、获取方式与版本核验流程。
Purpose and Scope
本页面向 SDK 使用者（开发者与方案商），回答以下问题：
- SDK 以什么形式发布、在哪里获取？
- 如何确定当前 SDK 的版本号与历史变更？
- 发布包由哪些部分组成（源码、预编译库、文档）？
- 各文档（手册、规格书、原理图）与 SDK 版本的配套关系？
- 版本不匹配时会出现哪些典型问题、如何规避？
边界说明：本页聚焦"版本与发布"本身。以下主题属于其他页面的范畴，本页只做交叉指引：
- SDK 的功能特性、编译与烧录步骤 → 见
doc/AW30N_SDK手册_V1.7.pdf（SDK 手册） - 芯片电气特性与引脚定义 → 见
doc/AW30N_芯片手册_V1.1.pdf与doc/datasheet/下的规格书 - 硬件原理图与 PCB 设计 → 见
doc/schematic/目录及硬件设计指南 - 具体应用示例（遥控器、对讲机、Dongle 等）→ 见 SDK 应用示例相关页面
Overview
AW30N 系列芯片是带 BLE 5.4 蓝牙功能的 32bit DSP MCU，支持蓝牙遥控器、蓝牙对讲机、BLE Dongle、小音箱、语音玩具等产品形态（README.md）。
该仓库的发布模型为"Release 源码 + 预编译库 + 文档"三者配套：
- Release 源码：仓库
main分支即 SDK Release 版本代码及示例工程； - 预编译库：编译需要配合对应命名规则的库文件
lib.a（不在仓库内，需按版本配套获取）； - 文档：
doc/目录集中存放发布版本信息、SDK 手册、芯片手册、硬件设计指南、规格书与原理图。
版本信息的权威载体是 doc/AW30N_SDK_发布版本信息.pdf（SDK 发布版本信息），同时在 README 中通过 Gitee Tag 徽章展示最新版本号，并链接到版本历史。注意：该 PDF 为二进制文档，本页无法解析其内部逐条变更记录；如需完整变更日志，请直接打开该 PDF 阅读。
关键版本事实（来自仓库文件）
| 事实 | 证据 |
|---|---|
| SDK 发布说明文档 | doc/AW30N_SDK_发布版本信息.pdf |
| SDK 手册当前版本 | V1.7（doc/AW30N_SDK手册_V1.7.pdf） |
| 芯片手册当前版本 | V1.1（doc/AW30N_芯片手册_V1.1.pdf） |
| 硬件设计指南版本 | V1.2（doc/AW30N硬件设计指南V1.2.pdf） |
| 芯片规格书（Datasheet） | AW302A / AW302C / AW305A / AW306A 均为 V2.0 |
| 蓝牙规范 | Core v5.4，QDID 223418 |
| 芯片选型表 | 杰理科技AW30N系列芯片选型表_20240816.pdf |
Architecture
SDK 版本信息的产生、发布与消费关系如下图所示：
flowchart TD
subgraph sg_Release["版本发布源"]
GitTags["Git Tags<br/>（gitee.com/Jieli-Tech/AW30N/tags）"]
ReleaseNotes["AW30N_SDK_发布版本信息.pdf"]
SDKCode["SDK Release 源码<br/>（main 分支）"]
LibA["预编译库 lib.a"]
Docs["doc/ 配套文档<br/>（手册 / 规格书 / 原理图）"]
end
subgraph sg_Consumers["版本消费方"]
README["README 徽章 + 版本历史链接"]
Dev["开发者 / 方案商"]
Toolchain["杰理编译工具链<br/>（pi32/clang）"]
end
GitTags -->|"徽章显示最新 Tag"| README
ReleaseNotes -->|"SDK 版本历史"| README
SDKCode --> Dev
Docs --> Dev
LibA -->|"按命名规则配套"| Dev
Toolchain -->|"clang 交叉编译"| Dev
Dev -->|"构建固件"| Firmware["目标固件 bin"]
架构说明
- 版本发布源：SDK 版本以 Gitee Tag 为版本号载体，以
AW30N_SDK_发布版本信息.pdf为变更说明载体，两者通过 README 中的徽章与链接对外暴露（README.md）。 - 发布包构成：
main分支的源码 + 按命名规则配套的lib.a+doc/下的文档体系，三者必须版本一致才能正确编译与调试。 - 消费方：开发者获取版本后，用杰理编译工具链（
/opt/jieli/pi32/bin/clang）编译 Release 源码，产出目标固件。
这种"源码开源 + 库文件配套 + 文档齐备"的发布模型，既保证了核心算法与编解码器代码的知识产权保护（以预编译库形式提供），又让应用层完全可见可改，是嵌入式 SDK 的常见做法。
版本管理机制
1. Tag 版本号（版本号的唯一权威来源）
SDK 的版本号以 Gitee 仓库 Tag 形式管理。README 顶部使用徽章实时展示最新 Tag：
[tag download]:https://gitee.com/Jieli-Tech/AW30N/tags
[tag_badgen]:https://img.shields.io/github/v/tag/Jieli-Tech/AW30N?style=plastic&logo=bluetooth&label=tag&labelColor=ffffff&color=informational
# fw-AW30N_BLE_SDK [![tag][tag_badgen]][tag download]
Source: README.md
设计意图：徽章自动拉取仓库最新 Tag 并展示，使用者无需进入仓库即可在 README 页面一眼确认当前 SDK 版本；点击徽章可直接跳转到 Tags 列表，按版本号下载对应历史版本代码。
2. 版本历史文档（变更记录的权威载体）
每次发布对应的变更内容记录在 doc/AW30N_SDK_发布版本信息.pdf 中，README 与英文版 README 均提供入口：
[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
说明：
AW30N_SDK_发布版本信息.pdf为 PDF 二进制文档，本页无法直接解析其内容。如需查看各版本新增功能、修复项与升级注意事项，请打开该 PDF 查阅。
3. 源码与库文件的版本配套
本仓库包含 SDK Release 版本代码及示例工程，需配合对应命名规则的库文件 (`lib.a`) 进行编译。
Source: README.md
这是本 SDK 发布模型的核心约束：代码仓库本身不包含预编译库，lib.a 需按命名规则与 SDK 版本配套获取（通常随版本发布或由代理商/工具链提供）。库文件与源码版本不一致时，可能出现链接错误、API 缺失或行为异常，详见下文"失败模式"一节。
发布产物构成
发布包由三部分构成，全部托管于本仓库 main 分支：
| 类别 | 内容 | 位置 |
|---|---|---|
| SDK 源码 | 应用层 apps/app/src/mbox_flash/、BSP、include_lib 头文件 | sdk/ |
| 预编译库 | lib.a（按命名规则配套，不在仓库内） | 配套发布 |
| 文档 | 发布版本信息、SDK 手册、芯片手册、硬件设计指南、规格书、原理图 | doc/ |
工程结构（节选 doc/ 部分）：
├── doc/ # 文档
│ ├── datasheet/ # 芯片规格书
│ ├── schematic/ # 原理图
│ ├── stuff/ # 杂项（钉钉群等）
│ ├── AW30N_SDK手册_V1.7.pdf # SDK 手册
│ ├── AW30N_SDK_发布版本信息.pdf # SDK 发布版本信息
│ ├── AW30N_芯片手册_V1.1.pdf # 芯片手册
│ ├── AW30N硬件设计指南V1.2.pdf # 硬件设计指南
│ └── 杰理科技AW30N系列芯片选型表_20240816.pdf # 芯片选型表
Source: README.md
文档版本矩阵
仓库内各文档均有独立版本号，按芯片型号与应用场景配套：
| 文档 | 版本 | 说明 |
|---|---|---|
| AW30N_SDK手册 | V1.7 | SDK 快速上手与功能说明 |
| AW30N_芯片手册 | V1.1 | 芯片架构、寄存器与引脚 |
| AW30N硬件设计指南 | V1.2 | 硬件参考设计 |
| AW302A Datasheet | V2.0 | 芯片规格书 |
| AW302C Datasheet | V2.0 | 芯片规格书 |
| AW305A Datasheet | V2.0 | 芯片规格书 |
| AW306A Datasheet | V2.0 | 芯片规格书 |
| AW305A BLE对讲机标准原理图 | V1.2 | 对讲机参考原理图 |
| AW305A BLE蓝牙语音遥控器标准原理图 | V1.2 | 遥控器参考原理图 |
| AW306A BLE对讲机标准原理图 | V1.2 | 对讲机参考原理图 |
| AW306A BLE蓝牙Dongle标准原理图 | V1.2 | Dongle 参考原理图 |
| AW306A BLE蓝牙语音遥控器标准原理图 | V1.3 | 遥控器参考原理图（更新版） |
| AW302A/AW302C BLE参考原理图（最小系统） | V1.0 | 最小系统参考 |
| AW305A/AW306A BLE参考原理图（最小系统） | V1.1 | 最小系统参考 |
资料来源：doc/ 目录文件清单（由 ListFiles 确认）。文档版本独立演进，硬件设计时请以对应型号、对应版本为准，避免新旧版本混用。
芯片选型与版本的关系
同一 SDK 面向 AW30N 全系列（AW302A / AW302C / AW305A / AW306A），选型信息见《杰理科技AW30N系列芯片选型表_20240816.pdf》。蓝牙协议栈方面，全系统一支持 Core v5.4（QDID 223418）（README.md），因此 SDK 版本与蓝牙协议版本解耦——协议能力由芯片硬件决定，SDK 版本只影响软件功能与修复内容。
核心流程：获取与核验 SDK 版本
flowchart TD
Start([获取 SDK 版本]) --> Step1["查看 README 徽章<br/>确认最新 Tag 版本号"]
Step1 --> Step2{"需要详细变更内容？"}
Step2 -->|"是"| Step3["打开 doc/AW30N_SDK_发布版本信息.pdf<br/>阅读版本历史"]
Step2 -->|"否"| Step4["按 Tag 或 main 分支拉取源码"]
Step3 --> Step5["确认配套 lib.a 命名与工具链版本"]
Step4 --> Step5
Step5 --> Step6["安装/核验杰理编译工具链"]
Step6 --> EndNode([开始编译开发])
步骤详解
- 确认版本号：进入仓库 README，徽章显示最新 Tag；点击徽章进入 Tags 列表 可查看全部历史版本。
- 阅读变更内容：打开
doc/AW30N_SDK_发布版本信息.pdf，逐条查看新增/修复/升级注意事项。 - 拉取对应代码：如需历史版本，按对应 Tag 检出；一般开发使用
main分支最新代码。 - 配套库与工具链：确认
lib.a命名与源码版本匹配，并安装对应版本的杰理工具链。 - 核验工具链：执行
clang --version确认交叉编译器可用（见下文示例）。
使用示例
示例 1：核验编译工具链版本
# 验证工具链是否安装成功
clang --version
Source: README.md
工具链安装路径约定为 /opt/jieli/pi32/bin/clang（Linux）。版本核验是 SDK 版本配套检查的第一步——工具链版本与 SDK 发布时的编译环境不一致时，可能导致链接或运行异常。
示例 2：按命名规则确认库文件配套
本仓库包含 SDK Release 版本代码及示例工程，需配合对应命名规则的库文件 (`lib.a`) 进行编译。
Source: README.md
设计意图：预编译库命名中通常包含芯片型号与 SDK 版本信息。务必让库文件与源码来自同一发布版本，这是 SDK 版本管理中最容易出错、也最需要遵守的约定。
示例 3：从文档中心获取最新资料
README 提供杰理在线文档中心入口（doc.zh-jieli.com/AW30/zh-cn/master/index.html），在线文档与仓库 doc/ 目录中的 PDF 配套更新，可作为版本资料的补充来源（README.md）。
失败模式、边界情况与注意事项
1. 库文件（lib.a）与源码版本不匹配
- 现象：链接报错（未定义符号）、API 签名不一致导致的编译错误，或编译通过但运行行为异常。
- 原因：
lib.a不在仓库内，按命名规则配套发布；若混用不同发布版本的源码与库文件，头文件声明与库内实现不一致。 - 规避：始终从同一发布版本获取源码与
lib.a；升级 SDK 时同步升级库文件，并阅读AW30N_SDK_发布版本信息.pdf中的升级注意事项。
2. 编译工具链版本不一致
- 现象：编译警告增多、链接失败或固件在目标板上异常。
- 原因：SDK 使用杰理私有工具链（
pi32/clang）交叉编译，不同工具链版本对语言特性与链接脚本的处理存在差异。 - 规避：按 README 安装官方工具链并执行
clang --version核验（README.md）。
3. 文档版本与 SDK 版本演进不同步
各文档版本号独立演进（SDK 手册 V1.7、芯片手册 V1.1、规格书 V2.0、原理图 V1.0~V1.3）。硬件设计、寄存器操作与 SDK API 使用应分别以对应文档最新版本为准，注意原理图存在"同型号多版本"的情况（如 AW306A 语音遥控器原理图 V1.2 与 V1.3 并存），选用时需确认与手中硬件一致。
4. 版本信息获取的已知限制
AW30N_SDK_发布版本信息.pdf 为二进制 PDF，自动化工具无法解析逐条变更记录；本页提供的版本事实均来自仓库 README 与 doc/ 目录清单。若需逐版本变更明细，请直接打开该 PDF。
5. 平台差异
- Windows 推荐使用 Code::Blocks IDE 编译；Linux 使用 Makefile 命令行编译，但需要重写
download_sh.c脚本适配 Linux 环境；macOS 需自行配置交叉编译工具链（README.md）。跨平台编译差异可能表现为同一版本在不同平台上的构建结果不一致。
性能与运维提示
- 编译：
sdk/目录下执行make -j4（并行编译加速）；make clean清理产物。首次编译需确保工具链在 PATH 中。 - 烧录与升级：SDK 支持 U 盘/SD 卡设备升级、测试盒串口升级、测试盒蓝牙升级、手机蓝牙 OTA 升级与手机 USB 升级等多通道升级方式（README.md），发布固件时应按目标产品选择对应的升级通道。
- 版本追踪：生产环境建议固定 Tag 版本 + 配套
lib.a+ 配套文档版本，形成可复现的构建基线，便于问题回溯。
扩展点与协作
- 报告问题：通过 Gitee Issues 提交缺陷或需求，问题跟踪与版本修复记录关联。
- 版本演进：新版本以 Tag 形式发布并同步更新
AW30N_SDK_发布版本信息.pdf与 README 徽章；使用者可通过 Tags 列表对比历史版本。 - 社区支持：
doc/stuff/中提供杰理技术交流群（钉钉群）入口，可获取版本配套库与技术支持。
Related Links
- SDK 发布版本信息 PDF — 版本历史的权威文档
- SDK 手册 V1.7 — SDK 快速上手（本页交叉指引）
- 芯片手册 V1.1 — 芯片架构与寄存器（本页交叉指引）
- 硬件设计指南 V1.2 — 硬件参考设计（本页交叉指引）
- 芯片规格书目录 — AW302A/AW302C/AW305A/AW306A Datasheet V2.0
- 参考原理图目录 — 各型号应用原理图
- README（中文） — 仓库总览、环境搭建、编译与烧录指南
- README（英文） — 英文版仓库总览
- Gitee Tags 列表 — 全部历史版本 Tag
- 杰理在线文档中心 — SDK 在线文档