SDK 文档中心与版本发布记录

本文档介绍 fw-AD16N_GP-MCU_SDK 仓库的文档中心体系与版本发布记录机制：包括文档资源的组织方式（仓库内 doc/ 目录与在线资源）、各文档的用途与获取路径、SDK 版本发布信息的记录载体（发布信息 PDF 与 Gitee Tags），以及开发者如何正确选择与核对 SDK 版本。

Purpose and Scope

本页面向使用或维护 fw-AD16N_GP-MCU_SDK 的开发者，系统梳理该 SDK 的文档体系与版本管理方式，帮助读者：

• 了解文档中心的入口（仓库 README.md）与文档目录结构（doc/ 下的规格书、原理图、手册、选型表等）；
• 明确各文档的定位与适用场景，快速定位所需的芯片资料、SDK 手册、硬件设计指南；
• 理解版本发布记录的承载方式（doc/AD16N_FLASH_SDK_发布版本信息.pdf 与 Gitee Tags），掌握"SDK 版本 ↔ 库文件 lib.a ↔ 固件"之间的对应关系；
• 了解在线文档资源（杰理工具在线文档、Bilibili 视频教程、Gitee Issues、FAE 支持仓库）与社区支持渠道。

不涉及的内容：环境搭建、工程编译、烧录升级、应用开发等具体操作细节属于 SDK 快速入门与使用手册范畴，本页仅在"文档导航"层面提及对应入口；芯片选型细节可参见 doc/README.md 选型表与各芯片 Datasheet。若目录中存在"SDK 快速入门"、"编译指南"等兄弟页面，请以对应页面为准。

概述

fw-AD16N_GP-MCU_SDK 是杰理科技为 AD16N 系列芯片提供的通用 MCU SDK 固件程序，主要面向语音玩具、小音箱与通用 MCU 三大应用场景。该仓库本身即是一个"代码 + 文档"一体化的发布载体：既有可编译的 SDK Release 代码与示例工程，也随附完整的文档资料。

从文档视角看，仓库的文档体系分为三个层次：

1. 导航入口层：仓库根目录 README.md（中文）与 README-en.md（英文）充当文档中心首页，通过 12 个章节和资源链接表把开发者引导到具体文档；
2. 仓库内文档层：doc/ 目录集中存放 PDF 文档，包括 SDK 手册、芯片手册、硬件设计指南、芯片选型表、SDK 发布版本信息，以及按 datasheet/（芯片规格书）、schematic/（参考原理图）、stuff/（杂项）组织的子目录；
3. 在线资源层：doc.zh-jieli.com 工具在线文档、Bilibili 视频教程、Gitee Issues 问题反馈、FAE 支持仓库等外部资源，与仓库内文档互补。

版本发布记录方面，仓库通过两条途径对外呈现版本信息：

• doc/AD16N_FLASH_SDK_发布版本信息.pdf：随仓库维护的 SDK 版本历史文档，README 的"SDK 版本历史"链接与免责声明均指向该文件；
• Gitee Tags：README 顶部的 Tag 徽章直接链接到 Gitee 仓库 Tags 页面，以版本标签形式记录每次 Release。

SDK 版本与代码之间存在强绑定关系：README 明确说明"本仓库包含 SDK Release 版本代码及示例工程，需配合对应命名规则的库文件（lib.a）进行编译"，因此在选用文档与固件时，核对版本号是开发流程中的关键一步。

架构

下图展示了 SDK 文档中心与版本发布记录的整体架构，以及文档入口与各资源之间的关系：

flowchart TD
    subgraph sg_Entry["文档入口层"]
        README["README.md 文档中心导航"]
        README_EN["README-en.md 英文版"]
    end

    subgraph sg_RepoDocs["仓库内文档 doc/"]
        TOPPDF["顶层文档（PDF）"]
        DS["datasheet/ 芯片规格书"]
        SCH["schematic/ 参考原理图"]
        STUFF["stuff/ 杂项资源"]
        SEL["README.md 芯片选型表"]
    end

    subgraph sg_Release["版本发布层"]
        VERPDF["AD16N_FLASH_SDK_发布版本信息.pdf"]
        TAGS["Gitee Tags 版本标签"]
    end

    subgraph sg_Online["在线资源层"]
        WEB["doc.zh-jieli.com 工具文档"]
        BILI["Bilibili 视频教程"]
        ISSUES["Gitee Issues 问题反馈"]
        FAE["FAE 支持仓库"]
    end

    README --> TOPPDF
    README --> DS
    README --> SCH
    README --> STUFF
    README --> SEL
    README --> VERPDF
    README --> TAGS
    README --> WEB
    README --> BILI
    README --> ISSUES
    README --> FAE
    README_EN --> README
    VERPDF --> TAGS

架构说明：

• README.md 是唯一的文档中心入口（英文版 README-en.md 通过导航链接回到中文版）。其顶部导航栏直接提供"文档中心"、"SDK 版本历史"、"报告问题"三个核心入口，正文 12 个章节覆盖从选型、环境搭建到烧录升级的完整链路，是文档体系的"总索引"。
• doc/ 目录承载全部仓库内文档：顶层 PDF（SDK 手册、芯片手册、硬件设计指南、选型表、发布版本信息）与三个子目录（datasheet/、schematic/、stuff/）各司其职，README 的工程结构章节对该目录树有完整描述。
• 版本发布层与文档层并列：AD16N_FLASH_SDK_发布版本信息.pdf 是版本记录的"官方文档"，Gitee Tags 是版本记录的"代码载体"，二者通过版本号相互对应，开发者应交叉核对。
• 在线资源层扩展了文档边界：工具使用文档、视频教程、问题反馈与 FAE 支持均通过 README 的资源链接表触达，弥补了仓库内 PDF 无法覆盖的动态内容（如工具更新、答疑）。

文档中心详解

入口导航：README.md 的文档组织方式

README.md 采用"顶部导航 + 12 章节 + 资源链接表"的三段式结构组织文档信息：

其中"社区与支持"章节的资源链接表是文档中心最重要的索引之一，它把仓库内文档（PDF）与仓库外资源（在线工具文档、视频、支持渠道）统一编目，是本文档后续各节的依据。

doc/ 目录结构

doc/ 目录按文档类型组织，顶层为综合文档，子目录按资料类别划分：

datasheet/ 子目录覆盖 AD16N 全系列芯片，规格书版本随芯片发布节奏更新：

schematic/ 子目录目前包含 AD160A 最小系统原理图 V1.0、AD161A 最小系统原理图 V1.0、AD161A LCD 段码屏参考原理图 V1.0，用于指导硬件设计阶段的原理图绘制。

版本发布记录

发布记录的承载方式

AD16N SDK 的版本发布记录由两个互补的载体构成：

1. doc/AD16N_FLASH_SDK_发布版本信息.pdf（版本历史文档） README 中两处引用该文件：顶部导航的"SDK 版本历史"链接，以及"资源链接表"中的"SDK 版本历史"条目。同时，免责声明明确指出"对应 SDK 版本请见 SDK 版本历史"，说明该 PDF 是判断"当前代码对应哪个 SDK 版本"的权威依据。

2. Gitee Tags（版本标签） README 标题行嵌入了 Tag 徽章（![tag][tag_badgen]），徽章指向 Gitee 仓库 Tags 页面。每次 SDK Release 以 Tag 形式标记代码快照，便于开发者按版本检出对应代码。

版本、库文件与固件的对应关系

SDK 版本并非独立存在，它与编译产物强绑定。README 概述章节明确说明：

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

这意味着开发者的版本核对流程应为：查看发布版本信息 PDF 确认版本号 → 按 Tag 检出对应代码 → 匹配对应命名规则的 lib.a 预编译库 → 编译生成固件。lib.a 库文件位于 sdk/apps/include_lib/liba/ 目录，命名规则与 SDK 版本对应，混用版本可能导致链接错误（README 常见编译错误表中的 cannot find -lxxx 即属此类问题）。

芯片与平台版本的差异管理

AD16N 系列包含多款芯片（AD160A、AD161A、AD162A/B/C/D、AD165A/C/D、AD166A、AD168A），它们在封装、内置 Flash、外设资源上存在差异。文档中心通过两份材料管理这种差异：

• doc/README.md 选型表：以 Markdown 表格给出全系列芯片的参数对比，适合快速筛选；
• doc/datasheet/ 各芯片规格书：给出每款芯片的详细电气与功能规格，适合深入设计。

芯片选型表（doc/README.md 摘录）

doc/README.md 以"型号 | 封装 | 内置系统 Flash | 外挂系统 Flash | 供电范围 | 关机功耗 | GPIO | 10bit ADC | FUSB | SPI | I2C | UART | SDIO | QDEC | 2812LED | IRDA | TIM PWM | MCPWM | MIC | AUX | AUD DAC | 直推耳机 | 锂电池充电 | RTC | LCD 段码屏 | 产品应用"的列结构，列出 AD16N 全系列芯片选型参数。以下为部分代表性型号摘录：

完整 26 列参数（含 SPI/I2C/UART/SDIO 数量、MCPWM、RTC、LCD 段码屏等）请查阅 doc/README.md 与 杰理科技32位AD系列语音MCU选型表.pdf。

核心流程

文档获取与使用流程

开发者从接触仓库到完成开发，文档中心的导航路径如下：

flowchart TD
    Start([开发者]) --> Step1["访问仓库 README.md"]
    Step1 --> Step2{"需要什么资料?"}
    Step2 -->|"SDK 使用手册"| Doc1["AD16N_开源SDK手册_V1.2.pdf"]
    Step2 -->|"芯片参数"| Doc2["datasheet/ 规格书 + 选型表"]
    Step2 -->|"硬件设计"| Doc3["硬件设计指南 + schematic/ 原理图"]
    Step2 -->|"版本信息"| Doc4["AD16N_FLASH_SDK_发布版本信息.pdf"]
    Step2 -->|"开发工具"| Doc5["doc.zh-jieli.com 在线文档"]
    Doc1 --> Step3["核对 SDK 版本与 lib.a 匹配"]
    Doc2 --> Step3
    Doc3 --> Step3
    Doc4 --> Step3
    Doc5 --> Step3
    Step3 --> Step4["按手册开发 / 编译 / 烧录"]
    Step4 --> Step5{"遇到问题?"}
    Step5 -->|"是"| Step6["Gitee Issues / 钉钉群 / FAE"]
    Step5 -->|"否"| End1([完成])
    Step6 --> End1

版本发布与消费流程

SDK 版本从发布到被开发者正确消费的完整链路如下：

flowchart LR
    subgraph sg_ReleaseFlow["版本发布与消费"]
        R1["杰理发布 SDK Release"] --> R2["代码入库 + 打 Gitee Tag"]
        R2 --> R3["维护发布版本信息 PDF"]
        R3 --> R4["开发者按 Tag 检出代码"]
        R4 --> R5{"库文件 lib.a 匹配?"}
        R5 -->|"是"| R6["编译生成固件"]
        R5 -->|"否"| R7["按命名规则下载对应 lib.a"]
        R7 --> R5
        R6 --> R8["烧录 / OTA 升级"]
    end

该流程体现了版本管理的两个设计意图：一是以 Tag 固化代码快照，保证任何时间点都能重现特定版本的 SDK；二是以发布信息 PDF 作为版本与代码的映射文档，避免开发者因库文件与代码版本不一致而产生难以排查的链接/运行错误。

使用示例

以下示例均摘自仓库实际文档内容，展示文档中心各入口对应的实际操作。

示例 1：克隆仓库（文档中心快速开始的入口）

git clone https://gitee.com/Jieli-Tech/fw-AD16N.git
cd fw-AD16N/sdk

Source: README.md

示例 2：验证编译工具链（环境搭建章节）

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

Source: README.md

示例 3：Makefile 命令行编译（编译指南章节）

# Windows 用户
双击 sdk/make_prompt.bat 打开命令行环境

# 编译
make -j4

# 显示编译详情
make VERBOSE=1 -j4

Source: README.md

示例 4：工程与应用代码入口（工程结构章节）

fw-AD16N/
├── sdk/                           # SDK 主目录
│   ├── apps/                      # 应用层代码
│   │   ├── app/src/mbox_flash/    #   小音箱/音频播放应用
│   │   ├── bsp/                   #   板级支持包（BSP）
│   │   └── include_lib/liba/      #   预编译库 (.a)
│   └── Makefile                   # 顶层 Makefile
├── doc/                           # 文档
│   ├── datasheet/                 #   芯片规格书
│   ├── schematic/                 #   原理图
│   ├── AD16N_FLASH_SDK_发布版本信息.pdf
│   ├── AD16N_开源SDK手册_V1.2.pdf
│   └── README.md                  #   芯片选型说明
└── README.md                      # 文档中心入口

Source: README.md

配置选项与文档导航参考

文档中心配置/导航入口

在线资源链接参考

失败模式、边界情况与注意事项

基于文档中的常见问题与工程结构，版本与文档使用中存在以下典型风险：

边界情况说明：

• README 明确指出 Linux 环境下需重写 download_sh.c 脚本适配，macOS 需自行配置交叉编译工具链——文档中心对环境差异给出了显式提示，但 Linux/macOS 的完整支持需开发者自行适配；
• doc/stuff/ 目录包含钉钉技术交流群二维码等非技术文档资源，其内容（群号）可能随时间变化，应以仓库最新版本为准；
• 发布版本信息 PDF 为二进制文档，无法在仓库内做 diff 对比，因此版本变更的"代码侧"证据应以 Gitee Tags 的提交历史为准。

扩展点与社区支持

文档中心的设计为开发者留出了多条参与路径：

• 问题反馈：通过 Gitee Issues 提交文档勘误、Bug 与功能需求，README 顶部导航"报告问题"即指向此处；
• 技术交流：钉钉技术交流群（二维码见 doc/stuff/dingtalk.jpg）；
• FAE 支持：通过 FAE 支持仓库 获取官方技术支持；
• 在线文档跟踪：工具链与量产工具文档托管在 doc.zh-jieli.com，随工具版本持续更新，是仓库内 PDF 的动态补充。

Related Links

• README.md（文档中心入口）
• doc/README.md（芯片选型表）
• AD16N_FLASH_SDK_发布版本信息.pdf（SDK 版本历史）
• AD16N_开源SDK手册_V1.2.pdf（SDK 手册）
• AD16N_芯片手册_V1.2.pdf（芯片手册）
• AD16N通用音频MCU硬件设计指南V1.3.pdf（硬件设计指南）
• Gitee Tags（版本标签）
• Gitee Issues（问题反馈）