mirror of
https://github.com/78/xiaozhi-esp32.git
synced 2026-01-14 01:07:30 +08:00
511349a7bd
* Upgrade component version * update fonts component version * change lcd display layout from grids to layers * Update English README as default * Handle OTA error code
173 lines
9.2 KiB
Markdown
173 lines
9.2 KiB
Markdown
# An MCP-based Chatbot
|
|
|
|
(English | [中文](README_zh.md) | [日本語](README_ja.md))
|
|
|
|
## Introduction
|
|
|
|
👉 [Human: Give AI a camera vs AI: Instantly finds out the owner hasn't washed hair for three days【bilibili】](https://www.bilibili.com/video/BV1bpjgzKEhd/)
|
|
|
|
👉 [Handcraft your AI girlfriend, beginner's guide【bilibili】](https://www.bilibili.com/video/BV1XnmFYLEJN/)
|
|
|
|
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.
|
|
|
|
<img src="docs/mcp-based-graph.jpg" alt="Control everything via MCP" width="320">
|
|
|
|
## 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](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](https://github.com/espressif/esp-sr)
|
|
- Supports two communication protocols ([Websocket](docs/websocket.md) or MQTT+UDP)
|
|
- Uses OPUS audio codec
|
|
- Voice interaction based on streaming ASR + LLM + TTS architecture
|
|
- Speaker recognition, identifies the current speaker [3D Speaker](https://github.com/modelscope/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](https://github.com/78/xiaozhi-assets-generator))
|
|
|
|
## Hardware
|
|
|
|
### Breadboard DIY Practice
|
|
|
|
See the Feishu document tutorial:
|
|
|
|
👉 ["XiaoZhi AI Chatbot Encyclopedia"](https://ccnphfhqs21z.feishu.cn/wiki/F5krwD16viZoF0kKkvDcrZNYnhb?from=from_copylink)
|
|
|
|
Breadboard demo:
|
|
|
|
|
|
|
|
### Supports 70+ Open Source Hardware (Partial List)
|
|
|
|
- <a href="https://oshwhub.com/li-chuang-kai-fa-ban/li-chuang-shi-zhan-pai-esp32-s3-kai-fa-ban" target="_blank" title="LiChuang ESP32-S3 Development Board">LiChuang ESP32-S3 Development Board</a>
|
|
- <a href="https://github.com/espressif/esp-box" target="_blank" title="Espressif ESP32-S3-BOX3">Espressif ESP32-S3-BOX3</a>
|
|
- <a href="https://docs.m5stack.com/zh_CN/core/CoreS3" target="_blank" title="M5Stack CoreS3">M5Stack CoreS3</a>
|
|
- <a href="https://docs.m5stack.com/en/atom/Atomic%20Echo%20Base" target="_blank" title="AtomS3R + Echo Base">M5Stack AtomS3R + Echo Base</a>
|
|
- <a href="https://gf.bilibili.com/item/detail/1108782064" target="_blank" title="Magic Button 2.4">Magic Button 2.4</a>
|
|
- <a href="https://www.waveshare.net/shop/ESP32-S3-Touch-AMOLED-1.8.htm" target="_blank" title="Waveshare ESP32-S3-Touch-AMOLED-1.8">Waveshare ESP32-S3-Touch-AMOLED-1.8</a>
|
|
- <a href="https://github.com/Xinyuan-LilyGO/T-Circle-S3" target="_blank" title="LILYGO T-Circle-S3">LILYGO T-Circle-S3</a>
|
|
- <a href="https://oshwhub.com/tenclass01/xmini_c3" target="_blank" title="XiaGe Mini C3">XiaGe Mini C3</a>
|
|
- <a href="https://oshwhub.com/movecall/cuican-ai-pendant-lights-up-y" target="_blank" title="Movecall CuiCan ESP32S3">CuiCan AI Pendant</a>
|
|
- <a href="https://github.com/WMnologo/xingzhi-ai" target="_blank" title="WMnologo-Xingzhi-1.54">WMnologo-Xingzhi-1.54TFT</a>
|
|
- <a href="https://www.seeedstudio.com/SenseCAP-Watcher-W1-A-p-5979.html" target="_blank" title="SenseCAP Watcher">SenseCAP Watcher</a>
|
|
- <a href="https://www.bilibili.com/video/BV1BHJtz6E2S/" target="_blank" title="ESP-HI Low Cost Robot Dog">ESP-HI Low Cost Robot Dog</a>
|
|
|
|
<div style="display: flex; justify-content: space-between;">
|
|
<a href="docs/v1/lichuang-s3.jpg" target="_blank" title="LiChuang ESP32-S3 Development Board">
|
|
<img src="docs/v1/lichuang-s3.jpg" width="240" />
|
|
</a>
|
|
<a href="docs/v1/espbox3.jpg" target="_blank" title="Espressif ESP32-S3-BOX3">
|
|
<img src="docs/v1/espbox3.jpg" width="240" />
|
|
</a>
|
|
<a href="docs/v1/m5cores3.jpg" target="_blank" title="M5Stack CoreS3">
|
|
<img src="docs/v1/m5cores3.jpg" width="240" />
|
|
</a>
|
|
<a href="docs/v1/atoms3r.jpg" target="_blank" title="AtomS3R + Echo Base">
|
|
<img src="docs/v1/atoms3r.jpg" width="240" />
|
|
</a>
|
|
<a href="docs/v1/magiclick.jpg" target="_blank" title="Magic Button 2.4">
|
|
<img src="docs/v1/magiclick.jpg" width="240" />
|
|
</a>
|
|
<a href="docs/v1/waveshare.jpg" target="_blank" title="Waveshare ESP32-S3-Touch-AMOLED-1.8">
|
|
<img src="docs/v1/waveshare.jpg" width="240" />
|
|
</a>
|
|
<a href="docs/v1/lilygo-t-circle-s3.jpg" target="_blank" title="LILYGO T-Circle-S3">
|
|
<img src="docs/v1/lilygo-t-circle-s3.jpg" width="240" />
|
|
</a>
|
|
<a href="docs/v1/xmini-c3.jpg" target="_blank" title="XiaGe Mini C3">
|
|
<img src="docs/v1/xmini-c3.jpg" width="240" />
|
|
</a>
|
|
<a href="docs/v1/movecall-cuican-esp32s3.jpg" target="_blank" title="CuiCan">
|
|
<img src="docs/v1/movecall-cuican-esp32s3.jpg" width="240" />
|
|
</a>
|
|
<a href="docs/v1/wmnologo_xingzhi_1.54.jpg" target="_blank" title="WMnologo-Xingzhi-1.54">
|
|
<img src="docs/v1/wmnologo_xingzhi_1.54.jpg" width="240" />
|
|
</a>
|
|
<a href="docs/v1/sensecap_watcher.jpg" target="_blank" title="SenseCAP Watcher">
|
|
<img src="docs/v1/sensecap_watcher.jpg" width="240" />
|
|
</a>
|
|
<a href="docs/v1/esp-hi.jpg" target="_blank" title="ESP-HI Low Cost Robot Dog">
|
|
<img src="docs/v1/esp-hi.jpg" width="240" />
|
|
</a>
|
|
</div>
|
|
|
|
## 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](https://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](https://ccnphfhqs21z.feishu.cn/wiki/Zpz4wXBtdimBrLk25WdcXzxcnNS)
|
|
|
|
### 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](docs/custom-board.md) - Learn how to create custom boards for XiaoZhi AI
|
|
- [MCP Protocol IoT Control Usage](docs/mcp-usage.md) - Learn how to control IoT devices via MCP protocol
|
|
- [MCP Protocol Interaction Flow](docs/mcp-protocol.md) - Device-side MCP protocol implementation
|
|
- [MQTT + UDP Hybrid Communication Protocol Document](docs/mqtt-udp.md)
|
|
- [A detailed WebSocket communication protocol document](docs/websocket.md)
|
|
|
|
## 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](https://xiaozhi.me) console for configuration.
|
|
|
|
👉 [Backend Operation Video Tutorial (Old Interface)](https://www.bilibili.com/video/BV1jUCUY2EKM/)
|
|
|
|
## Related Open Source Projects
|
|
|
|
For server deployment on personal computers, refer to the following open-source projects:
|
|
|
|
- [xinnan-tech/xiaozhi-esp32-server](https://github.com/xinnan-tech/xiaozhi-esp32-server) Python server
|
|
- [joey-zhou/xiaozhi-esp32-server-java](https://github.com/joey-zhou/xiaozhi-esp32-server-java) Java server
|
|
- [AnimeAIChat/xiaozhi-server-go](https://github.com/AnimeAIChat/xiaozhi-server-go) Golang server
|
|
|
|
Other client projects using the XiaoZhi communication protocol:
|
|
|
|
- [huangjunsen0406/py-xiaozhi](https://github.com/huangjunsen0406/py-xiaozhi) Python client
|
|
- [TOM88812/xiaozhi-android-client](https://github.com/TOM88812/xiaozhi-android-client) Android client
|
|
- [100askTeam/xiaozhi-linux](http://github.com/100askTeam/xiaozhi-linux) Linux client by 100ask
|
|
- [78/xiaozhi-sf32](https://github.com/78/xiaozhi-sf32) Bluetooth chip firmware by Sichuan
|
|
- [QuecPython/solution-xiaozhiAI](https://github.com/QuecPython/solution-xiaozhiAI) QuecPython firmware by Quectel
|
|
|
|
Custom Assets Tools:
|
|
|
|
- [78/xiaozhi-assets-generator](https://github.com/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 the QQ group: 1011329060
|
|
|
|
## Star History
|
|
|
|
<a href="https://star-history.com/#78/xiaozhi-esp32&Date">
|
|
<picture>
|
|
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=78/xiaozhi-esp32&type=Date&theme=dark" />
|
|
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=78/xiaozhi-esp32&type=Date" />
|
|
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=78/xiaozhi-esp32&type=Date" />
|
|
</picture>
|
|
</a>
|