diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..de296d1 --- /dev/null +++ b/README.en.md @@ -0,0 +1,173 @@ +# 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. + +Control everything via MCP + +## 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: + +![Breadboard Demo](docs/v1/wiring2.jpg) + +### 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](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 +- [hackers365/xiaozhi-esp32-server-golang](https://github.com/hackers365/xiaozhi-esp32-server-golang) 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 our [Discord](https://discord.gg/C759fGMBcZ) or QQ group: 994694848 + +## Star History + + + + + + Star History Chart + + \ No newline at end of file