ESP-IDF Development Environment Setup and XiaoZhi Compilation

This guide explains how to set up an ESP-IDF development environment and build the XiaoZhi firmware. Examples target Windows; the command-line steps are the same on Linux.

Choosing a Development Environment

• Editor: Cursor or VSCode with the ESP-IDF extension, selecting SDK v6.0.1 or later.
• OS: the project recommends Linux first (faster builds, no serial driver problems); Windows works as well.
• Code style: the project uses Google C++ style, see the Code Style Guide before submitting code.

Installing ESP-IDF

1. Download the installer

On Windows you can get the ESP-IDF installer from:

• Espressif official downloads
• Espressif China mirror

Choose v6.0.1 or later. To use the recommended release/v6.1 branch, fetch it with Git:

git clone -b release/v6.1 --recursive https://github.com/espressif/esp-idf.git

2. Installation steps

1. Run the downloaded installer
2. Accept the license agreement
3. Choose an installation path (avoid the C: drive and avoid non-ASCII characters in the path)
4. Complete the wizard

3. Verify the installation

1. Open the ESP-IDF PowerShell shortcut created by the installer (its name varies slightly with the selected version)
2. The terminal imports the IDF environment automatically
3. Confirm the version is 6.0.1 or later:

idf.py --version

4. Build an example project:

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

Building the XiaoZhi Firmware

1. Get the source code

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

# Or download the ZIP archive from GitHub

2. Configure the board

1. Set the target chip:

# ESP32-S3
idf.py set-target esp32s3

# ESP32-C3
idf.py set-target esp32c3

2. Select the board:

idf.py menuconfig
# Go to Xiaozhi Assistant -> Target Board

3. Build and flash

Basic commands:

# Build only
idf.py build

# Build and flash
idf.py build flash monitor

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

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

4. Common configuration changes

Change the wake word

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

Change the WebSocket API

idf.py menuconfig
# Go to Xiaozhi Assistant -> Websocket -> Websocket URL

Required Steps After Switching ESP-IDF Versions

After moving from 5.x (or any other version) to v6.0.1+, align the dependencies and caches with the new SDK:

# Update submodules inside the ESP-IDF directory
cd <esp-idf directory>
git submodule update --init --recursive

Then reload the export.sh of that directory (on Windows, use the matching ESP-IDF PowerShell environment), return to the XiaoZhi project directory and run:

idf.py fullclean
idf.py build

Troubleshooting

1. Speed up compilation

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

2. Serial port driver issues

If the serial port is not recognized, install the USB driver for your chip.

3. I2C conflicts

If you run into an I2C conflict:

1. Run idf.py menuconfig
2. Go to Component config -> Audio Codec Device Configuration
3. Disable the first option
4. Rebuild

4. Error: project depends on idf (>=6.0.1)

If you see an error like:

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

the ESP-IDF version in the current environment is too old (for example 5.x). The project declares idf: '>=6.0.1' in main/idf_component.yml. Install ESP-IDF v6.0.1 or later (the release/v6.1 branch is recommended), make sure the terminal loads the new environment, and retry:

idf.py set-target esp32s3
idf.py build

5. Wi-Fi initialization fails on ESP32-C3

If you use the v6.1 release tag and Wi-Fi initialization fails on ESP32-C3, switch to the release/v6.1 branch, see issue #2344.

6. Windows: command line too long

If Ninja reports a CreateProcess error (the compiler command exceeds the 32,767 character limit), run the following in the same project directory and the same ESP-IDF terminal:

idf.py -D CMAKE_NINJA_FORCE_RESPONSE_FILE=ON reconfigure
idf.py build

Run the reconfigure command again after idf.py fullclean or after clearing the CMake cache. Moving the project to a shorter path (for example E:\xz) may also help. See the workaround in issue #2340.

Notes

1. Do not use non-ASCII characters in the project path
2. Delete the build folder when moving a project
3. Make sure the correct chip model is configured
4. Clean the build directory regularly to resolve build problems

Further Reading

• Custom Board Guide
• Firmware Download and Release Notes
• Sources: xiaozhi-esp32 README, main/idf_component.yml