Skip to content

KWS Wake-Up Application*

Note

1. Overview*

The KWS wake-up application enables local keyword spotting (KWS) and voice command recognition without cloud connectivity. It supports wake word management, TTS playback, volume control, dynamic sensitivity adjustment, and other features, making it suitable for smart speakers, voice remote controls, and similar scenarios.

2. Features*

  • Keyword Spotting (KWS): Local real-time wake word detection, supports custom wake words
  • Voice Command Recognition: Recognizes command words after wake-up, configurable response timeout (default 10s)
  • TTS Playback: Supports active playback (wake-up/command response) and passive playback (MCU-controlled)
  • Wake Word Management: Supports three modes: one-step setting, two-step setting, and master synchronization
  • Volume Control: Adjustable from 10-100, step size 10
  • Dynamic Sensitivity: Gradually increases the KWS threshold in two stages after wake-up to reduce false wake-ups
  • Voice Activity Detection (VAD): VAD status LED indication
  • Sound Event Detection (SED): Supports non-speech sound events
  • Power-Down Memory: Persistent storage of configuration (wake word ID, volume, TTS/KWS switches)
  • Factory Test: Hardware verification test mode
  • LED Indication: VAD LED + status LED

3. Directory Structure*

app/offline_asr_app/
├── offline_asr_app.c          # Main program (event dispatch, state machine)
├── app_config.h               # Configuration type definitions
├── app.mk                      # Build configuration
├── app.name                    # Kconfig option
├── Kconfig                     # Sub-configuration (wake-up timeout, etc.)
├── config_manager/             # Configuration persistence (CRC, version control)
│   ├── config_manager.c
│   ├── config_manager.h
│   └── Kconfig
├── viva/                       # VIVA engine orchestration
│   ├── viva.c / viva.h
│   ├── viva.mk
│   ├── Kconfig
│   ├── volume_ctrl/            #   Volume control submodule
│   ├── kws_and_tts_ctrl/       #   KWS/TTS playback control
│   └── set_wake_word/          #   Wake word setting (one-step/two-step/master)
├── vad/                        # Voice activity detection
│   ├── vad.c / vad.h
├── sed/                        # Sound event detection
│   ├── sed.c / sed.h
├── led/                        # LED indication
│   ├── led.c / led.h
│   └── Kconfig
├── dynamic_sensitivity/        # Dynamic sensitivity adjustment
│   ├── dynamic_sensitivity.c / .h
│   └── Kconfig
└── factory_test/               # Factory test
    ├── factory_test.c / .h

4. Configuration Description*

4.1 Top-Level Configuration*

Configuration Item Type Default Value Description
CONFIG_APP_KWS_TIME_OUT int 10 Wake-up timeout (seconds), returns to listening state after timeout
CONFIG_DISABLE_WAKE_TIMEOUT bool n Debug only: disables wake-up timeout
CONFIG_FACTORY_TEST bool y Enables factory test mode

4.2 Power-Down Memory (config_manager)*

Configuration Item Type Default Value Description
CONFIG_ENABLE_POWER_DOWN_MEMORY bool n Enables power-down memory, restores volume, wake word, and other configurations after reboot

4.3 Volume Control (viva/volume_ctrl)*

Configuration Item Type Default Value Range Description
CONFIG_HAS_VOLUME_CTRL bool y Enables volume control
CONFIG_APP_DEFAULT_VOLUME int 100 10-100 Default volume
CONFIG_VOLUME_MIN int 10 10-100 Minimum volume
CONFIG_VOLUME_MAX int 100 10-100 Maximum volume
CONFIG_VOLUME_STEP int 10 — Volume adjustment step size (must satisfy (max-min)%step==0)

4.4 KWS/TTS Control (viva/kws_and_tts_ctrl)*

Configuration Item Type Default Value Description
CONFIG_HAS_KWS_AND_TTS_CONTROL bool y Enables KWS/TTS control
CONFIG_KWS_WAKEUP_REPORT_NONE bool y Does not report wake-up events (silent mode)
CONFIG_KWS_WAKEUP_REPORT_ALL bool — Reports all wake-up events
CONFIG_KWS_WAKEUP_REPORT_CUSTOM bool — Custom event reporting
CONFIG_TTS_RESPONSE_NONE bool y No playback response
CONFIG_TTS_RESPONSE_ACTIVE_CUSTOM bool — Active playback (locally triggered)
CONFIG_TTS_RESPONSE_PASSIVE_CUSTOM bool — Passive playback (MCU-controlled)

4.5 Wake Word Setting (viva/set_wake_word)*

Configuration Item Type Default Value Description
CONFIG_HAS_SET_WAKE_WORD bool n Enables wake word management
CONFIG_SET_WAKE_WORD_DEFAULT_ID int 100 Default wake word ID
CONFIG_SET_WAKE_WORD_MASTER_CONFIG_MODE bool n Master configuration mode (loaded from MCU)

4.6 Dynamic Sensitivity (dynamic_sensitivity)*

Configuration Item Type Default Value Description
CONFIG_DYNAMIC_WAKEUP_SENSITIVITY_ADJUST bool y Enables dynamic sensitivity
CONFIG_DYNAMIC_WAKEUP_TIME_WINDOW_1 int 5 First window time (seconds)
CONFIG_DYNAMIC_WAKEUP_THRESHOLD_INCREASE_1 int 10 First window threshold increase (%)
CONFIG_DYNAMIC_WAKEUP_TIME_WINDOW_2 int 10 Second window time (seconds)
CONFIG_DYNAMIC_WAKEUP_THRESHOLD_INCREASE_2 int 20 Second window threshold increase (%)

4.7 LED*

Configuration Item Type Default Value Description
CONFIG_ENABLE_LED bool n Enables LED indication
CONFIG_APP_LED_VAD_PIN int 5 VAD indicator GPIO
CONFIG_APP_LED_STATUS_PIN int 6 Status indicator GPIO
CONFIG_APP_LED_ON_LEVEL int 0 LED on level (0: active low, 1: active high)

5. Working Principle*

5.1 Initialization Flow*

  1. Check register values at power-on initialization to determine whether to enter factory test mode: if entered, execute the factory test flow; otherwise, execute the normal initialization flow
  2. Initialize the configuration manager and restore pre-power-down configurations from flash
  3. Read the wake-up source (cold boot / warm boot)
  4. Initialize the wake-up timeout countdown timer and set the VUI state to LISTEN_STATE
  5. If VIVA is enabled: load resource.bin, initialize volume control, KWS/TTS control, and wake word management submodules
  6. Send EVENT_POWER_ON_TTS_PLAY for power-on playback on cold boot
  7. Initialize the LED

5.2 State Machine*

        Wake word detection
LISTEN_STATE ──────────→ ACTIVE_STATE
     ↑                        │
     │                        │ Timeout / exit wake-up
     └────────────────────────┘
  • LISTEN_STATE: Listens for wake words, KWS runs continuously
  • ACTIVE_STATE: Woken up, listens for command words, timeout countdown in progress

5.3 Event Handling*

Event Handling Logic
EVENT_AUDIO_IN_RECORD_DONE Check wake-up timeout, dynamic sensitivity adjustment
EVENT_VAD_STATUS Forward to VAD module, control VAD LED
EVENT_SED_STATUS Forward to SED module
EVENT_WAKEUP_EXIT / EVENT_WAKEUP_EXIT_RX Exit active state, restore LISTEN_STATE
KWS wake-up event Set ACTIVE_STATE, restart timeout countdown, reset dynamic sensitivity

5.4 Wake-Up Timeout Mechanism*

  • Countdown timer initialized with CONFIG_APP_KWS_TIME_OUT (default 10s)
  • Restarts timing on each KWS wake-up
  • Automatically extends the window during playback or self-learning
  • Restores LISTEN_STATE after timeout and sends a timeout event

5.5 Dynamic Sensitivity*

After wake-up, the KWS threshold is gradually increased in two stages to reduce false wake-ups during user interaction:

Window 1 (0-5s): threshold increase 10%
Window 2 (5-10s): threshold increase 20%
After timeout: restore default threshold

5.6 Main Loop*

app_task_loop() calls viva_tick() to drive the periodic tasks of the VIVA engine.

6. Usage*

6.1 Compilation*

Configuration files are located in configs/example/kws/, select based on functional requirements:

Configuration File Description
8006_kws.config KWS keyword wake-up only
8006_kws_play.config KWS + playback
8006_kws_sed.config KWS + SED sound event detection
8006_aec_kws_vad.config AEC echo cancellation + KWS + VAD
8006_aec_kws_vad_play.config AEC + KWS + VAD + playback 
cp configs/example/kws/8006_kws.config .config
make defconfig
make clean; make

6.2 Flashing and Running*

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

7. Expected Output*

  1. Power-on TTS prompt tone after boot (cold boot)
  2. Say the wake word → enters active state, wake word detection result can be viewed via serial port print information
  3. Say a command word in active state → executes the corresponding action (playback/event reporting)
  4. Timeout without command → automatically returns to listening state

8. Notes*

  1. resource.bin: The VIVA engine depends on the resource.bin resource file. Ensure CONFIG_RESOURCE_BIN_PATH in the build configuration file points to the correct resource.bin path
  2. Wake Word Setting: Three modes (one-step/two-step/master), select based on actual requirements
  3. Power-Down Memory: Ensure flash storage space is configured before enabling (ENABLE_STORAGE_CUSTOM_DATA + CUSTOM_STORAGE_SPACE)
  4. Dynamic Sensitivity: The window time should not exceed the wake-up timeout, otherwise it will not take effect
  5. Factory Test: Enabled by default, decide whether to enable CONFIG_FACTORY_TEST based on requirements
  6. Debug Mode: CONFIG_DISABLE_WAKE_TIMEOUT prevents the system from ever timing out, for debugging only
  7. Sleep/Wake-Up Not Implemented: The current SDK does not support sleep functionality. app_suspend() and app_resume() can remain as empty implementations