2461efdc72
【中文】 7B 变体使用 v1.x 版本的 ESP32-P4 芯片和 32MB flash，但 config.json 中 对应的 sdkconfig_append 既没声明芯片版本，也没声明 flash 大小。IDF 因此 默认按 rev v3.1 + 16MB flash 构建，bootloader 被链接脚本 bootloader.rev3.ld 放到 0x4ffa_xxxx 的高位 HP_SRAM，这个区域在 v1.x 硅上不可取指，ROM 加载完跳过去，CPU 在第一条指令就 "Guru Meditation Error: Core 0 panic'ed (Illegal instruction)"， bootloader log 一行都打不出来。 添加 CONFIG_ESP32P4_SELECTS_REV_LESS_V3=y + CONFIG_ESP32P4_REV_MIN_100=y 让 bootloader.ld（低位 HP_SRAM 0x4ff2_xxxx）被选中，并声明 CONFIG_ESPTOOLPY_FLASHSIZE_32MB=y + partitions/v2/32m.csv，使 image header 和分区表和板子实际硬件对齐；CONFIG_ESPTOOLPY_FLASH_MODE_AUTO_DETECT=n 与已知 32MB 板子 sensecap-watcher 保持一致。 在 v1.3 版本的 P4-WIFI6-Touch-LCD-7B 上验证通过：bootloader 段现在加载到 0x4ff33ce0 / 0x4ff29ed0 / 0x4ff2cbd0；启动过程中 MIPI-DSI LCD、GT911 触控、OV5647 摄像头、ES8311+ES7210 音频和 ESP32-C6 SDIO 协处理器 全部正常初始化；状态机进入 wifi_configuring，对外发出 Xiaozhi-XXXX 配网热点。 --- [English] The 7B variant ships with a v1.x ESP32-P4 silicon and a 32 MB flash, but the existing sdkconfig_append declared neither. IDF then defaults to rev v3.1 + 16 MB, and the bootloader is linked via bootloader.rev3.ld into the 0x4ffa_xxxx upper HP_SRAM window. That range is not fetchable on v1.x silicon, so the ROM jumps to the loaded bootloader and the CPU panics on the first opcode with "Guru Meditation Error: Core 0 panic'ed (Illegal instruction)" before any bootloader log is printed. Add CONFIG_ESP32P4_SELECTS_REV_LESS_V3=y + CONFIG_ESP32P4_REV_MIN_100=y so bootloader.ld (low HP_SRAM 0x4ff2_xxxx) is used, and declare CONFIG_ESPTOOLPY_FLASHSIZE_32MB=y + partitions/v2/32m.csv so the image header and partition offsets match the board. Disable flash-mode auto-detect for parity with the other known 32 MB board (sensecap-watcher). Verified on a v1.3 P4-WIFI6-Touch-LCD-7B: bootloader segments now load at 0x4ff33ce0 / 0x4ff29ed0 / 0x4ff2cbd0; boot completes through MIPI DSI, GT911 touch, OV5647 camera, ES8311+ES7210 audio and the ESP32-C6 SDIO coprocessor; device reaches wifi_configuring and exposes the Xiaozhi-XXXX AP.
An MCP-based Chatbot
Introduction
👉 Handcraft your AI girlfriend, beginner's guide【bilibili】
As a voice interaction entry, the XiaoZhi AI chatbot leverages the AI capabilities of large models like Qwen / DeepSeek, and achieves multi-terminal control via the MCP protocol.
Version Notes
The current v2 version is incompatible with the v1 partition table, so it is not possible to upgrade from v1 to v2 via OTA. For partition table details, see partitions/v2/README.md.
All hardware running v1 can be upgraded to v2 by manually flashing the firmware.
The stable version of v1 is 1.9.2. You can switch to v1 by running git checkout v1. The v1 branch will be maintained until February 2026.
Features Implemented
- Wi-Fi / ML307 Cat.1 4G
- Offline voice wake-up ESP-SR
- Supports two communication protocols (Websocket or MQTT+UDP)
- Uses OPUS audio codec
- Voice interaction based on streaming ASR + LLM + TTS architecture
- Speaker recognition, identifies the current speaker 3D Speaker
- OLED / LCD display, supports emoji display
- Battery display and power management
- Multi-language support (Chinese, English, Japanese)
- Supports ESP32-C3, ESP32-S3, ESP32-P4 chip platforms
- Device-side MCP for device control (Speaker, LED, Servo, GPIO, etc.)
- Cloud-side MCP to extend large model capabilities (smart home control, PC desktop operation, knowledge search, email, etc.)
- Customizable wake words, fonts, emojis, and chat backgrounds with online web-based editing (Custom Assets Generator)
Hardware
Breadboard DIY Practice
See the Feishu document tutorial:
👉 "XiaoZhi AI Chatbot Encyclopedia"
Breadboard demo:
Supports 70+ Open Source Hardware (Partial List)
- LiChuang ESP32-S3 Development Board
- Espressif ESP32-S3-BOX3
- M5Stack CoreS3
- M5Stack AtomS3R + Echo Base
- Magic Button 2.4
- Waveshare ESP32-S3-Touch-AMOLED-1.8
- LILYGO T-Circle-S3
- XiaGe Mini C3
- CuiCan AI Pendant
- WMnologo-Xingzhi-1.54TFT
- SenseCAP Watcher
- ESP-HI Low Cost Robot Dog
Software
Firmware Flashing
For beginners, it is recommended to use the firmware that can be flashed without setting up a development environment.
The firmware connects to the official xiaozhi.me server by default. Personal users can register an account to use the Qwen real-time model for free.
👉 Beginner's Firmware Flashing Guide
Development Environment
- Cursor or VSCode
- Install ESP-IDF plugin, select SDK version 5.4 or above
- Linux is better than Windows for faster compilation and fewer driver issues
- This project uses Google C++ code style, please ensure compliance when submitting code
Developer Documentation
- Custom Board Guide - Learn how to create custom boards for XiaoZhi AI
- MCP Protocol IoT Control Usage - Learn how to control IoT devices via MCP protocol
- MCP Protocol Interaction Flow - Device-side MCP protocol implementation
- MQTT + UDP Hybrid Communication Protocol Document
- A detailed WebSocket communication protocol document
Large Model Configuration
If you already have a XiaoZhi AI chatbot device and have connected to the official server, you can log in to the xiaozhi.me console for configuration.
👉 Backend Operation Video Tutorial (Old Interface)
Related Open Source Projects
For server deployment on personal computers, refer to the following open-source projects:
- xinnan-tech/xiaozhi-esp32-server Python server
- joey-zhou/xiaozhi-esp32-server-java Java server
- AnimeAIChat/xiaozhi-server-go Golang server
- hackers365/xiaozhi-esp32-server-golang Golang server
Other client projects using the XiaoZhi communication protocol:
- huangjunsen0406/py-xiaozhi Python client
- TOM88812/xiaozhi-android-client Android client
- 100askTeam/xiaozhi-linux Linux client by 100ask
- 78/xiaozhi-sf32 Bluetooth chip firmware by Sichuan
- QuecPython/solution-xiaozhiAI QuecPython firmware by Quectel
Custom Assets Tools:
- 78/xiaozhi-assets-generator Custom Assets Generator (Wake words, fonts, emojis, backgrounds)
About the Project
This is an open-source ESP32 project, released under the MIT license, allowing anyone to use it for free, including for commercial purposes.
We hope this project helps everyone understand AI hardware development and apply rapidly evolving large language models to real hardware devices.
If you have any ideas or suggestions, please feel free to raise Issues or join our Discord or QQ group: 994694848