WIFI 大模型应用*

提示

SDK 路径: http://gitlab.nationalchip.com/nationalchip/voice-wifi-solution/ovp_aiot
App 路径: SDK 路径下 app/smartbot_app/
适用芯片 8005/8006

说明

本应用与 WIFI 大模型方案密切相关，建议先阅读 WIFI 大模型方案说明。

1. 概述*

WIFI 大模型应用，通过 UART 协议与 WIFI 模组配合工作。MCU 端负责语音算法（KWS、VAD），WIFI 模组端负责联网和大模型业务逻辑。所有事件（唤醒、VAD、音频数据）均通过 UART 协议上报 WIFI 模组，由 WIFI 模组下发指令控制播报、唤醒状态等。

2. 功能特性*

UART 协议通信：双向命令/响应协议，与 WIFI 模组交换事件和指令
关键词唤醒桥接：KWS 事件转发到 WIFI 模组，WIFI 模组决定激活/休眠状态
VAD 桥接：VAD 状态实时上报 WIFI 模组
延迟唤醒：唤醒词检测后可配置延迟后激活（默认 1000ms）
超时管理：可配置的活动窗口（默认 10s），超时后自动回到监听态
UART 音频传输：支持 Opus/PCM 格式扬声器音频流，ACK/GPIO 流控
I2S 音频传输：可选 I2S 音频输入/输出
麦克风上传：将麦克风数据上传到 WIFI 模组
固件升级：通过 UART 的 OTA 固件升级
出厂测试：音频环路、录音播放、GPIO 测试
自激活过滤：防止 MCU 自播时误唤醒
LED 指示：VAD LED + 状态 LED

3. 目录结构*

app/smartbot_app/
├── smartbot_app.c            # 主程序（事件分派、状态机）
├── app.mk                     # 编译配置
├── app.name                   # Kconfig 选项
├── Kconfig                    # 子配置（超时、UART、LED 等）
├── led/                       # LED 指示灯
│   ├── led.c / led.h
├── timeout_manager/           # 超时管理器
│   ├── timeout_manager.c / .h
├── vad/                       # 语音活动检测
│   ├── vad.c / vad.h
└── uart_protocol/             # UART 协议栈
    ├── uart_protocol.c / .h
    ├── user_kws/              #   用户自定义关键词
    ├── mic_upload/            #   麦克风上传
    ├── spk/                   #   扬声器音频（UART / I2S）
    │   ├── uart_spk/          #     UART 扬声器
    │   │   ├── flow_ctrl/     #       流控制（ACK / GPIO）
    │   │   ├── spk_buf_manager/#     缓冲管理
    │   │   └── uart_spk_player/#     播放器（Opus/PCM 解析）
    │   └── i2s_spk/           #     I2S 扬声器
    ├── factory_test/          #   出厂测试
    ├── upgrade/               #   OTA 升级
    ├── data_query/            #   状态查询
    ├── voice_config/          #   语音配置
    ├── filter_self_act/       #   自激活过滤
    └── utility/               #   通用工具

4. 配置说明*

4.1 顶层配置*

配置项	类型	默认值	说明
`CONFIG_APP_KWS_TIME_OUT`	int	10	KWS 唤醒超时（秒）
`CONFIG_DELAY_AWAKE_DELAY_MS`	int	1000	唤醒后延迟激活时间（毫秒），≤0 则立即激活
`CONFIG_ENABLE_REPORT_MCU_PLAY_STATUS`	bool	y	向 WIFI 模组上报播放状态
`CONFIG_ENABLE_RESET_VAD_ON_MIC_OPEN`	bool	y	MIC 开启时重置 VAD
`CONFIG_ENABLE_MIC_AUTO_TOGGLE`	bool	n	唤醒时自动开 MIC，超时时自动关 MIC
`CONFIG_ENABLE_WAKE_SKIP_PLAY_AUDIO_CHECK`	bool	n	跳过自播音频检测（允许自播时 KWS 仍工作）
`CONFIG_DISABLE_WAKE_TIMEOUT`	bool	n	调试用：禁用唤醒超时

4.2 UART 通信配置*

配置项	类型	默认值	说明
`CONFIG_SMARTBOT_UART`	int	0	UART 接口编号（0-2）
`CONFIG_SMARTBOT_UART_BAUDRATE`	int	1000000	UART 波特率
`CONFIG_ENABLE_UART_TRANSMISSION`	bool	y	启用 UART 音频传输

4.3 扬声器配置*

配置项	类型	默认值	说明
`CONFIG_ENABLE_FORMAT_OPUS`	bool	—	扬声器音频格式：Opus（默认）
`CONFIG_ENABLE_FORMAT_PCM`	bool	—	扬声器音频格式：PCM
`CONFIG_ENABLE_ACK_FLOW_CTRL`	bool	—	ACK 流控制（默认）
`CONFIG_ENABLE_GPIO_FLOW_CTRL`	bool	—	GPIO 流控制
`CONFIG_SPK_FLOW_CTRL_PIN`	int	9	GPIO 流控制引脚
`CONFIG_PLAY_MUTE_DELAY_TIME`	int	30	播放结束后延迟静音（秒）

4.4 麦克风上传配置*

配置项	类型	默认值	范围	说明
`CONFIG_VAD_FALLBACK_FRAMES`	int	22	15-35	VAD 回落帧数
`CONFIG_MIC_FALLBACK_DATA_CONTINUOUS_UPLOAD`	bool	n	连续上传麦克风回落数据

4.5 I2S 传输配置*

配置项	类型	默认值	说明
`CONFIG_ENABLE_I2S_TRANSFER`	bool	n	启用 I2S 音频传输（与 UART 传输互斥）
`CONFIG_CACHE_TIME_MS`	int	840	I2S 缓存时间（毫秒）
`CONFIG_ENABLE_I2S_RX_M_TX_M`	bool	—	RX 主 + TX 主模式（默认）
`CONFIG_ENABLE_I2S_RX_S_TX_S`	bool	—	RX 从 + TX 从模式

4.6 LED 配置*

配置项	类型	默认值	说明
`CONFIG_ENABLE_LED`	bool	y	启用 LED
`CONFIG_APP_LED_VAD_PIN`	int	6	VAD LED GPIO
`CONFIG_APP_LED_STATUS_PIN`	int	13	状态 LED GPIO
`CONFIG_APP_LED_ON_LEVEL`	int	1	LED 点亮电平（0: 低有效, 1: 高有效）

5. 工作原理*

5.1 整体架构*

  ┌──────────────┐        UART 协议       ┌──────────────┐
  │   MCU (GX8006)│ ◄──────────────────► │  WIFI 模组     │
  │              │                        │              │
  │  KWS / VAD   │ ──事件上报──►          │  业务逻辑    │
  │  音频处理    │ ◄──指令下发──          │  播报控制    │
  │  麦克风上传  │ ──音频数据──►          │  状态管理    │
  └──────────────┘                        └──────────────┘

5.2 初始化流程*

读取唤醒源
启用 VPA 模式自动切换
初始化超时管理器（默认 10s），初始状态为 TIMEOUT_ACTIVE（允许唤醒）
初始化 UART 协议栈，建立与 WIFI 模组的通信
初始化 LED，点亮状态 LED

5.3 状态机*

        唤醒词检测 / WIFI 模组进入唤醒
LISTEN_STATE ────────────────────→ ACTIVE_STATE
     ↑                                  │
     │                                  │ 超时 / WIFI 模组退出唤醒
     └──────────────────────────────────┘

LISTEN_STATE：等待唤醒词或 WIFI 模组指令
ACTIVE_STATE：已唤醒，VAD 激活，音频处理运行中

超时管理器的语义（注意命名）：

超时状态	实际含义
`TIMEOUT_ACTIVE`	空闲/超时已过期，允许再次唤醒
`TIMEOUT_INACTIVE`	系统处于活动窗口，尚未超时

5.4 延迟唤醒*

唤醒词检测后不立即激活，注册一个单次定时器：

收到 KWS 唤醒事件
等待 CONFIG_DELAY_AWAKE_DELAY_MS（默认 1000ms）
定时器触发 → 设置 ACTIVE_STATE → 初始化 VAD

5.5 事件处理*

事件	处理逻辑
`EVENT_AUDIO_IN_RECORD_DONE`	转发到 UART 协议，WIFI 模组可获取原始音频
`EVENT_VAD_STATUS`	更新 SPL，根据播放状态调整 VAD 灵敏度，转发到 WIFI 模组
`EVENT_WAKEUP_ENTER_RX`	WIFI 模组命令进入唤醒：重置超时，设置 ACTIVE_STATE
`EVENT_WAKEUP_EXIT_RX`	WIFI 模组命令退出唤醒：设置 LISTEN_STATE
KWS 唤醒事件	延迟后设置 ACTIVE_STATE，转发到 WIFI 模组

5.6 主循环*

app_task_loop() 中调用 uart_protocal_loop() 处理 UART 收发。

6. 使用方法*

6.1 编译*

配置文件位于 configs/lightning/，根据传输方式选择：

配置文件	说明
`lightning_vad_028_kws_021_ack_flowctrl.config`	UART 传输 + ACK 流控
`lightning_vad_028_kws_021_io_flowctrl.config`	UART 传输 + GPIO 流控
`lightning_vad_028_kws_021_i2s.config`	I2S 传输

cp configs/lightning/lightning_vad_028_kws_021_ack_flowctrl.config .config
make defconfig
make clean; make

6.2 烧录运行*

cd tools/bootx/
./flash_nor.sh 0 -r 1000000

6.3 WIFI 模组配合*

该 App 需要 WIFI 模组通过 UART 协议配合工作。MCU 端配置完成后，WIFI 模组端需实现对应的 UART 协议栈。

7. 预期输出*

上电后状态 LED 点亮，等待 WIFI 模组通信就绪
说出唤醒词 → MCU 上报 KWS 事件 → WIFI 模组决定是否激活
WIFI 模组下发播报指令 → MCU 通过 UART/I2S 播放音频
超时无活动 → MCU 自动回到监听态，上报超时事件

8. 注意事项*

依赖 WIFI 模组：该 App 不自带业务逻辑，必须配合 WIFI 模组使用，UART 协议栈需 WIFI 模组端对应实现
UART 初始化失败则中止：如果 UART 协议栈初始化失败，app_init() 会直接返回错误
UART 与 I2S 互斥：CONFIG_ENABLE_UART_TRANSMISSION 和 CONFIG_ENABLE_I2S_TRANSFER 不能同时启用
超时管理器命名：TIMEOUT_INACTIVE 表示活动窗口内（未超时），TIMEOUT_ACTIVE 表示超时已过期，命名与直觉相反
播报阻止超时：WIFI 模组驱动的播报进行中时，超时计时器会自动重置，防止播报过程中误超时
VAD 可独立唤醒：当唤醒开关关闭但 VAD 开关打开时，VAD 检测可直接触发系统唤醒
延迟唤醒：默认 1 秒延迟可在 Kconfig 中调整，设为 0 则立即激活
休眠/唤醒未实现：当前 SDK 不支持休眠功能，app_suspend() 和 app_resume() 保持空实现即可