跳转至

KWS 唤醒应用*

提示

1. 概述*

KWS 唤醒应用，实现本地关键词唤醒（KWS）和语音命令识别，无需云端连接。支持唤醒词管理、TTS 播报、音量控制、动态灵敏度调节等功能，适用于智能音箱、语音遥控器等场景。

2. 功能特性*

  • 关键词唤醒（KWS）：本地实时检测唤醒词，支持自定义唤醒词
  • 语音命令识别：唤醒后识别命令词，响应超时可配置（默认 10s）
  • TTS 播报：支持主动播报（唤醒/命令响应）和被动播报（MCU 控制）
  • 唤醒词管理：支持一键设置、两步设置、主控同步三种模式
  • 音量控制：10-100 范围可调，步进 10
  • 动态灵敏度：唤醒后分两阶段逐步提高 KWS 阈值，减少误唤醒
  • 语音活动检测（VAD）：VAD 状态 LED 指示
  • 声音事件检测（SED）：支持非语音声音事件
  • 断电记忆：配置（唤醒词 ID、音量、TTS/KWS 开关）持久化存储
  • 出厂测试：硬件验证测试模式
  • LED 指示：VAD LED + 状态 LED

3. 目录结构*

app/offline_asr_app/
├── offline_asr_app.c          # 主程序（事件分派、状态机）
├── app_config.h               # 配置类型定义
├── app.mk                      # 编译配置
├── app.name                    # Kconfig 选项
├── Kconfig                     # 子配置（唤醒超时等）
├── config_manager/             # 配置持久化（CRC、版本控制）
│   ├── config_manager.c
│   ├── config_manager.h
│   └── Kconfig
├── viva/                       # VIVA 引擎编排
│   ├── viva.c / viva.h
│   ├── viva.mk
│   ├── Kconfig
│   ├── volume_ctrl/            #   音量控制子模块
│   ├── kws_and_tts_ctrl/       #   KWS/TTS 播报控制
│   └── set_wake_word/          #   唤醒词设置（一键/两步/主控）
├── vad/                        # 语音活动检测
│   ├── vad.c / vad.h
├── sed/                        # 声音事件检测
│   ├── sed.c / sed.h
├── led/                        # LED 指示
│   ├── led.c / led.h
│   └── Kconfig
├── dynamic_sensitivity/        # 动态灵敏度调节
│   ├── dynamic_sensitivity.c / .h
│   └── Kconfig
└── factory_test/               # 出厂测试
    ├── factory_test.c / .h

4. 配置说明*

4.1 顶层配置*

配置项 类型 默认值 说明
CONFIG_APP_KWS_TIME_OUT int 10 唤醒超时（秒），超时后回到监听状态
CONFIG_DISABLE_WAKE_TIMEOUT bool n 调试用：禁用唤醒超时
CONFIG_FACTORY_TEST bool y 启用出厂测试模式

4.2 断电记忆（config_manager）*

配置项 类型 默认值 说明
CONFIG_ENABLE_POWER_DOWN_MEMORY bool n 启用断电记忆，重启后恢复音量、唤醒词等配置

4.3 音量控制（viva/volume_ctrl）*

配置项 类型 默认值 范围 说明
CONFIG_HAS_VOLUME_CTRL bool y 启用音量控制
CONFIG_APP_DEFAULT_VOLUME int 100 10-100 默认音量
CONFIG_VOLUME_MIN int 10 10-100 最小音量
CONFIG_VOLUME_MAX int 100 10-100 最大音量
CONFIG_VOLUME_STEP int 10 — 音量调节步进（须满足 (max-min)%step==0）

4.4 KWS/TTS 控制（viva/kws_and_tts_ctrl）*

配置项 类型 默认值 说明
CONFIG_HAS_KWS_AND_TTS_CONTROL bool y 启用 KWS/TTS 控制
CONFIG_KWS_WAKEUP_REPORT_NONE bool y 不上报唤醒事件（静默模式）
CONFIG_KWS_WAKEUP_REPORT_ALL bool — 上报所有唤醒事件
CONFIG_KWS_WAKEUP_REPORT_CUSTOM bool — 自定义上报事件
CONFIG_TTS_RESPONSE_NONE bool y 无播报响应
CONFIG_TTS_RESPONSE_ACTIVE_CUSTOM bool — 主动播报（本地触发）
CONFIG_TTS_RESPONSE_PASSIVE_CUSTOM bool — 被动播报（MCU 控制）

4.5 唤醒词设置（viva/set_wake_word）*

配置项 类型 默认值 说明
CONFIG_HAS_SET_WAKE_WORD bool n 启用唤醒词管理
CONFIG_SET_WAKE_WORD_DEFAULT_ID int 100 默认唤醒词 ID
CONFIG_SET_WAKE_WORD_MASTER_CONFIG_MODE bool n 主控配置模式（从 MCU 加载）

4.6 动态灵敏度（dynamic_sensitivity）*

配置项 类型 默认值 说明
CONFIG_DYNAMIC_WAKEUP_SENSITIVITY_ADJUST bool y 启用动态灵敏度
CONFIG_DYNAMIC_WAKEUP_TIME_WINDOW_1 int 5 第一窗口时间（秒）
CONFIG_DYNAMIC_WAKEUP_THRESHOLD_INCREASE_1 int 10 第一窗口阈值增幅（%）
CONFIG_DYNAMIC_WAKEUP_TIME_WINDOW_2 int 10 第二窗口时间（秒）
CONFIG_DYNAMIC_WAKEUP_THRESHOLD_INCREASE_2 int 20 第二窗口阈值增幅（%）

4.7 LED*

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

5. 工作原理*

5.1 初始化流程*

  1. 上电初始化时检查寄存器值，判断是否进入厂测模式：若进入则执行厂测流程，未进入则执行正常初始化流程
  2. 初始化配置管理器，从闪存恢复掉电前的配置
  3. 读取唤醒源（冷启动 / 热启动）
  4. 初始化唤醒超时倒计时器，设置 VUI 状态为 LISTEN_STATE
  5. 如果启用 VIVA：加载 resource.bin，初始化音量控制、KWS/TTS 控制、唤醒词管理子模块
  6. 冷启动时发送 EVENT_POWER_ON_TTS_PLAY 开机播报
  7. 初始化 LED

5.2 状态机*

        唤醒词检测
LISTEN_STATE ──────────→ ACTIVE_STATE
     ↑                        │
     │                        │ 超时 / 退出唤醒
     └────────────────────────┘
  • LISTEN_STATE：监听唤醒词，KWS 持续运行
  • ACTIVE_STATE：已唤醒，监听命令词，超时倒计时中

5.3 事件处理*

事件 处理逻辑
EVENT_AUDIO_IN_RECORD_DONE 检查唤醒超时、动态灵敏度调整
EVENT_VAD_STATUS 转发到 VAD 模块，控制 VAD LED
EVENT_SED_STATUS 转发到 SED 模块
EVENT_WAKEUP_EXIT / EVENT_WAKEUP_EXIT_RX 退出激活态，恢复 LISTEN_STATE
KWS 唤醒事件 设置 ACTIVE_STATE，重启超时倒计时，重置动态灵敏度

5.4 唤醒超时机制*

  • 倒计时器使用 CONFIG_APP_KWS_TIME_OUT 初始化（默认 10s）
  • 每次 KWS 唤醒时重新计时
  • 播放在进行中或自学习进行中时自动延长窗口
  • 超时后恢复 LISTEN_STATE，发送超时事件

5.5 动态灵敏度*

唤醒后分两个阶段逐步提高 KWS 阈值，减少用户交互过程中的误唤醒：

窗口1（0-5s）：阈值增加 10%
窗口2（5-10s）：阈值增加 20%
超时后：恢复默认阈值

5.6 主循环*

app_task_loop() 中调用 viva_tick() 驱动 VIVA 引擎的周期性任务。

6. 使用方法*

6.1 编译*

配置文件位于 configs/example/kws/，根据功能需求选择：

配置文件 说明
8006_kws.config 仅 KWS 关键词唤醒
8006_kws_play.config KWS + 播报
8006_kws_sed.config KWS + SED 声音事件检测
8006_aec_kws_vad.config AEC 回声消除 + KWS + VAD
8006_aec_kws_vad_play.config AEC + KWS + VAD + 播报 
cp configs/example/kws/8006_kws.config .config
make defconfig
make clean; make

6.2 烧录运行*

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

7. 预期输出*

  1. 上电后播报开机 TTS 提示音（冷启动）
  2. 说出唤醒词 → 进入激活态，可通过串口打印信息查看唤醒词检测结果
  3. 激活态下说出命令词 → 执行对应动作（播报/上报事件）
  4. 超时无命令 → 自动回到监听态

8. 注意事项*

  1. resource.bin：VIVA 引擎依赖 resource.bin 资源文件，确保编译配置文件中 CONFIG_RESOURCE_BIN_PATH 指定正确的 resource.bin 路径即可
  2. 唤醒词设置：三种模式（一键/两步/主控），根据实际需求选择
  3. 断电记忆：启用前需确保闪存存储空间已配置（ENABLE_STORAGE_CUSTOM_DATA + CUSTOM_STORAGE_SPACE）
  4. 动态灵敏度：窗口时间不应超过唤醒超时时间，否则无法生效
  5. 出厂测试：默认启用，根据需求决定是否开启 CONFIG_FACTORY_TEST
  6. 调试模式：CONFIG_DISABLE_WAKE_TIMEOUT 使系统永不超时，仅用于调试
  7. 休眠/唤醒未实现：当前 SDK 不支持休眠功能，app_suspend() 和 app_resume() 保持空实现即可