环境搭建与开发工具链

本文档介绍杰理科技 AD24N 系列通用 MCU SDK（fw-AD24N_GP-MCU_SDK）的开发环境搭建方法、编译工具链安装与验证、构建方式（Code::Blocks / Makefile / VS Code）、烧录工具选型，以及 SDK 工程入口结构，帮助开发者在 Windows、Linux、macOS 三种主机平台上从零开始完成可编译、可烧录的开发环境。

目的与范围

本页聚焦「开发前的环境准备与工具链」这一能力边界，覆盖：

• 主机操作系统（Windows / Linux / macOS）的前提条件与差异
• 杰理编译工具链（clang / pi32 交叉编译器）的下载、安装与验证
• 固件烧录工具（USB 升级工具、生产烧写工具）与音频工具链
• 三种编译入口：Code::Blocks 工程（.cbp）、Makefile 命令行、VS Code 任务
• SDK 顶层工程结构、应用工程入口与编译目标

以下主题属于其他目录页的范围，本页不展开：应用功能开发细节（语音玩具、扩音器应用实现）、芯片寄存器与外设编程、烧录协议的底层实现、量产产线流程。相关主题可参考本文末尾的「相关链接」。

概述

fw-AD24N_GP-MCU_SDK 是杰理科技面向 AD24N 系列芯片发布的通用 MCU SDK 固件开发包，目标场景包括语音玩具（故事机、学习机、语音遥控玩具、MIDI 乐器、声控灯）、小音箱（音乐播放器、扩音器）以及通用 MCU（智能控制、传感器采集、外设应用）。芯片核心为一颗 32bit 双发射 DSP @ 240MHz，内置 16bit DAC + 16bit ADC（8K–96K 采样率）、Class-D 功放、硬件 SRC，支持 .a/.b/.e、.f1a/.f1b/.f1c、UMP3 等多种音频格式及三路同时解码，并内置 ANS 降噪、变速变调、ECHO 混响、变声、PCM EQ 等音效算法（详见 README.md）。

SDK 采用 「源码 + 预编译库」 的分发模式：仓库内含 Release 版本应用源码与头文件，编译时必须配合对应命名规则的库文件（lib.a） 才能链接出最终固件。这意味着工具链版本与 lib.a 的 ABI 必须匹配，环境搭建的核心任务就是把杰理提供的交叉编译工具链正确安装并接入构建系统。

支持的芯片系列

（芯片型号/规格书/原理图资料见仓库 doc/ 目录，详见 README.md）

架构

下图展示从开发主机到目标板的完整工具链架构：三种编译入口最终都汇入顶层构建系统，构建系统调用杰理交叉工具链 clang 链接预编译库 lib.a 与应用源码，产出固件后经 USB 升级工具烧录到 AD24N 目标板。

flowchart TD
    subgraph sg_Host["开发主机"]
        OS["Windows / Linux / macOS"]
        CB["Code::Blocks IDE (.cbp)"]
        MK["Makefile 命令行 (make_prompt.bat)"]
        VS["VS Code 任务 (Ctrl+Shift+B)"]
    end

    subgraph sg_Toolchain["编译工具链"]
        CLANG["杰理编译工具链 clang (pi32)"]
        LIB["预编译库 lib.a (按命名规则)"]
    end

    subgraph sg_SDK["AD24N SDK 工程"]
        APP["app/src 应用源码"]
        INCLIB["include_lib 头文件"]
        MAKEFILE["顶层 Makefile / .cbp"]
    end

    subgraph sg_Target["烧录与目标板"]
        FW["固件产物"]
        USB["USB 升级工具"]
        BOARD["AD24N 目标板"]
    end

    OS --> CB
    OS --> MK
    OS --> VS
    CB --> MAKEFILE
    MK --> MAKEFILE
    VS --> MAKEFILE
    MAKEFILE --> CLANG
    CLANG --> LIB
    MAKEFILE --> APP
    MAKEFILE --> INCLIB
    MAKEFILE --> FW
    FW --> USB
    USB --> BOARD

架构要点：

• 构建入口统一性：Code::Blocks、Makefile、VS Code 三者共享同一套 SDK 构建规则（顶层 Makefile 与 .cbp 工程），切换 IDE 不改变产物与链接流程，方便团队协作时按个人习惯选择工具。
• 工具链前置性：clang（pi32 交叉编译器）是唯一的编译器来源，必须先安装并进入 PATH（或固定路径），构建系统才能解析头文件并链接 lib.a。
• 预编译库耦合：include_lib/liba/ 下的 .a 文件带命名规则（与芯片/应用类型相关），工具链版本与库 ABI 不匹配时会出现链接错误，这是环境问题排查的第一优先方向。
• 烧录闭环：固件产物必须通过杰理 USB 升级工具（目标板进入编程模式）写入，工具链的终点是目标板而非单纯的编译产物。

开发环境与工具链详解

主机平台支持

SDK 官方支持的主机平台与推荐方式如下（详见 README.md）：

设计意图：SDK 面向嵌入式量产场景，Windows + Code::Blocks 是官方验证过的「零配置」路径；Linux 用户多为 CI/服务器批量编译场景，因此 Makefile 是完整的一等公民；macOS 属非官方路径，需开发者自行解决工具链路径与下载脚本的兼容性。

编译工具链安装

杰理编译工具链（内含 pi32 架构的 clang 交叉编译器）是编译 AD24N 固件的唯一编译器，安装步骤如下（详见 README.md）：

1. 下载工具链：从杰理文档中心的开发环境页面获取安装包（dev_tools/dev_env）。
2. Linux 安装方式：从 pkgman.jieliapp.com 下载，解压到 /opt/jieli 目录，并确保 /opt/jieli/pi32/bin/clang 存在——构建系统会按此固定路径查找编译器。
3. 验证安装：执行 clang --version 确认工具链可用。

关键点：Linux 下工具链的安装路径是固定约定（/opt/jieli/pi32/bin/clang），而不是仅依赖 PATH。这是因为 SDK 的 Makefile/工程文件按该绝对路径引用编译器。若自定义路径，需要同步修改构建配置，否则会出现 "clang not found" 类错误。

烧录工具

（详见 README.md）

两者的分工体现了开发/量产两条烧录路径：开发期使用 USB 升级工具快速迭代；量产期使用代理商的专用烧写器保证裸片/大批量场景的稳定与效率。

音频工具

打包、音频文件转换、MIDI 等通用音频工具从百度网盘获取（提取码 3jey，详见 README.md）。这类工具用于把 .wav/.mp3 等素材转换为 SDK 支持的 .a/.b/.e、.f1a/.f1b/.f1c、UMP3 格式，并完成资源打包，是语音玩具类产品素材准备的必要环节。

SDK 工程入口与结构

SDK 主目录为 sdk/，包含两个应用工程（详见 README.md）：

应用源码位于 sdk/app/src/：

sdk/app/src/
├── voice_toy/          # 语音玩具应用
├── voice_func/         # 语音功能模块
└── voice_enhanced/     # 扩音器应用

顶层工程结构（详见 README.md）：

fw-AD24N/
├── sdk/                           # SDK 主目录
│   ├── app/                       # 应用层代码
│   │   ├── src/                   #   应用入口源码（voice_toy / voice_func / voice_enhanced）
│   │   ├── bsp/                   #   板级支持包（BSP）
│   │   └── post_build/            #   编译后处理脚本与工具
│   ├── include_lib/               # 头文件与预编译库
│   │   ├── cpu/                   #   CPU 平台头文件
│   │   ├── decoder/ encoder/ audio/ device/ dev_mg/ common/
│   │   ├── fs/ msg/ 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

设计意图：SDK 采用「应用层（app/）— 库层（include_lib/）— 构建层（Makefile + tools/）」三层分离。开发者日常只修改 app/src/ 下的应用代码，芯片驱动与算法以头文件 + 预编译库形式提供，既保护了核心算法知识产权，又保证了多工程（voice_toy / voice_enhanced）间的代码复用。

核心流程

环境搭建流程

flowchart TD
    A["下载杰理编译工具链"] --> B{"主机操作系统?"}
    B -->|"Windows"| C["安装程序安装 / Code::Blocks"]
    B -->|"Linux"| D["解压到 /opt/jieli，确认 clang 路径"]
    B -->|"macOS"| E["自行配置交叉编译工具链"]
    C --> V["验证 clang --version"]
    D --> V
    E --> V
    V --> R["准备 USB 升级工具"]
    R --> S["克隆仓库并开始编译"]

编译与烧录流程

flowchart TD
    Start(["git clone 仓库"]) --> Pick{"选择编译方式"}
    Pick -->|"Code::Blocks (Windows)"| CBP["打开 .cbp 工程文件"]
    Pick -->|"Makefile 命令行"| MAK["make ad24n_voice_toy -j4"]
    Pick -->|"VS Code"| VS["Ctrl+Shift+B 选择编译目标"]
    CBP --> Build["执行编译"]
    MAK --> Build
    VS --> Build
    Build --> Out{"编译成功?"}
    Out -->|"否"| Fix["检查工具链路径 / lib.a 匹配 / 工程配置"]
    Fix --> Build
    Out -->|"是"| Flash["USB 升级工具烧录固件"]
    Flash --> Run["目标板运行验证"]

流程要点：

• 编译前必须保证 USB 升级工具已正确连接且目标板进入编程模式（README 明确提示，见 README.md）。
• 三种编译方式产出同一固件，Code::Blocks 与 VS Code 底层仍走同一套 Makefile 规则，因此团队内混用 IDE 不会产生构建差异。
• 编译失败时优先排查「工具链路径 → lib.a 命名/ABI 匹配 → 工程配置」三层，避免在应用代码上浪费时间。

使用示例

以下示例均提取自仓库 README，可直接用于搭建与验证环境。

克隆仓库

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

Source: README.md

克隆后进入 sdk/ 目录——所有工程文件（.cbp）、顶层 Makefile、tools/ 脚本均位于此目录，它是构建的唯一工作目录。

验证编译工具链

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

Source: README.md

Linux 用户若 clang 不在 PATH，应确认 /opt/jieli/pi32/bin/clang 是否存在，并将 /opt/jieli/pi32/bin 加入 PATH 或建立符号链接。

Makefile 命令行编译

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

# 编译语音玩具
make ad24n_voice_toy -j4

# 编译语音增强
make ad24n_voice_enhanced -j4

Source: README.md

make_prompt.bat（位于 sdk/tools/）为 Windows 用户准备了带 make/rm 工具集的命令行环境，避免手工配置 PATH；-j4 启用 4 路并行编译以缩短构建时间。

Code::Blocks 图形化编译（Windows 推荐）

1. 双击打开对应的 .cbp 工程文件（AD24N_voice_toy.cbp 或 AD24N_voice_enhanced.cbp）
2. 点击 Build → Build（Ctrl+F9）
3. 编译成功后，使用 USB 升级工具烧录生成的固件

Source: README.md

VS Code 编译

仓库已预配置 VS Code 任务，按 Ctrl+Shift+B 即可选择编译目标（ad24n_voice_toy / ad24n_voice_enhanced），适合偏好现代编辑器的开发者。

Source: README.md

配置选项

编译目标（Makefile / VS Code 任务）

（详见 README.md 与 README.md）

环境级配置项

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

以下问题在 README 及工程结构中有明确证据，是环境搭建阶段最常见的失败点：

并发/一致性说明：-j4 并行编译下，Makefile 依赖关系已保证头文件与库的生成顺序一致，多工程（voice_toy / voice_enhanced）共享同一 include_lib，不建议同时修改 include_lib 与执行并行构建，避免头文件/库处于中间状态导致偶发编译错误。

性能与运维说明

• 构建性能：-j4 并行编译是官方示例的推荐参数；语音玩具与扩音器两个工程共享库层，增量编译只重编应用层，日常迭代速度较快。
• 工具链唯一性：编译器来源唯一（杰理 clang），不要混用宿主系统 GCC 编译 SDK 源码，否则会出现 ABI/内建头文件不兼容问题。
• 文档与版本：SDK 版本历史见 AD24N_SDK_发布版本信息.pdf，正式开发前应核对工具链版本与 SDK 版本配套关系。
• 网络依赖：Linux 工具链经 pkgman 下载，内网/离线环境需提前将工具链与音频工具包离线分发到构建机。

扩展点

• 新增应用工程：可仿照 AD24N_voice_toy.cbp / AD24N_voice_enhanced.cbp 新建 .cbp，并在顶层 Makefile 增加对应目标，应用代码放于 sdk/app/src/<app_name>/。
• 板级适配：sdk/app/bsp/ 为板级支持包，更换开发板时在此层适配引脚/外设配置，无需改动库层。
• 编译后处理：sdk/app/post_build/ 存放编译后处理脚本与工具，可扩展固件打包、校验、自动烧录等步骤。
• Linux 下载适配：重写 download_bat.c 使下载/烧录环节跨平台，是 Linux 环境的标准扩展点（README 明确指出需要改写）。

测试说明

本仓库为 SDK Release 代码仓库，未包含自动化单元测试工程；环境验证以「编译成功 + 烧录后目标板运行」为验收标准。README 的快速开始章节提供了从克隆到烧录的完整可执行步骤，可作为环境就绪性的冒烟测试流程（见 README.md）。

相关链接

• README.md（中文主文档）
• README-en.md（英文版）
• 杰理文档中心（AD24 系列）
• 杰理开发环境工具下载
• USB 升级工具使用文档
• SDK 版本历史（AD24N_SDK_发布版本信息.pdf）

相关目录页指引：应用功能开发（语音玩具 / 扩音器）请参考应用开发相关页面；烧录与升级协议细节请参考烧录升级相关页面；本页仅覆盖环境搭建与工具链。