编译、烧录与快速开始

本文档介绍 AD24N 通用 MCU SDK（fw-AD24N_GP-MCU_SDK）从获取代码、搭建环境、编译固件到烧录运行的完整流程，覆盖 Windows / Linux 双平台编译方式、两种示例应用（语音玩具、语音增强）的构建入口、USB 升级工具烧录、生产烧写与 OTA 升级，以及常见编译错误的排查方法。

Purpose and Scope（目的与范围）

本页面向首次接触 AD24N SDK 的开发者，目标是让你在最短时间内完成一次「源码 → 固件 → 上板运行」的完整闭环。具体包括：

• 开发环境搭建：杰理编译工具链的获取与验证、烧录工具的安装
• SDK 获取与工程入口：仓库克隆、.cbp 工程文件、应用源码目录
• 编译机制：顶层 Makefile 与子工程 Makefile 的调用关系、三种编译方式（Code::Blocks / Makefile 命令行 / VS Code）
• 烧录与升级：首次烧录步骤、编程模式、生产烧写（一拖二/一拖八）、OTA 双备份升级
• 配置入口：app_config.h 功能开关、Makefile target 选择
• 故障排查：常见编译错误、烧录失败原因、Linux 环境注意事项

以下主题属于其他页面的范畴，本页不做展开：具体应用功能的开发（voice_toy 语音玩具应用、voice_enhanced 扩音器应用的业务逻辑）、芯片硬件设计与选型、SDK 内部模块 API 细节（解码器、设备管理、文件系统等）、工具链自身的实现机制。

Overview（概述）

fw-AD24N_GP-MCU_SDK 是杰理科技为 AD24N 系列芯片提供的通用 MCU 开发包。AD24N 系列基于 32bit 双发射 DSP（240MHz），主要面向语音玩具、小音箱、通用 MCU 三类应用场景，支持 AD242A / AD245A / AD246A / AD248A / AD248B 等型号。SDK 以 Release 形式发布，源码配合 include_lib/ 下的预编译库（lib.a）使用，必须使用杰理官方编译工具链（基于 clang 的 pi32 交叉工具链）编译。

一次典型的开发闭环如下：

flowchart LR
    A["克隆仓库<br/>git clone"] --> B["搭建工具链<br/>/opt/jieli"]
    B --> C["选择目标<br/>voice_toy / voice_enhanced"]
    C --> D["编译<br/>make / Code::Blocks"]
    D --> E["生成固件<br/>post_build/"]
    E --> F["烧录<br/>USB 升级工具"]
    F --> G["目标板上电运行"]

SDK 预置两个应用工程：AD24N_voice_toy.cbp（语音玩具）与 AD24N_voice_enhanced.cbp（扩音器/语音增强），二者共用同一套芯片平台代码，通过编译目标（Makefile target 或 Code::Blocks 工程）区分。编译产物由 app/post_build/ 下的后处理脚本打包成最终固件，再经 USB 升级工具（调试/小批量）或生产烧写工具（量产裸片）写入目标板。固件升级支持 dual_bank 双备份机制，可进行 OTA 升级。

Architecture（架构）

编译-烧录全链路架构

flowchart TD
    subgraph sg_source["源码层 sdk/"]
        APP["app/src 应用源码<br/>voice_toy / voice_enhanced"]
        LIB["include_lib 预编译库 (.a)"]
        MK["Makefile + 子工程 Makefile<br/>.cbp 工程文件"]
    end

    subgraph sg_toolchain["工具链层"]
        CLANG["杰理编译工具链<br/>/opt/jieli/pi32/bin/clang"]
        POST["app/post_build 编译后处理"]
    end

    subgraph sg_output["产物层"]
        FW["固件<br/>post_build/"]
    end

    subgraph sg_flash["烧录层"]
        USBTOOL["USB 升级工具"]
        PROD["生产烧写工具<br/>一拖二 / 一拖八"]
    end

    subgraph sg_board["目标板"]
        BOARD["AD24N 开发板 / 裸片"]
    end

    APP --> MK
    LIB --> MK
    MK -->|"交叉编译 + 链接"| CLANG
    CLANG --> POST
    POST --> FW
    FW --> USBTOOL
    FW --> PROD
    USBTOOL -->|"USB / UART"| BOARD
    PROD -->|"裸片烧写"| BOARD

各层职责说明：

• 源码层：sdk/app/src/ 存放两个应用（voice_toy、voice_enhanced）及共用功能模块（voice_func）的入口代码；sdk/include_lib/ 提供芯片平台头文件（cpu/、audio/、device/、fs/、msg/ 等）与预编译库（liba/），这是 SDK 以 Release 形式发布的载体——源码必须与对应命名规则的 lib.a 配套编译。
• 工具链层：杰理编译工具链基于 clang 交叉编译器，Windows 下由 Code::Blocks 或 make_prompt.bat 注入环境变量调用，Linux 下要求工具链解压至 /opt/jieli 且 clang 可执行；app/post_build/ 负责编译后的固件打包。
• 产物层：编译成功后在 post_build/ 目录生成可烧录的固件文件。
• 烧录层：开发调试使用 USB 升级工具（支持 USB / UART 进入编程模式），量产场景使用一拖二/一拖八生产烧写工具直接烧写裸片。
• 目标板：AD24N 全系列芯片（AD242A/AD245A/AD246A/AD248A/AD248B），SDK 为全系列预配置了统一的编译入口，无需针对具体型号单独建工程。

决策点：选择哪种编译方式

环境搭建

前提条件

安装编译工具链

1. 从杰理官方工具链页面下载并安装「杰理编译工具链」（下载地址）。
2. Linux 用户可从 pkgman.jieliapp.com 下载，解压到 /opt/jieli 目录，并确认 /opt/jieli/pi32/bin/clang 存在（注意目录层次）。
3. 安装完成后用 clang --version 验证工具链可用。

设计意图：SDK 的 Makefile 体系（sdk/Makefile 顶部注释）明确要求工具链位于固定路径 /opt/jieli，且 Linux 下还要求 ulimit -n 大于 8096，否则链接阶段可能因为打开文件数过多而失败。将工具链路径固定化，可以保证多用户/多工程共享同一套编译环境，避免路径漂移导致的「换台机器就编译不过」问题。

安装烧录工具

以上信息来源：README.md

编译机制

获取 SDK 与工程入口

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

SDK 根目录（sdk/）包含以下工程入口文件：

应用代码入口位于 sdk/app/src/：

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

设计意图：SDK 采用「一个平台、两个应用」的组织方式。芯片平台代码、预编译库、BSP 全部复用，应用层按目录隔离（voice_toy / voice_enhanced），通过工程文件/编译目标选择最终固件形态。这样新增应用时无需复制整套 SDK，只需基于现有 .cbp 工程与 app/src/ 新增目录。

顶层 Makefile 的调度逻辑

Makefile 是总入口，本身不包含具体编译规则，而是将任务转发给各个子工程的 Makefile（Makefile.ad24n_voice_*），这是典型的「总控 + 子工程」分层设计：

# 总的 Makefile，用于调用目录下各个子工程对应的 Makefile
# 注意： Linux 下编译方式：
# 1. 从 http://pkgman.jieliapp.com/doc/all 处找到下载链接
# 2. 下载后，解压到 /opt/jieli 目录下，保证
#   /opt/jieli/common/bin/clang 存在（注意目录层次）
# 3. 确认 ulimit -n 的结果足够大（建议大于8096），否则链接可能会因为打开文件太多而失败
#   可以通过 ulimit -n 8096 来设置一个较大的值
# 支持的目标
# 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

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

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

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

Source: sdk/Makefile

关键点解读：

• .PHONY 声明：所有目标都是伪目标（不产生同名文件），确保每次执行都会重新进入子 Makefile 判断增量编译。
• 转发模式：$(MAKE) -C . -f Makefile.ad24n_voice_toy 在顶层目录用 -f 指定子工程 Makefile 执行；-C . 保持当前目录，使子 Makefile 中的相对路径（app/、include_lib/ 等）仍然有效。
• 成对清理目标：每个应用都有对应的 clean_xxx 目标，make clean 会依次清理两个子工程，避免陈旧产物干扰下一次构建。
• 工具链路径注释：Linux 下要求 /opt/jieli/common/bin/clang 存在，且 ulimit -n 建议大于 8096——这是链接阶段打开文件数上限的硬约束，编译大量 lib.a 归档时会同时打开大量文件句柄。

编译命令速查表

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

-j 参数指定并行编译任务数（如 -j4），可显著加快编译速度；Linux 下常用 -j\nproc`` 自动取 CPU 核心数。

三种编译方式详解

方式一：Code::Blocks（推荐 Windows 用户）

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

Code::Blocks 的 .cbp 工程内部已经绑定了杰理工具链的编译器路径与编译参数，因此 Windows 用户无需手动配置环境变量，这是 IDE 方式的根本优势。

方式二：Makefile 命令行

# Windows 用户：双击 sdk/make_prompt.bat 打开命令行环境
# （该脚本已设置好所有环境变量和 make 的路径）
make ad24n_voice_toy -j4

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

Source: README.md

方式三：VS Code

仓库已预配置 VS Code 任务，按 Ctrl+Shift+B 即可选择编译目标。适合偏好现代编辑器 + 命令行工作流的开发者。

编译产物

编译成功后在 app/post_build/ 目录下生成固件文件（README 5 节工程结构将 app/post_build/ 标注为「编译后处理脚本与工具」）。该目录中的脚本负责将链接产物打包为 USB 升级工具可识别的固件格式，是「链接产物 → 可烧录固件」之间的最后一环。

说明：固件的具体文件命名与格式细节未在本仓库 README 中展开，实际以 post_build/ 内脚本输出为准；若需深入理解打包规则，请查阅 sdk/app/post_build/ 目录内容。

Usage Examples（用法示例）

示例一：完整快速开始（克隆 → 编译 → 烧录）

# 1. 克隆仓库并进入 sdk 目录
git clone https://gitee.com/Jieli-Tech/AD24N.git
cd AD24N/sdk

# 2. Windows 下先双击 sdk/make_prompt.bat 打开命令行环境

# 3. 编译语音玩具（-j4 并行加速）
make ad24n_voice_toy -j4

# 4. 编译语音增强
make ad24n_voice_enhanced -j4

# 5. 编译成功后，使用 USB 升级工具烧录 post_build/ 下的固件
#    烧录前确保 USB 升级工具正确连接且目标板已进入编程模式

Source: README.md

示例二：Linux 工具链安装与验证

# 1. 从 http://pkgman.jieliapp.com/doc/all 下载工具链
# 2. 解压到 /opt/jieli 目录
# 3. 确保 /opt/jieli/pi32/bin/clang 存在（注意目录层次）
# 4. 验证工具链是否安装成功
clang --version

Source: README.md

示例三：Linux 编译前置约束

# 建议将文件描述符上限调大，否则链接可能因打开文件太多而失败
ulimit -n 8096

# 并行编译（取 CPU 核心数）
make ad24n_voice_toy -j`nproc`

Source: sdk/Makefile

烧录与升级

首次烧录步骤

1. 连接硬件：将开发板通过 USB 或者 USB 升级工具 连接到 PC。
2. 进入编程模式：
   • 方式一（USB）：按住开发板上的烧录按键，然后复位或重新上电；
   • 方式二（USB/UART）：通过 USB 升级工具进入编程模式。
3. 打开 USB 升级工具：启动烧录上位机。
4. 选择固件：选择编译生成的固件文件（post_build/ 产物）。
5. 开始烧录：点击下载按钮，等待烧录完成。

注意：烧录前请确保 USB 升级工具正确连接且目标板已进入编程模式。关于 ISD_CONFIG.INI 的配置详见 ISD 配置说明。

首次烧录决策流程

flowchart TD
    Start([开始]) --> HW["连接开发板<br/>USB / 升级工具"]
    HW --> Mode{"进入编程模式?"}
    Mode -->|"方式一<br/>按键 + 复位/重新上电"| USB["USB 编程模式"]
    Mode -->|"方式二<br/>USB 升级工具"| UART["USB/UART 编程模式"]
    USB --> Tool["打开 USB 升级工具"]
    UART --> Tool
    Tool --> Sel["选择 post_build/ 固件"]
    Sel --> Burn["点击下载 开始烧录"]
    Burn --> OK{"烧录成功?"}
    OK -->|"是"| Done([上电运行])
    OK -->|"否"| Fail["检查连接 / 编程模式 / 固件"]
    Fail --> HW

编译-烧录完整时序

sequenceDiagram
    participant Dev as 开发者
    participant Make as Makefile
    participant Clang as 杰理工具链
    participant Post as post_build 脚本
    participant Tool as USB 升级工具
    participant Board as AD24N 目标板

    Dev->>Make: make ad24n_voice_toy -j4
    activate Make
    Make->>Make: 解析目标，转发给 Makefile.ad24n_voice_toy
    Make->>Clang: 交叉编译 app/src 源码 (pi32)
    Clang-->>Make: 目标文件 (.o)
    Make->>Clang: 链接 include_lib/liba 中的预编译库 (.a)
    Clang-->>Post: 链接产物
    Post->>Post: 打包生成可烧录固件
    Post-->>Dev: 固件输出至 post_build/
    deactivate Make

    Dev->>Tool: 打开工具，选择固件并下载
    activate Tool
    Tool->>Board: 通过 USB/UART 写入固件
    Board-->>Tool: 烧录完成
    deactivate Tool
    Dev->>Board: 复位/重新上电运行

生产烧写（量产）

量产场景请使用杰理生产烧写工具，支持裸片烧写：

• 一拖二烧写器：同时烧写 2 片，详见 一拖二烧写器使用说明。
• 一拖八烧写器：同时烧写 8 片，详见 一拖八烧写器使用说明。

生产烧写工具由代理商处获取，与开发用的 USB 升级工具在烧写能力（并行通道数、裸片支持）上不同，二者不可互相替代。

OTA 升级

SDK 支持 dual_bank 双备份固件升级：固件区域划分为两个 bank，升级时先写入备用 bank，校验成功后切换启动，再回写主 bank。该机制的核心价值在于升级掉电不「变砖」——若写入过程异常中断，设备仍可从当前有效 bank 启动。

配置说明

• 编辑 sdk/app/src/<应用>/app_config.h 可配置目标应用的功能开关（编译期生效）。
• 通过 Makefile target 选择不同的应用类型；SDK 已为 AD24N 全系列芯片预配置统一的编译入口，切换芯片型号在配置中选择对应型号即可，无需修改工程结构。

故障模式、边界情况与并发

常见编译错误

烧录失败排查

• 目标板未进入编程模式（未按住烧录按键复位/重新上电，或升级工具未触发编程模式）。
• USB 连接异常（线缆/供电不足，升级工具驱动未安装）。
• 固件文件选择错误（选择了旧的或错误的 post_build/ 产物）。

Linux 环境边界

• 需重写 download_bat.c 脚本适配 Linux 环境——该脚本在 Windows 下负责工具链相关下载/路径处理，Linux 下需要自行适配。
• 工具链目录层次必须精确为 /opt/jieli/pi32/bin/clang（顶层 Makefile 注释中为 /opt/jieli/common/bin/clang，README 3.2 节为 /opt/jieli/pi32/bin/clang，安装时以实际工具链发布包结构为准，保证 clang 可执行文件可达）。

并发与一致性

• make -jN 并行编译作用于编译阶段（多个 .o 并行产出）；链接阶段由子 Makefile 内部串行控制，因此并行是安全的。
• 两个应用工程共享 include_lib/ 预编译库，若在同一工作区先后编译两个 target，make clean 只会清理对应子工程的产物，不影响共享库。
• dual_bank OTA 的 bank 切换依赖固件校验结果，保证升级过程断电后的启动一致性。

性能与运维建议

• 编译加速：使用 -j4（或 Linux 下 -j\nproc``）并行编译；首次全量编译较慢，之后增量编译只重编改动文件。
• 文件描述符上限：Linux 下务必保证 ulimit -n 大于 8096，否则链接大库时可能因句柄耗尽失败。
• 构建环境隔离：将工具链固定在 /opt/jieli，保证 CI/多机环境一致。
• 固件版本管理：post_build/ 产物与 AD24N_SDK_发布版本信息.pdf 中的 SDK 版本对应，量产前确认固件与库版本匹配。
• 低功耗验证：AD24N 关机功耗低至 2µA+、休眠 19µA+，烧录后可通过功耗测量快速验证固件运行状态（详见 README 核心特性）。

扩展点

• 创建新应用工程：基于现有 .cbp 工程和 app/src/ 中的应用代码进行修改，配置对应用例即可；顶层 Makefile 增加新 target 需仿照 Makefile.ad24n_voice_toy 新增子 Makefile 并挂到 all/clean。
• 切换芯片型号：在配置中选择对应芯片型号，SDK 已为全系列预配置统一编译入口（AD242A/AD245A/AD246A/AD248A/AD248B）。
• 平台适配：Linux 用户可通过重写 download_bat.c 将 Windows 的下载/路径逻辑移植到 Linux 环境。
• OTA 策略：基于 dual_bank 机制可在应用层扩展升级触发方式（按键、串口指令、USB 等）。

相关链接

• README.md（完整中文说明）
• 顶层 Makefile
• 语音玩具工程 AD24N_voice_toy.cbp
• 语音增强工程 AD24N_voice_enhanced.cbp
• Windows 编译入口 make_prompt.bat
• 杰理在线文档中心（AD24）
• SDK 手册（doc/AD24N_SDK手册_v1.1.pdf）
• AD24N 用户手册（doc/AD24N用户手册V1.2.pdf）
• SDK 发布版本信息（PDF）
• 工具链下载与安装文档
• USB 升级工具使用文档
• 一拖二烧写器使用说明
• 一拖八烧写器使用说明
• ISD_CONFIG.INI 配置说明

Configuration Options（配置选项）

Command Reference（命令参考）

Make 目标

所有命令在 sdk/ 目录下执行；Windows 下需先通过 make_prompt.bat 进入预配置命令行环境。

环境准备命令

IDE 快捷键