ESP-IDF Development Environment Setup and XiaoZhi Compilation

This article will guide you on how to set up the ESP-IDF 5.3.2 development environment on Windows systems and compile the XiaoZhi firmware.

Installing ESP-IDF

1. Download the Offline Installation Package

You can download the ESP-IDF installation package from the following addresses:

• Espressif Official Download
• Espressif China Mirror
• Baidu Netdisk Backup Link

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

2. Installation Steps

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

3. Verify Installation

1. Double-click the “ESP-IDF 5.3 PowerShell” shortcut on the desktop
2. The terminal will automatically import the IDF environment
3. Execute the test command:

cd examples/get-started/hello_world/
idf.py build

Compiling XiaoZhi Firmware

1. Get the Source Code

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

# Or download the ZIP archive from GitHub

2. Configure the Development Board

1. Set the target chip:

# ESP32-S3
idf.py set-target esp32s3

# ESP32-C3
idf.py set-target esp32c3

2. Configure the development board type:

idf.py menuconfig
# Enter Xiaozhi Assistant -> Board Selection

3. Compile and Flash

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 serial 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. Improving Compilation Speed

• Turn off antivirus software (including Windows Defender)
• Delete the build folder and recompile

2. Serial Port Driver Issues

If the serial port cannot be recognized, you need to install the USB driver for the corresponding chip.

3. I2C Conflict Resolution

If you encounter I2C conflict issues:

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

Notes

1. Project path should not contain Chinese characters
2. Remember to delete the build folder when transferring the project
3. Ensure you use the correct chip model configuration
4. It is recommended to regularly clean the build directory to resolve compilation issues