SDK 概述与芯片平台

杰理科技 AD24N 系列通用 MCU SDK（fw-AD24N_GP-MCU_SDK）的总体介绍：芯片平台、核心特性、SDK 组成结构与开发入口，帮助开发者在开始编码前建立对整套固件体系的整体认知。

目的与范围

本文档面向首次接触 AD24N SDK 的开发者，回答三个问题：这套 SDK 是什么、支持哪些芯片、代码仓库如何组织。具体包括：

SDK 的定位、典型应用场景与核心特性；
AD24N 系列 SoC 型号（AD242A / AD245A / AD246A / AD248A / AD248B）及平台差异；
sdk/ 目录结构、include_lib 中间件模块划分与各层职责；
从克隆仓库到编译烧录的整体开发流程与构建目标。

环境搭建、逐项编译细节、烧录升级操作与常见问题等主题，分别由「环境搭建」「快速开始」「编译指南」「烧录与升级」等姊妹页面承载，本文不做展开；文档中心与版本历史等外部资料在末尾「相关链接」中给出入口。

概述

fw-AD24N_GP-MCU_SDK 是杰理科技为 AD24N 系列芯片提供的通用 MCU SDK 固件程序（Release 版本代码及示例工程），核心是一颗 32bit 双发射 DSP @ 240MHz 的音频/控制 SoC 平台。它面向三类典型应用：

应用类型	典型产品
语音玩具	故事机、学习机、语音遥控玩具、MIDI 乐器、声控灯
小音箱	音乐播放器、扩音器
通用 MCU	智能控制、传感器采集、通用外设应用

表格内容来自仓库 README.md。

SDK 的设计意图是：在保证音频解码/音效/低功耗能力的前提下，通过**「应用层 + 预编译库层 + BSP/驱动层」**的分层结构，让开发者只关注 app/src/ 下的应用逻辑，而将编解码器、文件系统、消息机制、音效算法等以头文件 + lib.a 预编译库的形式提供，从而缩短产品开发周期并降低移植成本。

核心特性一览

双发射 DSP：32bit 双发射 DSP @ 240MHz；
音频解码：支持 .a/.b/.e、.f1a/.f1b/.f1c、UMP3 等多种格式解码播放；
MIDI 播放：支持 MIDI 合成与播放；
三路解码：支持 .a/.b/.e + .f1a/.f1b/.f1c + .f1a/.f1b/.f1c 三路音频同时解码播放；
变速变调：支持音频变速变调播放（需系统时钟 100MHz 以上）；
硬件重采样：内置硬件 SRC；
内置音频编解码：16bit DAC + 16bit ADC，支持 8K–96K 采样率；
Class-D 功放：直驱喇叭；
音效算法：ANS 降噪、变速、ECHO 混响、vo_pitch 变调、voice_changer 变声、PCM EQ；
低功耗：关机功耗低至 2µA+，休眠 19µA+；
多种存储：支持内置/外置 FLASH；
I2S 接口：部分型号支持数字音频输入输出。

架构

SDK 采用典型的分层固件架构，从下至上依次为芯片硬件、板级支持包与驱动、SDK 中间件（预编译库）、应用层：

flowchart TD
    subgraph sg_App["应用层 app/src"]
        VT["voice_toy 语音玩具"]
        VE["voice_enhanced 扩音器"]
        VF["voice_func 语音功能模块"]
    end

    subgraph sg_Mid["SDK 中间件 include_lib（头文件 + lib.a）"]
        DEC["decoder 解码器"]
        ENC["encoder 编码器"]
        AUD["audio 音频 API"]
        FS["fs 文件系统"]
        MSG["msg 消息机制"]
        FX["音效: ans / vo_changer / vo_pitch"]
        UPD["update 固件升级"]
    end

    subgraph sg_Dev["设备与平台层"]
        CPU["cpu 平台头文件"]
        BSP["app/bsp 板级支持包"]
        DEV["device 设备驱动"]
        DEVMG["dev_mg 设备管理"]
    end

    subgraph sg_HW["硬件平台"]
        SOC["AD24N SoC（240MHz DSP）"]
        FLASH["内置/外置 FLASH"]
        AUDIOHW["DAC/ADC/Class-D/I2S"]
    end

    VT --> DEC
    VT --> MSG
    VE --> FX
    VF --> AUD
    DEC --> AUD
    DEC --> FS
    AUD --> CPU
    FS --> DEV
    MSG --> DEVMG
    DEV --> SOC
    BSP --> SOC
    CPU --> SOC
    SOC --> FLASH
    SOC --> AUDIOHW

各层职责与设计意图：

应用层（sdk/app/src/）：产品逻辑的承载者。voice_toy（语音玩具）与 voice_enhanced（扩音器）是两个可编译的应用工程，voice_func 是二者复用的语音功能模块。开发者修改产品行为主要在这一层进行。
SDK 中间件（sdk/include_lib/）：以「公开头文件 + 预编译 lib.a」形式提供的功能库，覆盖解码、编码、音频、文件系统、消息、音效、升级等能力。仓库需配合对应命名规则的库文件编译，这是 Release SDK 常见的闭源分发方式。
设备与平台层：cpu/ 提供 CPU 平台抽象，app/bsp/ 是板级支持包（管脚、时钟、外设初始化），device/ 与 dev_mg/ 负责设备驱动与管理。
硬件平台：AD24N SoC 内集成了 DSP、Codec（DAC/ADC）、Class-D 功放与硬件 SRC，外接 FLASH 与喇叭即可构成最小系统。

目录结构依据 README.md 的工程结构说明绘制。

芯片平台

SoC 系列型号

AD24N 系列目前包含五颗型号，覆盖不同封装、引脚数与外设组合，供产品选型：

芯片系列	应用领域	封装	平台差异
AD242A	语音玩具 / 音频播放	SOP16	基础型号
AD245A	语音玩具 / 通用 MCU	QSOP24	支持 I2S
AD246A	语音玩具 / 通用 MCU	QFN32	GPIO 最多，支持 I2S
AD248A	语音玩具 / 声控灯	SOP8	无 DAC，最小封装
AD248B	语音玩具 / 声控灯	SOP8	无 Class-D

芯片型号/规格书/原理图资料请查阅仓库 doc/ 目录；选型对比可参考 doc/杰理科技32位AD系列语音MCU选型表.pdf。

选型要点（设计意图）：语音类产品优先关注 DAC/Class-D 是否保留（AD248A 无 DAC、AD248B 无 Class-D，适合仅做声控/开关类应用）；需要数字音频输入输出时选择 支持 I2S 的 AD245A/AD246A；GPIO 需求量大的场景选择 QFN32 封装的 AD246A。所有型号共用同一套 SDK，应用工程 AD24N_voice_toy.cbp 覆盖 AD24N 全系列，无需为不同型号维护独立代码树。

MCU 软硬件参数差异

各型号的 MCU 软硬件参数差异图位于仓库根目录 jl_ad_chip.png（见 README.md），芯片级参数（Flash 容量、GPIO 数量、外设清单等）以对应型号规格书为准。

核心特性详解

音频解码与三路解码

SDK 内置多种私有/通用音频格式的解码能力：.a/.b/.e（杰理私有格式）、.f1a/.f1b/.f1c、UMP3。其中「三路解码」指三种格式解码器可同时运行，典型应用是：背景音乐（.a/.b/.e）+ 音效（.f1a/.f1b/.f1c）+ 语音提示（.f1a/.f1b/.f1c）并发播放。多路并发由 DSP 的 240MHz 算力与硬件 SRC 共同保障。

音效算法族

SDK 提供完整的音效处理链，各算法以独立模块位于 include_lib/ 下：

ANS 降噪（ans/）：环境噪声抑制，提升语音清晰度；
变速/变调（vo_pitch/）：变速变调播放，需系统时钟 100MHz 以上；
变声（vo_changer/）：声音变换效果；
ECHO 混响 / PCM EQ：混响与均衡，多用于扩音器应用（voice_enhanced）。

低功耗设计

关机功耗低至 2µA+、休眠 19µA+，配合声控灯等电池供电产品场景；从 README 的应用类型看，低功耗是声控灯（AD248A/AD248B）选型的关键考量。

存储与接口

支持内置/外置 FLASH，覆盖代码存储与音频资源存放；I2S 接口（部分型号）支持数字音频输入输出，可外接 Codec 或数字功放；内置 16bit DAC + 16bit ADC 支持 8K–96K 采样率，配合 Class-D 功放直驱喇叭，降低 BOM 成本。

工程结构

SDK 主目录为 sdk/，整体结构如下（依据 README.md）：

fw-AD24N/
├── sdk/                           # SDK 主目录
│   ├── app/                       # 应用层代码
│   │   ├── src/                   #   应用入口源码
│   │   │   ├── voice_toy/         #     语音玩具应用
│   │   │   ├── voice_func/        #     语音功能模块
│   │   │   └── voice_enhanced/    #     扩音器应用
│   │   ├── bsp/                   #   板级支持包（BSP）
│   │   └── post_build/            #   编译后处理脚本与工具
│   ├── include_lib/               # 头文件与预编译库
│   │   ├── cpu/                   #   CPU 平台头文件
│   │   ├── decoder/               #   解码器 API 头文件
│   │   ├── encoder/               #   编码器 API 头文件
│   │   ├── audio/                 #   音频 API 头文件
│   │   ├── device/                #   设备驱动头文件
│   │   ├── dev_mg/                #   设备管理头文件
│   │   ├── common/                #   公共头文件
│   │   ├── fs/                    #   文件系统头文件
│   │   ├── msg/                   #   消息机制
│   │   ├── ans/                   #   ANS 降噪
│   │   ├── vo_changer/            #   变声算法
│   │   ├── vo_pitch/              #   变调算法
│   │   ├── update/                #   固件升级
│   │   └── liba/                  #   预编译库 (.a)
│   ├── tools/                     # 编译工具与脚本
│   │   ├── make_prompt.bat        #   Windows 编译命令行入口
│   │   └── utils/                 #   工具集（make、rm 等）
│   ├── Makefile                   # 顶层 Makefile
│   └── *.cbp                      # Code::Blocks 工程文件
├── doc/                           # 文档（硬件文档、SDK 手册、发布版本信息、用户手册、选型表）
└── README.md

include_lib 中间件模块

include_lib/ 是 SDK 的核心资产，以「公开 API 头文件 + 预编译 lib.a」形式提供：

模块	职责
`cpu/`	CPU 平台抽象与启动相关头文件
`decoder/` `encoder/`	音频解码/编码 API
`audio/`	音频通路、播放控制 API
`device/` `dev_mg/`	设备驱动与设备管理框架
`common/`	公共类型与工具
`fs/`	文件系统抽象（本地/外置 FLASH）
`msg/`	消息机制（事件分发）
`ans/` `vo_changer/` `vo_pitch/`	音效算法库
`update/`	固件升级
`liba/`	预编译库文件（.a）

核心开发流程

从零开始到固件上板，完整流程如下：

flowchart TD
    Start([开始]) --> Clone["git clone 仓库"]
    Clone --> Env{"环境就绪?"}
    Env -->|"否"| Setup["安装杰理编译工具链 / 烧录工具"]
    Setup --> Env
    Env -->|"是"| Choose{"选择应用工程"}
    Choose -->|"语音玩具"| Toy["AD24N_voice_toy.cbp / make ad24n_voice_toy"]
    Choose -->|"扩音器"| Enh["AD24N_voice_enhanced.cbp / make ad24n_voice_enhanced"]
    Toy --> Modify["修改 app/src 应用代码"]
    Enh --> Modify
    Modify --> Build{"编译通过?"}
    Build -->|"否"| Modify
    Build -->|"是"| Flash["USB 升级工具烧录"]
    Flash --> Verify["目标板验证"]
    Verify --> End([结束])

各环节要点：

克隆：git clone https://gitee.com/Jieli-Tech/AD24N.git，进入 sdk/ 目录；
环境：Windows 推荐 Code::Blocks IDE；Linux 使用 Makefile 命令行（需将工具链解压至 /opt/jieli，保证 clang 可用，并调大 ulimit -n）；macOS 需自行配置交叉编译工具链；
选工程：两个应用工程均覆盖 AD24N 全系列芯片；
修改：产品逻辑集中在 sdk/app/src/voice_toy/ 或 sdk/app/src/voice_enhanced/；
烧录：使用 USB 升级工具（开发）或生产烧写工具（量产/裸片）。

使用示例

克隆与编译（快速开始）

仓库 README 给出的标准入口，克隆后进入 sdk/ 即可直接编译：

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

来源：README.md

命令行编译方式（Linux/Windows make_prompt.bat 环境）：

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

# 编译语音玩具
make ad24n_voice_toy -j4

# 编译语音增强
make ad24n_voice_enhanced -j4

来源：README.md

顶层 Makefile 目标

sdk/Makefile 是构建系统入口，负责分发到各子工程 Makefile：

# 支持的目标
# make ad24n_voice_enhanced
# make ad24n_voice_toy

.PHONY: all clean ad24n_voice_enhanced ad24n_voice_toy clean_ad24n_voice_enhanced clean_ad24n_voice_toy

all: ad24n_voice_enhanced ad24n_voice_toy
	@echo +ALL DONE

clean: clean_ad24n_voice_enhanced clean_ad24n_voice_toy
	@echo +CLEAN DONE

ad24n_voice_enhanced:
	$(MAKE) -C . -f Makefile.ad24n_voice_enhanced

ad24n_voice_toy:
	$(MAKE) -C . -f Makefile.ad24n_voice_toy

来源：sdk/Makefile

设计意图：顶层 Makefile 通过 $(MAKE) -C . -f Makefile.<target> 复用 GNU Make 的递归构建机制，将每个应用工程隔离为独立的 Makefile.ad24n_voice_toy / Makefile.ad24n_voice_enhanced，保证两个应用可并行开发、独立清理，互不污染。

工具链验证

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

来源：README.md

配置选项

构建目标

目标	命令	说明
编译全部	`make all`	依次构建 voice_enhanced 与 voice_toy
语音玩具	`make ad24n_voice_toy -j4`	构建语音玩具应用固件
扩音器	`make ad24n_voice_enhanced -j4`	构建扩音器应用固件
清理全部	`make clean`	清理两个子工程产物
清理单个	`make clean_ad24n_voice_toy` / `make clean_ad24n_voice_enhanced`	按工程清理

环境相关配置

项	取值	说明
Linux 工具链路径	`/opt/jieli/pi32/bin/clang`	保证 `clang` 可执行
Linux 链接文件数上限	`ulimit -n` 建议 > 8096	否则链接可能因打开文件过多失败
Code::Blocks 工程	`sdk/*.cbp`	Windows 图形化编译入口
VS Code 任务	预配置	`Ctrl+Shift+B` 选择编译目标

环境说明来源：README.md；ulimit 提示来源：sdk/Makefile。

失败模式与边界情况

工具链缺失/路径错误：Linux 下未将工具链解压到 /opt/jieli 或 clang 路径不对，编译将直接失败。按 README 要求确保 /opt/jieli/pi32/bin/clang 存在（顶层 Makefile 注释中提示需保证 /opt/jieli/common/bin/clang 存在，注意目录层次，两者以实际安装为准）。
链接期打开文件过多：ulimit -n 过小时，链接阶段会因打开文件数量超限失败；通过 ulimit -n 8096 调大。
平台差异：download_bat.c 脚本按 Windows 环境编写，Linux 下使用 Makefile 命令行编译需要重写该脚本适配；macOS 需自行配置交叉编译工具链，无现成开箱支持。
库文件匹配：仓库仅含 SDK Release 代码与示例工程，必须配合对应命名规则的库文件（lib.a）编译，库版本不匹配可能导致链接错误或运行异常。
变速变调时钟限制：变速变调播放要求系统时钟 100MHz 以上，低时钟配置下该功能不可用。

性能与运维注意

DSP 主频 240MHz，双发射架构，承担三路并发解码与音效处理；资源敏感应用需评估解码路数与音效链叠加后的算力余量。
内置 Codec 支持 8K–96K 采样率，硬件 SRC 负责采样率转换，避免软件重采样占用 CPU。
低功耗指标（关机 2µA+、休眠 19µA+）为芯片级目标值，实际整机功耗取决于外围电路与唤醒源配置。
固件升级依赖 update/ 模块与 USB 升级工具；量产场景使用生产烧写工具，流程不同，见「烧录与升级」页面。

扩展点

新增应用工程：参照 Makefile.ad24n_voice_toy 的结构，在顶层 sdk/Makefile 的 .PHONY 与目标规则中追加 Makefile.ad24n_<app> 即可接入构建系统。
应用层扩展：app/src/voice_func/ 是应用间共享的语音功能模块，新功能可在此沉淀，供 voice_toy 与 voice_enhanced 复用。
板级适配：app/bsp/ 提供板级支持包，更换硬件平台（不同封装型号/外设）时主要修改 BSP 层，上层应用与中间件 API 无需变动。
编译后处理：app/post_build/ 提供编译后脚本与工具，可用于固件打包、资源合并等定制流程。