From d0e3426d9f10f4dfbaf3f0d5e15c664a6d787409 Mon Sep 17 00:00:00 2001 From: Terrence Date: Thu, 20 Feb 2025 04:15:56 +0800 Subject: [PATCH] Update docs --- README.md | 29 ++-- README_en.md | 60 ++++---- README_ja.md | 95 +++++++------ docs/websocket.md | 338 ++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 447 insertions(+), 75 deletions(-) create mode 100644 docs/websocket.md diff --git a/README.md b/README.md index 907eabdb..dc0173a5 100644 --- a/README.md +++ b/README.md @@ -4,15 +4,17 @@ 这是虾哥的第一个硬件作品。 -👉 [ESP32+SenseVoice+Qwen72B打造你的AI聊天伴侣！【bilibili】](https://www.bilibili.com/video/BV11msTenEH3/?share_source=copy_web&vd_source=ee1aafe19d6e60cf22e60a93881faeba) +👉 [ESP32+SenseVoice+Qwen72B打造你的AI聊天伴侣！【bilibili】](https://www.bilibili.com/video/BV11msTenEH3/) + +👉 [给小智装上 DeepSeek 的聪明大脑【bilibili】](https://www.bilibili.com/video/BV1GQP6eNEFG/) 👉 [手工打造你的 AI 女友，新手入门教程【bilibili】](https://www.bilibili.com/video/BV1XnmFYLEJN/) ## 项目目的 -本项目基于乐鑫的 ESP-IDF 进行开发。 +本项目是一个开源项目，以 MIT 许可证发布，允许任何人免费使用，并可以用于商业用途。 -本项目是一个开源项目，主要用于教学目的。我们希望通过这个项目，能够帮助更多人入门 AI 硬件开发，了解如何将当下飞速发展的大语言模型应用到实际的硬件设备中。无论你是对 AI 感兴趣的学生，还是想要探索新技术的开发者，都可以通过这个项目获得宝贵的学习经验。 +我们希望通过这个项目，能够帮助更多人入门 AI 硬件开发，了解如何将当下飞速发展的大语言模型应用到实际的硬件设备中。无论你是对 AI 感兴趣的学生，还是想要探索新技术的开发者，都可以通过这个项目获得宝贵的学习经验。 欢迎所有人参与到项目的开发和改进中来。如果你有任何想法或建议，请随时提出 Issue 或加入群聊。 @@ -32,6 +34,7 @@ - 短期记忆，每轮对话后自我总结 - OLED / LCD 显示屏，显示信号强弱或对话内容 - 支持 LCD 显示图片表情 +- 支持多语言（中文、英文） ## 硬件部分 @@ -71,9 +74,6 @@ - - - @@ -95,7 +95,9 @@ ### 免开发环境烧录 -新手第一次操作建议先不要搭建开发环境，直接使用免开发环境烧录的固件。固件使用的是作者友情提供的测试服，目前开放免费使用，请勿用于商业用途。 +新手第一次操作建议先不要搭建开发环境，直接使用免开发环境烧录的固件。 + +固件默认接入 [xiaozhi.me](https://xiaozhi.me) 官方服务器，目前个人用户注册账号可以免费使用 Qwen 实时模型。 👉 [Flash烧录固件（无IDF开发环境）](https://ccnphfhqs21z.feishu.cn/wiki/Zpz4wXBtdimBrLk25WdcXzxcnNS) @@ -105,13 +107,20 @@ - Cursor 或 VSCode - 安装 ESP-IDF 插件，选择 SDK 版本 5.3 或以上 - Linux 比 Windows 更好，编译速度快，也免去驱动问题的困扰 +- 使用 Google C++ 代码风格，提交代码时请确保符合规范 -## AI 角色配置 +## 智能体配置 -如果你已经拥有一个小智 AI 聊天机器人，可以参考 👉 [后台操作视频教程](https://www.bilibili.com/video/BV1jUCUY2EKM/) +如果你已经拥有一个小智 AI 聊天机器人设备，可以登录 [xiaozhi.me](https://xiaozhi.me) 控制台进行配置。 -详细的使用说明以及测试服的注意事项，请参考 👉 [小智测试服的帮助说明](https://xiaozhi.me/help)。 +👉 [后台操作视频教程（旧版界面）](https://www.bilibili.com/video/BV1jUCUY2EKM/) + +## 技术原理与私有化部署 + +👉 [一份详细的 WebSocket 通信协议文档](docs/websocket.md) + +在个人电脑上部署服务器，可以参考另一位作者同样以 MIT 许可证开源的项目 [xiaozhi-esp32-server](https://github.com/xinnan-tech/xiaozhi-esp32-server) ## Star History diff --git a/README_en.md b/README_en.md index d1172b62..8f206947 100644 --- a/README_en.md +++ b/README_en.md @@ -1,62 +1,65 @@ # XiaoZhi AI Chatbot -（[中文](README.md) | English | [日本語](README_ja.md)） +([中文](README.md) | English | [日本語](README_ja.md)) This is Terrence's first hardware project. -👉 [Build your AI chat companion with ESP32+SenseVoice+Qwen72B! [bilibili]](https://www.bilibili.com/video/BV11msTenEH3/?share_source=copy_web&vd_source=ee1aafe19d6e60cf22e60a93881faeba) +👉 [Build your AI chat companion with ESP32+SenseVoice+Qwen72B!【bilibili】](https://www.bilibili.com/video/BV11msTenEH3/) -👉 [DIY Your AI Companion - Beginner's Tutorial [bilibili]](https://www.bilibili.com/video/BV1XnmFYLEJN/) +👉 [Equipping XiaoZhi with DeepSeek's smart brain【bilibili】](https://www.bilibili.com/video/BV1GQP6eNEFG/) + +👉 [Build your own AI companion, a beginner's guide【bilibili】](https://www.bilibili.com/video/BV1XnmFYLEJN/) ## Project Purpose -This project is developed based on Espressif's ESP-IDF. +This is an open-source project released under the MIT license, allowing anyone to use it freely, including for commercial purposes. -This is an open-source project primarily for educational purposes. Through this project, we aim to help more people get started with AI hardware development and understand how to integrate rapidly evolving large language models into actual hardware devices. Whether you're a student interested in AI or a developer looking to explore new technologies, this project offers valuable learning experiences. +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. -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 our chat group. +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: 946599635 ## Implemented Features - Wi-Fi / ML307 Cat.1 4G -- BOOT button wake-up and interrupt, supporting both click and long-press triggers +- 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 (Volcengine or CosyVoice) -- Large Language Model (Qwen2.5 72B or Doubao API) +- Large model TTS (Volcano Engine or CosyVoice) +- Large Language Models (Qwen, DeepSeek, Doubao) - Configurable prompts and voice tones (custom characters) -- Short-term memory with self-summary after each conversation round +- Short-term memory, self-summarizing after each conversation round - OLED / LCD display showing signal strength or conversation content -- Support for displaying emoji images on LCD +- Support for LCD image expressions +- Multi-language support (Chinese, English) ## Hardware Section -### Breadboard Practice +### Breadboard DIY Practice -For detailed tutorial, see the Feishu document: +See the Feishu document tutorial: 👉 [XiaoZhi AI Chatbot Encyclopedia](https://ccnphfhqs21z.feishu.cn/wiki/F5krwD16viZoF0kKkvDcrZNYnhb?from=from_copylink) -Breadboard setup shown below: +Breadboard demonstration: -![Breadboard Setup](docs/wiring2.jpg) +![Breadboard Demo](docs/wiring2.jpg) -### Supported Open-Source Hardware +### Supported Open Source Hardware - LiChuang ESP32-S3 Development Board - Espressif ESP32-S3-BOX3 - M5Stack CoreS3 - AtomS3R + Echo Base - AtomMatrix + Echo Base -- MagiClick 2.4 +- Magic Button 2.4 - Waveshare ESP32-S3-Touch-AMOLED-1.8 - LILYGO T-Circle-S3 -- Xmini C3 -- Movecall Moji ESP32S3 +- XiaGe Mini C3 +- Moji XiaoZhi AI Derivative Version
@@ -95,21 +98,30 @@ Breadboard setup shown below: ### Flashing Without Development Environment -For beginners, it's recommended to first try flashing the firmware without setting up a development environment. The firmware uses a test server provided by the author, currently available for free use (not for commercial purposes). +For beginners, it's recommended to first use the firmware that can be flashed without setting up a development environment. -👉 [Flash Firmware Guide (No IDF Environment Required)](https://ccnphfhqs21z.feishu.cn/wiki/Zpz4wXBtdimBrLk25WdcXzxcnNS) +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. + +👉 [Flash Firmware Guide (No IDF Environment)](https://ccnphfhqs21z.feishu.cn/wiki/Zpz4wXBtdimBrLk25WdcXzxcnNS) ### Development Environment - Cursor or VSCode - Install ESP-IDF plugin, select SDK version 5.3 or above - Linux is preferred over Windows for faster compilation and fewer driver issues +- Use Google C++ code style, ensure compliance when submitting code -## AI Character Configuration +## AI Agent Configuration -If you already have a XiaoZhi AI chatbot, please refer to 👉 [Backend Operation Video Tutorial](https://www.bilibili.com/video/BV1jUCUY2EKM/) +If you already have a XiaoZhi AI chatbot device, you can configure it through the [xiaozhi.me](https://xiaozhi.me) console. -For detailed usage instructions and test server notes, please refer to 👉 [XiaoZhi Test Server Help Guide](https://xiaozhi.me/help). +👉 [Backend Operation Tutorial (Old Interface)](https://www.bilibili.com/video/BV1jUCUY2EKM/) + +## Technical Principles and Private Deployment + +👉 [Detailed WebSocket Communication Protocol Documentation](docs/websocket.md) + +For server deployment on personal computers, refer to another MIT-licensed project [xiaozhi-esp32-server](https://github.com/xinnan-tech/xiaozhi-esp32-server) ## Star History diff --git a/README_ja.md b/README_ja.md index bc95798b..c448ae56 100644 --- a/README_ja.md +++ b/README_ja.md @@ -1,49 +1,52 @@ -# XiaoZhi AI チャットボット +# シャオジー AI チャットボット -（[中文](README.md) | [English](README_en.md) | 日本語） +([中文](README.md) | [English](README_en.md) | 日本語) -これはテレンスの最初のハードウェアプロジェクトです。 +これは シャーガー（Terrence）の最初のハードウェア作品です。 -👉 [ESP32+SenseVoice+Qwen72BでAIチャットコンパニオンを作ろう！【bilibili】](https://www.bilibili.com/video/BV11msTenEH3/?share_source=copy_web&vd_source=ee1aafe19d6e60cf22e60a93881faeba) +👉 [ESP32+SenseVoice+Qwen72Bで AI チャット仲間を作ろう！【bilibili】](https://www.bilibili.com/video/BV11msTenEH3/) -👉 [AIコンパニオンをDIYする - 初心者向けチュートリアル【bilibili】](https://www.bilibili.com/video/BV1XnmFYLEJN/) +👉 [シャオジーに DeepSeek のスマートな頭脳を搭載【bilibili】](https://www.bilibili.com/video/BV1GQP6eNEFG/) + +👉 [自分だけの AI パートナーを作る、初心者向けガイド【bilibili】](https://www.bilibili.com/video/BV1XnmFYLEJN/) ## プロジェクトの目的 -このプロジェクトはEspressifのESP-IDFに基づいて開発されています。 +このプロジェクトは MIT ライセンスの下で公開されているオープンソースプロジェクトで、商用利用を含め、誰でも自由に使用することができます。 -このプロジェクトは主に教育目的のためのオープンソースプロジェクトです。このプロジェクトを通じて、より多くの人々がAIハードウェア開発を始め、急速に進化する大規模言語モデルを実際のハードウェアデバイスに統合する方法を理解する手助けをすることを目指しています。AIに興味のある学生や新しい技術を探求したい開発者にとって、このプロジェクトは貴重な学習体験を提供します。 +このプロジェクトを通じて、より多くの人々が AI ハードウェア開発を始め、急速に進化している大規模言語モデルを実際のハードウェアデバイスに実装する方法を理解できるようになることを目指しています。AI に興味のある学生でも、新しい技術を探求する開発者でも、このプロジェクトから貴重な学習経験を得ることができます。 -プロジェクトの開発と改善に参加することを歓迎します。アイデアや提案があれば、Issueを提起するか、チャットグループに参加してください。 +プロジェクトの開発と改善には誰でも参加できます。アイデアや提案がありましたら、Issue を立てるかチャットグループにご参加ください。 -学習・ディスカッションQQグループ: 946599635 +学習・交流 QQ グループ：946599635 -## 実装された機能 +## 実装済みの機能 - 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（VolcengineまたはCosyVoice） -- 大規模言語モデル（Qwen2.5 72BまたはDoubao API） -- カスタマイズ可能なプロンプトと音声トーン（カスタムキャラクター） -- 短期記憶、各対話ラウンド後の自己要約 -- 信号強度や対話内容を表示するOLED / LCDディスプレイ -- LCDディスプレイでの絵文字表示をサポート +- 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 での画像表情表示に対応 +- 多言語対応（中国語、英語） -## ハードウェアセクション +## ハードウェア部分 -### ブレッドボードの練習 +### ブレッドボード DIY 実践 -詳細なチュートリアルについては、Feishuドキュメントを参照してください： +Feishu ドキュメントチュートリアルをご覧ください： -👉 [XiaoZhi AI チャットボット百事典](https://ccnphfhqs21z.feishu.cn/wiki/F5krwD16viZoF0kKkvDcrZNYnhb?from=from_copylink) +👉 [シャオジー AI チャットボット百科事典](https://ccnphfhqs21z.feishu.cn/wiki/F5krwD16viZoF0kKkvDcrZNYnhb?from=from_copylink) -以下にブレッドボードのセットアップを示します： +ブレッドボードのデモ： -![ブレッドボードのセットアップ](docs/wiring2.jpg) +![ブレッドボードデモ](docs/wiring2.jpg) ### サポートされているオープンソースハードウェア @@ -51,11 +54,12 @@ - Espressif ESP32-S3-BOX3 - M5Stack CoreS3 - AtomS3R + Echo Base -- MagiClick 2.4 +- AtomMatrix + Echo Base +- マジックボタン 2.4 - Waveshare ESP32-S3-Touch-AMOLED-1.8 - LILYGO T-Circle-S3 -- Xmini C3 -- Movecall Moji ESP32S3 +- XiaGe Mini C3 +- Moji シャオジー AI 派生版
@@ -87,27 +91,36 @@
-## ファームウェアセクション +## ファームウェア部分 -### 開発環境なしでのフラッシュ +### 開発環境なしのフラッシュ -初心者には、最初に開発環境を設定せずにファームウェアをフラッシュすることをお勧めします。ファームウェアは著者が提供するテストサーバーを使用しており、現在無料で使用できます（商業目的では使用しないでください）。 +初心者の方は、まず開発環境のセットアップなしでフラッシュできるファームウェアを使用することをお勧めします。 -👉 [開発環境なしでのフラッシュガイド](https://ccnphfhqs21z.feishu.cn/wiki/Zpz4wXBtdimBrLk25WdcXzxcnNS) +ファームウェアはデフォルトで公式 [xiaozhi.me](https://xiaozhi.me) サーバーに接続します。現在、個人ユーザーはアカウントを登録することで、Qwen リアルタイムモデルを無料で使用できます。 + +👉 [フラッシュファームウェアガイド（IDF環境なし）](https://ccnphfhqs21z.feishu.cn/wiki/Zpz4wXBtdimBrLk25WdcXzxcnNS) ### 開発環境 -- CursorまたはVSCode -- ESP-IDFプラグインをインストールし、SDKバージョン5.3以上を選択 -- LinuxはWindowsよりも優れており、コンパイルが速く、ドライバの問題も少ない +- Cursor または VSCode +- ESP-IDF プラグインをインストール、SDK バージョン 5.3 以上を選択 +- Linux は Windows より好ましい（コンパイルが速く、ドライバーの問題も少ない） +- Google C++ コードスタイルを使用、コード提出時にはコンプライアンスを確認 -## AIキャラクターの設定 +## AI エージェント設定 -すでにXiaoZhi AIチャットボットをお持ちの場合は、👉 [バックエンド操作ビデオチュートリアル](https://www.bilibili.com/video/BV1jUCUY2EKM/)を参照してください。 +シャオジー AI チャットボットデバイスをお持ちの場合は、[xiaozhi.me](https://xiaozhi.me) コンソールで設定できます。 -詳細な使用方法とテストサーバーの注意事項については、👉 [XiaoZhiテストサーバーヘルプガイド](https://xiaozhi.me/help)を参照してください。 +👉 [バックエンド操作チュートリアル（旧インターフェース）](https://www.bilibili.com/video/BV1jUCUY2EKM/) -## Star History +## 技術原理とプライベートデプロイメント + +👉 [詳細な WebSocket 通信プロトコルドキュメント](docs/websocket.md) + +個人のコンピュータでのサーバーデプロイメントについては、同じく MIT ライセンスで公開されている別のプロジェクト [xiaozhi-esp32-server](https://github.com/xinnan-tech/xiaozhi-esp32-server) を参照してください。 + +## スター履歴 diff --git a/docs/websocket.md b/docs/websocket.md new file mode 100644 index 00000000..bad6ea19 --- /dev/null +++ b/docs/websocket.md @@ -0,0 +1,338 @@ +以下是一份基于代码实现整理的 WebSocket 通信协议文档，概述客户端（设备）与服务器之间如何通过 WebSocket 进行交互。该文档仅基于所提供的代码推断，实际部署时可能需要结合服务器端实现进行进一步确认或补充。 + +--- + +## 1. 总体流程概览 + +1. **设备端初始化** + - 设备上电、初始化 `Application`： + - 初始化音频编解码器、显示屏、LED 等 + - 连接网络 + - 创建并初始化实现 `Protocol` 接口的 WebSocket 协议实例（`WebsocketProtocol`） + - 进入主循环等待事件（音频输入、音频输出、调度任务等）。 + +2. **建立 WebSocket 连接** + - 当设备需要开始语音会话时（例如用户唤醒、手动按键触发等），调用 `OpenAudioChannel()`： + - 根据编译配置获取 WebSocket URL（`CONFIG_WEBSOCKET_URL`） + - 设置若干请求头（`Authorization`, `Protocol-Version`, `Device-Id`, `Client-Id`） + - 调用 `Connect()` 与服务器建立 WebSocket 连接 + +3. **发送客户端 “hello” 消息** + - 连接成功后，设备会发送一条 JSON 消息，示例结构如下： + ```json + { + "type": "hello", + "version": 1, + "transport": "websocket", + "audio_params": { + "format": "opus", + "sample_rate": 16000, + "channels": 1, + "frame_duration": 60 + } + } + ``` + - 其中 `"frame_duration"` 的值对应 `OPUS_FRAME_DURATION_MS`（例如 60ms）。 + +4. **服务器回复 “hello”** + - 设备等待服务器返回一条包含 `"type": "hello"` 的 JSON 消息，并检查 `"transport": "websocket"` 是否匹配。 + - 如果匹配，则认为服务器已就绪，标记音频通道打开成功。 + - 如果在超时时间（默认 10 秒）内未收到正确回复，认为连接失败并触发网络错误回调。 + +5. **后续消息交互** + - 设备端和服务器端之间可发送两种主要类型的数据： + 1. **二进制音频数据**（Opus 编码） + 2. **文本 JSON 消息**（用于传输聊天状态、TTS/STT 事件、IoT 命令等） + + - 在代码里，接收回调主要分为： + - `OnData(...)`: + - 当 `binary` 为 `true` 时，认为是音频帧；设备会将其当作 Opus 数据进行解码。 + - 当 `binary` 为 `false` 时，认为是 JSON 文本，需要在设备端用 cJSON 进行解析并做相应业务逻辑处理（见下文消息结构）。 + + - 当服务器或网络出现断连，回调 `OnDisconnected()` 被触发： + - 设备会调用 `on_audio_channel_closed_()`，并最终回到空闲状态。 + +6. **关闭 WebSocket 连接** + - 设备在需要结束语音会话时，会调用 `CloseAudioChannel()` 主动断开连接，并回到空闲状态。 + - 或者如果服务器端主动断开，也会引发同样的回调流程。 + +--- + +## 2. 通用请求头 + +在建立 WebSocket 连接时，代码示例中设置了以下请求头： + +- `Authorization`: 用于存放访问令牌，形如 `"Bearer "` +- `Protocol-Version`: 固定示例中为 `"1"` +- `Device-Id`: 设备物理网卡 MAC 地址 +- `Client-Id`: 设备 UUID（可在应用中唯一标识设备） + +这些头会随着 WebSocket 握手一起发送到服务器，服务器可根据需求进行校验、认证等。 + +--- + +## 3. JSON 消息结构 + +WebSocket 文本帧以 JSON 方式传输，以下为常见的 `"type"` 字段及其对应业务逻辑。若消息里包含未列出的字段，可能为可选或特定实现细节。 + +### 3.1 客户端→服务器 + +1. **Hello** + - 连接成功后，由客户端发送，告知服务器基本参数。 + - 例： + ```json + { + "type": "hello", + "version": 1, + "transport": "websocket", + "audio_params": { + "format": "opus", + "sample_rate": 16000, + "channels": 1, + "frame_duration": 60 + } + } + ``` + +2. **Listen** + - 表示客户端开始或停止录音监听。 + - 常见字段： + - `"session_id"`：会话标识 + - `"type": "listen"` + - `"state"`：`"start"`, `"stop"`, `"detect"`（唤醒检测已触发） + - `"mode"`：`"auto"`, `"manual"` 或 `"realtime"`，表示识别模式。 + - 例：开始监听 + ```json + { + "session_id": "xxx", + "type": "listen", + "state": "start", + "mode": "manual" + } + ``` + +3. **Abort** + - 终止当前说话（TTS 播放）或语音通道。 + - 例： + ```json + { + "session_id": "xxx", + "type": "abort", + "reason": "wake_word_detected" + } + ``` + - `reason` 值可为 `"wake_word_detected"` 或其他。 + +4. **Wake Word Detected** + - 用于客户端向服务器告知检测到唤醒词。 + - 例： + ```json + { + "session_id": "xxx", + "type": "listen", + "state": "detect", + "text": "你好小明" + } + ``` + +5. **IoT** + - 发送当前设备的物联网相关信息： + - **Descriptors**（描述设备功能、属性等） + - **States**（设备状态的实时更新） + - 例： + ```json + { + "session_id": "xxx", + "type": "iot", + "descriptors": { ... } + } + ``` + 或 + ```json + { + "session_id": "xxx", + "type": "iot", + "states": { ... } + } + ``` + +--- + +### 3.2 服务器→客户端 + +1. **Hello** + - 服务器端返回的握手确认消息。 + - 必须包含 `"type": "hello"` 和 `"transport": "websocket"`。 + - 可能会带有 `audio_params`，表示服务器期望的音频参数，或与客户端对齐的配置。 + - 成功接收后客户端会设置事件标志，表示 WebSocket 通道就绪。 + +2. **STT** + - `{"type": "stt", "text": "..."}` + - 表示服务器端识别到了用户语音。（例如语音转文本结果） + - 设备可能将此文本显示到屏幕上，后续再进入回答等流程。 + +3. **LLM** + - `{"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": "..."}` + - 让设备在界面上显示当前要播放或朗读的文本片段（例如用于显示给用户）。 + +5. **IoT** + - `{"type": "iot", "commands": [ ... ]}` + - 服务器向设备发送物联网的动作指令，设备解析并执行（如打开灯、设置温度等）。 + +6. **音频数据：二进制帧** + - 当服务器发送音频二进制帧（Opus 编码）时，客户端解码并播放。 + - 若客户端正在处于 “listening” （录音）状态，收到的音频帧会被忽略或清空以防冲突。 + +--- + +## 4. 音频编解码 + +1. **客户端发送录音数据** + - 音频输入经过可能的回声消除、降噪或音量增益后，通过 Opus 编码打包为二进制帧发送给服务器。 + - 如果客户端每次编码生成的二进制帧大小为 N 字节，则会通过 WebSocket 的 **binary** 消息发送这块数据。 + +2. **客户端播放收到的音频** + - 收到服务器的二进制帧时，同样认定是 Opus 数据。 + - 设备端会进行解码，然后交由音频输出接口播放。 + - 如果服务器的音频采样率与设备不一致，会在解码后再进行重采样。 + +--- + +## 5. 常见状态流转 + +以下简述设备端关键状态流转，与 WebSocket 消息对应： + +1. **Idle** → **Connecting** + - 用户触发或唤醒后，设备调用 `OpenAudioChannel()` → 建立 WebSocket 连接 → 发送 `"type":"hello"`。 + +2. **Connecting** → **Listening** + - 成功建立连接后，若继续执行 `SendStartListening(...)`，则进入录音状态。此时设备会持续编码麦克风数据并发送到服务器。 + +3. **Listening** → **Speaking** + - 收到服务器 TTS Start 消息 (`{"type":"tts","state":"start"}`) → 停止录音并播放接收到的音频。 + +4. **Speaking** → **Idle** + - 服务器 TTS Stop (`{"type":"tts","state":"stop"}`) → 音频播放结束。若未继续进入自动监听，则返回 Idle；如果配置了自动循环，则再度进入 Listening。 + +5. **Listening** / **Speaking** → **Idle**（遇到异常或主动中断） + - 调用 `SendAbortSpeaking(...)` 或 `CloseAudioChannel()` → 中断会话 → 关闭 WebSocket → 状态回到 Idle。 + +--- + +## 6. 错误处理 + +1. **连接失败** + - 如果 `Connect(url)` 返回失败或在等待服务器 “hello” 消息时超时，触发 `on_network_error_()` 回调。设备会提示“无法连接到服务”或类似错误信息。 + +2. **服务器断开** + - 如果 WebSocket 异常断开，回调 `OnDisconnected()`： + - 设备回调 `on_audio_channel_closed_()` + - 切换到 Idle 或其他重试逻辑。 + +--- + +## 7. 其它注意事项 + +1. **鉴权** + - 设备通过设置 `Authorization: Bearer ` 提供鉴权，服务器端需验证是否有效。 + - 如果令牌过期或无效，服务器可拒绝握手或在后续断开。 + +2. **会话控制** + - 代码中部分消息包含 `session_id`，用于区分独立的对话或操作。服务端可根据需要对不同会话做分离处理，WebSocket 协议为空。 + +3. **音频负载** + - 代码里默认使用 Opus 格式，并设置 `sample_rate = 16000`，单声道。帧时长由 `OPUS_FRAME_DURATION_MS` 控制，一般为 60ms。可根据带宽或性能做适当调整。 + +4. **IoT 指令** + - `"type":"iot"` 的消息用户端代码对接 `thing_manager` 执行具体命令，因设备定制而不同。服务器端需确保下发格式与客户端保持一致。 + +5. **错误或异常 JSON** + - 当 JSON 中缺少必要字段，例如 `{"type": ...}`，客户端会记录错误日志（`ESP_LOGE(TAG, "Missing message type, data: %s", data);`），不会执行任何业务。 + +--- + +## 8. 消息示例 + +下面给出一个典型的双向消息示例（流程简化示意）： + +1. **客户端 → 服务器**（握手） + ```json + { + "type": "hello", + "version": 1, + "transport": "websocket", + "audio_params": { + "format": "opus", + "sample_rate": 16000, + "channels": 1, + "frame_duration": 60 + } + } + ``` + +2. **服务器 → 客户端**（握手应答） + ```json + { + "type": "hello", + "transport": "websocket", + "audio_params": { + "sample_rate": 16000 + } + } + ``` + +3. **客户端 → 服务器**（开始监听） + ```json + { + "session_id": "", + "type": "listen", + "state": "start", + "mode": "auto" + } + ``` + 同时客户端开始发送二进制帧（Opus 数据）。 + +4. **服务器 → 客户端**（ASR 结果） + ```json + { + "type": "stt", + "text": "用户说的话" + } + ``` + +5. **服务器 → 客户端**（TTS开始） + ```json + { + "type": "tts", + "state": "start" + } + ``` + 接着服务器发送二进制音频帧给客户端播放。 + +6. **服务器 → 客户端**（TTS结束） + ```json + { + "type": "tts", + "state": "stop" + } + ``` + 客户端停止播放音频，若无更多指令，则回到空闲状态。 + +--- + +## 9. 总结 + +本协议通过在 WebSocket 上层传输 JSON 文本与二进制音频帧，完成功能包括音频流上传、TTS 音频播放、语音识别与状态管理、IoT 指令下发等。其核心特征： + +- **握手阶段**：发送 `"type":"hello"`，等待服务器返回。 +- **音频通道**：采用 Opus 编码的二进制帧双向传输语音流。 +- **JSON 消息**：使用 `"type"` 为核心字段标识不同业务逻辑，包括 TTS、STT、IoT、WakeWord 等。 +- **扩展性**：可根据实际需求在 JSON 消息中添加字段，或在 headers 里进行额外鉴权。 + +服务器与客户端需提前约定各类消息的字段含义、时序逻辑以及错误处理规则，方能保证通信顺畅。上述信息可作为基础文档，便于后续对接、开发或扩展。