Documentation
Development Documentation
ESP-IDF Development Environment Setup and Xiaozhi Compilation

ESP-IDF Development Environment Setup and Xiaozhi Compilation

ESP-IDF Development Environment Setup

This guide will help you set up the ESP-IDF 5.3.2 development environment on Windows and compile the Xiaozhi firmware.

Installing ESP-IDF

1. Download Offline Installer

You can download the ESP-IDF installer from:

Note: Both versions 5.3.1 and 5.3.2 can be used, with minimal functional differences.

2. Installation Steps

  1. Double-click the downloaded EXE file to start installation
  2. Accept the license agreement
  3. Choose installation path (recommended not to install on C drive)
  4. Follow the wizard to complete installation

3. Verify Installation

  1. Double-click the “ESP-IDF 5.3 PowerShell” shortcut on desktop
  2. Terminal will automatically import IDF environment
  3. Run test command:
cd examples/get-started/hello_world/
idf.py build

Compiling Xiaozhi Firmware

1. Get Source Code 

# Clone via Git (recommended)
git clone https://github.com/78/xiaozhi-esp32

# Or download ZIP from GitHub

2. Configure Development Board

  1. Set target chip:
# ESP32-S3
idf.py set-target esp32s3

# ESP32-C3
idf.py set-target esp32c3
  1. Configure board type:
idf.py menuconfig
# Enter Xiaozhi Assistant -> Board Selection

3. Compilation and Flashing

Basic commands:

# Compile only
idf.py build

# Compile and flash
idf.py build flash monitor

# Use faster flashing speed
idf.py -b 2000000 build flash monitor

# Specify COM port
idf.py -p COM5 build flash monitor

4. Common Configuration Changes

Modify Wake Word 

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

Modify WebSocket API 

idf.py menuconfig
# Enter Xiaozhi Assistant -> Websocket -> Websocket URL

Common Issues

1. Improve Compilation Speed

  • Disable antivirus software (including Windows Defender)
  • Delete build folder and recompile

2. Serial Port Driver Issues

If serial ports are not recognized, install the corresponding chip’s USB drivers.

3. I2C Conflict Resolution

If encountering I2C conflicts:

  1. Enter idf.py menuconfig
  2. Select Component config -> Audio Codec Device Configuration
  3. Disable the first option
  4. Recompile

Notes

  1. Project path should not contain Chinese characters
  2. Delete build folder when moving the project
  3. Ensure correct chip model configuration
  4. Regularly clean build directory to resolve compilation issues
WebSocket Communication Protocol