The 171 release variants are the product and the burden
Xiaozhi-esp32 supports 138 board directories and 171 release variants according to its current README. The firmware spans ESP32, C3, C5, C6, S3, and P4 chips, then adds board-specific audio codecs, screens, cameras, batteries, and networking. That breadth makes it far more useful than a single-board demo. It also changes the buying decision. You are choosing a supported hardware and firmware pair, with the voice-assistant features layered on top.
The common layer is substantial. It handles offline wake words, Opus audio streaming, WebSocket or MQTT plus UDP transport, streaming speech services, displays, camera input, and power management. Device-side MCP exposes hardware such as speakers, LEDs, servos, and GPIO. Cloud-side MCP can reach services beyond the board. The README lists 39 interface languages, though localized voice prompts fall back to English where a translation is unavailable.
Networking varies with the selected hardware too. The README covers Wi-Fi, Ethernet, USB RNDIS, and supported Cat.1 4G modules, with some boards able to switch between Wi-Fi and 4G. Full-duplex conversation depends on echo-cancellation hardware. A board appearing in the matrix therefore answers only the first compatibility question. You still need to confirm its microphone channels, speaker path, display controller, camera sensor, power behavior, and chosen network transport.
What happened when we ran it
Our sandbox cloned commit abc177c into an unprivileged container with 3 CPUs and 8 GB of RAM. The checkout held 1,712 files, about 128,047 lines of source, and occupied 9.4 MB. Installation failed after 11 seconds. The repository scan found 1 CI workflow file, no Dockerfile, and no tests directory. Those are source-tree facts, not evidence that a particular board image works or fails.
CMake reported two concrete errors. It could not find /tools/cmake/project.cmake, then treated idf_build_set_property as an unknown command. Configuration stopped there. The supplied lab record contains no later build or test measurement, so there is no defensible firmware result to report. The log does not tell us which package, environment setting, or image change would have fixed the run.
That failed 11-second configuration is useful to a buyer. Xiaozhi-esp32 does not behave like a portable CMake project in a general C++ container. Its build expects the ESP-IDF project machinery described by the repository. A team should provision that toolchain first, select the exact board target, and treat a successful compile as the beginning of hardware validation rather than the end.
ESP-IDF 6.0.1 is the source-build starting line
The current README requires ESP-IDF 6.0.1 or later, recommends 6.1, and says ESP-IDF 5.x is unsupported. It recommends Linux over Windows for faster compilation and fewer driver problems. That is clearer than leaving the SDK implicit, but it also means an existing ESP32 shop may need a separate toolchain for Xiaozhi instead of dropping the firmware into an older IDF environment.
Beginners have an easier route. The project recommends flashing prepared firmware without setting up the development environment, and the firmware connects to the official Xiaozhi server by default. The README says personal users can register through the console and use its Qwen real-time model. Self-hosting is possible through separately maintained Python, Java, and Go server projects, so operating your own backend is another deployment decision rather than a switch inside this repository.
Three v2.5.0 reports show why the exact board matters
Open issue 2278 reports an illegal-instruction boot loop on an M5Stack Tab5 P4 Rev 1.0 using both the official v2.5.0 image and a self-built target. The report includes the repeatable point after touch and camera initialization. Open issue 2262 says an ESP32-S3-Box Lite recognizes its wake word but does not hear later speech. These are reporter findings on named devices, not results from our generic container.
Open issue 2251 describes a different failure on the Waveshare ESP32-S3 Touch LCD 1.54: enabling echo cancellation can make the device interrupt its own speech, with the behavior reported as worse after reducing volume. The issue concerns one audio path and board combination. Together, the 3 reports explain why a green compile would not be enough for a product team. Microphone routing, echo cancellation, camera startup, and board revision need physical tests.
An October 1 push accompanies 669 open issues and pull requests
GitHub showed 30,358 stars and 669 open issues and pull requests on October 2, 2026. The repository was pushed on October 1, and the latest release was v2.5.0 from September 10. That release added board support, languages, audio playback work, display fixes, MCP validation, and several hardware-specific corrections. The dates and current pull requests show active maintenance, while the combined queue reflects the cost of supporting a large hardware matrix.
Prepared firmware is the sensible entry point when its filename already matches your board. Source builders should reproduce the IDF 6.x environment, then lock the board directory, revision, audio hardware, transport, and backend they intend to ship. Our run never crossed configuration. The next proof belongs on the physical device, where the v2.5.0 reports show that audio and startup behavior can change with the board revision.