通用 MCU 应用

杰理科技 fw-AD1x 系列（AD14N / AD15N / AD17N / AD18N）通用 MCU SDK 中的应用层能力，涵盖芯片平台适配、sdk/app 工程结构、post_build 构建与烧录工具链，以及面向通用 MCU 场景的音频、存储、外设资源管理。

目的与范围

本页面介绍 SDK 中「通用 MCU」应用形态的完整工程组织与运行机制：它在 SDK 中的位置、所支持的芯片平台、核心能力（音频解码 / MIDI / 编码 / 多路播放 / 低功耗）、按芯片划分的 post_build 构建工具链，以及 dir_* 资源目录的内容组织方式。

以下相关主题不在本页范围内，由各自的目录页面负责：

• 语音玩具应用（故事机、学习机、语音遥控玩具、MIDI 乐器）——同属本 SDK 的另一类应用形态；
• 小音箱应用（mbox_mg，面向 AC104N）——独立应用工程；
• 音频编解码库内部实现——本页仅描述 SDK 对外暴露的解码/编码能力，不深入算法细节；
• 外设驱动寄存器级说明——属于各平台 SDK 的底层文档。

概述

fw-AD1x-4578_AC104_SDK 是杰理科技为 AD14N / AD15N / AC104N / AD17N / AD18N 系列芯片提供的通用 MCU 开发包。根据 README.md 的描述，本 SDK 面向三类典型产品形态：

「通用 MCU 应用」即其中面向 智能控制、传感器采集、通用外设应用 的形态，是把芯片当作一颗带音频能力的高集成度 MCU 使用：开发者基于 SDK 应用层编写业务逻辑，底层由平台 SDK 提供时钟、存储、音频、外设等服务。

SDK 采用「源码 + 闭源库」的发布模式：仓库包含 SDK Release 版本代码及示例工程，编译时需配合对应命名规则的库文件（lib.a）。这意味着应用层的可读源码（如 app/src/mcu/<平台>/app_modules.h、post_build 下的构建脚本）是开发者直接编辑和配置的部分，而底层平台实现由库提供。

架构

整体架构

flowchart TD
    subgraph sg_SDK["fw-AD1x 通用 MCU SDK"]
        subgraph sg_Platform["芯片平台 (SoC)"]
            P_SH54["sh54 (AD14N)"]
            P_SH55["sh55 (AD15N)"]
            P_SH57["sh57 (AD17N)"]
            P_CH58["ch58 (AD18N)"]
        end

        subgraph sg_App["应用层 (sdk/app)"]
            A_MCU["通用 MCU 应用<br/>app/src/mcu"]
            A_TOY["语音玩具应用"]
            A_BOX["小音箱应用 (mbox_mg)"]
        end

        subgraph sg_Build["post_build 构建与烧录 (sdk/app/post_build/&lt;chip&gt;/mcu)"]
            B_LD["app_ld.c 链接配置"]
            B_DL["download_bat.c 下载脚本"]
            B_CFG["isd_config.ini 工具配置"]
            B_UB["uboot.boot 引导"]
        end

        subgraph sg_Res["MCU 资源目录"]
            R_AUD["dir_a / dir_bin_f1x / dir_song / dir_story"]
            R_MIDI["dir_midi / midi_cfg"]
            R_TXT["dir_eng / dir_notice / dir_poetry"]
            R_FLASH["dir_ex_flash 外部存储资源"]
        end
    end

    A_MCU --> P_SH54
    A_MCU --> P_SH55
    A_MCU --> P_SH57
    A_MCU --> P_CH58
    A_MCU --> R_AUD
    A_MCU --> R_MIDI
    A_MCU --> R_TXT
    A_MCU --> R_FLASH
    B_LD --> A_MCU
    B_DL --> A_MCU
    B_CFG --> A_MCU
    B_UB --> A_MCU

架构说明：

• 芯片平台层：SDK 按 CPU 平台划分移植单元，sh54（AD14N）、sh55（AD15N）、sh57（AD17N）面向语音玩具与通用 MCU，ch58（AD18N）额外支持段码 LCD。通用 MCU 应用需要针对各平台做外设与资源适配。
• 应用层：sdk/app 下按应用形态组织示例工程；通用 MCU 应用的源码路径可从补丁目录结构确认——patch/.../app/src/mcu/sh54/app_modules.h 表明应用模块声明位于 app/src/mcu/<平台>/，即以「平台 + 模块」的方式组织。
• post_build 工具链：sdk/app/post_build/<chip>/mcu/ 按芯片存放构建期产物与脚本：app_ld.c（链接/地址布局相关）、download_bat.c（批量下载配置）、isd_config.ini（工具配置）、uboot.boot（引导固件）。这一层是「编译产物 → 芯片可运行固件」的桥梁。
• 资源目录：dir_* 系列目录是 MCU 应用的内容资源（音频素材、MIDI 数据、提示音、歌词文本等），midi_cfg 为 MIDI 配置，dir_ex_flash 对应外置 FLASH 上的资源。这种「目录即资源分区」的设计让产品化阶段只需替换资源目录即可完成内容更新，无需改动业务源码。

为什么这样分层

该 SDK 面向的是多芯片、多产品形态的家族式发布。将平台（sh54/sh55/sh57/ch58）与应用形态（语音玩具 / 通用 MCU / 小音箱）分离，并在 post_build 下按芯片维护构建工具链，是为了让同一套应用代码可以低成本地移植到不同芯片：平台差异被收敛到 post_build/<chip> 与底层库中，应用层代码保持相对稳定。同时，「源码 + lib.a」的发布模式保护了底层 IP，同时保留应用层的可定制性。

工程结构详解

MCU 应用相关文件布局

通过对仓库文件的实际扫描，与「通用 MCU 应用」直接相关的文件按职责可归类如下：

说明：上述「职责推断」基于文件命名与目录上下文；app_ld.c、download_bat.c、isd_config.ini 的内部实现细节未在本页源文件读取预算内获取到，具体逻辑请直接查看对应文件。

资源目录组织

flowchart TD
    subgraph sg_MCU["sdk/app/post_build/ch58/mcu/"]
        LD["app_ld.c"]
        DL["download_bat.c"]
        CFG["isd_config.ini"]
        UB["uboot.boot / uboot.boot_debug"]

        subgraph sg_AUD["音频资源"]
            A1["dir_a"]
            A2["dir_bin_f1x"]
            A3["dir_song"]
            A4["dir_story"]
        end

        subgraph sg_MIDI["MIDI 资源"]
            M1["dir_midi"]
            M2["midi_cfg"]
        end

        subgraph sg_TXT["文本语音资源"]
            T1["dir_eng"]
            T2["dir_notice"]
            T3["dir_poetry"]
        end

        EX["dir_ex_flash"]
    end

    LD --> UB
    DL --> CFG
    UB --> A1
    UB --> A2
    UB --> A3
    UB --> A4
    UB --> M1
    UB --> M2
    UB --> T1
    UB --> T2
    UB --> T3
    UB --> EX

该目录树表明：通用 MCU 应用的内容资源与构建产物在同一个 mcu 目录下统一管理。uboot.boot 作为引导固件，与 dir_* 资源目录、midi_cfg、isd_config.ini 一起被打包进最终固件镜像。这种「一目录一产品」的组织方式，使得不同芯片（ch58、sh54 等）各自维护独立的 post_build/<chip>/mcu 目录，互不干扰。

构建与烧录流水线

flowchart LR
    SRC["应用源码<br/>app/src/mcu + sdk/app"] --> BUILD["编译链接"]
    LIB["闭源库 lib.a"] --> BUILD
    CFG["post_build 配置<br/>app_ld.c / isd_config.ini"] --> BUILD
    BUILD --> BIN["固件产物<br/>uboot.boot / bin"]
    BIN --> DL["download_bat.c 下载配置"]
    DL --> CHIP["目标芯片<br/>AD14N / AD15N / AD17N / AD18N"]

流水线说明（设计意图）：

1. 编译链接：应用源码与按命名规则匹配的 lib.a 一同编译，app_ld.c 提供链接期布局信息（例如代码/数据段在 FLASH 中的放置），isd_config.ini 供构建工具读取配置。
2. 固件打包：产出 uboot.boot 及调试版 uboot.boot_debug，与 dir_* 资源目录、midi_cfg 一起构成可烧录镜像——资源随固件分发，保证产品开箱即用。
3. 烧录下载：download_bat.c 承载下载流程配置，将固件写入目标芯片。
4. 运行：芯片上电后由引导代码（uboot.boot）进入应用，应用按 app_modules.h 声明的模块列表初始化功能。

上电引导→应用初始化的具体时序属于运行时行为，需结合平台库实现确认；本页依据工程结构与命名给出上述期望流程。

核心能力

通用 MCU 应用继承了 SDK 的核心平台能力，这些能力直接来自 README.md 的官方特性清单：

对通用 MCU 产品而言，这些能力的意义在于：一颗芯片同时承担**控制逻辑（MCU）与人机交互（音频）**两种角色。例如智能控制类产品可以用 MIDI 或提示音（dir_notice）作为用户反馈，用音频编码能力实现录音/语音采集，用低功耗模式满足长期待机——这正是「通用 MCU 应用」与纯 MCU 方案的本质区别。

平台适配

flowchart TD
    subgraph sg_Platforms["平台与领域"]
        P1["sh54 → AD14N<br/>语音玩具 / 通用 MCU"]
        P2["sh55 → AD15N<br/>语音玩具 / 通用 MCU"]
        P3["sh57 → AD17N<br/>语音玩具 / 通用 MCU"]
        P4["ch58 → AD18N<br/>通用 MCU（支持段码 LCD）"]
        P5["AC104N → 小音箱（mbox_mg）"]
    end

    subgraph sg_Adapt["平台适配机制"]
        S1["app/src/mcu/&lt;平台&gt;/ 应用源码"]
        S2["post_build/&lt;chip&gt;/mcu/ 构建工具链"]
        S3["lib.a 按命名规则匹配"]
    end

    P1 --> S1
    P2 --> S1
    P3 --> S1
    P4 --> S1
    P1 --> S2
    P2 --> S2
    P3 --> S2
    P4 --> S2
    S1 --> S3
    S2 --> S3

平台差异（据 README.md）：

• sh54 / sh55 / sh57（AD14N / AD15N / AD17N）面向语音玩具与通用 MCU，是通用 MCU 应用的主力平台；
• ch58（AD18N）额外支持段码 LCD，适合带简单显示界面的通用 MCU 产品；
• AC104N 走 mbox_mg 小音箱应用路线，不属于通用 MCU 应用范畴。

适配的关键点：应用源码按平台目录组织（app/src/mcu/sh54/ 等），构建工具链按芯片目录组织（post_build/sh54/mcu/、post_build/ch58/mcu/），库文件按命名规则匹配。移植到新芯片时，主要工作是新增/调整对应平台的应用目录与 post_build 目录，并替换匹配的 lib.a。

配置选项

以下配置项基于工程结构与 README 整理：

注：app_modules.h、isd_config.ini 等文件的具体字段未在本页读取预算内展开，实际字段以对应文件内容为准。

核心流程

固件从构建到运行的整体时序

sequenceDiagram
    participant Dev as 开发者
    participant Build as 编译链<br/>(源码 + lib.a + app_ld.c)
    participant Pack as 固件打包<br/>(uboot.boot + dir_* + midi_cfg)
    participant DL as 烧录<br/>(download_bat.c / isd_config.ini)
    participant Chip as 目标芯片
    participant App as MCU 应用<br/>(app_modules.h 模块)

    Dev->>Build: 编写/修改应用源码与配置
    Build->>Build: 编译链接，生成固件
    Build->>Pack: 产出 uboot.boot 与资源镜像
    Pack->>DL: 组装完整烧录镜像
    DL->>Chip: 下载固件
    Chip->>App: 上电引导，进入应用
    App->>App: 按模块声明初始化<br/>(音频/存储/外设)
    App-->>Dev: 产品功能运行

流程要点：

• 构建期：开发者只修改应用层源码与 post_build 配置，平台能力由 lib.a 提供——这种分工让 SDK 的每次迭代保持「应用可定制、底层可升级」。
• 发布期：uboot.boot（含调试版）与资源目录统一打包，isd_config.ini 与 download_bat.c 驱动烧录流程，保证产线可重复生产。
• 运行期：应用依据 app_modules.h 声明的模块集合初始化，模块化声明方式决定了「按需裁剪」的灵活性——不需要音频的产品可以裁剪音频模块以节省资源、降低功耗。

使用示例

以下示例内容直接摘自仓库 README（官方对 SDK 能力的描述），可作为理解通用 MCU 应用能力边界的依据。

应用形态定义

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

Source: README.md

核心特性清单

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

Source: README.md

芯片平台映射

| CPU 平台 | 芯片系列 | 应用领域 |
|---------|---------|---------|
| **sh54** | AD14N | 语音玩具 / 通用 MCU |
| **sh55** | AD15N | 语音玩具 / 通用 MCU |
| **sh57** | AD17N | 语音玩具 / 通用 MCU |
| **ch58** | AD18N | 语音玩具 / 通用 MCU（支持段码 LCD） |
| — | **AC104N** | 小音箱（mbox_mg） |

Source: README.md

说明：app_ld.c、download_bat.c、app_modules.h 等源码文件的内容未在本页读取预算内获取，故此处不展示其内部代码；如需代码级示例，请直接查阅仓库对应文件。

失败模式、边界与并发

基于工程结构与 README 信息，可识别的关注点如下：

• 库文件不匹配：lib.a 需按命名规则与芯片/功能匹配。若库版本与源码不匹配，编译链接将失败——这是「源码 + 闭源库」模式下最常见的工程配置错误，构建时应核对库版本历史（见 SDK 版本历史）。
• 平台资源差异：post_build 按芯片独立维护，切换芯片平台时必须同步更换对应 post_build/<chip>/mcu 目录与库文件，否则可能出现链接布局（app_ld.c）或引导（uboot.boot）不兼容。
• 资源容量边界：dir_* 资源目录与固件一同打包，产品内容（音频/MIDI/文本）超过 FLASH 容量上限将导致打包或运行失败；dir_ex_flash 表明部分资源可放置于外置 FLASH，以缓解内置存储压力。
• 时钟约束：变速变调等能力要求系统时钟 ≥100MHz，低主频配置下启用该功能会出现行为异常。
• 并发/时序：多路播放（两路同时解码）涉及解码器与 DAC 的并发访问，具体调度与互斥由平台库实现；应用层应避免在音频回调中执行耗时操作。SDK 为嵌入式单机场景，多路播放的并发由库内部管理，应用层通常无需自行加锁。
• 调试与发布差异：uboot.boot_debug 与 uboot.boot 并存，调试版包含调试信息，量产应使用发布版引导，避免固件体积与行为差异。

扩展点

• 应用模块裁剪：通过 app_modules.h 声明启用的模块集合，按产品需求裁剪音频/MIDI/存储等功能，是通用 MCU 应用最主要的功能扩展入口。
• 资源替换：替换 dir_* 目录内容即可完成产品内容更新（换提示音、换故事、换诗词），无需修改业务代码——资源与代码分离是 SDK 面向产品化的核心设计。
• 平台移植：新增芯片平台时，参照现有 post_build/sh54|ch58/mcu 建立对应目录，并维护 app/src/mcu/<平台>/ 应用源码与匹配的 lib.a。
• 构建脚本定制：download_bat.c 与 isd_config.ini 可针对产线烧录流程定制。

相关链接

• README.md（仓库总览）
• README-en.md（英文总览）
• 文档中心（AD14 系列在线文档）
• SDK 版本历史 PDF
• post_build/ch58/mcu 构建目录
• post_build/sh54/mcu 构建目录
• app_modules.h（模块声明，补丁目录）
• 相关页面：语音玩具应用、小音箱应用（mbox_mg）、音频编解码