Skip to content

kwsModelAutoDeploy Tool User Guide*

📌 Basic Information

1. Tool Introduction*

kwsModelAutoDeploy is a model auto-deployment tool that deploys trained models to the ovp_aiot SDK with one click.

⚠️ Notes

Manual configuration is required in the following cases, refer to Section 5.2 for manual model configuration

  • -b parameter fails
  • Default configuration does not match your hardware setup or actual requirements

2. Deployment Mode Selection*

Select the corresponding deployment mode based on model type and business requirements:

Deployment Mode Applicable Scenario
BunKws-DeploymentMode Pure classification wake-up solution
BunKws+CTC-DeploymentMode WIFI large model solution
BunKws+CTC+MP-DeploymentMode Configurable + classification wake-up solution

3. Command Parameters*

3.1 Common Parameters (Shared by All Modes)*

./kwsModelAutoDeploy <MODE> [OPTIONS]
Parameter Abbreviation Description Example/Requirement
--inputPath -i Model directory path output by BunKws Directory must contain: keyword.txt, mean_std.txt, model_fornax.h, cmd_id.txt
--sdkRootPath -r SDK root path (ending with ovp_aiot) ~/work/ovp/ovp_aiot
--customerName -c Customer identifier Only letters/underscores allowed, e.g., nationalchip
--projectName -p Project name (model deployment subdirectory) Only letters/underscores allowed, e.g., xiaoshu_ai
--deployVersion -dv Model version number Default v0.1.0, prompts for overwrite on duplicate
--bulidConfig -b Generate build configuration (enable auto integration) No value parameter; manual configuration is still recommended
--debug -d Debug mode (output detailed logs) No value parameter; enable for troubleshooting

3.2 Input Directory Structure Requirements*

<inputPath>/
├── keyword.txt      # Ordered keyword list (do not modify)
├── mean_std.txt     # Model normalization parameters (do not modify)
├── model_fornax.h   # Model header file exported from Fornax platform (do not modify)
└── cmd_id.txt       # Model metadata (thresholds, main wake-up word identifier, event IDs, etc.)

⚠️ Missing files will cause deployment failure; please verify in advance

4. Usage Examples*

4.1 Basic Deployment Command*

# Mode: BunKws+CTC-DeploymentMode
./kwsModelAutoDeploy BunKws+CTC-DeploymentMode \
  -i ~/Downloads/v0.1.1 \
  -r ../../../ovp_aiot/ \
  -c test \
  -p t1 \
  -dv v0.1.1 \
  -b

4.2 Parameter Quick Reference*

# View main help
./kwsModelAutoDeploy -h

# View help for a specific mode
./kwsModelAutoDeploy BunKws+CTC-DeploymentMode -h

5. Firmware Compilation and Flashing*

5.1 Keyword Type and Event ID Configuration*

If the model contains multiple wake-up words/command words, it is recommended to modify event IDs to distinguish reporting:

  1. Edit the generated vocabulary file: 

    ovp/vpa/olab_panda/vui/kws_engine/model_fst/bunkws/<customer>/<project>/kws_list.h

  2. Modification example: 

    // Format: {"keyword", {reserved}, reserved, non-AEC threshold, AEC threshold, event ID, keyword type}
{"Xiao Fan Xiao Fan", {0}, 1, 666, 333, 101, 1},  // Event ID = 101, Type 1: wake-up word
{"Open Device", {0}, 1, 666, 333, 102, 0},  // Event ID = 102, Type 0: secondary command word

    ⚠️ Notes:

    • At least one wake-up word (keyword type 1) is required; otherwise, wake-up will not work
    • It is recommended to have only one wake-up word, no more than three, to avoid high false wake-up rates
    • Event IDs correspond to the IDs reported in the offline voice wake-up event report (0x08) command in the UART protocol
    • If wake-up performance is poor under normal conditions (speaker not playing), try lowering the non-AEC threshold for testing
    • If wake-up performance is poor under AEC conditions (speaker playing), try lowering the AEC threshold for testing

5.2 Manual Model Configuration*

If the wake-up words are not updated after flashing, configure manually:

# 1. Enter the SDK root directory
cd ../../

# 2. Copy the base configuration (select io/ack solution based on hardware)
cp configs/lightning/lightning_*_flowctrl.config .config

# 3. Enter menu configuration
make menuconfig

Model Configuration Path: 

Olab Panda Settings 
  └─> VUI Settings 
       └─> Enable Keyword Recognition 
            ├─> Model Type Select:        general bunkws
            ├─> Customer Select:          <your -c parameter>
            ├─> Model Version Select:     <your -p parameter> + <your -dv parameter>
            ├─> Language Model Select:    model fst bunkws + <your -p parameter>
            └─> Kws Select:               [select keywords as needed]

⚠️ Notes:

Ensure configurations that need to match your specific board are modified accordingly

5.3 Compilation and Flashing*

# === Compile firmware ===
cd ~/work/ovp/ovp_aiot
make clean;make

# === Flash firmware on Ubuntu ===
cd tools/bootx
# Parameters: <serial port number> <baud rate>
./flash_nor.sh 0 1000000

🔧 Flashing Notes

  • Ensure the development board enters download mode (usually by holding the BOOT button while pressing Reset to power on)
  • Serial port number 0 corresponds to /dev/ttyUSB0; adjust according to your actual device
  • For Windows systems, refer to NCDownloader User Guide

6. Common Issue Troubleshooting*

Issue Possible Cause Solution
Deployment error file not found Missing files in input directory Check the 4 required files under inputPath
Compilation failure model not found -b failed or manual configuration error Run make menuconfig to re-select the model version
Wake-up word not responding No keyword with type 1 / threshold too high Check wake-up type in kws_list.h, lower threshold if needed
Flashing hangs Serial port permission / baud rate mismatch sudo chmod 666 /dev/ttyUSB*, try lowering the baud rate

📬 Technical Support

If you encounter tool anomalies or model compatibility issues, please provide:
1. Complete command and error logs
2. Original model files
3. SDK version information (git log)
Contact the NationalChip voice team for assistance.