本文介绍如何在嵌入式设备上接入自定义唤醒词能力，包括适用硬件、资源准备、ESP-IDF menuconfig 配置以及接入注意事项。

前提条件

根据本文操作前，请确保您已经完成了以下工作：

• 基础实现流程。
• 使用乐鑫 ESP32-S3 或 ESP32-P4 芯片，并具备 PSRAM。
• 工程中已正确集成 nertc_wake_up 组件。
• 访问 GitHub 查看 nertc-iot-demo 示例项目。

功能概述

自定义唤醒词功能基于 ESP-SR 的 Multinet 模型实现，适用于需要将设备唤醒词替换为品牌词、角色词或业务专属口令的场景。

典型能力包括：

• 使用自定义唤醒词替代默认唤醒词。
• 在本地完成唤醒检测，减少误唤醒带来的无效上行。
• 与 AI 对话流程联动，在唤醒后进入后续识别与交互流程。

适用条件

自定义唤醒词当前主要适用于以下条件：

条件	说明
芯片	ESP32-S3 / ESP32-P4
内存	需具备 PSRAM
唤醒实现	基于 ESP-SR Multinet
资源文件	assets.bin 中需包含对应模型资源

若沿用当前 Demo 默认配置与资源，通常无需额外调整底层模型实现；如需替换为自定义资源，请重点确认模型和资源文件是否匹配。

配置步骤

第一步：确认工程依赖

在 demo/esp32/main/CMakeLists.txt 的 idf_component_register(... PRIV_REQUIRES ...) 中，确保已声明 nertc_wake_up 组件。

cmakeidf_component_register(SRCS ${SOURCES}
    ...
    PRIV_REQUIRES
        ...
        nertc_sdk
        nertc_wake_up
        ...
)

第二步：在 menuconfig 中开启自定义唤醒词

在 ESP-IDF 的 menuconfig 中完成以下配置：

1. 选择 Wake Word Implementation Type → Multinet model (Custom Wake Word)。
2. 选择 ESP Speech Recognition → Chinese Speech Commands Model（general chinese recognition (mn7_cn)）。

如果您使用的是默认板级配置，请确认对应的 sdkconfig.defaults.esp32s3 或板级追加配置没有覆盖以上选项。

第三步：确认资源文件包含唤醒模型

如果 assets.bin 使用的是自定义生成方式，请确认其中包含 mn7_cn 模型资源。

当前开源工程提供的 xiaozhi-assets-generator 默认不会自动选中该模型；如需生成带有该模型的资源，可参考 xiaozhi-assets-generator 工程。

第四步：编译并烧录资源

完成配置后，重新生成资源并编译固件：

bashcd demo/esp32

# 生成默认资源（如需,默认执行build的时候会自动执行）
python3 scripts/build_default_assets.py

# 构建 ESP32-S3
idf.py -B out/esp32s3 -DIDF_TARGET=esp32s3 build

# 烧录并查看日志
idf.py -B out/esp32s3 -p /dev/ttyUSB0 flash monitor

如果目标芯片为 ESP32-C3，则不建议启用该方案；如目标芯片为 ESP32-P4，请使用对应 target 与板级配置构建。

接入流程

建议直接参考 demo/esp32/main/audio/wake_words/nertc_afe_wake_word.cc 的实际实现，按“初始化 → 喂入音频 → 执行检测 → 触发回调”的顺序接入自定义唤醒词能力。

1. 初始化唤醒词实例

NertcAfeWakeWord::Initialize 中完成了 nertc_wake_up 的核心初始化流程，主要包括以下步骤：

1. 准备 nertc_wakeup_sdk_config_t config 配置结构。
2. 设置事件回调 config.event_handler.on_wake_word_detected，用于在命中唤醒词后通知业务层。
3. 按网络环境决定是否注入 http_io：
   • 4G 板卡（如 ml307）使用外部 HTTP IO；
   • 普通 Wi-Fi 板卡可传 nullptr。
4. 设置 deviceId、appkey、custom_config、models_list 等初始化参数。
5. 调用 nertc_wakeup_create(&config) 创建唤醒词实例。
6. 调用 nertc_wakeup_init(...) 完成引擎初始化。

可重点参考：demo/esp32/main/audio/wake_words/nertc_afe_wake_word.cc:127

2. 关键接口说明

nertc_wakeup_create

根据 config 创建唤醒词实例，返回后续检测流程使用的句柄。创建前需要先把回调、模型列表、业务配置等参数准备好。

nertc_wakeup_init

初始化唤醒词引擎。创建实例后，需要继续调用该接口，完成模型和检测器的实际初始化，之后才能开始送入音频数据。

nertc_wakeup_feed

向唤醒词引擎持续输入 PCM 音频数据。实际工程中是在 Feed 函数中按帧送入；如果输入为双声道，demo 会先取左声道，再送入检测器。

可重点参考：demo/esp32/main/audio/wake_words/nertc_afe_wake_word.cc:235

nertc_wakeup_detect

在送入一帧音频后主动执行一次检测。demo 的做法是每次 feed 完一帧，就立即调用一次 detect，确保能够持续检测当前音频流中是否命中自定义唤醒词。

on_wake_word_detected

命中唤醒词后的回调入口。demo 中通过 on_wake_word_detected_handle 将 SDK 回调转发到 NertcAfeWakeWord::DoCallBack，再通知上层业务执行后续逻辑。

可重点参考：demo/esp32/main/audio/wake_words/nertc_afe_wake_word.cc:14

3. 推荐调用方式

结合 demo，设备侧接入时可按以下顺序实现：

cppnertc_wakeup_sdk_config_t config;
config.event_handler.on_wake_word_detected = on_wake_word_detected_handle;
config.user_data = this;
config.models_list = models_list;
config.deviceId = device_id.c_str();
config.appkey = appkey.c_str();
config.custom_config = custom_config_json.c_str();

nertc_wake_word_ = nertc_wakeup_create(&config);
nertc_wakeup_init(nertc_wake_word_, 1, 0);

运行阶段持续送入音频：

cppnertc_wakeup_feed(nertc_wake_word_, pcm_data, samples);
nertc_wakeup_detect(nertc_wake_word_);

如果命中唤醒词，on_wake_word_detected 会被触发，您可以在回调中继续执行启动 AI 对话、更新界面状态或记录命中的唤醒词内容等业务逻辑。

4. demo 中的几个实现细节

• models_list 不能为空，否则初始化直接失败。
• custom_config 会优先合并本地 config.json 与 OTA 下发的 device_sdk_config，用于覆盖默认唤醒配置。
• 双声道输入场景下，demo 默认取左声道数据参与唤醒词检测。
• StoreWakeWordData 会保留一段最近的 PCM 数据，便于后续扩展命中前音频的缓存处理。

调试建议

1. 先验证基础唤醒能力

在替换自定义资源前，建议先使用默认资源验证以下链路正常：

• 设备录音正常
• Wake Word 检测正常
• 唤醒后可进入 AI 对话流程

2. 验证关键配置项

若出现“编译成功但始终无法唤醒”的情况，可先查看 demo/esp32/sdkconfig，确认以下配置是否已经生效：

• CONFIG_USE_CUSTOM_WAKE_WORD=y
• CONFIG_SR_MN_CN_MULTINET7_QUANT=y

如果以上配置未开启，即使工程能够正常编译，也可能无法正确加载自定义唤醒词能力。

3. 关注内存占用

自定义唤醒词模型对内存要求高于普通配置。若运行时出现初始化失败、模型加载失败或异常重启，请优先排查：

• PSRAM 是否正常启用
• 板级配置是否裁剪了必要资源
• 资源分区是否成功烧录

常见问题

Q1：ESP32-C3 能否使用自定义唤醒词？

通常不建议。当前自定义唤醒词方案主要面向 ESP32-S3 / P4 + PSRAM 硬件。

Q2：只改 menuconfig，不更新 assets.bin 可以吗？

不一定可以。如果使用了自定义生成的资源包，需要确认其中包含 mn7_cn 模型；否则即使配置正确，也可能无法正常唤醒。

Q3：默认 demo 是否已经包含相关能力？

默认 demo 已包含自定义唤醒词接入路径；如果沿用默认配置和资源，通常只需在 menuconfig 中切换到对应实现类型即可。