Skip to content
Get packs

Guide · Open source

How to use xiaozhi-esp32: flash, build and configure

Updated · written with AI from the project's own documentation and checked against our catalogue data

xiaozhi-esp32 is MIT-licensed C++ firmware that turns supported ESP32-family development boards into a voice assistant. It combines speech recognition, a large language model and speech output, and uses the MCP protocol so the assistant can control devices and reach outside tools. This guide explains the two ways to get started, what hardware you need, and how to build the project yourself.

XiaoZhi78/xiaozhi-esp32 · ★ 32.5k · MIT

Quick start

  1. 1Check your board. Confirm your ESP32-family board appears in the README's supported list.
  2. 2Pick flashing or building. Use the beginner flashing guide for a quick start, or the developer route to modify code.
  3. 3Install the toolchain. Install Cursor or VSCode and the ESP-IDF plugin, using ESP-IDF v6.0.1 or later (release/v6.1 recommended).
  4. 4Clone the repository. Run git clone https://github.com/78/xiaozhi-esp32 to get the source.
  5. 5Update submodules and clean. After switching SDK revisions, run git submodule update --init --recursive and idf.py fullclean before rebuilding.
  6. 6Connect and configure. Connect the device to xiaozhi.me, register for the free Qwen model if you want it, and configure via the console.

What hardware do you need?

The firmware runs only on ESP32-family microcontroller boards. The README lists chip platforms ESP32, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-S3 and ESP32-P4, and says the project supports 138 board directories and 171 release variants. Boards with audio and display peripherals give the most complete experience, and the README mentions OLED and LCD displays and camera input on supported boards.

  • Pick a board from the README's list, such as LiChuang ESP32-S3, Espressif ESP32-S3-BOX-3, or M5Stack CoreS3.
  • Check that your exact board is supported before you buy or flash it.

Choose between flashing and building from source

The README recommends beginners use the firmware that can be flashed without setting up a development environment. Follow the linked Beginner's Firmware Flashing Guide for that route.

If you want to modify the code or build a custom device, you need the development path: an editor with the ESP-IDF plugin and a clone of the repository.

  • Beginner route: flash prebuilt firmware using the official guide.
  • Developer route: clone the repo, install ESP-IDF, and build with idf.py.

Set up the development environment

The README lists Cursor or VSCode with the ESP-IDF plugin as the development environment. The minimum SDK is ESP-IDF v6.0.1, and the README recommends the release/v6.1 branch. ESP-IDF 5.x is not supported.

Use the release/v6.1 branch rather than the v6.1 release tag. The README reports an ESP32-C3 Wi-Fi initialization failure with that tag in issue #2344. The README also says Linux is better than Windows for faster compilation and fewer driver issues.

  • Install Cursor or VSCode.
  • Install the ESP-IDF plugin and ESP-IDF v6.0.1 or later (release/v6.1 recommended).
  • Use Linux if you can; the README says it is better than Windows.

Clone the repository and build the firmware

Clone the project from GitHub. After you switch SDK revisions, the README says to update the ESP-IDF submodules, source ESP-IDF's export.sh, and clean the project before rebuilding.

Run the clean step in this project before rebuilding after an SDK change. The README gives these steps for the process.

  • Update ESP-IDF submodules after switching SDK revision, in the ESP-IDF directory.
  • Source ESP-IDF's export.sh before building.
  • Run idf.py fullclean in this project before rebuilding after an SDK change.
git clone https://github.com/78/xiaozhi-esp32 git submodule update --init --recursive idf.py fullclean

Connect the device to a server and configure the model

By default, the firmware connects to the official xiaozhi.me server. Personal users can register an account to use the Qwen real-time model for free, according to the README.

If you already have a XiaoZhi device connected to the official server, log in to the xiaozhi.me console to configure it. The README also links an older video tutorial for backend operation.

The README points to open-source server projects for running your own server on a personal computer, including xinnan-tech/xiaozhi-esp32-server (Python), a Java server and a Golang server.

  • Default: the firmware connects to xiaozhi.me.
  • Register an account on xiaozhi.me for the free Qwen real-time model.
  • Self-host: see the server projects listed in the README.

Understand MCP control and the protocol docs

MCP is what lets the assistant control things. The README describes device-side MCP for controlling hardware such as speaker, LED, servo and GPIO, and cloud-side MCP that extends the model with smart home control, PC desktop operation, knowledge search and email.

The repository includes developer documents for custom boards, MCP IoT control, the MCP interaction flow, and the MQTT + UDP and WebSocket protocols.

  • docs/custom-board.md: create custom boards.
  • docs/mcp-usage.md: control IoT devices via MCP.
  • docs/mcp-protocol.md: device-side MCP implementation.
  • docs/mqtt-udp.md and docs/websocket.md: communication protocols.

What people use it for

  • A voice assistant on a supported ESP32-S3 development board.
  • A custom voice device built on the project's custom board guide.
  • Adding MCP-controlled hardware such as a servo, LED or GPIO output.
  • Learning embedded C++ with audio and display peripherals on real hardware.

Frequently asked questions

Is xiaozhi-esp32 free and what license does it use?

The repository is licensed under MIT. The README also says personal users can register on xiaozhi.me to use the Qwen real-time model for free.

What hardware do I need to run xiaozhi-esp32?

You need an ESP32-family board that the project supports, such as ESP32-S3, ESP32-C3 or ESP32-P4 chips on a listed board. The firmware runs only on that hardware.

Which ESP-IDF version should I use?

Use ESP-IDF v6.0.1 or later, with the release/v6.1 branch recommended. The README says ESP-IDF 5.x is no longer supported.

Can I flash it without setting up a development environment?

Yes. The README recommends beginners use the firmware that can be flashed without a development environment, and links a Beginner's Firmware Flashing Guide.

Why does my build fail after switching SDK versions?

After switching SDK revisions, update submodules with git submodule update --init --recursive in the ESP-IDF directory, source export.sh, and run idf.py fullclean in this project before rebuilding.

How does xiaozhi-esp32 compare to Home Assistant Voice or ESPHome?

The README describes xiaozhi-esp32 as a voice interaction entry point built around large models such as Qwen and DeepSeek, with MCP control. This source does not compare it directly with Home Assistant Voice or ESPHome, so check those projects' own docs for their approach.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Choose xiaozhi-esp32 if you have a supported ESP32 board and want a voice assistant you can flash, modify and extend through MCP. Skip it if you need a finished consumer device with no setup, or if you cannot run ESP-IDF v6.0.1 or later.

Install options & downloads