语音玩具应用 voice_toy

语音玩具（voice_toy）是杰理 AD24N 通用 MCU SDK（fw-AD24N_GP-MCU_SDK）中的典型应用工程，面向儿童语音玩具、早教机、故事机等产品形态。本页说明该应用的工程结构、构建后处理（post_build）流水线、Flash 资源布局、下载与写保护机制等端到端能力。

Purpose and Scope

本页覆盖 sdk/app/post_build/sh58/voice_toy/ 目录所体现的 voice_toy 应用完整打包与烧录链路：

• 应用构建产物如何通过后处理脚本生成可烧录固件；
• Flash 链接布局（app_ld.c）与分区规划；
• 各类音频资源目录（歌曲、故事、诗歌、MIDI、英文、提示音等）的组织方式；
• 下载参数配置（download_bat.c、isd_config_ini.c）与量产烧录工具（isd_download.exe、fw_add.exe）；
• Flash 写保护（flash_write_protect/）的配置与生成流程。

以下内容不在本页范围，属于相邻目录页：

• 具体业务逻辑（如播放状态机、按键交互、协议解析）——若仓库中存在对应应用源码，请参见相关应用源码页；
• 芯片底层驱动、音频编解码、蓝牙/WiFi 协议栈——请参见 SDK 平台相关页面；
• 其他应用工程（非 voice_toy 的 post_build 配置）——请参见各自应用页。

说明：本次文档编写受源文件阅读预算限制，仅获取到 voice_toy 目录的完整文件清单；未逐行读取脚本实现。凡未经源码验证的细节，均明确标注"源码未验证"，不进行推测性描述。

Overview

voice_toy 是 AD24N（杰理 24 系列 GPIO MCU）上以音频播放为核心的玩具类应用。产品典型形态包括：

• 故事机 / 早教机：播放故事（dir_story）、诗歌（dir_poetry）、儿歌（dir_song）；
• 双语学习机：英文资源（dir_eng）与中文资源混排；
• 音乐玩具：MIDI 资源（dir_midi）与提示音（dir_notice）；
• 需要外挂 Flash 容量的产品：外部 Flash 资源（dir_ex_flash）。

从仓库证据看，sdk/app/post_build/sh58/voice_toy/ 是专门为 SH58 系列芯片（AD24N 家族）voice_toy 工程提供的构建后处理与量产准备目录。它把编译产物、音频资源、下载脚本、写保护配置组织成一套可复现的烧录流水线。目录中同时包含：

设计意图：把"应用编译"与"量产准备"解耦。应用源码只关心功能；post_build 目录负责把固件+资源+烧录参数组装成产线可直接使用的镜像，并可对特定 Flash 厂商开启写保护，防止产线/终端误擦除关键区。

Architecture

下图基于仓库实际文件布局，展示 voice_toy 应用从源码到量产固件的整体架构与数据流：

flowchart TD
    subgraph sg_App["应用层 (sdk/app)"]
        VoiceToy["voice_toy 应用源码<br/>(播放/按键/协议逻辑)"]
    end

    subgraph sg_Build["构建层"]
        Compile["编译链接<br/>(app_ld.c 定义段布局)"]
        FwBin["固件产物<br/>(dir_bin_f1x 等)"]
    end

    subgraph sg_Res["资源层"]
        DirSong["dir_song 歌曲"]
        DirStory["dir_story 故事"]
        DirPoetry["dir_poetry 诗歌"]
        DirMidi["dir_midi 音乐"]
        DirEng["dir_eng 英文"]
        DirNotice["dir_notice 提示音"]
        DirExFlash["dir_ex_flash 外挂Flash"]
    end

    subgraph sg_Post["后处理层 (post_build/sh58/voice_toy)"]
        DownloadBat["download_bat.c 下载配置"]
        IsdIni["isd_config_ini.c ISD参数"]
        FwAdd["fw_add.exe 固件合并"]
        IsdDl["isd_download.exe 下载工具"]
        WpBat["flash_write_protect/ 写保护脚本"]
    end

    subgraph sg_Target["目标 Flash 布局"]
        CodeArea["代码区"]
        ResArea["资源区"]
        ParamArea["参数/写保护区"]
    end

    VoiceToy --> Compile
    Compile --> FwBin
    DirSong --> FwAdd
    DirStory --> FwAdd
    DirPoetry --> FwAdd
    DirMidi --> FwAdd
    DirEng --> FwAdd
    DirNotice --> FwAdd
    DirExFlash --> FwAdd
    DownloadBat --> IsdDl
    IsdIni --> IsdDl
    FwAdd --> IsdDl
    WpBat --> IsdDl
    IsdDl --> CodeArea
    IsdDl --> ResArea
    IsdDl --> ParamArea

各层职责与连接关系：

• 应用层：voice_toy 业务源码决定"播什么、何时播、如何响应用户操作"，是固件逻辑的入口（本仓库当前可验证的目录证据为 post_build 侧；应用主源码不在本次阅读范围内）。
• 构建层：编译链接过程依据 app_ld.c 的段布局把代码与只读数据安排到 Flash 指定地址，产物落入 dir_bin_f1x 等固件目录。
• 资源层：按内容类型分目录组织音频资源。分目录存放的设计便于按产品 SKU 裁剪（例如不带英文资源的产品可移除 dir_eng），也便于版本管理与产线打包。
• 后处理层：download_bat.c 与 isd_config_ini.c 生成/携带烧录参数；fw_add.exe 把多段固件与资源合并成整包；isd_download.exe 通过 UART/下载口写入芯片；flash_write_protect/ 为指定 Flash 厂商型号生成写保护参数。
• 目标 Flash 布局：代码区、资源区、参数区分离。写保护只针对参数区/关键区，避免产线误操作。

依据：以上节点全部取自 sdk/app/post_build/sh58/voice_toy/ 实际目录与文件名；各 exe/脚本的具体内部逻辑未经本次读取验证，标注为推断。

核心实现详解

链接脚本 app_ld.c

文件：sdk/app/post_build/sh58/voice_toy/app_ld.c

该文件是 voice_toy 工程的链接布局定义（以 .c 命名、由构建系统在链接阶段引用，是杰理 SDK 常见做法）。其职责是：

• 划定代码段（text）、只读数据段（rodata）、资源段在 Flash 中的起始地址与长度；
• 为下载/量产工具提供分区基地址，使 isd_download.exe 能把固件写入正确位置；
• 与 dir_bin_f1x（F1x 系列 bin 固件）的产物地址保持一致，保证"编译地址 = 烧录地址"。

设计意图：玩具类产品往往在产线需要"只升级资源、不升级代码"或反之。将代码区与资源区在链接阶段就分离，量产工具即可按区写入、按区校验，避免整片擦除带来的产线节拍损耗。

源码未验证：本次未读取 app_ld.c 的具体段定义内容，以上为基于文件角色与杰理 SDK 通用约定的推断。如需确切段地址，请打开该文件核对。

下载配置 download_bat.c 与 isd_config_ini.c

文件：

• sdk/app/post_build/sh58/voice_toy/download_bat.c
• sdk/app/post_build/sh58/voice_toy/isd_config_ini.c

这两个文件共同构成量产烧录参数源：

• download_bat.c 推断负责生成/描述下载批处理流程（如"合并固件 → 配置串口 → 执行下载"的批处理骨架），是产线脚本与芯片下载协议之间的桥；
• isd_config_ini.c 推断为 ISD（In-System Download，杰理量产下载工具）生成 ini 格式参数文件，内容包括下载口波特率、Flash 类型、分区写入表、校验开关等。

设计意图：把"下载参数"与"下载工具"解耦——产线工具（isd_download.exe）保持通用，具体工程的 Flash 型号、地址映射、串口参数通过 ini 注入，使同一工具可服务多个产品线。

源码未验证：本次未读取两个 .c 的实现细节，具体参数键名与默认值需打开文件确认。

核心流程 Core Flow

voice_toy 从构建到产线烧录的端到端流程如下：

sequenceDiagram
    participant Dev as 开发者/CI
    participant Build as 编译链接(引用 app_ld.c)
    participant Res as 资源目录(dir_song 等)
    participant Post as post_build 脚本
    participant Fw as fw_add.exe
    participant Dld as isd_download.exe
    participant Chip as AD24N Flash

    Dev->>Build: 编译 voice_toy 工程
    Build-->>Post: 固件产物(bin_f1x)
    Res-->>Post: 音频资源按类型汇总
    Post->>Fw: 合并代码+资源+参数
    Fw-->>Post: 整包镜像
    Post->>Dld: 读取 download/isd 配置
    Dld->>Chip: 按分区写入代码区/资源区/参数区
    Dld->>Chip: 应用写保护(flash_write_protect)
    Chip-->>Dld: 校验回读
    Dld-->>Post: 烧录完成

流程要点：

1. 编译：应用源码依据 app_ld.c 的段布局链接，产出地址确定的 bin；
2. 资源汇总：dir_* 各目录内容按分区表归位，dir_ex_flash 中资源映射到外挂 Flash 地址；
3. 固件合并：fw_add.exe 将多段产物打包为整包镜像，规避多文件传输的产线风险；
4. 参数注入：download_bat.c/isd_config_ini.c 提供下载参数，写保护脚本提供 Flash 厂商型号对应参数；
5. 写入与校验：isd_download.exe 按区写入并回读校验；
6. 写保护：对参数区/关键区施加写保护，防止后续误擦除。

资源目录组织

voice_toy 采用"按内容类型分目录"的资源组织策略，共 8 个资源/固件目录：

设计意图：

• SKU 裁剪：不同产品只需打包不同目录组合（如"基础款 = dir_a + dir_notice + dir_story"），构建脚本按目录拾取资源，无需改动应用代码；
• 版本管理：内容更新只影响对应目录，方便增量发布；
• 内外 Flash 协同：dir_ex_flash 独立成目录，允许小容量内置 Flash 跑代码、大容量外挂 Flash 存内容，是玩具类产品最经济的存储方案。

说明：各目录内部的具体文件命名规则、编解码格式（如杰理私有音频格式）、资源表索引生成方式未在本次读取中验证。

Flash 写保护机制

目录：sdk/app/post_build/sh58/voice_toy/flash_write_protect/

工作逻辑（推断）：产线按芯片实际使用的 Flash 厂商标记（如 0xC8671A、0xEF4017）查表，flash_wp_tool.exe 依据 xlsx 中的型号信息生成对应的写保护参数 bin，再由 isd_download.exe 在烧录后写入保护寄存器。

设计意图：AD24N 玩具产品量大、产线多，Flash 供应商常有多家（对应不同 JEDEC ID）。把"厂商型号 → 写保护参数"做成查表+工具生成，可避免为每个供应商手工维护参数，同时降低因参数错误导致的批量返工风险。

源码未验证：xlsx 的具体表结构、bat 脚本的命令序列、flash_wp_tool.exe 的输入输出格式未在本次读取中验证。

配置选项

基于目录与文件名归纳的 voice_toy 量产相关配置项（具体键名与默认值需以 download_bat.c、isd_config_ini.c 源码为准，本次未读取）：

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

以下分析基于 voice_toy post_build 目录的结构性证据与嵌入式量产常识，具体行为请以实际脚本/工具为准。

失败模式

边界情况

• 空目录：若某 SKU 不含某类资源（如无 MIDI），对应 dir_midi 为空时打包脚本需跳过该分区，避免生成空区导致烧录工具报错；
• 内外 Flash 容量差异：dir_ex_flash 的地址映射依赖外挂 Flash 容量，换用不同容量 Flash 时需同步更新分区表；
• 写保护参数版本：目录中同时存在 v3 参数与工具，升级 Flash 厂商型号时须保持 bin 与 xlsx 版本一致。

并发/一致性注意

• 产线通常多工位并行烧录，isd_download.exe 为独立进程、互不影响；但共享的写保护参数 bin 与下载配置若在产线运行中修改，会导致不同工位参数不一致——应把 flash_params_v3.bin、isd_config_ini.c 视为产线冻结资产，变更需走版本发布流程；
• 构建产物（dir_bin_f1x）与资源目录若由 CI 并发生成，建议在打包阶段加版本号/时间戳，避免整包镜像混入新旧资源。

性能与运维注意事项

• 产线节拍：代码区/资源区分离后，可支持"仅更新资源区"的增量烧录，显著缩短单机烧录时间（推断，需工具支持按区写入）；
• 校验策略：下载流程含回读校验，玩具类大批量产线建议开启，防止偶发位错流入终端；
• 写保护：量产最后一步施加写保护，可防止终端用户通过异常操作（如断电重试升级）破坏参数区；但注意写保护一旦开启，后续返修烧录需先解除保护，运维流程中应保留解除工具与权限；
• 工具链环境：fw_add.exe、isd_download.exe、flash_wp_tool.exe 均为 Windows 可执行程序，产线/CI 需在 Windows 环境或兼容层运行；批处理脚本路径建议使用绝对路径或固定相对路径，避免中文/空格路径引发问题。

扩展点

• 新增内容类型：按 dir_* 模式新增目录（如 dir_pinyin），并在分区表与打包脚本中登记即可，应用代码无需改动；
• 新增 Flash 厂商：在 flash_write_protect/ 的 xlsx 查表中追加 JEDEC ID 与参数行，用 flash_wp_tool.exe 重新生成 flash_params_v3.bin；
• 多产品复用：download_bat.c/isd_config_ini.c 参数化后，同一套后处理框架可服务多个玩具 SKU，仅替换资源目录与分区配置；
• CI 集成：post_build 目录中的脚本/配置可被 CI 调用，实现"提交资源 → 自动打包 → 生成整包镜像"的流水线（脚本入口为 flash_list_to_bin_v3.bat 及下载配置生成逻辑）。

相关链接

• app_ld.c（链接布局）
• download_bat.c（下载配置）
• isd_config_ini.c（ISD 参数）
• flash_list_to_bin_v3.bat（写保护生成脚本）

与相邻页面的关系：本页聚焦 voice_toy 的构建/打包/烧录链路；应用运行时逻辑（播放状态机、按键事件、协议）属于应用源码页，SDK 驱动与芯片外设属于平台页，请按目录结构跳转阅读。

使用示例与已验证证据

本次文档编写受源工具预算限制（6/6 次调用已用尽），未读取到 app_ld.c、download_bat.c、isd_config_ini.c 及 bat 脚本的正文内容，因此无可用代码示例，不进行任何代码推断。以下是本次实际读取（ListFiles）验证到的 voice_toy 目录结构，作为本页全部结论的事实依据：

sdk/app/post_build/sh58/voice_toy/
├── app_ld.c                        # 链接布局定义
├── dir_a/                          # 通用资源
├── dir_bin_f1x/                    # F1x 固件产物
├── dir_eng/                        # 英文音频资源
├── dir_ex_flash/                   # 外挂 Flash 资源
├── dir_midi/                       # MIDI 曲目
├── dir_notice/                     # 提示音
├── dir_poetry/                     # 诗歌资源
├── dir_song/                       # 歌曲资源
├── dir_story/                      # 故事资源
├── download_bat.c                  # 下载批处理配置
├── flash_wp_tool.exe               # 写保护工具
├── fw_add.exe                     # 固件合并工具
├── isd_config_ini.c                # ISD 下载参数
├── isd_download.exe                # 量产下载工具
└── flash_write_protect/
    ├── 0xC8671A_v3.xlsx            # Flash 厂商型号表 (JEDEC 0xC8671A)
    ├── 0xEF4017_v3.xlsx            # Flash 厂商型号表 (JEDEC 0xEF4017)
    ├── flash_list_to_bin_v3.bat    # 型号清单→写保护 bin 生成脚本
    ├── flash_wp_tool.exe           # 写保护参数生成工具
    └── inside_flash/
        └── flash_params_v3.bin     # 内置 Flash 写保护参数

说明：以上文件清单来自对仓库的实际目录列举（ListFiles），文件名与相对路径 100% 真实；各文件内部实现细节标注"源码未验证"的部分，请在后续阅读时打开对应文件核对，再补充到本页。

后续补充建议

如需深化本页内容，建议优先读取并按序补充：

1. app_ld.c：提取真实的段地址与大小宏定义，替换"推断"表述；
2. isd_config_ini.c：提取真实的下载参数键值表（波特率、分区写入项）；
3. flash_write_protect/flash_list_to_bin_v3.bat：提取真实的批处理命令序列；
4. 若仓库存在 apps/ 下 voice_toy 业务源码，补充播放控制流与状态机。