Which Board Should Run XiaoZhi? A Three-Step Guide by Chip, Network and Ready-Made Board
The question newcomers ask most is: which board should I buy? The upstream v2.5.2 release manifest lists 154 board directories and 188 prebuilt firmware variants. There is a lot to choose from, but only a few factors really decide it. This article sticks to what can be verified in the firmware source and the release manifest, and does not recommend any brand.
1. Step one: choose the chip
Chip counts come from the v2.5.2 release manifest; audio and wake-word capabilities come from upstream main/audio/README.md and main/Kconfig.projbuild:
| Chip | Board dirs | Variants | Audio input engine | On-device wake word |
|---|---|---|---|---|
| ESP32-S3 | 114 | 126 | AfeAudioEngine (echo cancellation and VAD) | Enabled by default with PSRAM |
| ESP32-P4 | 6 | 27 | AfeAudioEngine | Same as ESP32-S3 |
| ESP32-S31 | 4 | 4 | AfeAudioEngine | Same as ESP32-S3; needs ESP-IDF 6.1 or later |
| ESP32-C3 / C6 / C5 | 10 / 10 / 4 | 10 / 10 / 4 | LiteAudioEngine (raw mono PCM) | Optional, without AFE |
| ESP32 | 6 | 7 | LiteAudioEngine | Needs PSRAM to be selectable |
Reading the table:
- ESP32-S3 has the most boards (114 directories) and the most complete AFE audio processing and wake-word support, which makes it the general first choice;
- PSRAM matters: custom wake words, the AFE wake word and audio processing all require PSRAM. For an S3 development board prefer N16R8 (16 MB Flash, 8 MB PSRAM); N8R2 needs extra configuration, see the Hardware Setup Guide;
- C3, C6, C5 and ESP32 use the lightweight engine without echo cancellation and suit low-cost, button-triggered builds;
- see Chip Support and Storage Specs for details per chip.
2. Step two: choose the connectivity
The upstream README lists Wi-Fi, wired Ethernet, USB RNDIS, and ML307, EC801E or NT26 Cat.1 4G networks; some hardware can switch between Wi-Fi and 4G.
| Need | What to do |
|---|---|
| Home or office with Wi-Fi | Use Wi-Fi firmware; provisioning is covered in First Boot and Network Configuration |
| Outdoors or no Wi-Fi | Pick a variant with a 4G module, such as the breadboard series bread-compact-ml307 or bread-compact-nt26 |
| A wired network is available | Pick hardware with wired Ethernet; the firmware provides an Ethernet board base class and the XIAOZHI_NETWORK_ETHERNET option (the default PHY is IP101), the exact support depends on the board directory |
For a 4G build the module must be an AT-firmware version, and a model with a removable SIM is recommended; see the ML307R section of the hardware guide.
3. Step three: ready-made board or DIY
| Route | Best for | Notes |
|---|---|---|
| Breadboard DIY | Learning, and you don’t mind wiring | An ESP32-S3 dev board plus an INMP441 microphone and MAX98357A amplifier; wiring is in the Hardware Setup Guide; the matching variants are the bread-compact-wifi series |
| Buy a ready-made board | You want less fiddling | Find your board in Supported Boards and download the variant with the same name |
| Tight budget | Just trying it out | Build a “budget version” on an early ESP32 board; fewer capabilities, see the next section |
Displays and cameras: the upstream README states support for OLED and LCD displays, and some hardware supports camera vision input. One board directory can ship several variants, for example bread-compact-wifi uses a 128x32 SSD1306 OLED while bread-compact-wifi-128x64 uses a 128x64 one. Check the variant name before downloading.
4. Budget option: what an ESP32 build can do
On an early ESP32 board (commonly 4 MB Flash and no PSRAM) you use the bread-compact-esp32 series:
| Item | ESP32 (budget) | ESP32-S3 |
|---|---|---|
| Audio input engine | LiteAudioEngine, raw mono PCM | AfeAudioEngine, with echo cancellation and VAD |
| On-device wake word | Off by default; selectable only with PSRAM | Enabled by default with PSRAM |
| Conversation trigger | Button, or an external wake-up module | Wake word or button |
Wiring and variants are in ESP32 Budget Version. If you want a wake word and full-duplex conversation, go straight to an ESP32-S3.
5. What if your board is missing?
- Check whether it is just a naming difference: look it up by chip in Supported Boards; the same board may appear under a “vendor/directory” name.
- Your board differs from an existing one by a few pins: do not overwrite the existing board directory. Create a new board type, or distinguish builds in
config.jsonwith a differentnameandsdkconfigmacros, as described in the Custom Board Guide. - You build it yourself: you need ESP-IDF v6.0.1 or later; for board-code changes see Migrating a Custom Board to ESP-IDF 6.
Pre-purchase checklist
- Is the chip in the table above, and does it have PSRAM (S3 / P4 / S31 need it for wake word and audio processing)?
- Does the Flash size meet the partition-table requirement? See Chip Support and Storage Specs.
- Do you need Wi-Fi or 4G; is the 4G module an AT-firmware version?
- Do the display model and driver match the target variant (OLEDs need the SSD1306 driver)?
- Is there a variant with the same name in the release manifest? If not, you will need to build it yourself.
- Are the board’s RGB LED and buttons actually connected? Some DevKits need solder bridges for the RGB LED, see the hardware guide.
Sources
- Upstream
v2.5.2: the release manifest (release-manifest.json),README.md,main/audio/README.mdandmain/Kconfig.projbuild. - This site’s Supported Boards, Hardware Setup Guide and ESP32 Budget Version.
- Checked on 2026-10-23. Send corrections to [email protected].