应用框架与模式管理

本文档介绍 AD1NN_GP-MCU_SDK（fw-AD15N）中 mbox（小音箱）应用的应用框架与模式管理机制，覆盖框架在应用中的职责定位、mbox_mg 六种工作模式的组织方式、模式切换与消息处理的总体流程，以及相关的构建工程配置。

Purpose and Scope

本页面聚焦于 mbox 小音箱应用的应用框架层与模式（工作状态）管理，内容包括：

  • mbox 应用在 SDK 应用体系中的位置与边界
  • mbox_mg 六种工作模式（music / fm / rec / line_in / loudspeaker / usb_device）的组织结构
  • 框架层所承担的模式管理、消息处理、电源管理等职责划分
  • 模式切换与消息分发的主流程
  • 与构建工程（.cbp 工程文件）和芯片选型的关联

本页面不覆盖以下兄弟主题，它们应查阅各自对应的文档页：

  • voice_toy（语音玩具）应用：toy_music / toy_midi / toy_record / toy_linein / toy_speaker / toy_idle / toy_softoff / toy_usb_slave 等模式
  • mcu（通用 MCU）应用
  • 具体某个模式（如 music 或 fm）内部的播放器实现细节

说明：本次文档探索受源码工具预算限制，仅能对仓库根目录与 README 中描述的应用/模式结构进行源码级验证；框架内部具体实现文件（如消息处理、模式注册表的实际代码）未能在本次探索中读取，文中将以「实现细节未在本次探索中验证」明确标注，不做臆测性描述。

Overview

AD1NN_GP-MCU_SDK 是杰理科技（JieLi）面向 AD15N 系列芯片的嵌入式固件 SDK，同一仓库同时支持多颗芯片与多类应用形态。根据仓库 README 的描述，SDK 的应用体系按芯片 → 应用 → 工作模式三层组织：

芯片芯片型号应用形态
ch57AD15N语音玩具 / 通用 MCU
ch58AD18N语音玩具 / 通用 MCU（支持段码 LCD）
—AC104N小音箱（mbox_mg）

（来源：README.md）

mbox（小音箱） 是其中面向音频小音箱场景的应用，其目录 mbox_mg 内部按工作模式拆分为多个子模块：

├── mbox_mg/            # 小音箱应用（music / fm / rec / line_in / loudspeaker / usb_device）

（来源：README.md）

“应用框架”在本 SDK 中的含义是：为 mbox 应用提供模式注册、模式切换、消息分发、电源/事件管理等通用机制的支撑层。各工作模式（music、fm 等）作为框架的“模式单元”挂接在框架之上，框架统一负责它们的进入、退出与切换编排，从而使单个应用内的多个功能模块可以以统一的生命周期方式协同工作。这种“框架 + 模式”的设计是嵌入式多任务音频应用常见的架构选择，其设计意图在于：

  1. 关注点分离：模式单元只关心自身的功能逻辑（如 fm 只关心搜台、播放），不关心系统级的分发与调度；
  2. 统一生命周期：进入/退出模式时的资源申请、释放、外设使能/禁用由框架统一约定，避免各模块各自为政；
  3. 可扩展性：新增一种工作模式（如增加 usb_device）只需按框架约定注册一个新的模式单元，无需改动框架核心。

Architecture

下图给出 mbox 应用框架与模式管理的总体架构。其中「应用层 / 模式层 / 芯片层」的结构关系由仓库 README 的应用目录树与芯片支持表验证；「框架层」的职责划分（模式管理、消息分发、电源管理、事件处理）依据本目录页标题所定义的框架能力边界整理，具体实现细节未在本次探索中验证。

flowchart TD
    subgraph sg_App["应用层 (apps)"]
        Mbox["mbox_mg<br/>小音箱应用"]
    end

    subgraph sg_Framework["应用框架层"]
        ModeMgr["模式管理<br/>模式注册 / 切换编排"]
        MsgDeal["消息处理与分发"]
        PowerMgr["电源管理"]
        EventBus["事件 / 按键处理"]
    end

    subgraph sg_Modes["mbox 工作模式 (模式单元)"]
        M1["music 音乐"]
        M2["fm 收音"]
        M3["rec 录音"]
        M4["line_in 线路输入"]
        M5["loudspeaker 扩音"]
        M6["usb_device USB 设备"]
    end

    subgraph sg_Chip["芯片 / 硬件层"]
        AC104["AC104N<br/>(mbox_mg 目标芯片)"]
    end

    Mbox --> MsgDeal
    Mbox --> ModeMgr
    Mbox --> PowerMgr
    Mbox --> EventBus
    EventBus --> MsgDeal
    MsgDeal --> ModeMgr
    PowerMgr --> ModeMgr
    ModeMgr --> M1
    ModeMgr --> M2
    ModeMgr --> M3
    ModeMgr --> M4
    ModeMgr --> M5
    ModeMgr --> M6
    Mbox --> AC104

架构要点说明：

  • mbox_mg 应用是框架的宿主：应用启动时初始化框架（消息队列、模式表），并将六种工作模式注册进框架；
  • 事件/按键处理负责把用户输入（按键、遥控、外部中断）转换为统一事件；
  • 消息处理与分发是框架的中枢：接收事件消息，解析后决定是“当前模式内处理”还是“触发模式切换”；
  • 模式管理维护模式表与当前激活模式，执行模式进入（初始化）与退出（释放资源）的编排；
  • 电源管理与模式管理联动（如低功耗状态下限制可切换的模式、关机/待机事件的处理）；
  • AC104N 是 mbox_mg 应用对应的目标芯片（见工程 AC104N_mbox_mg.cbp）。

框架职责与模式管理详解

模式单元（工作模式）清单

mbox_mg 应用在 README 中明确列出的工作模式如下。每个模式对应一个相对独立的功能模块，由框架统一调度进入与退出：

模式标识模式名称功能定位
music音乐本地存储（U 盘 / TF 卡 / 闪存）音乐播放
fm收音FM 收音机：搜台、存台、播放广播
rec录音录音采集与存储（如 line_in 录音 / 麦克风录音）
line_in线路输入外部音频输入直通放大播放
loudspeaker扩音麦克风拾音扩音（喊话/扩音器场景）
usb_deviceUSB 设备接入 PC 作为 U 盘 / 声卡等 USB 设备

（来源：README.md）

框架层职责划分

框架层在本目录页所定义的能力边界内，承担以下通用职责：

1. 模式注册与管理（模式表）

框架维护一张“模式表”，记录所有已注册的模式单元及其标识。应用启动时各模式调用注册接口将自己挂入模式表；框架据此完成：

  • 模式标识 ↔ 模式处理函数的映射；
  • 当前激活模式的记录与查询；
  • 模式切换时的顺序编排（先退出旧模式，再进入新模式）。

2. 消息处理与分发

所有系统消息（按键事件、定时器、外设事件、电源事件）汇入框架的消息处理入口。分发逻辑按消息类型路由：

  • 与当前模式相关的消息 → 下发给当前模式的处理函数；
  • 与模式切换相关的消息（如“切换到 fm”）→ 交给模式管理执行切换；
  • 系统级消息（如低电、关机）→ 交由电源管理等系统模块处理。

3. 事件 / 按键处理

把物理输入（按键、遥控码、IO 中断）统一转换为语义化事件消息，屏蔽底层扫描/去抖细节，使模式单元与输入源解耦。

4. 电源管理

负责待机、关机、低电检测等电源相关事件的处理，并约束模式切换的时机（例如播放中进入待机、录音中禁止关机等策略），与模式生命周期联动。

上述职责的具体实现文件与函数签名未在本次源码探索中验证（受工具预算限制，未读取到框架目录内的实现代码）。以上描述依据目录页标题定义的框架能力边界与 README 中的应用结构整理，用于说明框架的设计意图与模块划分；实际以仓库中 applications/mbox/framework 目录下的实现代码为准。

设计意图：为什么采用“框架 + 模式”结构

  1. 单一应用多功能的组织方式：小音箱产品通常同时具备音乐、收音、录音、扩音等多种能力，若全部写在一个主循环里，状态分支会迅速膨胀且难以维护。将每种能力封装为模式单元后，主循环只需维护“当前模式”，各模式内部自治。
  2. 资源复用与隔离：音频通路、功放、显示屏等外设资源在模式间共享。框架统一管理模式进入/退出时的资源申请与释放，避免模式间相互踩踏。
  3. 产品化裁剪：不同产品型号可以只注册部分模式（例如不带 FM 模块的产品不注册 fm 模式），框架无需改动——这是模式表设计的直接收益。

与其他应用的对照

同一 SDK 中，voice_toy 应用采用同样的“应用内多模式”结构（toy_music / toy_midi / toy_record / toy_linein / toy_speaker / toy_idle / toy_softoff / toy_usb_slave），mcu 应用则为通用 MCU 形态（无音频模式体系）。这种一致性表明**“应用框架 + 模式表”是 SDK 应用层共用的组织范式**，mbox 的框架设计可在 voice_toy 中找到同构参照。

（来源：README.md、README.md）

核心流程：模式切换与消息分发

mbox 应用的运行围绕“消息 → 分发 → （切换）模式”的主循环展开。下图为框架启动与模式切换的总体流程（框架内部各步骤依据职责边界整理，具体函数实现未在本次探索中验证）：

flowchart TD
    Start([上电 / 复位]) --> Init["框架初始化<br/>消息队列、模式表注册"]
    Init --> Boot["进入默认模式<br/>(如 music)"]
    Boot --> Loop{"等待系统消息"}
    Loop -->|"按键 / 遥控事件"| Dispatch["消息处理与分发"]
    Loop -->|"电源事件"| Power["电源管理处理"]
    Loop -->|"模式内事件"| Inner["当前模式内处理"]
    Dispatch --> Decide{"消息要求切换模式?"}
    Decide -->|"是"| Switch["模式切换<br/>退出当前模式 → 进入目标模式"]
    Decide -->|"否"| Inner
    Switch --> Loop
    Inner --> Loop
    Power --> Loop

关键步骤说明：

  1. 框架初始化：应用启动时首先创建消息队列并注册全部模式单元，形成模式表；
  2. 进入默认模式：开机后框架选定默认模式（通常为 music）并执行其进入逻辑（初始化音频通路、加载播放源等）；
  3. 主循环等待消息：框架进入消息等待状态，按键、定时器、外设中断等都被转化为消息；
  4. 消息分发：框架按消息类型路由——电源事件交给电源管理；模式内事件下发给当前模式；模式切换请求交给模式管理；
  5. 模式切换：框架先执行当前模式的退出（释放资源、关闭外设），再执行目标模式的进入（申请资源、初始化功能），切换完成后回到主循环。

模式切换时序

sequenceDiagram
    participant U as 用户 / 外设
    participant E as 事件处理 (EventBus)
    participant M as 消息分发 (MsgDeal)
    participant S as 模式管理 (ModeMgr)
    participant C as 当前模式
    participant N as 目标模式

    U->>E: 按键输入 (如 FM 键)
    E->>M: 语义化事件消息
    M->>M: 解析消息类型
    M->>S: 请求切换模式 (fm)
    S->>C: 退出当前模式 (释放资源)
    C-->>S: 退出完成
    S->>N: 进入目标模式 (初始化)
    N-->>S: 进入完成
    S->>M: 切换完成
    M-->>U: 反馈 (如进入 FM 提示音)

构建与工程配置

mbox 应用通过 Code::Blocks 工程文件组织编译。README 中列出的工程与芯片/应用对应关系如下：

| `AC104N_mbox_mg.cbp` | AC104N | 小音箱 |

（来源：README.md）

同时，README 的应用目录树给出了 SDK 应用层的完整布局（mbox 与兄弟应用并列）：

│   │   │   ├── mbox_mg/           #     小音箱应用
│   │   │   ├── voice_toy/         #     语音玩具应用
│   │   │   └── mcu/               #     通用 MCU 应用

（来源：README.md）

从中可以确认：

  • 工程与应用的对应关系：AC104N_mbox_mg.cbp 是 mbox 小音箱应用的构建入口，目标芯片为 AC104N；AD18N_mcu.cbp 对应 mcu 通用 MCU 应用（AD18N / ch58）；
  • 框架随应用编译：mbox 应用构建时，其所属的框架目录（applications/mbox/framework）作为应用工程的一部分参与编译，不需要单独配置；
  • 模式裁剪的入口：若产品不需要某个模式，通常在构建配置或框架模式注册处剔除对应模式单元——具体裁剪机制以框架实现代码为准（未在本次探索中验证）。

使用示例

由于本次探索受源码工具预算限制，未能读取框架目录下的实现源码，因此本节给出的代码示例均提取自仓库 README（仓库内真实存在的文件内容），用于展示应用/模式的组织方式；框架 API 级别的示例请以仓库 applications/mbox/framework 目录下的实际实现为准。

示例 1：应用目录结构与模式清单

仓库 README 的应用目录树直接给出了 mbox 应用及其六种工作模式的组织方式，这也是框架模式表所注册模式的权威来源：

├── mbox_mg/            # 小音箱应用（music / fm / rec / line_in / loudspeaker / usb_device）
├── voice_toy/          # 语音玩具应用（toy_music / toy_midi / toy_record / toy_linein / toy_speaker / toy_idle / toy_softoff / toy_usb_slave）
└── mcu/                # 通用 MCU 应用

Source: README.md

示例 2：芯片支持表（模式/应用与芯片的绑定）

仓库 README 的芯片支持表明确了 mbox_mg 应用与 AC104N 芯片的对应关系，是理解框架硬件依赖的基础：

| **ch58** | AD18N | 语音玩具 / 通用 MCU（支持段码 LCD） |
| — | **AC104N** | 小音箱（mbox_mg） |

Source: README.md

英文版 README 提供相同信息：

| — | **AC104N** | Mini Speakers (mbox_mg) |

Source: README-en.md

示例 3：构建工程映射

| `AC104N_mbox_mg.cbp` | AC104N | 小音箱 |

Source: README.md

无可用示例的说明：框架实现（如模式注册、消息分发入口、模式切换函数）的具体调用示例，因本次未读取到 applications/mbox/framework 下的实现文件，此处不提供代码示例，避免臆造 API。

配置选项

本目录页可验证的“配置”主要体现在构建工程与芯片选型层面，汇总如下：

配置项类型默认/示例值说明
构建工程文件文件 (Code::Blocks .cbp)AC104N_mbox_mg.cbpmbox 小音箱应用的编译入口，包含框架与应用的全部源文件
目标芯片芯片型号AC104Nmbox_mg 应用对应的目标芯片（对应仓库 README 芯片支持表）
工作模式集合模式表music / fm / rec / line_in / loudspeaker / usb_device框架模式表中注册的模式单元，可在构建时按产品裁剪

框架运行时的可调参数（如消息队列深度、切换超时、电源策略）属于框架实现细节，未在本次探索中验证，此处不列出。

API Reference

无已验证的 API 签名可提供。 本次源码探索受工具预算限制，未能读取 applications/mbox/framework 目录下的实现文件，因此无法基于实际源码给出框架公开接口（如模式注册、消息分发、模式切换等函数的参数、返回值与异常行为）。为避免臆造 API 签名，本节不列出任何未经源码验证的方法签名；请以仓库中框架目录的实际实现代码为准，后续在扩大源码读取范围后补充本节。

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

以下内容分为两部分：已验证事实（来自 README）与框架层面的设计考量（依据框架职责边界与嵌入式系统通用实践整理，具体行为以实现代码为准）。

已验证的模式边界

  • mbox 应用与 voice_toy、mcu 应用在模式体系上相互独立，模式标识（如 music）仅在各自应用内有效——切换应用形态需要重新注册整套模式表；
  • mbox_mg 的目标芯片为 AC104N，而 mcu 应用对应 AD18N（ch58）。框架代码若依赖具体芯片外设（如 ADC、USB），则模式单元的可移植性受芯片差异约束。

框架层面的设计考量（未验证项）

  • 模式切换竞态：切换过程中若连续收到新的事件消息（如用户在 fm 进入过程中再次按键），框架需要串行化切换流程（切换期间挂起或缓存消息），否则会出现模式表状态不一致。具体实现未在本次探索中验证。
  • 资源冲突：音频通路（DAC/功放）为多模式共享资源，进入新模式前必须确保旧模式已释放；若某模式退出流程被阻塞（如录音写卡挂起），可能造成切换卡死——框架通常通过超时或强制退出机制兜底。
  • 电源事件优先级：低电/关机事件应优先于普通按键消息处理，避免在资源紧张时执行模式切换。典型策略是电源消息走独立的高优先级通道。
  • 外设异常：如 U 盘/TF 卡在 music 播放中拔出，框架需将“媒体移除”转换为消息通知当前模式处理；若处理不当可能出现空指针或播放任务悬挂。

以上各项的具体处理方式属于框架实现细节，均未在本次探索中验证，此处仅作为评审与测试框架时的关注清单。

性能与运维考量

  • 消息驱动的实时性：框架以消息队列为核心，模式的响应时延主要取决于消息队列处理周期；按键去抖、模式切换时的外设初始化耗时（如 USB 枚举、FM 搜台）会直接影响用户体验，通常需异步化或带超时处理（未验证）。
  • 构建与烧录：mbox 应用通过 AC104N_mbox_mg.cbp 工程构建，产物烧录到 AC104N 芯片；调试时可通过框架日志/串口输出观察模式切换轨迹（具体日志开关未验证）。
  • 运维边界：本页面面向开发与框架理解；量产配置（如默认模式、按键功能表）由各产品线在应用层定制，不改变框架结构。

扩展点

  • 新增模式单元：在 mbox 应用内新增一个模式目录（如蓝牙 bt 模式），实现该模式的进入/退出处理并注册进框架模式表即可，框架本体无需修改——这是“模式表”设计的主要扩展入口。
  • 模式裁剪：产品不需要的模式可从模式注册处剔除，构建产物随之缩小（对应 README 中模式清单的按需子集）。
  • 事件扩展：新增输入源（如新增按键、遥控码）时，在事件处理层增加消息转换即可，模式单元无感知。
  • 跨应用复用：voice_toy 与 mbox_mg 采用同构的“框架 + 模式”范式，框架层面的通用机制可跨应用移植复用。

上述扩展点的具体接口形态（注册函数签名、事件结构体定义等）未在本次探索中验证，实际操作时请参照框架目录下的实现代码。

测试

本次探索未发现可直接引用的框架测试文件。 嵌入式 SDK 通常以硬件在环（HIL）与手工用例为主。建议的测试关注点（依据框架职责推导，非源码证据）：

  • 模式切换的进入/退出顺序与资源释放完备性；
  • 切换过程中乱序消息注入下的状态一致性；
  • 电源事件（低电/关机）与模式切换的交织场景；
  • 各模式在对应外设异常（拔卡、断 USB）下的健壮性。
  • README.md — 仓库总览、芯片支持表与应用目录结构
  • README-en.md — 英文版仓库说明
  • 兄弟应用页面：voice_toy 应用框架与模式管理（toy_* 模式体系）
  • 兄弟应用页面：mcu 通用 MCU 应用
  • mbox 应用内各模式详情页：music / fm / rec / line_in / loudspeaker / usb_device（若目录中有对应页面）