User-Defined Command Word Tool User Guide*

Note

The current script has been tested on Ubuntu 22.04; other environments have not been tested.
SDK link: http://gitlab.nationalchip.com/nationalchip/voice-wifi-solution/ovp_aiot/
The tool is located in the SDK at: tools/kws_setup_tool/
Note: Access to this link requires permissions. Please contact NationalChip Micro.

This script is used to generate UART configuration commands for configuring user-defined command words on the GX8006.

Modify the config.yaml file according to your requirements, then run the script and send the generated configuration commands to the 8006 via UART to complete the custom command word configuration.

1. Configuration File Description*

# Number of CPU cores; takes effect when the number of command words requiring threshold calculation exceeds 1
cpu_num: 1

# Model path
model_path: gxmodel/v0.1.0

# Whether to use the default command words (command words used when the firmware has no command words set)
use_default_command_words: false    # true / false

# Set command words; if you need to include the default command words, please add them manually
# word            : User-defined command word
# type            : 0 indicates a command word; 1 indicates a wake word
# event_id        : Wake word ID, reported via the offline voice wake-up event (0x08)
# misactive_number: Allowed number of false wake-ups
# threshold       : Use the specified threshold. When this parameter is set, the threshold will no longer be calculated based on the false wake-up count but will use this value directly. Set to null or omit this field if calculation is needed.
# aec_threshold   : Use the specified AEC threshold. When this parameter is set, the threshold will no longer be calculated based on the false wake-up count but will use this value directly. Set to null or omit this field if calculation is needed.
user_kws_list:
  - word: 小好小好
    type: 1
    event_id: 101
    misactive_number: 1
    # threshold: 750        # When specified, the threshold is no longer calculated based on the false wake-up count but uses this value directly
    # aec_threshold: 375    # When specified, the threshold is no longer calculated based on the false wake-up count but uses this value directly

  - word: 小好同学
    type: 1
    event_id: 102
    misactive_number: 1
    # threshold: 750        # When this field is not set, the threshold will be calculated based on the false wake-up count
    # aec_threshold: 375    # When this field is not set, the threshold will be calculated based on the false wake-up count

2. Command Parameter Description*

$ python main.py -h
usage: main.py [-h] [-v] [-i INPUTCONFIGPATH] [-o OUTPUT] [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
               [--debug]

User-defined command word setup generation tool

options:
  -h, --help            show this help message and exit
  -v, -V, --version     Display version information
  -i INPUTCONFIGPATH, --inputConfigPath INPUTCONFIGPATH
                        config.yaml configuration path
  -o OUTPUT, --output OUTPUT
                        Output file save path
  --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        Set log level
  --debug               Enable debug mode

3. Execution Instructions*

3.1. Running the Packaged Executable*

3.1.1. Modify the `config.yaml` Configuration File*

3.1.2. Run*

By default, the config.yaml in the main directory is used, and temporary files are generated in output:
```
$ ./main
```

3.2. Running from Source Code*

3.2.1. Environment Preparation*

The test environment uses Ubuntu 22.04 with Python version 3.10.12
```
$ python --version
Python 3.10.12
```
Create a virtual environment to avoid conflicts with other Python environments on the system:
```
python3 -m venv .venv
```
Activate the virtual environment:
```
source .venv/bin/activate
```
Install dependencies using pip:
```
pip3 install -r requirements.txt
```

3.2.2. Modify the `config.yaml` Configuration File*

3.2.3. Run*

By default, the config.yaml in the main directory is used, and temporary files are generated in output:
```
$ python3 main.py
```

4. Script Output Usage Instructions*

Each time the setting command is sent, the previously set entries will be reset, so all entries must be set in one go.
If the chip loses power, the setting data will also be lost.

Output example; you can directly send the complete protocol frame to the device via UART for testing.

$ python main.py
......
Command words not requiring threshold calculation: ['小好小好']
Command words requiring automatic threshold calculation: ['小好同学']
......
Final threshold results: {'小好小好': 750, '小好同学': 824}
Default command words not used
Command word: 小好小好, Length: 12, Label length: 8, Label values: [14, 38, 11, 37, 14, 38, 11, 37]
Command word: 小好同学, Length: 12, Label length: 8, Label values: [14, 38, 11, 37, 6, 51, 14, 35]
Complete protocol frame (binary): bytearray(b'U\xaa\x00\x92\x00d\x11\x00\x00\x00\x00\x00\x00\x02\x00\x00\x00e\x00\x00\x03I\x00\x00\x01\xa4\x00\x00\x00\x01\x0c\xe5\xb0\x8f\xe5\xa5\xbd\xe5\xb0\x8f\xe5\xa5\xbd\x10\x00\x0e\x00&\x00\x0b\x00%\x00\x0e\x00&\x00\x0b\x00%\x00\x00\x00f\x00\x00\x038\x00\x00\x01\x9c\x00\x00\x00\x01\x0c\xe5\xb0\x8f\xe5\xa5\xbd\xe5\x90\x8c\xe5\xad\xa6\x10\x00\x0e\x00&\x00\x0b\x00%\x00\x06\x003\x00\x0e\x00#\xe6')
Complete protocol frame (hexadecimal): 55aa0092006411000000000000020000006500000349000001a4000000010ce5b08fe5a5bde5b08fe5a5bd10000e0026000b0025000e0026000b002500000066000003380000019c000000010ce5b08fe5a5bde5908ce5ada610000e0026000b002500060033000e0023e6
UART data after the subcommand, excluding the subcommand and checksum (binary): bytearray(b'\x00\x00\x00\x00\x00\x00\x02\x00\x00\x00e\x00\x00\x03I\x00\x00\x01\xa4\x00\x00\x00\x01\x0c\xe5\xb0\x8f\xe5\xa5\xbd\xe5\xb0\x8f\xe5\xa5\xbd\x10\x00\x0e\x00&\x00\x0b\x00%\x00\x0e\x00&\x00\x0b\x00%\x00\x00\x00f\x00\x00\x038\x00\x00\x01\x9c\x00\x00\x00\x01\x0c\xe5\xb0\x8f\xe5\xa5\xbd\xe5\x90\x8c\xe5\xad\xa6\x10\x00\x0e\x00&\x00\x0b\x00%\x00\x06\x003\x00\x0e\x00#')
UART data after the subcommand, excluding the subcommand and checksum (hexadecimal): 000000000000020000006500000349000001a4000000010ce5b08fe5a5bde5b08fe5a5bd10000e0026000b0025000e0026000b002500000066000003380000019c000000010ce5b08fe5a5bde5908ce5ada610000e0026000b002500060033000e0023
Command word setting command generated. Please send it to the device using the 0x11 command
Program execution completed

5. FAQ*

5.1. What is the general usage flow?*

                    ┌──────────────┐
                    │   User Operation |
                    └──────┬───────┘
                           │ [HTTP]
                           ▼
                    ┌──────────────┐
                    │   Cloud Server |
                    └──────┬───────┘
                           │ [Load Configuration]
                           ▼
                    ┌──────────────┐
                    │ config.yaml  │
                    └──────┬───────┘
                           │ [Execute]
                           ▼
                    ┌──────────────┐
                    │Custom Command Word Tool|
                    └──────┬───────┘
                           │ [Output]
                           ▼
                    ┌──────────────┐
                    │   UART Commands |
                    └──────┬───────┘
                           │ [MQTT]
                           ▼
                    ┌──────────────┐
                    │   WIFI Module |
                    └──────┬───────┘
                           │ [UART]
                           ▼
                    ┌──────────────┐
                    │    MCU Device  |
                    └──────────────┘

5.2. How to manually set the threshold for command words?*

To manually set the threshold for command words, you need to set the threshold field for the command word in the configuration file config.yaml.

As follows:

user_kws_list:
  - word: 你好小智
    type: 1
    event_id: 101
    misactive_number: 1
    threshold: 750        # When specified, the threshold is no longer calculated based on the false wake-up count but uses this value directly
    aec_threshold: 375    # When specified, the threshold is no longer calculated based on the false wake-up count but uses this value directly

5.3. How to control whether to use the default command words in the firmware?*

The default command words in the firmware refer to the command words built into the default firmware (command words used when the firmware has no command words set), such as 你好小智 and 小智同学 in the standard firmware.

You can control whether to use the default command words in the firmware through the use_default_kws field in the configuration file config.yaml.

As follows:

# Whether to use the default command words (command words used when the firmware has no command words set)
use_default_command_words: false    # true / false

5.4. How to modify the default command words in the firmware?*

If you need to modify the default command words in the firmware, you need to modify the firmware source code and re-flash the firmware.

The source code path to modify is located at ovp/vpa/olab_panda/vui/kws_engine/model_fst/*/kws_list.h. (The * position is the name of the model package used)

kws_list.h file description:

const static OVP_KWS_PARAM g_ctc_kws_param_list[] = {
#ifdef CONFIG_ENABLE_NI_HAO_XIAO_ZHI
    {"你好小智", {7, 21, 11, 37, 14, 38, 63, 21}, 8, 750, 370, 100, 1},
#endif
#ifdef CONFIG_ENABLE_XIAO_ZHI_TONG_XUE
    {"小智同学", {14, 38, 63, 21, 6, 51, 14, 35}, 8, 750, 370, 100, 1},
#endif
#ifdef CONFIG_ENABLE_XIAO_MEI_XIAO_MEI
    {"小美小美", {14, 38, 3, 33, 14, 38, 3, 33}, 8, 750, 370, 100, 1},
#endif
};

Taking {"你好小智", {7, 21, 11, 37, 14, 38, 63, 21}, 8, 750, 370, 1}, as an example, the field descriptions are as follows:

你好小智: The command word.
{7, 21, 11, 37, 14, 38, 63, 21}: The label values corresponding to the command word, obtained from the log output by setting the desired command word in the config.yml file.
8: The label length of the command word.
750: The wake-up threshold for the command word, which can be obtained from the log output by setting the desired command word in the config.yml file.
370: The wake-up threshold under AEC for the command word, which can be obtained from the log output by setting the desired command word in the config.yml file.
100: The ID reported after wake-up.
1: The command word type; 0 indicates a command word, and 1 indicates a wake word.

Modification instructions:

To delete, simply comment out the array element for the unwanted command word.
To add, add the corresponding array element according to the instructions above.
To modify, modify the corresponding fields according to the instructions above.