项目概述与芯片支持

本文介绍杰理科技 fw-AD14N-AD15N-AC104N-AD17N-AD18N_GP-MCU_SDK 通用 MCU 固件 SDK 的整体架构、支持的芯片平台、应用工程入口、编译/烧录流程与配置方式，帮助开发者快速了解仓库全貌并选择合适的芯片与工程。

Purpose and Scope

本页面作为 Getting Started / 项目概述 的入口页，回答以下问题：

• 这个 SDK 是什么？面向哪些产品场景？
• 支持哪些芯片系列？各芯片的 CPU 平台（sh54 / sh55 / sh57 / ch58）与 AC104N 有何差异？
• SDK 目录如何组织？应用层（voice_toy / mcu / mbox_mg）、BSP 通用模块、CPU 平台驱动与预编译库（liba）分别位于何处？
• 有哪些编译入口（Code::Blocks 工程 / Makefile 目标）？如何烧录与升级？

本页面不深入的内容（由同级页面覆盖，可参考 Related Links）：具体应用（语音玩具、小音箱、通用 MCU）的内部实现、各外设驱动（UART/SPI/IIC/ADC/DAC/PWM）细节、文件系统与解码器 API 的详细用法，以及烧录工具的完整配置说明。

概述

fw-AD1x-4578_AC104_SDK 是杰理科技（Jieli-Tech）为 AD14N / AD15N / AC104N / AD17N / AD18N 系列芯片提供的通用 MCU 固件开发包。该系列芯片采用杰理自研的 pi32 内核架构，SDK 以「应用源码 + 预编译静态库（.a）」的形式发布：应用层、板级支持包（BSP）部分代码开放源码，而核心算法（解码器、编码器、系统库等）以对应命名规则的 lib.a 库文件提供，需配合正确芯片平台的库文件进行编译。

SDK 面向三类典型应用场景：

核心特性

• 音频解码：支持 .a / .b / .e、.f1a / .f1b / .f1c 等多种音频格式解码播放
• MIDI 播放：支持 MIDI 合成与播放（配套 midi_open 开源库）
• 音频编码：支持 A / MP3 / UMP3 编码
• 多路播放：最多支持两路音频同时解码播放
• 变速变调：支持音频变速变调播放（需系统时钟 100MHz 以上）
• 硬件重采样：芯片内置硬件重采样单元
• 低功耗：关机功耗低至 1.7µA+
• 多种存储：支持内置/外置 FLASH，FAT / NORFS / SYDF 文件系统
• DAC 输出：支持 PWM 差分输出及外接单端功放，支持 8K~32K 采样率

该 SDK 为 Release 版本代码，包含示例工程；编译时必须使用与芯片平台匹配的库文件（include_lib/liba/ 下的 sh54 / sh55 / sh57 / ch58 目录）。

架构

下图展示了 SDK 的整体分层架构与各层之间的关系。架构自底向上分为：硬件（SoC 芯片）→ 预编译库与 CPU 平台驱动 → BSP 通用模块 → 应用层；最外层是编译/烧录工具链。

flowchart TD
    subgraph sg_App["应用层 (sdk/app/src)"]
        VT["voice_toy 语音玩具"]
        MCU["mcu 通用 MCU"]
        MB["mbox_mg 小音箱"]
    end

    subgraph sg_BSP["板级支持包 (sdk/app/bsp)"]
        COMMON["common 通用模块<br/>decoder / encoder / fs / key / usb / fm<br/>midi / vm / msg / norflash / speaker<br/>power_manage / rtc / iic_soft / spi_soft"]
        CPU_DRV["cpu 平台驱动<br/>sh54 / sh55 / sh57 / ch58"]
    end

    subgraph sg_Lib["预编译库 (sdk/include_lib)"]
        LIBA["liba 静态库 (.a)<br/>pi32_lto 通用算法 + 各平台库"]
        HDR["头文件 include_lib<br/>driver / system / cpu / decoder / fs / audio"]
    end

    subgraph sg_Chip["芯片平台"]
        SH54["AD14N (sh54)"]
        SH55["AD15N (sh55)"]
        SH57["AD17N (sh57)"]
        CH58["AD18N (ch58)"]
        AC104["AC104N (mbox_mg)"]
    end

    VT --> COMMON
    MCU --> COMMON
    MB --> COMMON
    COMMON --> CPU_DRV
    COMMON --> LIBA
    CPU_DRV --> LIBA
    LIBA --> HDR
    SH54 --> CPU_DRV
    SH55 --> CPU_DRV
    SH57 --> CPU_DRV
    CH58 --> CPU_DRV
    AC104 --> CPU_DRV

架构分层说明

设计意图：将应用逻辑与硬件抽象分离是这套 SDK 的核心设计——同一份 voice_toy 应用源码可编译到 AD14N~AD18N 四个平台，差异被隔离在 bsp/cpu/<平台> 驱动层与对应平台的 liba 库中；开发者只需选择正确的 .cbp 工程或 Makefile 目标，即可完成平台切换（见「切换芯片平台」FAQ）。

支持的芯片与平台

SDK 覆盖五个 SoC 系列，分属四个 CPU 平台（bsp/cpu/ 目录名）与一个小音箱专用平台。芯片型号、规格书与原理图资料集中在仓库 doc/ 目录（按芯片型号分子目录存放）。

SoC 系列与 CPU 平台

平台目录与芯片的对应关系见 README.md：sh54 对应 AD14N、sh55 对应 AD15N、sh57 对应 AD17N、ch58 对应 AD18N，AC104N 走 mbox_mg 应用。

芯片支持架构

flowchart LR
    subgraph sg_Chips["SoC 芯片系列"]
        AD14N["AD14N"]
        AD15N["AD15N"]
        AD17N["AD17N"]
        AD18N["AD18N"]
        AC104N["AC104N"]
    end

    subgraph sg_Platforms["CPU 平台 (bsp/cpu)"]
        SH54["sh54"]
        SH55["sh55"]
        SH57["sh57"]
        CH58["ch58"]
    end

    subgraph sg_Apps["应用工程"]
        VT["voice_toy / mcu"]
        MBX["mbox_mg"]
    end

    AD14N --> SH54
    AD15N --> SH55
    AD17N --> SH57
    AD18N --> CH58
    SH54 --> VT
    SH55 --> VT
    SH57 --> VT
    CH58 --> VT
    AC104N --> MBX

软硬件参数差异

各芯片在封装、Flash 容量、GPIO 数量、ADC/DAC 通道、低功耗指标等方面存在差异，具体参数见仓库 doc/ 下的芯片手册（Datasheet）与选型表：

• AD14N 系列数据手册：doc/ad14n/datasheet/（AD142A0 / AD142A4 / AD145A0 / AD145A4 / AD146A 等型号）
• AD15N 系列数据手册：doc/ad15n/datasheet/
• AC104N 系列数据手册：doc/ac104n/datasheet/（AC1042A / AC1042B / AC1044A 等型号）
• 全系列选型表：杰理科技 AD14/AD15/AD16/AD17/AD18 系列语音 MCU 选型表

应用工程与入口

SDK 在 sdk/ 根目录预配置了 9 个 Code::Blocks 工程（.cbp） 与对应的 9 个 Makefile 目标，每个工程绑定一个「芯片 + 应用类型」组合：

工程文件清单见 sdk/ 目录，Makefile 支持的全部目标见 sdk/Makefile。

应用代码入口

sdk/app/src/
├── voice_toy/          # 语音玩具应用
│   ├── toy_music       #   音乐播放（本地/外置 FLASH）
│   ├── toy_midi        #   MIDI 乐器演奏与播放
│   ├── toy_record      #   录音
│   ├── toy_linein      #   线路输入（AUX）
│   ├── toy_speaker     #   扩音/喊话
│   ├── toy_idle        #   待机/空闲处理
│   ├── toy_softoff     #   软关机
│   └── toy_usb_slave   #   USB 从设备
├── mbox_mg/            # 小音箱应用
│   ├── music           #   音乐播放（FAT/SD/USB）
│   ├── fm              #   FM 收音机（BK1080/QN8035/RDA5807）
│   ├── rec             #   录音模式
│   ├── line_in         #   线路输入（AUX）
│   ├── loudspeaker     #   扩音/喊话
│   └── usb_device      #   USB 从设备（UAC/CDC/MSD/HID）
└── mcu/                # 通用 MCU 应用
    └── ...             #   智能控制/传感器采集/通用外设

设计意图：应用目录即「场景模板」。voice_toy 通过 toy_* 子模块的开关组合，可快速拼装出故事机、学习机、MIDI 乐器等产品；mbox_mg 则围绕小音箱的 music/fm/rec/line_in/loudspeaker/usb_device 六种工作模式组织。开发者通常以现有工程为起点修改，而非从零搭建（见 README FAQ「如何创建一个新的工程」）。

编译流程

SDK 支持三种编译方式：Code::Blocks IDE（推荐 Windows）、Makefile 命令行、VS Code 任务。三者最终都调用杰理编译工具链（基于 clang 的 pi32 交叉编译器）产出固件，产物输出到 sdk/app/post_build/ 目录。

编译环境前提

编译流程

flowchart TD
    Start([开始]) --> Env{"选择编译方式"}
    Env -->|"Code::Blocks"| CB["双击 .cbp 工程文件<br/>Build → Build (Ctrl+F9)"]
    Env -->|"Makefile"| MF["进入 sdk/ 目录<br/>选择对应 Makefile"]
    Env -->|"VS Code"| VS["Ctrl+Shift+B 选择编译目标"]
    CB --> TC["杰理工具链 (clang/pi32)"]
    MF --> TC
    VS --> TC
    TC --> LNK{"链接阶段"}
    LNK -->|"缺少库"| ERR1["cannot find -lxxx<br/>检查 include_lib/liba 目录"]
    LNK -->|"成功"| FW["生成固件<br/>输出到 sdk/app/post_build/"]
    FW --> BURN["USB 升级工具 / 生产烧写工具烧录"]
    ERR1 --> TC

Makefile 目标（顶层入口）

顶层 sdk/Makefile 是一个总控 Makefile，将每个子工程委托给对应的 Makefile.<target> 执行。其开头的注释明确列出了全部支持目标：

# 支持的目标
# make ac104n_mbox_mg
# make ad17n_mcu
# make ad15n_mcu
# make ad14n_mcu
# make ad15n_voice_toy
# make ad18n_voice_toy
# make ad14n_voice_toy
# make ad17n_voice_toy
# make ad18n_mcu

Source: sdk/Makefile

总控目标将各子目标委托给独立 Makefile：

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

clean_ad15n_mcu:
	$(MAKE) -C . -f Makefile.ad15n_mcu clean

Source: sdk/Makefile

all 目标会依次编译全部 9 个工程（make all），clean 则清理全部产物（make clean）。

编译命令速查

Linux 下并行编译可改用 make -f Makefile.ad15n_voice_toy all -j$(nproc)；链接阶段若因打开文件过多失败，需先 ulimit -n 8096（见 sdk/Makefile 注释）。

烧录与升级

首次烧录流程

1. 连接硬件：开发板通过 USB 或 USB 升级工具连接 PC
2. 进入编程模式：
   • 方式一（USB）：按住开发板烧录按键，复位或重新上电
   • 方式二（USB/UART）：通过 USB 升级工具进入编程模式
3. 打开 USB 升级工具并选择编译生成的固件
4. 点击下载，等待烧录完成

烧录工具

OTA 升级

SDK 支持双备份固件升级（dual_bank），实现见 sdk/app/bsp/common/dual_bank_demo.c，适用于需要空中升级（OTA）的产品场景。

配置选项

SDK 的功能开关通过头文件宏配置，遵循「应用级 + 平台级」两级配置模型：

配置方式示例：

# 编辑应用级功能开关
sdk/app/src/<应用>/app_config.h

# 编辑平台级模块配置
sdk/app/src/<应用>/<平台>/app_modules.h

Source: README.md

设计意图：两级配置让「产品功能集」与「芯片能力」解耦。例如同一款故事机固件，通过 app_config.h 打开/关闭 toy_music、toy_midi 等子模块；而平台差异（如 AD18N 的段码 LCD 驱动）则收敛到平台目录的 app_modules.h，避免应用代码被 #ifdef 淹没。

平台相关配置项

使用示例

示例 1：克隆仓库并查看应用入口

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

Source: README.md

示例 2：命令行编译语音玩具工程（Windows）

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

# 选择对应的 Makefile 进行编译
make -f Makefile.ad15n_voice_toy all -j4
make -f Makefile.ad15n_mcu all -j4

Source: README.md

示例 3：编译全部工程与清理

# 编译全部 9 个工程
make all

# 清理全部产物
make clean

Source: sdk/Makefile

示例 4：验证工具链安装

# 验证工具链是否安装成功（Linux 下路径为 /opt/jieli/pi32/bin/clang）
clang --version

Source: README.md

示例 5：单个子目标编译（顶层 Makefile 委托机制）

# 在 sdk/ 目录下直接调用总控 Makefile 的命名目标
make ad15n_mcu
make clean_ad15n_mcu

Source: sdk/Makefile

失败模式与边界情况

以下问题与对策来自 README 的「常见问题」与「常见编译错误」章节，属于该 SDK 使用中最常遇到的边界情况：

调试技巧（来自 README）：可通过 UART 输出串口日志；也可利用空闲 GPIO 输出调试波形测量时序。

性能与运维考虑

• 并行编译：SDK 支持 -jN 并行编译（如 -j4、-j$(nproc)），可显著缩短构建时间；但链接阶段文件描述符占用高，Linux 下建议 ulimit -n 8096。
• 编译产物位置：固件统一输出到 sdk/app/post_build/，配合 isd_download.exe 与 isd_config.ini 完成下载，生产环节应固化该目录的烧录配置。
• 低功耗指标：关机功耗低至 1.7µA+，适合电池供电的故事机/遥控玩具等产品；需通过 power_manage 模块与 toy_softoff 软关机流程配合实现。
• 资源约束：语音玩具与通用 MCU 场景受芯片 Flash/RAM 限制，通过 app_config.h / app_modules.h 裁剪未用模块（如不需要 FM 或 USB 时）可减小固件体积。
• OTA 可靠性：dual_bank 双备份升级机制保证升级失败时可回退，量产固件应保留该能力（sdk/app/bsp/common/dual_bank_demo.c）。

扩展点

SDK 的开放性体现在以下几处，开发者可在不修改核心库的前提下扩展产品功能：

设计意图：SDK 采用「源码开放的应用/BSP + 预编译核心库」双轨模式——开发者可自由修改应用层与板级代码，而解码器/编码器等算法以 liba 形式交付，既保护了核心 IP，又保证了库与源码的接口稳定性。新增能力优先复用 include_lib 头文件声明的 API。

Related Links

• README.md（项目总览） — 本页面的原始依据，含完整目录、FAQ 与社区支持
• sdk/Makefile（编译目标） — 全部编译目标与 clean 目标定义
• SDK 手册（官方 PDF） — 快速入门与整体说明
• SDK 版本历史 — Release 版本信息
• 芯片选型表 — 各系列软硬件参数对比
• 官方在线文档中心：doc.zh-jieli.com/AD14
• 问题反馈：Gitee Issues