diff --git a/README.md b/README.md index b211b1e..f9cfd5a 100644 --- a/README.md +++ b/README.md @@ -1,48 +1,43 @@ -# 小智 AI 聊天机器人 （XiaoZhi AI Chatbot） +# An MCP-based Chatbot | 一个基于 MCP 的聊天机器人 （中文 | [English](README_en.md) | [日本語](README_ja.md)） -## 视频介绍 +## 视频 -👉 [ESP32+SenseVoice+Qwen72B 打造你的 AI 聊天伴侣！【bilibili】](https://www.bilibili.com/video/BV11msTenEH3/) - -👉 [给小智装上 DeepSeek 的聪明大脑【bilibili】](https://www.bilibili.com/video/BV1GQP6eNEFG/) +👉 [人类：给 AI 装摄像头 vs AI：当场发现主人三天没洗头【bilibili】](https://www.bilibili.com/video/BV1bpjgzKEhd/) 👉 [手工打造你的 AI 女友，新手入门教程【bilibili】](https://www.bilibili.com/video/BV1XnmFYLEJN/) -## 项目目的 +## 介绍 -本项目是由虾哥开源的一个开源项目，以 MIT 许可证发布，允许任何人免费使用，并可以用于商业用途。 +这是一个由虾哥开源的 ESP32 项目，以 MIT 许可证发布，允许任何人免费使用，或用于商业用途。 -我们希望通过这个项目，能够帮助更多人入门 AI 硬件开发，了解如何将当下飞速发展的大语言模型应用到实际的硬件设备中。无论你是对 AI 感兴趣的学生，还是想要探索新技术的开发者，都可以通过这个项目获得宝贵的学习经验。 +我们希望通过这个项目，能够帮助大家了解 AI 硬件开发，将当下飞速发展的大语言模型应用到实际的硬件设备中。 -欢迎所有人参与到项目的开发和改进中来。如果你有任何想法或建议，请随时提出 Issue 或加入群聊。 +如果你有任何想法或建议，请随时提出 Issues 或加入 QQ 群：575180511 -学习交流 QQ 群：376893254 +### 基于 MCP 控制万物 -## 已实现功能 +小智 AI 聊天机器人作为一个语音交互入口，利用 Qwen / DeepSeek 等大模型的 AI 能力，通过 MCP 协议实现多端控制。 + +![通过MCP控制万物](docs/mcp-based-graph.jpg) + +### 已实现功能 - Wi-Fi / ML307 Cat.1 4G -- BOOT 键唤醒和打断，支持点击和长按两种触发方式 - 离线语音唤醒 [ESP-SR](https://github.com/espressif/esp-sr) -- 流式语音对话（WebSocket 或 UDP 协议） -- 支持国语、粤语、英语、日语、韩语 5 种语言识别 [SenseVoice](https://github.com/FunAudioLLM/SenseVoice) -- 声纹识别，识别是谁在喊 AI 的名字 [3D Speaker](https://github.com/modelscope/3D-Speaker) -- 大模型 TTS（火山引擎 或 CosyVoice） -- 大模型 LLM（Qwen, DeepSeek, Doubao） -- 可配置的提示词和音色（自定义角色） -- 短期记忆，每轮对话后自我总结 -- OLED / LCD 显示屏，显示信号强弱或对话内容 -- 支持 LCD 显示图片表情 -- 支持多语言（中文、英文） +- 支持两种通信协议（[Websocket](docs/websocket.md) 或 MQTT+UDP） +- 采用 OPUS 音频编解码 +- 基于流式 ASR + LLM + TTS 架构的语音交互 +- 声纹识别，识别当前说话人的身份 [3D Speaker](https://github.com/modelscope/3D-Speaker) +- OLED / LCD 显示屏，支持表情显示 +- 电量显示与电源管理 +- 支持多语言（中文、英文、日文） +- 支持ESP32-C3、ESP32-S3、ESP32-P4芯片平台 +- 通过设备端 MCP 实现设备控制（音量、灯光、电机、GPIO等） +- 通过云端 MCP 扩展大模型能力（智能家居控制、PC桌面操作、知识搜索、邮件收发等） -## ✅ 已支持的芯片平台 - -- ✅ ESP32-S3 -- ✅ ESP32-C3 -- ✅ ESP32-P4 - -## 硬件部分 +## 硬件 ### 面包板手工制作实践 @@ -52,23 +47,23 @@ 面包板效果图如下： -![面包板效果图](docs/wiring2.jpg) +![面包板效果图](docs/v1/wiring2.jpg) -### 已支持的开源硬件 +### 支持 70 多个开源硬件（仅展示部分） - 立创·实战派 ESP32-S3 开发板 - 乐鑫 ESP32-S3-BOX3 - M5Stack CoreS3 -- AtomS3R + Echo Base -- AtomMatrix + Echo Base +- M5Stack AtomS3R + Echo Base - 神奇按钮 2.4 - 微雪电子 ESP32-S3-Touch-AMOLED-1.8 - LILYGO T-Circle-S3 - 虾哥 Mini C3 -- Moji 小智 AI 衍生版 - 璀璨·AI 吊坠 - 无名科技 Nologo-星智-1.54TFT - SenseCAP Watcher +- ESP-HI 超低成本机器狗 +
@@ -88,14 +83,11 @@ - - + + - - - - - + + @@ -106,42 +98,53 @@ + + +
-## 固件部分 +## 软件 -### 免开发环境烧录 +### 固件烧录 新手第一次操作建议先不要搭建开发环境，直接使用免开发环境烧录的固件。 -固件默认接入 [xiaozhi.me](https://xiaozhi.me) 官方服务器，目前个人用户注册账号可以免费使用 Qwen 实时模型。 +固件默认接入 [xiaozhi.me](https://xiaozhi.me) 官方服务器，个人用户注册账号可以免费使用 Qwen 实时模型。 -👉 [Flash 烧录固件（无 IDF 开发环境）](https://ccnphfhqs21z.feishu.cn/wiki/Zpz4wXBtdimBrLk25WdcXzxcnNS) +👉 [新手烧录固件教程](https://ccnphfhqs21z.feishu.cn/wiki/Zpz4wXBtdimBrLk25WdcXzxcnNS) ### 开发环境 - Cursor 或 VSCode - 安装 ESP-IDF 插件，选择 SDK 版本 5.4 或以上 - Linux 比 Windows 更好，编译速度快，也免去驱动问题的困扰 -- 使用 Google C++ 代码风格，提交代码时请确保符合规范 +- 本项目使用 Google C++ 代码风格，提交代码时请确保符合规范 ### 开发者文档 -- [开发板定制指南](main/boards/README.md) - 学习如何为小智创建自定义开发板适配 -- [物联网控制模块](main/iot/README.md) - 了解如何通过 AI 语音控制物联网设备 +- [自定义开发板指南](main/boards/README.md) - 学习如何为小智AI创建自定义开发板 +- [MCP 协议物联网控制用法说明](docs/mcp-usage.md) - 了解如何通过 MCP 协议控制物联网设备 +- [MCP 协议交互流程](docs/mcp-protocol.md) - 设备端 MCP 协议的实现方式 +- [一份详细的 WebSocket 通信协议文档](docs/websocket.md) -## 智能体配置 +## 大模型配置 -如果你已经拥有一个小智 AI 聊天机器人设备，可以登录 [xiaozhi.me](https://xiaozhi.me) 控制台进行配置。 +如果你已经拥有一个的小智 AI 聊天机器人设备，并且已接入官方服务器，可以登录 [xiaozhi.me](https://xiaozhi.me) 控制台进行配置。 👉 [后台操作视频教程（旧版界面）](https://www.bilibili.com/video/BV1jUCUY2EKM/) -## 技术原理与私有化部署 +## 相关开源项目 -👉 [一份详细的 WebSocket 通信协议文档](docs/websocket.md) -👉 [MCP 协议 通信协议](docs/mcp_protocol.md) +在个人电脑上部署服务器，可以参考以下开源的项目： -在个人电脑上部署服务器，可以参考另一位作者同样以 MIT 许可证开源的项目 [xiaozhi-esp32-server](https://github.com/xinnan-tech/xiaozhi-esp32-server) +- [xinnan-tech/xiaozhi-esp32-server](https://github.com/xinnan-tech/xiaozhi-esp32-server) Python 服务器 +- [joey-zhou/xiaozhi-esp32-server-java](https://github.com/joey-zhou/xiaozhi-esp32-server-java) Java 服务器 +- [AnimeAIChat/xiaozhi-server-go](https://github.com/AnimeAIChat/xiaozhi-server-go) Golang 服务器 + +使用小智通信协议的其他客户端项目： + +- [huangjunsen0406/py-xiaozhi](https://github.com/huangjunsen0406/py-xiaozhi) Python 客户端 +- [TOM88812/xiaozhi-android-client](https://github.com/TOM88812/xiaozhi-android-client) Android 客户端 ## Star History diff --git a/README_en.md b/README_en.md index 5138323..aa4a8b3 100644 --- a/README_en.md +++ b/README_en.md @@ -1,74 +1,68 @@ -# XiaoZhi AI Chatbot +# An MCP-based Chatbot -([中文](README.md) | English | [日本語](README_ja.md)) +(English | [中文](README.md) | [日本語](README_ja.md)) + +## Video + +👉 [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/) ## Introduction -👉 [Build your AI chat companion with ESP32+SenseVoice+Qwen72B!【bilibili】](https://www.bilibili.com/video/BV11msTenEH3/) +This is an open-source ESP32 project, released under the MIT license, allowing anyone to use it for free, including for commercial purposes. -👉 [Equipping XiaoZhi with DeepSeek's smart brain【bilibili】](https://www.bilibili.com/video/BV1GQP6eNEFG/) +We hope this project helps everyone understand AI hardware development and apply rapidly evolving large language models to real hardware devices. -👉 [Build your own AI companion, a beginner's guide【bilibili】](https://www.bilibili.com/video/BV1XnmFYLEJN/) +If you have any ideas or suggestions, please feel free to raise Issues or join the QQ group: 575180511 -## Project Purpose +### Control Everything with MCP -This is an open-source project released under the MIT license, allowing anyone to use it freely, including for commercial purposes. +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. -Through this project, we aim to help more people get started with AI hardware development and understand how to implement rapidly evolving large language models in actual hardware devices. Whether you're a student interested in AI or a developer exploring new technologies, this project offers valuable learning experiences. +![Control everything via MCP](docs/mcp-based-graph.jpg) -Everyone is welcome to participate in the project's development and improvement. If you have any ideas or suggestions, please feel free to raise an Issue or join the chat group. - -Learning & Discussion QQ Group: 376893254 - -## Implemented Features +### Features Implemented - Wi-Fi / ML307 Cat.1 4G -- BOOT button wake-up and interruption, supporting both click and long-press triggers - Offline voice wake-up [ESP-SR](https://github.com/espressif/esp-sr) -- Streaming voice dialogue (WebSocket or UDP protocol) -- Support for 5 languages: Mandarin, Cantonese, English, Japanese, Korean [SenseVoice](https://github.com/FunAudioLLM/SenseVoice) -- Voice print recognition to identify who's calling AI's name [3D Speaker](https://github.com/modelscope/3D-Speaker) -- Large model TTS (Volcano Engine or CosyVoice) -- Large Language Models (Qwen, DeepSeek, Doubao) -- Configurable prompts and voice tones (custom characters) -- Short-term memory, self-summarizing after each conversation round -- OLED / LCD display showing signal strength or conversation content -- Support for LCD image expressions -- Multi-language support (Chinese, English) +- 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.) -## ✅ Supported chips - -- ✅ ESP32-S3 -- ✅ ESP32-C3 -- ✅ ESP32-P4 - -## Hardware Section +## Hardware ### Breadboard DIY Practice See the Feishu document tutorial: -👉 [XiaoZhi AI Chatbot Encyclopedia](https://ccnphfhqs21z.feishu.cn/wiki/F5krwD16viZoF0kKkvDcrZNYnhb?from=from_copylink) +👉 ["XiaoZhi AI Chatbot Encyclopedia"](https://ccnphfhqs21z.feishu.cn/wiki/F5krwD16viZoF0kKkvDcrZNYnhb?from=from_copylink) -Breadboard demonstration: +Breadboard demo: -![Breadboard Demo](docs/wiring2.jpg) +![Breadboard Demo](docs/v1/wiring2.jpg) -### Supported Open Source Hardware +### Supports 70+ Open Source Hardware (Partial List) - LiChuang ESP32-S3 Development Board - Espressif ESP32-S3-BOX3 - M5Stack CoreS3 -- AtomS3R + Echo Base -- AtomMatrix + Echo Base +- M5Stack AtomS3R + Echo Base - Magic Button 2.4 - Waveshare ESP32-S3-Touch-AMOLED-1.8 - LILYGO T-Circle-S3 - XiaGe Mini C3 -- Moji XiaoZhi AI Derivative Version -- CuiCan AI pendant +- CuiCan AI Pendant - WMnologo-Xingzhi-1.54TFT - SenseCAP Watcher +- ESP-HI Low Cost Robot Dog
@@ -83,23 +77,17 @@ Breadboard demonstration: - - - - + - - + + - - - - - + + @@ -110,41 +98,53 @@ Breadboard demonstration: + + +
-## Firmware Section +## Software -### Flashing Without Development Environment +### Firmware Flashing -For beginners, it's recommended to first use the firmware that can be flashed without setting up a development environment. +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. Currently, personal users can register an account to use the Qwen real-time model for free. +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. -👉 [Flash Firmware Guide (No IDF Environment)](https://ccnphfhqs21z.feishu.cn/wiki/Zpz4wXBtdimBrLk25WdcXzxcnNS) +👉 [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 preferred over Windows for faster compilation and fewer driver issues -- Use Google C++ code style, ensure compliance when submitting code +- 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 -- [Board Customization Guide](main/boards/README.md) - Learn how to create custom board adaptations for XiaoZhi -- [IoT Control Module](main/iot/README.md) - Understand how to control IoT devices through AI voice commands +- [Custom Board Guide](main/boards/README.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 +- [A detailed WebSocket communication protocol document](docs/websocket.md) -## AI Agent Configuration +## Large Model Configuration -If you already have a XiaoZhi AI chatbot device, you can configure it through the [xiaozhi.me](https://xiaozhi.me) console. +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 Tutorial (Old Interface)](https://www.bilibili.com/video/BV1jUCUY2EKM/) +👉 [Backend Operation Video Tutorial (Old Interface)](https://www.bilibili.com/video/BV1jUCUY2EKM/) -## Technical Principles and Private Deployment +## Related Open Source Projects -👉 [Detailed WebSocket Communication Protocol Documentation](docs/websocket.md) +For server deployment on personal computers, refer to the following open-source projects: -For server deployment on personal computers, refer to another MIT-licensed project [xiaozhi-esp32-server](https://github.com/xinnan-tech/xiaozhi-esp32-server) +- [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 ## Star History diff --git a/README_ja.md b/README_ja.md index 4294654..de4c89c 100644 --- a/README_ja.md +++ b/README_ja.md @@ -1,80 +1,74 @@ -# シャオジー AI チャットボット +# MCP ベースのチャットボット -([中文](README.md) | [English](README_en.md) | 日本語) +（日本語 | [中文](README.md) | [English](README_en.md)） -## プロジェクト紹介 +## 動画 -👉 [ESP32+SenseVoice+Qwen72Bで AI チャット仲間を作ろう！【bilibili】](https://www.bilibili.com/video/BV11msTenEH3/) +👉 [人間：AIにカメラを装着 vs AI：その場で飼い主が3日間髪を洗っていないことを発見【bilibili】](https://www.bilibili.com/video/BV1bpjgzKEhd/) -👉 [シャオジーに DeepSeek のスマートな頭脳を搭載【bilibili】](https://www.bilibili.com/video/BV1GQP6eNEFG/) +👉 [手作りでAIガールフレンドを作る、初心者入門チュートリアル【bilibili】](https://www.bilibili.com/video/BV1XnmFYLEJN/) -👉 [自分だけの AI パートナーを作る、初心者向けガイド【bilibili】](https://www.bilibili.com/video/BV1XnmFYLEJN/) +## イントロダクション -## プロジェクトの目的 +これはエビ兄さんがオープンソースで公開しているESP32プロジェクトで、MITライセンスのもと、誰でも無料で、商用利用も可能です。 -このプロジェクトは MIT ライセンスの下で公開されているオープンソースプロジェクトで、商用利用を含め、誰でも自由に使用することができます。 +このプロジェクトを通じて、AIハードウェア開発を理解し、急速に進化する大規模言語モデルを実際のハードウェアデバイスに応用できるようになることを目指しています。 -このプロジェクトを通じて、より多くの人々が AI ハードウェア開発を始め、急速に進化している大規模言語モデルを実際のハードウェアデバイスに実装する方法を理解できるようになることを目指しています。AI に興味のある学生でも、新しい技術を探求する開発者でも、このプロジェクトから貴重な学習経験を得ることができます。 +ご意見やご提案があれば、いつでもIssueを提出するか、QQグループ：575180511 にご参加ください。 -プロジェクトの開発と改善には誰でも参加できます。アイデアや提案がありましたら、Issue を立てるかチャットグループにご参加ください。 +### MCPであらゆるものを制御 -学習・交流 QQ グループ：376893254 +シャオジーAIチャットボットは音声インタラクションの入口として、Qwen / DeepSeekなどの大規模モデルのAI能力を活用し、MCPプロトコルを通じてマルチエンド制御を実現します。 -## 実装済みの機能 +![MCPであらゆるものを制御](docs/mcp-based-graph.jpg) + +### 実装済み機能 - Wi-Fi / ML307 Cat.1 4G -- BOOT ボタンによる起動と中断、クリックと長押しの2種類のトリガーに対応 -- オフライン音声起動 [ESP-SR](https://github.com/espressif/esp-sr) -- ストリーミング音声対話（WebSocket または UDP プロトコル） -- 5言語対応：標準中国語、広東語、英語、日本語、韓国語 [SenseVoice](https://github.com/FunAudioLLM/SenseVoice) -- 話者認識、AI の名前を呼んでいる人を識別 [3D Speaker](https://github.com/modelscope/3D-Speaker) -- 大規模モデル TTS（Volcano Engine または CosyVoice） -- 大規模言語モデル（Qwen, DeepSeek, Doubao） -- 設定可能なプロンプトと音声トーン（カスタムキャラクター） -- 短期記憶、各会話ラウンド後の自己要約 -- OLED / LCD ディスプレイ、信号強度や会話内容を表示 -- LCD での画像表情表示に対応 -- 多言語対応（中国語、英語） +- オフライン音声ウェイクアップ [ESP-SR](https://github.com/espressif/esp-sr) +- 2種類の通信プロトコルに対応（[Websocket](docs/websocket.md) または MQTT+UDP） +- OPUSオーディオコーデックを採用 +- ストリーミングASR + LLM + TTSアーキテクチャに基づく音声インタラクション +- 話者認識、現在話している人を識別 [3D Speaker](https://github.com/modelscope/3D-Speaker) +- OLED / LCDディスプレイ、表情表示対応 +- バッテリー表示と電源管理 +- 多言語対応（中国語、英語、日本語） +- ESP32-C3、ESP32-S3、ESP32-P4チッププラットフォーム対応 +- デバイス側MCPによるデバイス制御（音量・明るさ調整、アクション制御など） +- クラウド側MCPで大規模モデル能力を拡張（スマートホーム制御、PCデスクトップ操作、知識検索、メール送受信など） -## ✅ サポートチップです +## ハードウェア -- ✅ ESP32-S3 -- ✅ ESP32-C3 -- ✅ ESP32-P4 +### ブレッドボード手作り実践 -## ハードウェア部分 +Feishuドキュメントチュートリアルをご覧ください： -### ブレッドボード DIY 実践 - -Feishu ドキュメントチュートリアルをご覧ください： - -👉 [シャオジー AI チャットボット百科事典](https://ccnphfhqs21z.feishu.cn/wiki/F5krwD16viZoF0kKkvDcrZNYnhb?from=from_copylink) +👉 [「シャオジーAIチャットボット百科事典」](https://ccnphfhqs21z.feishu.cn/wiki/F5krwD16viZoF0kKkvDcrZNYnhb?from=from_copylink) ブレッドボードのデモ： -![ブレッドボードデモ](docs/wiring2.jpg) +![ブレッドボードデモ](docs/v1/wiring2.jpg) -### サポートされているオープンソースハードウェア +### 70種類以上のオープンソースハードウェアに対応（一部のみ表示） -- LiChuang ESP32-S3 開発ボード -- Espressif ESP32-S3-BOX3 +- 立創・実戦派 ESP32-S3 開発ボード +- 楽鑫 ESP32-S3-BOX3 - M5Stack CoreS3 -- AtomS3R + Echo Base -- AtomMatrix + Echo Base -- マジックボタン 2.4 -- Waveshare ESP32-S3-Touch-AMOLED-1.8 +- M5Stack AtomS3R + Echo Base +- マジックボタン2.4 +- 微雪電子 ESP32-S3-Touch-AMOLED-1.8 - LILYGO T-Circle-S3 -- XiaGe Mini C3 -- Moji シャオジー AI 派生版 -- Cuican AI ペンダント +- エビ兄さん Mini C3 +- CuiCan AIペンダント - 無名科技Nologo-星智-1.54TFT - SenseCAP Watcher +- ESP-HI 超低コストロボット犬
- + - + @@ -83,20 +77,17 @@ Feishu ドキュメントチュートリアルをご覧ください： - + - + - - + + - - - - - + + @@ -107,41 +98,53 @@ Feishu ドキュメントチュートリアルをご覧ください： + + +
-## ファームウェア部分 +## ソフトウェア -### 開発環境なしのフラッシュ +### ファームウェア書き込み -初心者の方は、まず開発環境のセットアップなしでフラッシュできるファームウェアを使用することをお勧めします。 +初心者の方は、まず開発環境を構築せずに書き込み可能なファームウェアを使用することをおすすめします。 -ファームウェアはデフォルトで公式 [xiaozhi.me](https://xiaozhi.me) サーバーに接続します。現在、個人ユーザーはアカウントを登録することで、Qwen リアルタイムモデルを無料で使用できます。 +ファームウェアはデフォルトで公式 [xiaozhi.me](https://xiaozhi.me) サーバーに接続します。個人ユーザーはアカウント登録でQwenリアルタイムモデルを無料で利用できます。 -👉 [フラッシュファームウェアガイド（IDF環境なし）](https://ccnphfhqs21z.feishu.cn/wiki/Zpz4wXBtdimBrLk25WdcXzxcnNS) +👉 [初心者向けファームウェア書き込みガイド](https://ccnphfhqs21z.feishu.cn/wiki/Zpz4wXBtdimBrLk25WdcXzxcnNS) ### 開発環境 - Cursor または VSCode -- ESP-IDF プラグインをインストール、SDK バージョン 5.4 以上を選択 -- Linux は Windows より好ましい（コンパイルが速く、ドライバーの問題も少ない） -- Google C++ コードスタイルを使用、コード提出時にはコンプライアンスを確認 +- ESP-IDFプラグインをインストールし、SDKバージョン5.4以上を選択 +- LinuxはWindowsよりも優れており、コンパイルが速く、ドライバの問題も少ない +- 本プロジェクトはGoogle C++コードスタイルを採用、コード提出時は準拠を確認してください ### 開発者ドキュメント -- [ボードカスタマイズガイド](main/boards/README.md) - シャオジー向けのカスタムボード適応を作成する方法を学ぶ -- [IoT 制御モジュール](main/iot/README.md) - AI 音声コマンドでIoTデバイスを制御する方法を理解する +- [カスタム開発ボードガイド](main/boards/README.md) - シャオジーAI用のカスタム開発ボード作成方法 +- [MCPプロトコルIoT制御使用法](docs/mcp-usage.md) - MCPプロトコルでIoTデバイスを制御する方法 +- [MCPプロトコルインタラクションフロー](docs/mcp-protocol.md) - デバイス側MCPプロトコルの実装方法 +- [詳細なWebSocket通信プロトコルドキュメント](docs/websocket.md) -## AI エージェント設定 +## 大規模モデル設定 -シャオジー AI チャットボットデバイスをお持ちの場合は、[xiaozhi.me](https://xiaozhi.me) コンソールで設定できます。 +すでにシャオジーAIチャットボットデバイスをお持ちで、公式サーバーに接続済みの場合は、[xiaozhi.me](https://xiaozhi.me) コンソールで設定できます。 -👉 [バックエンド操作チュートリアル（旧インターフェース）](https://www.bilibili.com/video/BV1jUCUY2EKM/) +👉 [バックエンド操作ビデオチュートリアル（旧インターフェース）](https://www.bilibili.com/video/BV1jUCUY2EKM/) -## 技術原理とプライベートデプロイメント +## 関連オープンソースプロジェクト -👉 [詳細な WebSocket 通信プロトコルドキュメント](docs/websocket.md) +個人PCでサーバーをデプロイする場合は、以下のオープンソースプロジェクトを参照してください： -個人のコンピュータでのサーバーデプロイメントについては、同じく MIT ライセンスで公開されている別のプロジェクト [xiaozhi-esp32-server](https://github.com/xinnan-tech/xiaozhi-esp32-server) を参照してください。 +- [xinnan-tech/xiaozhi-esp32-server](https://github.com/xinnan-tech/xiaozhi-esp32-server) Pythonサーバー +- [joey-zhou/xiaozhi-esp32-server-java](https://github.com/joey-zhou/xiaozhi-esp32-server-java) Javaサーバー +- [AnimeAIChat/xiaozhi-server-go](https://github.com/AnimeAIChat/xiaozhi-server-go) Golangサーバー + +シャオジー通信プロトコルを利用した他のクライアントプロジェクト： + +- [huangjunsen0406/py-xiaozhi](https://github.com/huangjunsen0406/py-xiaozhi) Pythonクライアント +- [TOM88812/xiaozhi-android-client](https://github.com/TOM88812/xiaozhi-android-client) Androidクライアント ## スター履歴 diff --git a/docs/mcp-based-graph.jpg b/docs/mcp-based-graph.jpg new file mode 100644 index 0000000..af81cd2 Binary files /dev/null and b/docs/mcp-based-graph.jpg differ diff --git a/docs/mcp_protocol.md b/docs/mcp-protocol.md similarity index 100% rename from docs/mcp_protocol.md rename to docs/mcp-protocol.md diff --git a/docs/mcp-usage.md b/docs/mcp-usage.md new file mode 100644 index 0000000..fa50a39 --- /dev/null +++ b/docs/mcp-usage.md @@ -0,0 +1,115 @@ +# MCP 协议物联网控制用法说明 + +> 本文档介绍如何基于 MCP 协议实现 ESP32 设备的物联网控制。详细协议流程请参考 [`mcp-protocol.md`](./mcp-protocol.md)。 + +## 简介 + +MCP（Model Context Protocol）是新一代推荐用于物联网控制的协议，通过标准 JSON-RPC 2.0 格式在后台与设备间发现和调用"工具"（Tool），实现灵活的设备控制。 + +## 典型使用流程 + +1. 设备启动后通过基础协议（如 WebSocket/MQTT）与后台建立连接。 +2. 后台通过 MCP 协议的 `initialize` 方法初始化会话。 +3. 后台通过 `tools/list` 获取设备支持的所有工具（功能）及参数说明。 +4. 后台通过 `tools/call` 调用具体工具，实现对设备的控制。 + +详细协议格式与交互请见 [`mcp-protocol.md`](./mcp-protocol.md)。 + +## 设备端工具注册方法说明 + +设备通过 `McpServer::AddTool` 方法注册可被后台调用的"工具"。其常用函数签名如下： + +```cpp +void AddTool( + const std::string& name, // 工具名称，建议唯一且有层次感，如 self.dog.forward + const std::string& description, // 工具描述，简明说明功能，便于大模型理解 + const PropertyList& properties, // 输入参数列表（可为空），支持类型：布尔、整数、字符串 + std::function callback // 工具被调用时的回调实现 +); +``` +- name：工具唯一标识，建议用"模块.功能"命名风格。 +- description：自然语言描述，便于 AI/用户理解。 +- properties：参数列表，支持类型有布尔、整数、字符串，可指定范围和默认值。 +- callback：收到调用请求时的实际执行逻辑，返回值可为 bool/int/string。 + +## 典型注册示例（以 ESP-Hi 为例） + +```cpp +void InitializeTools() { + auto& mcp_server = McpServer::GetInstance(); + // 例1：无参数，控制机器人前进 + mcp_server.AddTool("self.dog.forward", "机器人向前移动", PropertyList(), [this](const PropertyList&) -> ReturnValue { + servo_dog_ctrl_send(DOG_STATE_FORWARD, NULL); + return true; + }); + // 例2：带参数，设置灯光 RGB 颜色 + mcp_server.AddTool("self.light.set_rgb", "设置RGB颜色", PropertyList({ + Property("r", kPropertyTypeInteger, 0, 255), + Property("g", kPropertyTypeInteger, 0, 255), + Property("b", kPropertyTypeInteger, 0, 255) + }), [this](const PropertyList& properties) -> ReturnValue { + int r = properties["r"].value(); + int g = properties["g"].value(); + int b = properties["b"].value(); + led_on_ = true; + SetLedColor(r, g, b); + return true; + }); +} +``` + +## 常见工具调用 JSON-RPC 示例 + +### 1. 获取工具列表 +```json +{ + "jsonrpc": "2.0", + "method": "tools/list", + "params": { "cursor": "" }, + "id": 1 +} +``` + +### 2. 控制底盘前进 +```json +{ + "jsonrpc": "2.0", + "method": "tools/call", + "params": { + "name": "self.chassis.go_forward", + "arguments": {} + }, + "id": 2 +} +``` + +### 3. 切换灯光模式 +```json +{ + "jsonrpc": "2.0", + "method": "tools/call", + "params": { + "name": "self.chassis.switch_light_mode", + "arguments": { "light_mode": 3 } + }, + "id": 3 +} +``` + +### 4. 摄像头翻转 +```json +{ + "jsonrpc": "2.0", + "method": "tools/call", + "params": { + "name": "self.camera.set_camera_flipped", + "arguments": {} + }, + "id": 4 +} +``` + +## 备注 +- 工具名称、参数及返回值请以设备端 `AddTool` 注册为准。 +- 推荐所有新项目统一采用 MCP 协议进行物联网控制。 +- 详细协议与进阶用法请查阅 [`mcp-protocol.md`](./mcp-protocol.md)。 \ No newline at end of file diff --git a/docs/AtomMatrix-echo-base.jpg b/docs/v0/AtomMatrix-echo-base.jpg similarity index 100% rename from docs/AtomMatrix-echo-base.jpg rename to docs/v0/AtomMatrix-echo-base.jpg diff --git a/docs/ESP32-BreadBoard.jpg b/docs/v0/ESP32-BreadBoard.jpg similarity index 100% rename from docs/ESP32-BreadBoard.jpg rename to docs/v0/ESP32-BreadBoard.jpg diff --git a/docs/atoms3r-echo-base.jpg b/docs/v0/atoms3r-echo-base.jpg similarity index 100% rename from docs/atoms3r-echo-base.jpg rename to docs/v0/atoms3r-echo-base.jpg diff --git a/docs/esp32s3-box3.jpg b/docs/v0/esp32s3-box3.jpg similarity index 100% rename from docs/esp32s3-box3.jpg rename to docs/v0/esp32s3-box3.jpg diff --git a/docs/lichuang-s3.jpg b/docs/v0/lichuang-s3.jpg similarity index 100% rename from docs/lichuang-s3.jpg rename to docs/v0/lichuang-s3.jpg diff --git a/docs/m5stack-cores3.jpg b/docs/v0/m5stack-cores3.jpg similarity index 100% rename from docs/m5stack-cores3.jpg rename to docs/v0/m5stack-cores3.jpg diff --git a/docs/magiclick-2p4.jpg b/docs/v0/magiclick-2p4.jpg similarity index 100% rename from docs/magiclick-2p4.jpg rename to docs/v0/magiclick-2p4.jpg diff --git a/docs/waveshare-esp32-s3-touch-amoled-1.8.jpg b/docs/v0/waveshare-esp32-s3-touch-amoled-1.8.jpg similarity index 100% rename from docs/waveshare-esp32-s3-touch-amoled-1.8.jpg rename to docs/v0/waveshare-esp32-s3-touch-amoled-1.8.jpg diff --git a/docs/wiring.jpg b/docs/v0/wiring.jpg similarity index 100% rename from docs/wiring.jpg rename to docs/v0/wiring.jpg diff --git a/docs/v1/esp-hi.jpg b/docs/v1/esp-hi.jpg new file mode 100644 index 0000000..d6fc714 Binary files /dev/null and b/docs/v1/esp-hi.jpg differ diff --git a/docs/esp-sparkbot.jpg b/docs/v1/esp-sparkbot.jpg similarity index 100% rename from docs/esp-sparkbot.jpg rename to docs/v1/esp-sparkbot.jpg diff --git a/docs/lilygo-t-circle-s3.jpg b/docs/v1/lilygo-t-circle-s3.jpg similarity index 100% rename from docs/lilygo-t-circle-s3.jpg rename to docs/v1/lilygo-t-circle-s3.jpg diff --git a/docs/wiring2.jpg b/docs/v1/wiring2.jpg similarity index 100% rename from docs/wiring2.jpg rename to docs/v1/wiring2.jpg diff --git a/docs/xmini-c3.jpg b/docs/v1/xmini-c3.jpg similarity index 100% rename from docs/xmini-c3.jpg rename to docs/v1/xmini-c3.jpg diff --git a/docs/websocket.md b/docs/websocket.md index b976953..8e62128 100644 --- a/docs/websocket.md +++ b/docs/websocket.md @@ -1,4 +1,6 @@ -以下是一份基于代码实现整理的 WebSocket 通信协议文档，概述客户端（设备）与服务器之间如何通过 WebSocket 进行交互。该文档仅基于所提供的代码推断，实际部署时可能需要结合服务器端实现进行进一步确认或补充。 +以下是一份基于代码实现整理的 WebSocket 通信协议文档，概述设备端与服务器之间如何通过 WebSocket 进行交互。 + +该文档仅基于所提供的代码推断，实际部署时可能需要结合服务器端实现进行进一步确认或补充。 --- @@ -17,12 +19,15 @@ - 设置若干请求头（`Authorization`, `Protocol-Version`, `Device-Id`, `Client-Id`） - 调用 `Connect()` 与服务器建立 WebSocket 连接 -3. **发送客户端 “hello” 消息** +3. **设备端发送 "hello" 消息** - 连接成功后，设备会发送一条 JSON 消息，示例结构如下： ```json { "type": "hello", "version": 1, + "features": { + "mcp": true + }, "transport": "websocket", "audio_params": { "format": "opus", @@ -32,22 +37,38 @@ } } ``` - - 其中 `"frame_duration"` 的值对应 `OPUS_FRAME_DURATION_MS`（例如 60ms）。 + - 其中 `features` 字段为可选，内容根据设备编译配置自动生成。例如：`"mcp": true` 表示支持 MCP 协议。 + - `frame_duration` 的值对应 `OPUS_FRAME_DURATION_MS`（例如 60ms）。 -4. **服务器回复 “hello”** +4. **服务器回复 "hello"** - 设备等待服务器返回一条包含 `"type": "hello"` 的 JSON 消息，并检查 `"transport": "websocket"` 是否匹配。 + - 服务器可选下发 `session_id` 字段，设备端收到后会自动记录。 + - 示例： + ```json + { + "type": "hello", + "transport": "websocket", + "session_id": "xxx", + "audio_params": { + "format": "opus", + "sample_rate": 24000, + "channels": 1, + "frame_duration": 60 + } + } + ``` - 如果匹配，则认为服务器已就绪，标记音频通道打开成功。 - 如果在超时时间（默认 10 秒）内未收到正确回复，认为连接失败并触发网络错误回调。 5. **后续消息交互** - 设备端和服务器端之间可发送两种主要类型的数据： 1. **二进制音频数据**（Opus 编码） - 2. **文本 JSON 消息**（用于传输聊天状态、TTS/STT 事件、IoT 命令等） + 2. **文本 JSON 消息**（用于传输聊天状态、TTS/STT 事件、MCP 协议消息等） - 在代码里，接收回调主要分为： - `OnData(...)`: - 当 `binary` 为 `true` 时，认为是音频帧；设备会将其当作 Opus 数据进行解码。 - - 当 `binary` 为 `false` 时，认为是 JSON 文本，需要在设备端用 cJSON 进行解析并做相应业务逻辑处理（见下文消息结构）。 + - 当 `binary` 为 `false` 时，认为是 JSON 文本，需要在设备端用 cJSON 进行解析并做相应业务逻辑处理（如聊天、TTS、MCP 协议消息等）。 - 当服务器或网络出现断连，回调 `OnDisconnected()` 被触发： - 设备会调用 `on_audio_channel_closed_()`，并最终回到空闲状态。 @@ -63,9 +84,9 @@ 在建立 WebSocket 连接时，代码示例中设置了以下请求头： - `Authorization`: 用于存放访问令牌，形如 `"Bearer "` -- `Protocol-Version`: 固定示例中为 `"1"` -- `Device-Id`: 设备物理网卡 MAC 地址 -- `Client-Id`: 设备 UUID（可在应用中唯一标识设备） +- `Protocol-Version`: 固定示例中为 `"1"`，与 hello 消息体内的 `version` 字段保持一致 +- `Device-Id`: 设备物理网卡 MAC 地址 +- `Client-Id`: 软件生成的 UUID（擦除 NVS 或重新烧录完整固件会重置） 这些头会随着 WebSocket 握手一起发送到服务器，服务器可根据需求进行校验、认证等。 @@ -75,15 +96,18 @@ WebSocket 文本帧以 JSON 方式传输，以下为常见的 `"type"` 字段及其对应业务逻辑。若消息里包含未列出的字段，可能为可选或特定实现细节。 -### 3.1 客户端→服务器 +### 3.1 设备端→服务器 1. **Hello** - - 连接成功后，由客户端发送，告知服务器基本参数。 + - 连接成功后，由设备端发送，告知服务器基本参数。 - 例： ```json { "type": "hello", "version": 1, + "features": { + "mcp": true + }, "transport": "websocket", "audio_params": { "format": "opus", @@ -95,7 +119,7 @@ WebSocket 文本帧以 JSON 方式传输，以下为常见的 `"type"` 字段及 ``` 2. **Listen** - - 表示客户端开始或停止录音监听。 + - 表示设备端开始或停止录音监听。 - 常见字段： - `"session_id"`：会话标识 - `"type": "listen"` @@ -124,7 +148,8 @@ WebSocket 文本帧以 JSON 方式传输，以下为常见的 `"type"` 字段及 - `reason` 值可为 `"wake_word_detected"` 或其他。 4. **Wake Word Detected** - - 用于客户端向服务器告知检测到唤醒词。 + - 用于设备端向服务器告知检测到唤醒词。 + - 在发送该消息之前，可提前发送唤醒词的 Opus 音频数据，用于服务器进行声纹检测。 - 例： ```json { @@ -135,69 +160,86 @@ WebSocket 文本帧以 JSON 方式传输，以下为常见的 `"type"` 字段及 } ``` -5. **IoT** - - 发送当前设备的物联网相关信息： - - **Descriptors**（描述设备功能、属性等） - - **States**（设备状态的实时更新） - - 例： +5. **MCP** + - 推荐用于物联网控制的新一代协议。所有设备能力发现、工具调用等均通过 type: "mcp" 的消息进行，payload 内部为标准 JSON-RPC 2.0（详见 [MCP 协议文档](./mcp-protocol.md)）。 + + - **设备端到服务器发送 result 的例子：** ```json { "session_id": "xxx", - "type": "iot", - "descriptors": { ... } - } - ``` - 或 - ```json - { - "session_id": "xxx", - "type": "iot", - "states": { ... } + "type": "mcp", + "payload": { + "jsonrpc": "2.0", + "id": 1, + "result": { + "content": [ + { "type": "text", "text": "true" } + ], + "isError": false + } + } } ``` --- -### 3.2 服务器→客户端 +### 3.2 服务器→设备端 1. **Hello** - 服务器端返回的握手确认消息。 - 必须包含 `"type": "hello"` 和 `"transport": "websocket"`。 - - 可能会带有 `audio_params`，表示服务器期望的音频参数，或与客户端对齐的配置。 - - 成功接收后客户端会设置事件标志，表示 WebSocket 通道就绪。 + - 可能会带有 `audio_params`，表示服务器期望的音频参数，或与设备端对齐的配置。 + - 服务器可选下发 `session_id` 字段，设备端收到后会自动记录。 + - 成功接收后设备端会设置事件标志，表示 WebSocket 通道就绪。 2. **STT** - - `{"type": "stt", "text": "..."}` + - `{"session_id": "xxx", "type": "stt", "text": "..."}` - 表示服务器端识别到了用户语音。（例如语音转文本结果） - 设备可能将此文本显示到屏幕上，后续再进入回答等流程。 3. **LLM** - - `{"type": "llm", "emotion": "happy", "text": "😀"}` + - `{"session_id": "xxx", "type": "llm", "emotion": "happy", "text": "😀"}` - 服务器指示设备调整表情动画 / UI 表达。 4. **TTS** - - `{"type": "tts", "state": "start"}`：服务器准备下发 TTS 音频，客户端进入 “speaking” 播放状态。 - - `{"type": "tts", "state": "stop"}`：表示本次 TTS 结束。 - - `{"type": "tts", "state": "sentence_start", "text": "..."}` + - `{"session_id": "xxx", "type": "tts", "state": "start"}`：服务器准备下发 TTS 音频，设备端进入 "speaking" 播放状态。 + - `{"session_id": "xxx", "type": "tts", "state": "stop"}`：表示本次 TTS 结束。 + - `{"session_id": "xxx", "type": "tts", "state": "sentence_start", "text": "..."}` - 让设备在界面上显示当前要播放或朗读的文本片段（例如用于显示给用户）。 -5. **IoT** - - `{"type": "iot", "commands": [ ... ]}` - - 服务器向设备发送物联网的动作指令，设备解析并执行（如打开灯、设置温度等）。 +5. **MCP** + - 服务器通过 type: "mcp" 的消息下发物联网相关的控制指令或返回调用结果，payload 结构同上。 + + - **服务器到设备端发送 tools/call 的例子：** + ```json + { + "session_id": "xxx", + "type": "mcp", + "payload": { + "jsonrpc": "2.0", + "method": "tools/call", + "params": { + "name": "self.light.set_rgb", + "arguments": { "r": 255, "g": 0, "b": 0 } + }, + "id": 1 + } + } + ``` 6. **音频数据：二进制帧** - - 当服务器发送音频二进制帧（Opus 编码）时，客户端解码并播放。 - - 若客户端正在处于 “listening” （录音）状态，收到的音频帧会被忽略或清空以防冲突。 + - 当服务器发送音频二进制帧（Opus 编码）时，设备端解码并播放。 + - 若设备端正在处于 "listening" （录音）状态，收到的音频帧会被忽略或清空以防冲突。 --- ## 4. 音频编解码 -1. **客户端发送录音数据** +1. **设备端发送录音数据** - 音频输入经过可能的回声消除、降噪或音量增益后，通过 Opus 编码打包为二进制帧发送给服务器。 - - 如果客户端每次编码生成的二进制帧大小为 N 字节，则会通过 WebSocket 的 **binary** 消息发送这块数据。 + - 如果设备端每次编码生成的二进制帧大小为 N 字节，则会通过 WebSocket 的 **binary** 消息发送这块数据。 -2. **客户端播放收到的音频** +2. **设备端播放收到的音频** - 收到服务器的二进制帧时，同样认定是 Opus 数据。 - 设备端会进行解码，然后交由音频输出接口播放。 - 如果服务器的音频采样率与设备不一致，会在解码后再进行重采样。 @@ -206,7 +248,7 @@ WebSocket 文本帧以 JSON 方式传输，以下为常见的 `"type"` 字段及 ## 5. 常见状态流转 -以下简述设备端关键状态流转，与 WebSocket 消息对应： +以下为常见设备端关键状态流转，与 WebSocket 消息对应： 1. **Idle** → **Connecting** - 用户触发或唤醒后，设备调用 `OpenAudioChannel()` → 建立 WebSocket 连接 → 发送 `"type":"hello"`。 @@ -223,12 +265,52 @@ WebSocket 文本帧以 JSON 方式传输，以下为常见的 `"type"` 字段及 5. **Listening** / **Speaking** → **Idle**（遇到异常或主动中断） - 调用 `SendAbortSpeaking(...)` 或 `CloseAudioChannel()` → 中断会话 → 关闭 WebSocket → 状态回到 Idle。 +### 自动模式状态流转图 + +```mermaid +stateDiagram + direction TB + [*] --> kDeviceStateUnknown + kDeviceStateUnknown --> kDeviceStateStarting:初始化 + kDeviceStateStarting --> kDeviceStateWifiConfiguring:配置WiFi + kDeviceStateStarting --> kDeviceStateActivating:激活设备 + kDeviceStateActivating --> kDeviceStateUpgrading:检测到新版本 + kDeviceStateActivating --> kDeviceStateIdle:激活完成 + kDeviceStateIdle --> kDeviceStateConnecting:开始连接 + kDeviceStateConnecting --> kDeviceStateIdle:连接失败 + kDeviceStateConnecting --> kDeviceStateListening:连接成功 + kDeviceStateListening --> kDeviceStateSpeaking:开始说话 + kDeviceStateSpeaking --> kDeviceStateListening:结束说话 + kDeviceStateListening --> kDeviceStateIdle:手动终止 + kDeviceStateSpeaking --> kDeviceStateIdle:自动终止 +``` + +### 手动模式状态流转图 + +```mermaid +stateDiagram + direction TB + [*] --> kDeviceStateUnknown + kDeviceStateUnknown --> kDeviceStateStarting:初始化 + kDeviceStateStarting --> kDeviceStateWifiConfiguring:配置WiFi + kDeviceStateStarting --> kDeviceStateActivating:激活设备 + kDeviceStateActivating --> kDeviceStateUpgrading:检测到新版本 + kDeviceStateActivating --> kDeviceStateIdle:激活完成 + kDeviceStateIdle --> kDeviceStateConnecting:开始连接 + kDeviceStateConnecting --> kDeviceStateIdle:连接失败 + kDeviceStateConnecting --> kDeviceStateListening:连接成功 + kDeviceStateIdle --> kDeviceStateListening:开始监听 + kDeviceStateListening --> kDeviceStateIdle:停止监听 + kDeviceStateIdle --> kDeviceStateSpeaking:开始说话 + kDeviceStateSpeaking --> kDeviceStateIdle:结束说话 +``` + --- ## 6. 错误处理 1. **连接失败** - - 如果 `Connect(url)` 返回失败或在等待服务器 “hello” 消息时超时，触发 `on_network_error_()` 回调。设备会提示“无法连接到服务”或类似错误信息。 + - 如果 `Connect(url)` 返回失败或在等待服务器 "hello" 消息时超时，触发 `on_network_error_()` 回调。设备会提示"无法连接到服务"或类似错误信息。 2. **服务器断开** - 如果 WebSocket 异常断开，回调 `OnDisconnected()`： @@ -244,16 +326,18 @@ WebSocket 文本帧以 JSON 方式传输，以下为常见的 `"type"` 字段及 - 如果令牌过期或无效，服务器可拒绝握手或在后续断开。 2. **会话控制** - - 代码中部分消息包含 `session_id`，用于区分独立的对话或操作。服务端可根据需要对不同会话做分离处理，WebSocket 协议为空。 + - 代码中部分消息包含 `session_id`，用于区分独立的对话或操作。服务端可根据需要对不同会话做分离处理。 3. **音频负载** - - 代码里默认使用 Opus 格式，并设置 `sample_rate = 16000`，单声道。帧时长由 `OPUS_FRAME_DURATION_MS` 控制，一般为 60ms。可根据带宽或性能做适当调整。 + - 代码里默认使用 Opus 格式，并设置 `sample_rate = 16000`，单声道。帧时长由 `OPUS_FRAME_DURATION_MS` 控制，一般为 60ms。可根据带宽或性能做适当调整。为了获得更好的音乐播放效果，服务器下行音频可能使用 24000 采样率。 -4. **IoT 指令** - - `"type":"iot"` 的消息用户端代码对接 `thing_manager` 执行具体命令，因设备定制而不同。服务器端需确保下发格式与客户端保持一致。 +4. **物联网控制推荐 MCP 协议** + - 设备与服务器之间的物联网能力发现、状态同步、控制指令等，建议全部通过 MCP 协议（type: "mcp"）实现。原有的 type: "iot" 方案已废弃。 + - MCP 协议可在 WebSocket、MQTT 等多种底层协议上传输，具备更好的扩展性和标准化能力。 + - 详细用法请参考 [MCP 协议文档](./mcp-protocol.md) 及 [MCP 物联网控制用法](./mcp-usage.md)。 5. **错误或异常 JSON** - - 当 JSON 中缺少必要字段，例如 `{"type": ...}`，客户端会记录错误日志（`ESP_LOGE(TAG, "Missing message type, data: %s", data);`），不会执行任何业务。 + - 当 JSON 中缺少必要字段，例如 `{"type": ...}`，设备端会记录错误日志（`ESP_LOGE(TAG, "Missing message type, data: %s", data);`），不会执行任何业务。 --- @@ -261,11 +345,14 @@ WebSocket 文本帧以 JSON 方式传输，以下为常见的 `"type"` 字段及 下面给出一个典型的双向消息示例（流程简化示意）： -1. **客户端 → 服务器**（握手） +1. **设备端 → 服务器**（握手） ```json { "type": "hello", "version": 1, + "features": { + "mcp": true + }, "transport": "websocket", "audio_params": { "format": "opus", @@ -276,63 +363,68 @@ WebSocket 文本帧以 JSON 方式传输，以下为常见的 `"type"` 字段及 } ``` -2. **服务器 → 客户端**（握手应答） +2. **服务器 → 设备端**（握手应答） ```json { "type": "hello", "transport": "websocket", + "session_id": "xxx", "audio_params": { + "format": "opus", "sample_rate": 16000 } } ``` -3. **客户端 → 服务器**（开始监听） +3. **设备端 → 服务器**（开始监听） ```json { - "session_id": "", + "session_id": "xxx", "type": "listen", "state": "start", "mode": "auto" } ``` - 同时客户端开始发送二进制帧（Opus 数据）。 + 同时设备端开始发送二进制帧（Opus 数据）。 -4. **服务器 → 客户端**（ASR 结果） +4. **服务器 → 设备端**（ASR 结果） ```json { + "session_id": "xxx", "type": "stt", "text": "用户说的话" } ``` -5. **服务器 → 客户端**（TTS开始） +5. **服务器 → 设备端**（TTS开始） ```json { + "session_id": "xxx", "type": "tts", "state": "start" } ``` - 接着服务器发送二进制音频帧给客户端播放。 + 接着服务器发送二进制音频帧给设备端播放。 -6. **服务器 → 客户端**（TTS结束） +6. **服务器 → 设备端**（TTS结束） ```json { + "session_id": "xxx", "type": "tts", "state": "stop" } ``` - 客户端停止播放音频，若无更多指令，则回到空闲状态。 + 设备端停止播放音频，若无更多指令，则回到空闲状态。 --- ## 9. 总结 -本协议通过在 WebSocket 上层传输 JSON 文本与二进制音频帧，完成功能包括音频流上传、TTS 音频播放、语音识别与状态管理、IoT 指令下发等。其核心特征： +本协议通过在 WebSocket 上层传输 JSON 文本与二进制音频帧，完成功能包括音频流上传、TTS 音频播放、语音识别与状态管理、MCP 指令下发等。其核心特征： - **握手阶段**：发送 `"type":"hello"`，等待服务器返回。 - **音频通道**：采用 Opus 编码的二进制帧双向传输语音流。 -- **JSON 消息**：使用 `"type"` 为核心字段标识不同业务逻辑，包括 TTS、STT、IoT、WakeWord 等。 +- **JSON 消息**：使用 `"type"` 为核心字段标识不同业务逻辑，包括 TTS、STT、MCP、WakeWord 等。 - **扩展性**：可根据实际需求在 JSON 消息中添加字段，或在 headers 里进行额外鉴权。 -服务器与客户端需提前约定各类消息的字段含义、时序逻辑以及错误处理规则，方能保证通信顺畅。上述信息可作为基础文档，便于后续对接、开发或扩展。 +服务器与设备端需提前约定各类消息的字段含义、时序逻辑以及错误处理规则，方能保证通信顺畅。上述信息可作为基础文档，便于后续对接、开发或扩展。 diff --git a/main/Kconfig.projbuild b/main/Kconfig.projbuild index 1f759b7..c39f8ec 100644 --- a/main/Kconfig.projbuild +++ b/main/Kconfig.projbuild @@ -388,9 +388,9 @@ choice IOT_PROTOCOL help IoT 协议，用于获取设备状态与发送控制指令 config IOT_PROTOCOL_MCP - bool "MCP协议 2024-11-05" + bool "MCP 2024-11-05" config IOT_PROTOCOL_XIAOZHI - bool "小智IoT协议 1.0" + bool "Xiaozhi IoT 1.0 (Deprecated)" endchoice endmenu diff --git a/main/boards/README.md b/main/boards/README.md index 3f10780..7b8ab26 100644 --- a/main/boards/README.md +++ b/main/boards/README.md @@ -111,7 +111,7 @@ mkdir main/boards/my-custom-board 一个基本的开发板类定义包含以下几个部分： -1. **类定义**：继承自`WifiBoard`或`ML307Board` +1. **类定义**：继承自`WifiBoard`或`Ml307Board` 2. **初始化函数**：包括I2C、显示屏、按钮、IoT等组件的初始化 3. **虚函数重写**：如`GetAudioCodec()`、`GetDisplay()`、`GetBacklight()`等 4. **注册开发板**：使用`DECLARE_BOARD`宏注册开发板 @@ -301,20 +301,21 @@ DECLARE_BOARD(MyCustomBoard); - AXP2101 - 其他可用的PMIC -### 4. IoT设备 +### 4. MCP设备控制 -可以添加各种IoT设备，让AI能够"看到"和控制: -- Speaker (扬声器) -- Screen (屏幕) -- Battery (电池) -- Light (灯光) +可以添加各种MCP工具，让AI能够使用: +- Speaker (扬声器控制) +- Screen (屏幕亮度调节) +- Battery (电池电量读取) +- Light (灯光控制) - 等... ## 开发板类继承关系 - `Board` - 基础板级类 - - `WifiBoard` - WiFi连接的开发板 - - `ML307Board` - 使用4G模块的开发板 + - `WifiBoard` - Wi-Fi连接的开发板 + - `Ml307Board` - 使用4G模块的开发板 + - `DualNetworkBoard` - 支持Wi-Fi与4G网络切换的开发板 ## 开发技巧 @@ -327,7 +328,7 @@ DECLARE_BOARD(MyCustomBoard); 1. **显示屏不正常**：检查SPI配置、镜像设置和颜色反转设置 2. **音频无输出**：检查I2S配置、PA使能引脚和编解码器地址 -3. **无法连接网络**：检查WiFi凭据和网络配置 +3. **无法连接网络**：检查Wi-Fi凭据和网络配置 4. **无法与服务器通信**：检查MQTT或WebSocket配置 ## 参考资料 diff --git a/main/iot/README.md b/main/iot/README.md index 7bbfd52..7ce70da 100644 --- a/main/iot/README.md +++ b/main/iot/README.md @@ -1,5 +1,7 @@ # 物联网控制模块 +> ⚠️ **注意：本模块已不推荐使用。请使用"MCP协议"来实现物联网控制，获得更好的兼容性与功能支持。** + 本模块实现了小智AI语音聊天机器人的物联网控制功能，使用户可以通过语音指令控制接入到ESP32开发板的各种物联网设备。 ## 工作原理 diff --git a/main/ota.cc b/main/ota.cc index 5741eb1..bb70eaf 100644 --- a/main/ota.cc +++ b/main/ota.cc @@ -60,6 +60,7 @@ Http* Ota::SetupHttp() { if (has_serial_number_) { http->SetHeader("Serial-Number", serial_number_.c_str()); } + http->SetHeader("User-Agent", std::string(BOARD_NAME "/") + app_desc->version); http->SetHeader("Accept-Language", Lang::CODE); http->SetHeader("Content-Type", "application/json");