小智 AI 聊天机器人文档中心 | 小智AI.Dev
开发说明
ESP-IDF 开发环境搭建及编译小智

ESP-IDF 开发环境搭建及编译小智

本文将指导你如何在 Windows 系统上搭建 ESP-IDF 开发环境（5.4.0 或更高版本），并编译小智固件。

安装 ESP-IDF

1. 下载离线安装包

可以从以下地址下载 ESP-IDF 安装包：

重要提示： 小智 v2.x 要求 ESP-IDF 5.4.0 或更高版本。
安装 SDK 时请选择 ESP-IDF 5.4.x（推荐） 或更新的稳定版本。
如果使用旧版 5.3.x，执行 idf.py set-target 等命令时会报错，错误信息类似：

ERROR: Because project depends on idf (>=5.4.0) which doesn't match any versions, version solving failed.

2. 安装步骤

  1. 双击下载的 EXE 文件开始安装
  2. 同意许可协议
  3. 选择安装路径（建议不要安装在 C 盘）
  4. 按照向导完成安装

3. 验证安装

  1. 双击桌面的 “ESP-IDF 5.4 PowerShell” 快捷方式
  2. 终端会自动导入 IDF 环境
  3. 执行测试命令：
cd examples/get-started/hello_world/
idf.py build

编译小智固件

1. 获取源码 

# 通过 Git 克隆（推荐）
git clone https://github.com/78/xiaozhi-esp32

# 或者从 GitHub 下载 ZIP 压缩包

2. 配置开发板

  1. 设置目标芯片：
# ESP32-S3
idf.py set-target esp32s3

# ESP32-C3
idf.py set-target esp32c3
  1. 配置开发板类型：
idf.py menuconfig
# 进入 Xiaozhi Assistant -> Board Selection

3. 编译与烧录

基本命令：

# 仅编译
idf.py build

# 编译并烧录
idf.py build flash monitor

# 使用更快的烧录速度
idf.py -b 2000000 build flash monitor

# 指定串口
idf.py -p COM5 build flash monitor

4. 常见配置修改

修改唤醒词 

idf.py menuconfig
# 进入 ESP Speech Recognition -> Wake Word

修改 WebSocket API 

idf.py menuconfig
# 进入 Xiaozhi Assistant -> Websocket -> Websocket URL

常见问题

1. 提升编译速度

  • 关闭杀毒软件（包括 Windows Defender）
  • 删除 build 文件夹后重新编译

2. 串口驱动问题

如果无法识别串口，需要安装对应芯片的 USB 驱动。

3. I2C 冲突解决

如遇到 I2C 冲突问题：

  1. 进入 idf.py menuconfig
  2. 选择 Component config -> Audio Codec Device Configuration
  3. 关闭第一个选项
  4. 重新编译

4. 错误：project depends on idf (>=5.4.0)

如果遇到类似下面的错误：

ERROR: Because project depends on idf (>=5.4.0) which doesn't match any versions, version solving failed.

说明你安装的 ESP-IDF 版本过旧（如 5.3.x）。
请安装 ESP-IDF 5.4.0 或更高版本，并确保开发环境使用了正确的版本，然后重试：

idf.py set-target esp32s3
idf.py build

注意事项

  1. 工程路径不要包含中文
  2. 转移工程时记得删除 build 文件夹
  3. 确保使用正确的芯片型号配置
  4. 建议定期清理 build 目录以解决编译问题
WebSocket 通信协议