xiaozhi-esphome回刷官方固件指南：ESP-IDF编译xiaozhi-esp32与WakeNet唤醒词烧录-平芜编程栈

【免费下载链接】xiaozhi-esphome

Alternative code to use xiaozhi ai devices in esphome/home assistant.

项目地址：https://gitcode.com/gh_mirrors/xi/xiaozhi-esphome

xiaozhi-esphome是让 Xiaozhi AI 设备通过ESPHome接入Home Assistant、充当语音助手卫星的开源项目。本指南讲反向操作：如果你的小智硬件刷了 ESPHome 固件，想回刷 xiaozhi-esp32 官方固件，如何用ESP-IDF完成编译与烧录，并正确选择WakeNet 唤醒词。

1️⃣ 什么情况下需要回刷官方固件

刷回原厂 xiaozhi-esp32 固件，通常出于这几类需求：

🔄体验对比：ESPHome 版与官方版交互逻辑不同，想换回原厂的"单表情 + 对话"风格
🧩功能差异：官方固件支持 WeChat 聊天式界面、更多板型与语音特性
🛠️排障定位：设备异常时，先回到官方固件基线确认是硬件还是固件问题

💡 官方刷写手册就在本项目里：other/README.md，文中给出了完整的仓库克隆地址与每一步命令，建议配合本指南使用。

2️⃣ 刷写前准备：安装 ESP-IDF

从乐鑫（Espressif）官方下载页获取ESP-IDF 5.4 或更高版本安装包
按提示完成安装，打开ESP-IDF PowerShell（Windows）或激活 ESP-IDF 环境变量（Linux/macOS）
将目标设备用 USB 连接电脑，确认系统能识别到对应串口

⚠️ 版本注意：请确保 ESP-IDF ≥ 5.4，低版本可能缺少新版 xiaozhi-esp32 源码所需的依赖。

3️⃣ 克隆 xiaozhi-esp32 源码

在终端中执行克隆命令拉取官方 xiaozhi-esp32 仓库（完整地址见 other/README.md），克隆完成后进入仓库目录：

cd xiaozhi-esp32

4️⃣ 设置目标芯片与设备配置

第一步：指定芯片（小智系列设备普遍使用 ESP32-S3）：

idf.py set-target esp32s3

第二步：打开图形化配置：

idf.py menuconfig

在Xiaozhi Assistant菜单中重点设置三项：

配置项	说明
Default Language	默认中文，可按需切换英文
Board Type	按实际硬件选择，例如 Ball V2 选`Spotpear ESP32-S3-1.28-BOX`
WeChat 选项	开启后从"居中单表情"变为聊天式界面，适合方形屏，圆屏不推荐

5️⃣ 选择并烧录 WakeNet 唤醒词

唤醒词决定设备"喊它什么名字才会开始听"。在menuconfig中进入：

ESP Speech Recognition → Load Multiple Wake Words (WakeNet9)

在 WakeNet9 唤醒词列表中勾选你偏好的唤醒词，保存后该词会被编译进固件，烧录时自动写入设备，无需额外操作。

配置完成后按Esc退出menuconfig，选择Yes保存。

6️⃣ 编译并烧录固件

编译（首次编译耗时较长，请耐心等待依赖下载）：

idf.py build

烧录（把端口号换成设备实际串口，Windows 常见为 COMx，Linux 为 /dev/ttyUSBx）：

idf.py -p COM5 flash

烧录完成后设备会自动重启，看到官方固件的默认界面即回刷成功 🎉

7️⃣ 再次修改配置或升级源码

想换唤醒词、换板型或刷新版固件？只需重复三步：

idf.py menuconfig idf.py build idf.py -p COM5 flash

想同步上游最新代码，在 xiaozhi-esp32 目录内执行git pull后重新编译烧录即可。

8️⃣ 官方固件 vs ESPHome 版：唤醒词机制有何不同

官方 xiaozhi-esp32	xiaozhi-esphome（ESPHome 版）
唤醒引擎	WakeNet9 多唤醒词，编译期烧录	`micro_wake_word`组件
自定义唤醒词	在 menuconfig 中从预设列表选择	仓库内置模型库 + 自训练模型
接入中心	小智官方云服务	Home Assistant

ESPHome 侧的唤醒词模型文件集中在 MicroWakeWords/ 目录，例如 v2 模型 hey_sarah.json 对应的.tflite模型；设备 YAML 中只需按文件名引用（见 MicroWakeWords/README.md）：

micro_wake_word: models: - model: okay_nabu

主流模块化配置的核心唤醒词定义在 core.yaml 的micro_wake_word段落中。如果你最终决定返回 ESPHome，按项目主页 README.md 的快速开始步骤重新无线安装即可，无需再折腾 ESP-IDF。

✅ 小结

回刷官方固件的核心链路：ESP-IDF ≥ 5.4 → 克隆 xiaozhi-esp32 →set-target→menuconfig（含 WakeNet 唤醒词）→build→flash
详细步骤与仓库地址以 other/README.md 为准
官方版与 ESPHome 版唤醒词机制不同，切换固件后原唤醒词设置不会保留，需重新配置