Who Xiaozhi Esp32 is for#
Hardware hobbyists building DIY voice assistants
Xiaozhi ESP32 provides a complete firmware-to-backend path for building a working voice AI device on a supported board. The pre-compiled beginner firmware connects to the official xiaozhi.me server, so a first device can be working without setting up a build environment. More advanced builds can add custom wake words, display animations, and cloud-side MCP tools.
Skip if:
Skip if you need a production-certified device for retail sale. Xiaozhi ESP32 targets the maker and developer community; commercial hardware that requires UL/CE certification or OEM agreements is outside its current scope.
IoT developers building MCP-connected smart home controllers
The firmware's cloud-side MCP integration lets an LLM issue commands to smart home devices, query knowledge bases, or operate a PC desktop from a voice interaction on the hardware device. MCP tools are server-side, so the set of controllable devices can be extended without firmware updates.
Skip if:
Skip if your smart home is built around Amazon Alexa or Google Home and needs native skill compatibility. Xiaozhi ESP32 uses the MCP protocol for device control, not Alexa Smart Home Skills or Google Home SDK interfaces.
AI researchers prototyping embedded LLM interaction
The project provides a hardware path for studying how users interact with LLM-backed voice devices in real settings. Speaker recognition via 3D-Speaker, full-duplex interaction on AEC-capable boards, and camera vision input on supported hardware give researchers multiple modalities to work with on low-cost ESP32 boards.
Skip if:
Skip if your research platform needs to extend beyond the ESP32 chip family. The firmware targets ESP32, ESP32-S3, ESP32-C3, ESP32-C6, and ESP32-P4 only; Raspberry Pi, NVIDIA Jetson, or other single-board computers are not supported by this firmware.
Educators teaching AI hardware development
The project was built to help people understand AI hardware development and apply large language models to real devices, per the README. Breadboard wiring tutorials, Feishu documentation, and 39-language support make it accessible across classrooms in many regions. Pre-compiled firmware lowers the initial setup barrier for students.
Skip if:
Skip if students have no embedded development background and the course cannot cover ESP-IDF setup and C++ compilation. The pre-compiled firmware path reduces the barrier for initial demos, but hardware debugging and meaningful customization require embedded development skills.
The problem it solves#
Most commercial platforms for voice AI on hardware require a proprietary cloud backend, a certification or approval program, and licensing terms that follow the device into production. Amazon Alexa Voice Service requires AVS certification for commercial products and enforces Amazon's Alexa cloud as the only inference endpoint. Changing which model runs, adding a custom tool, or routing requests to your own server means leaving the SDK entirely.
For makers, students, and IoT developers building on ESP32, this creates a real bottleneck. The chip handles Wi-Fi, audio codecs, and display output ably, but pairing it with a proprietary voice platform adds a dependency on a cloud service the device maker does not control. Server pricing changes, API deprecations, or policy updates can break a product built on that foundation.
How it solves it#
MCP device and cloud control
The firmware uses the Model Context Protocol to control physical peripherals from cloud-side agent calls. On-device, this covers LEDs, servos, and GPIO pins. Cloud-side MCP extends LLM capabilities to smart home control, PC desktop operation, email, and knowledge search. Adding a new cloud tool requires no firmware update.
Offline wake-word detection via ESP-SR
Wake-word detection runs fully on-device via Espressif's ESP-SR library, so the device can listen and activate without a network connection. Wake words are customizable using the Custom Assets Generator tool. On hardware with acoustic echo cancellation support, the device handles full-duplex realtime conversation without interrupting the speaker mid-sentence.
Any-LLM backend over open transports
The firmware connects to any LLM backend via WebSocket or MQTT+UDP transport. The official xiaozhi.me server provides free access to Qwen's real-time model, but developers can point the device at a self-hosted backend running any LLM. Model selection is entirely server-side, so changing models or adding tools requires no firmware reflash.
138-board hardware support matrix
The project ships 171 pre-built firmware variants across 138 confirmed board types, covering the ESP32, ESP32-S3, ESP32-C3, ESP32-C6, and ESP32-P4 chip families. Supported boards include the Espressif ESP32-S3-BOX-3, M5Stack CoreS3, Waveshare ESP32-S3-Touch-AMOLED-1.8, and LILYGO T-Circle-S3, among others. Boards with OLED or LCD displays show emoji expressions and rich visual output.
39-language interface with voice prompts
The firmware ships with 39 interface language configurations. Localized voice prompts are included where available, with English as the fallback. Custom fonts, emoji sets, and chat backgrounds can be generated and applied using the online Custom Assets Generator, without rebuilding the firmware from source.
Strengths and trade-offs#
Strengths
- MIT license with no per-device feesThe firmware and all official documentation are MIT licensed, allowing commercial use, modification, and redistribution without licensing fees or vendor agreements. Device makers can ship hardware built on Xiaozhi ESP32 without paying per-device royalties or negotiating SDK access, which platforms like Amazon Alexa Voice Service require.
- Self-hosted backend options in Python, Java, and GoFour community-built server implementations exist in Python, Java, and Go, giving teams the option to run the complete backend on their own infrastructure. Self-hosting removes the dependency on the xiaozhi.me cloud service and allows direct control over which LLMs the device calls, what tools are available, and where conversation data is stored.
- Single codebase targeting 138 confirmed board typesA single firmware codebase produces 171 pre-built variants across 138 confirmed boards, reducing the work of getting a supported board running to a binary flash operation. The project documents a custom board guide for adding new targets, making the support matrix extensible beyond the confirmed list.
- Active project with 31k+ stars and continuous commitsThe repository has accumulated over 31,000 GitHub stars since its creation in August 2024, with the last push occurring on the same day as this writing. The project ships documented updates on networking, cryptography, audio pipeline hardening, and new chip support across each release. The 7,352 forks indicate significant community experimentation and adaptation.
Trade-offs
- -ESP-IDF v6.1 required; v5.x explicitly unsupportedThe project requires ESP-IDF v6.0.1 or later, with v6.1 as the recommended SDK. ESP-IDF 5.x is explicitly unsupported as of the current release. Developers upgrading from older projects or using board support packages that target IDF 5.x will need to migrate to IDF 6 before building. The project notes that IDF 6 component splits and third-party dependency compatibility have been addressed, indicating that library-level changes are part of the upgrade path.
- -677 open issues for a project less than two years oldThe GitHub repository carries 677 open issues as of October 2026 for a project created in August 2024. The pace of feature additions means some hardware configurations and edge cases are not yet fully supported. Users on non-mainline boards should review open issues for their specific hardware before committing to a build.
- -C++ and ESP-IDF expertise required for firmware developmentContributing to or significantly modifying the firmware requires C++ proficiency and familiarity with the ESP-IDF build system. The README recommends Linux over Windows for faster compilation and fewer driver issues. Beginners can use the pre-compiled binary path to connect to the official server without touching the build system, but customization beyond configuration changes requires a full development environment.
Xiaozhi Esp32 vs alternatives#
Xiaozhi ESP32 vs Amazon Alexa Voice Service
Both target custom hardware devices that respond to voice commands, but they differ on backend flexibility and deployment model. Amazon Alexa Voice Service (AVS) is a managed cloud platform with a proprietary SDK; Xiaozhi ESP32 is MIT-licensed firmware that connects to any LLM backend the developer chooses.
| Feature | Xiaozhi ESP32 | Amazon Alexa Voice Service |
|---|---|---|
| License | MIT | Proprietary |
| LLM backend | Any (Qwen, DeepSeek, custom) | Amazon Alexa cloud only |
| Self-hosting | Yes (Python/Java/Go servers) | No |
| API access | Open | Requires AVS certification |
| Device control | MCP protocol (LEDs, servos, GPIO) | Alexa Smart Home Skills |
| Supported hardware | 138 ESP32 board variants | Varies by certification tier |
| Cost | Free (self-hosted) | AVS per-request pricing |
Xiaozhi ESP32 is the better choice when you need full control over which LLM the device calls, want to avoid per-request API fees, or are building a device that cannot go through AVS certification. Because model selection is server-side and device control uses the open MCP protocol, changing the backend or adding new capabilities does not require a firmware reflash. The MIT license removes any restriction on commercial use or redistribution.
Amazon Alexa Voice Service is worth considering when your device needs to join the existing Alexa ecosystem, including compatibility with third-party Alexa-enabled smart home devices. AVS provides a commercially-supported SDK with established certification pathways for consumer electronics shipping at volume through retail channels. For a device that does not need Alexa compatibility, the certification overhead is difficult to justify over the open-source path.
Quick start#
Clone the repo to begin firmware setup; the project requires ESP-IDF v6.1 configured in VS Code or Cursor.
```bash
git clone https://github.com/78/xiaozhi-esp32.git
```What it's built on#
- Languages
- CC++Python
FAQ#
Does Xiaozhi ESP32 require the official xiaozhi.me server?
No. The firmware connects to xiaozhi.me by default, which offers a free Qwen real-time model for registered personal accounts, but you can point it at any self-hosted backend. Four community server implementations exist in Python, Java, and Go. Self-hosting gives you full control over which LLMs run and where conversation data is stored.
Which ESP32 boards are compatible with Xiaozhi ESP32?
The project supports 138 confirmed board types and ships 171 pre-built firmware variants, covering the ESP32, ESP32-S3, ESP32-C3, ESP32-C6, and ESP32-P4 chip families. Specific boards include the Espressif ESP32-S3-BOX-3, M5Stack CoreS3, Waveshare ESP32-S3-Touch-AMOLED-1.8, and LILYGO T-Circle-S3, among over 130 others. The full board list and per-board documentation are in the GitHub repository.
Is Xiaozhi ESP32 free to use in commercial products?
Yes. The project is MIT licensed, which allows commercial use, modification, and redistribution without paying licensing fees or negotiating a vendor agreement. The README explicitly states the firmware is released for free use including commercial purposes. You can build and sell hardware based on this firmware without restriction.
Which LLMs does Xiaozhi ESP32 support?
By default, the firmware connects to the official xiaozhi.me server, which provides access to Qwen real-time models. Because model selection is server-side rather than firmware-side, any LLM your backend supports can be used without a firmware reflash. Developers running a self-hosted server can configure DeepSeek, Qwen, or any other model the server supports.
What SDK version is required to build Xiaozhi ESP32?
The project requires ESP-IDF v6.0.1 or later. ESP-IDF v6.1 is the recommended version and the target for the current build matrix. ESP-IDF 5.x is explicitly unsupported. The development environment also requires VS Code or Cursor with the ESP-IDF plugin installed, and the README recommends Linux over Windows for faster compilation and fewer driver issues.
Similar open-source tools#
Hermes Agent
254,611 GitHub starsSelf-hosted AI agent: persistent memory, multi-channel chat, model choice.
Alternative to
Grok Bot
Orgtree
146 GitHub starsDesktop canvas for persistent multi-agent AI teams, Windows-only
Alternative to
Conductor
Agent Cache Web
11 GitHub starsConvert docs URLs into Markdown bundles for AI coding agents
Alternative to
Context7
iFixAi
29,142 GitHub starsSelf-hosted AI agent auditing across 60 trust and safety inspections.
Alternative to
Zenity
WeKnora
34,526 GitHub starsSelf-hosted knowledge base with RAG search, AI agent, and wiki
Alternative to
Glean
Marker
40,517 GitHub starsConvert documents to clean markdown and JSON with open source AI.
Alternative to
Unstructured.io