AD23N SDK 概述与芯片平台

fw-AD23N_GP-MCU_SDK 是杰理科技（Jieli）为 AD23N 系列芯片提供的通用 MCU SDK 固件开发包，面向语音玩具、小音箱与通用 MCU 三大应用场景，内置 NPU、DSP+FPU、多格式音频解码与多种音效算法支持。

Purpose and Scope

本文档介绍 AD23N SDK 的整体能力与芯片平台概况，帮助开发者在阅读具体源码之前建立全局认知。页面覆盖以下内容：

  • SDK 定位、应用场景与核心特性（NPU、DSP+FPU、音频解码、音效算法、低功耗等）
  • AD23N 系列 SoC 型号（AD232A/AD232S/AD235A/AD236A/AD236B、AD238A/AD238B）与平台差异
  • SDK 工程目录结构（sdk/ 与 doc/）及各目录职责
  • 从克隆、编译到烧录的完整开发流程
  • 配置入口与常见开发问题

以下主题属于其他目录页面的范畴，本文只做指向、不展开：解码器/编码器具体 API（见 decoder/encoder 相关页面）、文件系统实现（SydFs/NorFs/FreeFs/FATFS）、各音效算法（ANS/变调/变声/EQ）、固件 OTA 升级机制、烧录工具使用细节。工程内部各模块（include_lib/ 下的 CPU、audio、device、power、update 等）在各自页面详述。

概述

fw-AD23N_GP-MCU_SDK 是 AD23N 系列芯片的通用 MCU SDK 发布包，仓库同时包含 SDK Release 版本代码与示例工程，需配合对应命名规则的预编译库（lib.a）进行链接编译。SDK 面向的典型产品如下：

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

来源：README.md 概述章节

核心特性速览

SDK 依赖芯片硬件能力提供以下关键特性（均为 README 声明、由芯片平台支撑的硬件/软件能力）：

  • NPU 神经网络加速：内置 NPU，支持 AI 语音算法加速
  • DSP + FPU：32bit 双发射 DSP @ 288MHz，集成 IEEE754 单精度硬件浮点单元
  • 大容量 SRAM：184KB 片上 SRAM（含 32KB 共享 Cache），支持 MMU/MPU
  • 多格式音频解码：支持 .a/.b/.e、.f1a/.f1b/.f1c、UMP3、MP3、WAV 等
  • MIDI 播放：支持 MIDI 合成与播放
  • 三路解码：.a/.b/.e + .f1a/.f1b/.f1c + .f1a/.f1b/.f1c 三路音频同时解码播放
  • 高保真音频：16bit DAC（SNR 110dB）+ 16bit ADC（SNR 93dB），支持 8K–96K 采样率
  • Class-D 功放：1.2W@4Ω 直驱喇叭
  • I2S/PDM 接口：支持数字音频输入输出
  • 硬件重采样：内置硬件 SRC
  • 音效算法：ANS 降噪、变速、ECHO 混响、vo_pitch 变调、voice_changer 变声、PCM 浮点 EQ
  • 低功耗：软关机 <3µA
  • 多种存储：支持内置/外置 NOR Flash，SydFs/NorFs/FreeFs/FATFS 文件系统
  • DAC 输出：支持差分和单端输出，可外接功放

架构

系统架构总览

以下架构图展示了 SDK 从硬件平台到应用层的分层关系，节点名称均取自 README 与工程结构中的真实组件：

flowchart TD
    subgraph sg_App["应用层 (sdk/app)"]
        App["app/src/mbox_flash<br/>小音箱/音频播放应用"]
        BSP["app/bsp<br/>板级支持包"]
        PB["app/post_build<br/>编译后处理脚本"]
    end

    subgraph sg_Include["中间件与驱动层 (sdk/include_lib)"]
        CPU["cpu 平台头文件"]
        Decoder["decoder 解码器 API"]
        Encoder["encoder 编码器 API"]
        Audio["audio 音频 API"]
        Device["device 设备驱动"]
        DevMg["dev_mg 设备管理"]
        FS["fs 文件系统"]
        Msg["msg 消息机制"]
        ALG["算法: ans / pcm_eq_float<br/>vo_changer / vo_pitch"]
        Update["update 固件升级"]
        Power["power 电源管理"]
        LibA["liba 预编译库 (.a)"]
    end

    subgraph sg_Chip["芯片平台 (AD23N 系列 SoC)"]
        NPU["NPU 神经网络加速"]
        DSP["32bit 双发射 DSP @ 288MHz + FPU"]
        SRAM["184KB SRAM (含 32KB 共享 Cache)"]
        AudioHW["DAC/ADC/Class-D/I2S/PDM/SRC"]
        Store["内置/外置 NOR Flash"]
    end

    App --> BSP
    App --> PB
    App --> CPU
    App --> Msg
    App --> Decoder
    App --> Encoder
    App --> Audio
    App --> Device
    App --> DevMg
    App --> FS
    App --> ALG
    App --> Update
    App --> Power
    App --> LibA
    CPU --> DSP
    Audio --> AudioHW
    ALG --> NPU
    FS --> Store
    Device --> Store
    Update --> Store
    Power --> SRAM

架构说明

  • 应用层是开发者主要修改的区域：app/src/mbox_flash/ 为小音箱/音频播放应用入口，app/bsp/ 提供板级初始化，app/post_build/ 负责编译后的固件打包处理。
  • 中间件与驱动层以头文件 + 预编译库（liba/）形式提供，开发者通过 include_lib/ 下各目录的 API 头文件调用能力，不必关心库内部实现；这也是 SDK 需要"对应命名规则的 lib.a 库文件"才能编译的原因。
  • 芯片平台是能力的物理基础：NPU 加速 AI 语音算法、DSP+FPU 执行音频处理、184KB SRAM 支撑多路解码、DAC/ADC/Class-D/I2S/PDM/SRC 完成模拟与数字音频通路、NOR Flash 承载固件与文件系统。

芯片平台：AD23N 系列 SoC

支持型号

SDK 为 AD23N 全系列芯片预配置了统一的编译入口（AD23N_mbox_flash.cbp），开发者只需在配置中选择对应芯片型号即可：

芯片系列应用领域
AD232A / AD232S / AD235A / AD236A / AD236B语音玩具 / 小音箱 / 通用 MCU
AD238A / AD238B语音控制 / 音频播放（SOP8 最小封装）

芯片型号/规格书/原理图资料请查阅仓库 doc/ 目录；芯片差异示意图见根目录 jl_ad_chip.png。来源：README.md 芯片章节

平台能力分层

AD23N 平台的硬件能力可归纳为四个维度，SDK 的软件模块按此分层组织：

  1. 计算单元：NPU（AI 语音算法加速）、32bit 双发射 DSP @ 288MHz、IEEE754 单精度 FPU、MMU/MPU 内存保护
  2. 存储单元：184KB 片上 SRAM（含 32KB 共享 Cache），内置/外置 NOR Flash，多文件系统支持
  3. 音频通路：16bit DAC（SNR 110dB）、16bit ADC（SNR 93dB）、Class-D 功放（1.2W@4Ω）、I2S/PDM 数字接口、硬件 SRC 重采样、差分/单端 DAC 输出
  4. 低功耗机制：软关机 <3µA，配合电源管理模块（include_lib/power/）实现待机控制

SDK 工程结构

仓库根目录除 README.md、LICENSE、发布版本信息 PDF 与芯片示意图外，主体为 sdk/ 与 doc/ 两个目录。工程结构如下（摘自 README 工程结构章节）：

fw-AD23N/
├── sdk/                           # SDK 主目录
│   ├── app/                       # 应用层代码
│   │   ├── src/                   #   应用入口源码
│   │   │   └── mbox_flash/        #     小音箱/音频播放应用
│   │   ├── bsp/                   #   板级支持包（BSP）
│   │   └── post_build/            #   编译后处理脚本与工具
│   ├── include_lib/               # 头文件与预编译库
│   │   ├── cpu/                   #   CPU 平台头文件
│   │   ├── decoder/               #   解码器 API 头文件
│   │   ├── encoder/               #   编码器 API 头文件
│   │   ├── audio/                 #   音频 API 头文件
│   │   ├── device/                #   设备驱动头文件
│   │   ├── dev_mg/                #   设备管理头文件
│   │   ├── common/                #   公共头文件
│   │   ├── fs/                    #   文件系统头文件
│   │   ├── msg/                   #   消息机制
│   │   ├── ans/                   #   ANS 降噪
│   │   ├── pcm_eq_float/          #   浮点 PCM EQ
│   │   ├── vo_changer/            #   变声算法
│   │   ├── vo_pitch/              #   变调算法
│   │   ├── update/                #   固件升级
│   │   ├── power/                 #   电源管理
│   │   └── liba/                  #   预编译库 (.a)
│   ├── tools/                     # 编译工具与脚本
│   │   ├── make_prompt.bat        #   Windows 编译命令行入口
│   │   └── utils/                 #   工具集（make、rm 等）
│   ├── Makefile                   # 顶层 Makefile
│   └── *.cbp                      # Code::Blocks 工程文件
├── doc/                           # 文档
│   ├── AD23N硬件资料/              #   硬件文档（规格书/原理图/开发板资料）
│   ├── stuff/                     #   杂项（钉钉群、烧录工具文档等）
│   ├── AD23N_SDK手册_v1.0.pdf     #   SDK 手册
│   ├── AD23N_SDK_发布版本信息.pdf  #   SDK 发布版本信息
│   ├── AD23N用户手册V1.1.pdf       #   芯片用户手册
│   └── 杰理科技32位AD系列语音MCU选型表.pdf  # 芯片选型表
└── README.md                      # 本文件

来源：README.md 工程结构章节

关键目录职责

  • sdk/app/src/mbox_flash/：唯一预置应用工程，对应 AD23N_mbox_flash.cbp，覆盖音乐播放、MIDI 演奏、录音、USB Device、LINEIN、扩音等功能；新工程建议基于该工程与应用代码修改。
  • sdk/include_lib/liba/：预编译库目录。编译时若报 cannot find -lxxx，应检查该目录是否缺少对应 .a 库文件——这是 SDK"库文件 + 头文件"发布模式的核心。
  • sdk/tools/make_prompt.bat：Windows 下预配置的编译命令行环境，已设置好环境变量与 make 路径，解决"make 不是有效命令"问题。
  • doc/：存放芯片选型表、用户手册、SDK 手册与发布版本信息，是获取硬件规格的一手资料。

开发环境与快速开始

工具链前提

系统说明
Windows推荐使用 Code::Blocks IDE 编译
LinuxMakefile 命令行编译（需重写 download_bat.c 脚本适配 Linux 环境）
macOS需自行配置交叉编译工具链

工具链要求：

  1. 安装杰理编译工具链（Linux 下解压到 /opt/jieli，确保 /opt/jieli/pi32/bin/clang 存在）
  2. 安装烧录工具：USB 升级工具（开发烧录）与生产烧写工具（量产/裸片烧写，需向代理商获取）

来源：README.md 环境搭建章节

克隆与工程入口

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

来源：README.md 快速开始章节

SDK 包含以下应用工程，位于 sdk/ 根目录：

工程文件芯片应用类型
AD23N_mbox_flash.cbpAD23N 全系列小音箱 / 语音玩具 / MIDI 琴

应用代码入口为 sdk/app/src/mbox_flash/，其功能矩阵包括：音乐播放（本地/外置 FLASH，支持 .a/.b/.e、.f1a/.f1b/.f1c、UMP3、MP3、WAV 等格式）、MIDI 演奏、录音、USB Device、LINEIN 线路输入与扩音/喊话。

核心流程：编译与烧录

端到端开发流程

从克隆仓库到固件上板的完整流程如下图所示（节点均为 README 中实际步骤）：

flowchart TD
    Start([开始]) --> Clone["git clone 仓库<br/>cd AD23N/sdk"]
    Clone --> Toolchain{"工具链已安装?"}
    Toolchain -->|"否"| Install["安装杰理编译工具链<br/>/opt/jieli/pi32/bin/clang"]
    Install --> Verify["验证: clang --version"]
    Toolchain -->|"是"| PickEnv{"选择编译方式"}
    Verify --> PickEnv
    PickEnv -->|"Windows"| CB["Code::Blocks 打开<br/>AD23N_mbox_flash.cbp"]
    PickEnv -->|"命令行"| Make["make_prompt.bat 环境<br/>make -j4"]
    CB --> Build["编译 (Build / Ctrl+F9)"]
    Make --> Build
    Build --> Firmware["生成固件 (post_build 目录)"]
    Firmware --> Burn["USB 升级工具烧录"]
    Burn --> Done([固件上板运行])

编译命令速查

以下命令在 sdk/ 目录下执行：

目标命令
编译make -j4
编译（verbose）make VERBOSE=1 -j4
清理make clean

方式一：Code::Blocks（推荐 Windows 用户）——双击 AD23N_mbox_flash.cbp 打开工程，Build → Build（Ctrl+F9）编译，成功后固件生成在 post_build/ 目录。

方式二：Makefile 命令行：

# Windows 用户：双击 sdk/make_prompt.bat 打开命令行环境
# 编译
make -j4

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

来源：README.md 编译指南章节

方式三：VS Code——仓库已预配置 VS Code 任务，按 Ctrl+Shift+B 选择编译目标。

烧录与升级时序

sequenceDiagram
    participant Dev as 开发者
    participant Board as 目标板
    participant Tool as USB 升级工具
    participant PC as 烧录上位机

    Dev->>Board: 连接硬件 (USB / USB 升级工具)
    Dev->>Board: 按住烧录按键并复位/上电 (进入编程模式)
    Board-->>Tool: 枚举为编程设备
    Dev->>PC: 启动烧录上位机
    Dev->>PC: 选择编译生成的固件文件
    PC->>Tool: 点击下载
    Tool->>Board: 传输固件数据
    Board-->>Dev: 烧录完成

烧录前需确认：USB 升级工具正确连接、目标板已进入编程模式。量产场景改用杰理生产烧写工具（一拖二/一拖八）支持裸片烧写；运行时支持双备份固件 OTA 升级。固件配置涉及 ISD_CONFIG.INI，详见杰理在线文档的 ISD 配置说明。

使用示例

示例一：验证工具链安装

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

来源：README.md 环境搭建章节

示例二：命令行编译固件

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

# 编译
make -j4

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

来源：README.md 快速开始章节

示例三：Linux 环境并行编译

# Linux 用户（需要自行修改 download_bat.c 文件适配 Linux）
cd sdk
make -j`nproc`

来源：README.md 编译指南章节

示例四：克隆并进入工程

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

来源：README.md 快速开始章节

配置说明

应用功能配置

SDK 的功能开关集中在应用配置头文件，编辑 sdk/app/src/mbox_flash/app_config.h 可配置目标应用的功能开关（如解码格式、外设使能、算法开关等）。芯片型号切换同样在配置中选择，SDK 已为全系列预配置统一的编译入口。

来源：README.md 配置说明章节

配置入口类型说明
app_config.h头文件宏目标应用功能开关，编译期生效
芯片型号选择编译配置在配置中切换 AD232A/AD232S/AD235A/AD236A/AD236B/AD238A/AD238B
ISD_CONFIG.INI烧录配置USB 升级工具下载配置，详见杰理在线文档
download_bat.c脚本Linux 环境编译需重写以适配下载流程

失败模式与常见问题

编译期错误

错误提示原因解决方法
clang: command not found未安装杰理编译工具链，或环境变量未配置安装工具链并确保 /opt/jieli/pi32/bin/clang 存在
cannot find -lxxx缺少对应的 .a 库文件检查 include_lib/liba/ 目录
make: command not foundWindows 下 make 未加入 PATH使用 tools/make_prompt.bat 打开编译命令环境
链接错误Makefile target 与当前芯片型号不匹配检查 Makefile target 是否匹配当前芯片型号

来源：README.md 常见编译错误章节

烧录阶段注意事项

  • 烧录前必须确保 USB 升级工具正确连接且目标板已进入编程模式（按住烧录按键后复位或重新上电）
  • 首次烧录与量产烧写使用不同工具：开发用 USB 升级工具，量产用生产烧写工具（一拖二/一拖八，支持裸片烧写）
  • 编译前确认目标板已进入编程模式，否则下载会失败

调试技巧

  • 串口日志：通过 UART 输出调试日志
  • GPIO Debug：利用空闲 GPIO 输出调试波形，测量时序

来源：README.md 调试技巧章节

性能与运维要点

  • 并行编译：使用 make -j4（或 -j\nproc`）并行编译可显著加快构建速度；make VERBOSE=1` 用于查看详细编译日志排查问题。
  • 三路解码能力：平台支持三路音频同时解码，多路播放场景下 184KB SRAM 与硬件 SRC 是资源规划的关键约束，新增播放任务前需评估内存占用。
  • 低功耗设计：软关机电流 <3µA，依赖 include_lib/power/ 电源管理模块；量产产品需结合睡眠唤醒路径验证功耗。
  • 固件升级：运行时支持双备份 OTA 升级（include_lib/update/），可降低升级失败导致的变砖风险；生产阶段使用专业烧写工具保证裸片烧录一致性。

扩展点

  • 新建应用工程：基于现有 .cbp 工程和 app/src/ 中的应用代码修改，配置对应用例即可，无需改动底层库。
  • 切换芯片型号：AD23N 全系列共用统一编译入口，通过配置选择型号，SDK 自动匹配平台头文件（include_lib/cpu/）与预编译库。
  • 算法接入：ANS 降噪、vo_pitch 变调、voice_changer 变声、PCM 浮点 EQ 等以头文件 API 形式暴露在 include_lib/ 对应目录，应用层可通过配置开关启用/组合。
  • 文件系统选型：支持 SydFs/NorFs/FreeFs/FATFS，应用可依据存储介质（内置/外置 NOR Flash）与兼容性需求选择。

相关链接