xiaozhi-esphome turns Xiaozhi hardware into Home Assistant voice satellites

Replacing the firmware on Xiaozhi AI devices with ESPHome

Xiaozhi-based devices are compact voice assistant hardware. Out of the box they run the vendor firmware, and the project in question exists to give them a second life inside a Home Assistant setup.

The README states the purpose directly: by request, the GitHub project provides a simple way to use Xiaozhi-based devices with ESPHome, so that these compact devices can serve as voice assistants integrated with Home Assistant. The rest of the repository is the code and the supporting files that make that possible.

This is not a Home Assistant integration in the usual sense and it is not a service. It is ESPHome configuration: YAML that describes the hardware, plus the prompts, sounds and reference files needed to make the device behave as a voice assistant once it is running your code. The audience is a Home Assistant user with one of these devices on the desk who is comfortable flashing firmware over USB and configuring an ESP32 board from YAML.

The repository also sells the hardware question for you in a literal sense. There is a Where to Buy section in the README listing purchase links for most of the supported boards, plus accessories such as cases, 3D printed stands and a wireless charger, with a 3D_Files directory for the printable parts.

What the repository does not spell out is the protocol side. The README describes the flashing and pairing workflow in detail, but it does not document how the voice link to the Xiaozhi service is negotiated once ESPHome is running, so that is where you will have to read the configuration yourself.

Two configuration lines to choose between: Modular and Sendspin

The repository carries many device folders, but the README points you at two that are being worked on, and the difference between them is the version of ESPHome you are running.

The Modular configuration is the one listed for ESPHome 2026.4.0 and later. The second is Modular with Sendspin, listed for ESPHome 2026.9.0 and later, and it lives in a SENDSPIN subfolder under the Modular device directory. The README describes both as the versions updated with more functionality and still being developed on.

So there are effectively three tiers. The per-device folders under devices are demos. The modular build is the moving target for people on a recent ESPHome. The Sendspin variant is the same idea for people on the newest ESPHome releases, and it presumably differs in how audio is handled, since the name points at the Sendspin audio transport.

New hardware shows up in the modular version first, during testing, and only later gets a dedicated entry among the supported devices. That is a useful signal about how the project works: the modular configuration is the place where a new board is validated, and the device-specific YAML is the frozen result of that validation.

If you are picking a starting point, pick the modular one that matches your ESPHome version and treat the device folder as a reference for the pieces that are board specific.

The per-device YAML files are demos, and the README says so

This is the sentence in the README that should shape how you use the repository: the YAML files in Devices/<device_name>/ are demo configurations and may be outdated, but they are useful for identifying a device.

Read that carefully. The value of those files is diagnostic rather than operational. They tell you what board is behind a particular model, which peripherals are wired to which pins, and roughly how a working configuration for that hardware looks. Once you know the board, you can take that information into the modular configuration and adapt it.

That is also why the supported device list matters. It runs from Espressif EchoEar v1.0 and v1.2 through Spotpear Ball v1 to v3, Spotpear Muma Box, Muma Horse, Puck, the Guition Taichi pi 1.8 inch JC3636W518C in both v1 and v2, Xingzhi Cube 1.54, a DIY breadboard build, the 7 dollar Breadboard Mini custom ESP32-S3 with everything onboard, and a set of Waveshare boards including the 2.06 inch OLED Wrist Watch, the ESP32-S3-Touch-LCD-1.85C in v1 and v1.2, the ESP32-S3-Touch-LCD-3.49, the ESP32-P4-86-Panel-ETH-2RO and an audio board. Items marked NEW in the list are the most recent additions, and the list also carries a note that Guition 1.8 inch Taichi pi v1 was discontinued after July 2025.

Devices marked discontinued are a warning, not a blocker. It tells you the vendor moved on, and parts for that board may be harder to find later.

The install path: take over the device, keep the original name

The Quick Start Guide in the README is a four step sequence, and the second step is the one people get wrong.

Step one is connecting the device to your computer over USB and opening ESPHome Web at web.esphome.io, clicking the new device button and following the prompts to set it up and connect it to Wi-Fi. This is the standard ESPHome onboarding path and it discovers the board before any custom code is applied.

Step two is where this project differs from a normal ESPHome device. In the ESPHome Builder you take over the newly discovered device, edit the configuration, paste in the code for your device, and keep the original device name. The friendly_name can be changed to whatever you prefer. The reason to keep the name is that it preserves the identity the device already has in your ESPHome installation, so the takeover does not create a second entry for the same hardware.

Step three is saving and installing the configuration wirelessly, then waiting for the device to reboot and start running your code.

Step four happens in Home Assistant. Once the device is online you go to Home Assistant, then Devices, and accept the new device, and that acceptance is what starts the voice assistant setup process.

One note covers the common failure. If the wireless installation fails and you are prompted to use USB flashing, reconnect the device, save and install again, choose the option to plug into this computer, and let the firmware compile and download before installing over USB with ESPHome Web. The README is specific that this happens only the first time, when the partition table needs to be updated, and that future updates can be done wirelessly. That is a normal part of the process rather than a fault.

The repository also ships the install video as install-xiaozhi-esphome.mp4, linked from the README, for the steps that are easier to watch than to read.

The repository is more than YAML: prompts, sounds and wake words

The top level entries of the repository show that the project reaches past the firmware configuration. Alongside devices and images there are directories for MicroWakeWords, Prompts, sounds and 3D_Files, plus an other directory and a few documentation files.

Prompts and sounds matter for a voice assistant. The Prompts directory is where the text given to the model and the spoken responses live, and the sounds directory holds the audio the device plays for feedback and alerts. These are the files you edit to change what your satellite says and how it sounds, and they are the part of the repository you are most likely to modify after the initial flash.

MicroWakeWords is a separate directory with its own meaning. Wake word handling is what decides when the device starts listening, and on a device with a small display and a microphone this is often a separate subsystem with its own tuning. The README does not describe how it is configured, so treat it as something to inspect in the repository rather than something the documentation explains.

The 3D_Files directory collects the printable parts referenced in the accessories section, including the Eggvenger figure used to hold the Ball, a wireless charger stand for the Guition JC3636W518C display and a case for the Freenove 2.8 inch unit.

The practical consequence of this layout is that a working install is not one file. It is a device YAML, a set of prompts, some sounds, and possibly wake word configuration, all of which have to agree with each other for the thing to behave like a voice assistant.

Keeping the stock firmware is the other route, and it is not a bad one

The alternative to flashing ESPHome onto these devices is leaving them on the firmware they shipped with, which is what the vendor intends and what the buy links in the README point you at.

The difference in approach is exactly what the project says it is for. On the stock firmware the device is a voice assistant with its own behaviour and its own ecosystem, and the vendor maintains it. On ESPHome the device becomes a Home Assistant device: you accept it under Devices, it starts the voice assistant setup process inside Home Assistant, and the configuration is yours to edit. The trade goes the other way too, because once ESPHome owns the board you own the maintenance of it, including the pin mappings, the partition table and any firmware updates, and none of that is covered by the hardware vendor.

A third option sits between the two and is what the README actually offers. You can take the device-specific demo YAML as a starting point and adapt it, or you can start from the modular configuration and add the board specific pieces yourself. The modular route is more work up front and less work later, because it inherits whatever the project fixes for everyone else.

For a device you already own and use daily, the stock firmware is a reasonable default. This project earns its place when the Home Assistant integration and the ability to edit prompts and sounds matter more than the convenience of the vendor image.

No releases, MIT licence, and a repository you clone from

The repository has no GitHub releases at all. Everything is taken from the main branch, which is also the default branch, and there is no version tag to pin. That is the single most important operational fact about this project: there is no stable artefact, so a config that works today is a config against whatever main happened to contain when you copied it.

The repository is not archived and the last push was on 2026-10-13, so work is still landing on it. The README even flags which parts are under active development, pointing to the Modular and Modular with Sendspin folders rather than the device demos.

The licence is MIT, which is permissive enough that you can take the configuration, adapt it, and use it in a private or commercial setup without asking. The MIT notice requirement still applies if you redistribute the files themselves.

Given there are no releases, the sensible practice is to copy the configuration into your own ESPHome configuration directory once it works, rather than pointing ESPHome at the repository. That way a change upstream cannot alter a device that is already running, and you keep a record of what was flashed to which board.

Editorial conclusion

Home Assistant users who own a Xiaozhi-based device and want it to register as a satellite in their own dashboard should adopt xiaozhi-esphome, provided they are willing to flash firmware and to treat the modular configuration as a starting point rather than a finished product. It suits hobby hardware that arrives with a vendor firmware the user cannot control; it does not suit anyone who wants a supported vendor image or a device whose stock setup already meets their needs. Before you flash, confirm that the modular build matches your ESPHome version, read the device YAML for your model in the devices directory to check pin assignments, and note that the repository publishes no releases, so every install is from the main branch.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. RealDeco/xiaozhi-esphome on GitHub