ESP32 Development Guide
ESP32 Development Guide
This chapter is for developers who want to read, modify or port the XiaoZhi ESP32 firmware. It follows the upstream 78/xiaozhi-esp32 v2.5.2: first understand chips and partitions, then read the source map, and look up extension points and troubleshooting as needed.
The firmware supports ESP32-S3, ESP32-P4, ESP32-C3, ESP32-C5, ESP32-C6, ESP32 and ESP32-S31. Each chip has a different audio engine and wake word capability, see Chip Support and Storage Specs. To add a new board, read the Custom Board Guide.
Reading Path
Audio engines, PSRAM requirements and the v2 partition tables
Directory layout, device state machine, board abstraction and development rules
Network types, wake words, MCP, notifications and asset customization
Where to look for build, flashing, audio and assets problems
Related Entries
- ESP-IDF Development Environment Setup: requires ESP-IDF v6.0.1 or later,
release/v6.1recommended - Hardware Build Guide: breadboard DIY plan and wiring tables
- ESP32 Budget Version: using an early ESP32 development board
- Supported Boards: all firmware variants
- Custom Assets Guide: wake words, fonts, emoji and chat backgrounds
- MCP Protocol: device-side tools and protocol flow
Contact
For site content issues, email [email protected]. For problems in the firmware itself, please use the upstream GitHub Issues.