From 911fee2d85c129099a6bba80a10e6e846a35089b Mon Sep 17 00:00:00 2001 From: Xiaoxia Date: Thu, 2 Oct 2025 03:29:16 +0800 Subject: [PATCH] Update README (#1251) * Upgrade to the latest ml307 component * update README --- .clangd | 2 - README.md | 35 +++-- README_en.md | 41 ++++-- README_ja.md | 37 +++-- main/boards/README.md => docs/custom-board.md | 138 +++++++++++++++++- main/boards/echoear/README.md | 42 +++--- main/boards/echoear/config.json | 2 - main/boards/esp-box-3/README.md | 132 +++++++++++++++++ main/boards/esp-box-3/config.json | 2 - main/boards/esp-hi/config.json | 1 - main/boards/jiuchuan-s3/README.md | 5 +- main/boards/lichuang-dev/config.json | 3 +- main/idf_component.yml | 2 +- 13 files changed, 366 insertions(+), 76 deletions(-) delete mode 100644 .clangd rename main/boards/README.md => docs/custom-board.md (69%) create mode 100644 main/boards/esp-box-3/README.md diff --git a/.clangd b/.clangd deleted file mode 100644 index 437f2554..00000000 --- a/.clangd +++ /dev/null @@ -1,2 +0,0 @@ -CompileFlags: - Remove: [-f*, -m*] diff --git a/README.md b/README.md index fcb7519d..9026ec9f 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,24 @@ -# An MCP-based Chatbot | 一个基于 MCP 的聊天机器人 +# An MCP-based Chatbot （中文 | [English](README_en.md) | [日本語](README_ja.md)） -## 视频 +## 介绍 👉 [人类：给 AI 装摄像头 vs AI：当场发现主人三天没洗头【bilibili】](https://www.bilibili.com/video/BV1bpjgzKEhd/) 👉 [手工打造你的 AI 女友，新手入门教程【bilibili】](https://www.bilibili.com/video/BV1XnmFYLEJN/) -## 介绍 - -这是一个由虾哥开源的 ESP32 项目，以 MIT 许可证发布，允许任何人免费使用，或用于商业用途。 - -我们希望通过这个项目，能够帮助大家了解 AI 硬件开发，将当下飞速发展的大语言模型应用到实际的硬件设备中。 - -如果你有任何想法或建议，请随时提出 Issues 或加入 QQ 群：1011329060 - -### 基于 MCP 控制万物 - 小智 AI 聊天机器人作为一个语音交互入口，利用 Qwen / DeepSeek 等大模型的 AI 能力，通过 MCP 协议实现多端控制。 -![通过MCP控制万物](docs/mcp-based-graph.jpg) +通过MCP控制万物 + +### 版本说明 + +当前 v2 版本与 v1 版本分区表不兼容，所以无法从 v1 版本通过 OTA 升级到 v2 版本。分区表说明参见 [partitions/v2/README.md](partitions/v2/README.md)。 + +使用 v1 版本的所有硬件，可以通过手动烧录固件来升级到 v2 版本。 + +v1 的稳定版本为 1.9.2，可以通过 `git checkout v1` 来切换到 v1 版本，该分支会持续维护到 2026 年 2 月。 ### 已实现功能 @@ -36,6 +34,7 @@ - 支持 ESP32-C3、ESP32-S3、ESP32-P4 芯片平台 - 通过设备端 MCP 实现设备控制（音量、灯光、电机、GPIO 等） - 通过云端 MCP 扩展大模型能力（智能家居控制、PC桌面操作、知识搜索、邮件收发等） +- 自定义唤醒词、字体、表情与聊天背景，支持网页端在线修改 ([自定义Assets生成器](https://github.com/78/xiaozhi-assets-generator)) ## 硬件 @@ -122,7 +121,7 @@ ### 开发者文档 -- [自定义开发板指南](main/boards/README.md) - 学习如何为小智 AI 创建自定义开发板 +- [自定义开发板指南](docs/custom-board.md) - 学习如何为小智 AI 创建自定义开发板 - [MCP 协议物联网控制用法说明](docs/mcp-usage.md) - 了解如何通过 MCP 协议控制物联网设备 - [MCP 协议交互流程](docs/mcp-protocol.md) - 设备端 MCP 协议的实现方式 - [MQTT + UDP 混合通信协议文档](docs/mqtt-udp.md) @@ -150,6 +149,14 @@ - [78/xiaozhi-sf32](https://github.com/78/xiaozhi-sf32) 思澈科技的蓝牙芯片固件 - [QuecPython/solution-xiaozhiAI](https://github.com/QuecPython/solution-xiaozhiAI) 移远提供的 QuecPython 固件 +## 关于项目 + +这是一个由虾哥开源的 ESP32 项目，以 MIT 许可证发布，允许任何人免费使用，修改或用于商业用途。 + +我们希望通过这个项目，能够帮助大家了解 AI 硬件开发，将当下飞速发展的大语言模型应用到实际的硬件设备中。 + +如果你有任何想法或建议，请随时提出 Issues 或加入 QQ 群：1011329060 + ## Star History diff --git a/README_en.md b/README_en.md index f6a6a490..d3ad0f05 100644 --- a/README_en.md +++ b/README_en.md @@ -2,25 +2,23 @@ (English | [中文](README.md) | [日本語](README_ja.md)) -## Video +## 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/) -## Introduction - -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 - -### Control Everything with MCP - 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](docs/mcp-based-graph.jpg) +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 @@ -36,6 +34,7 @@ As a voice interaction entry, the XiaoZhi AI chatbot leverages the AI capabiliti - 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 @@ -122,9 +121,10 @@ The firmware connects to the official [xiaozhi.me](https://xiaozhi.me) server by ### Developer Documentation -- [Custom Board Guide](main/boards/README.md) - Learn how to create custom boards for XiaoZhi AI +- [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 @@ -145,6 +145,21 @@ 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 diff --git a/README_ja.md b/README_ja.md index b5a2b650..c7dd029e 100644 --- a/README_ja.md +++ b/README_ja.md @@ -2,25 +2,23 @@ （日本語 | [中文](README.md) | [English](README_en.md)） -## 動画 +## はじめに 👉 [人間：AIにカメラを装着 vs AI：その場で飼い主が3日間髪を洗っていないことを発見【bilibili】](https://www.bilibili.com/video/BV1bpjgzKEhd/) 👉 [手作りでAIガールフレンドを作る、初心者入門チュートリアル【bilibili】](https://www.bilibili.com/video/BV1XnmFYLEJN/) -## イントロダクション - -これはエビ兄さんがオープンソースで公開しているESP32プロジェクトで、MITライセンスのもと、誰でも無料で、商用利用も可能です。 - -このプロジェクトを通じて、AIハードウェア開発を理解し、急速に進化する大規模言語モデルを実際のハードウェアデバイスに応用できるようになることを目指しています。 - -ご意見やご提案があれば、いつでもIssueを提出するか、QQグループ：1011329060 にご参加ください。 - -### MCPであらゆるものを制御 - シャオジーAIチャットボットは音声インタラクションの入口として、Qwen / DeepSeekなどの大規模モデルのAI能力を活用し、MCPプロトコルを通じてマルチエンド制御を実現します。 -![MCPであらゆるものを制御](docs/mcp-based-graph.jpg) +MCPであらゆるものを制御 + +## バージョンノート + +現在のv2バージョンはv1パーティションテーブルと互換性がないため、v1からv2へOTAでアップグレードすることはできません。パーティションテーブルの詳細については、[partitions/v2/README.md](partitions/v2/README.md)をご参照ください。 + +v1を実行しているすべてのハードウェアは、ファームウェアを手動で書き込むことでv2にアップグレードできます。 + +v1の安定版は1.9.2です。`git checkout v1`でv1に切り替えることができます。v1ブランチは2026年2月まで継続的にメンテナンスされます。 ### 実装済み機能 @@ -36,6 +34,7 @@ - ESP32-C3、ESP32-S3、ESP32-P4チッププラットフォーム対応 - デバイス側MCPによるデバイス制御（音量・明るさ調整、アクション制御など） - クラウド側MCPで大規模モデル能力を拡張（スマートホーム制御、PCデスクトップ操作、知識検索、メール送受信など） +- カスタマイズ可能なウェイクワード、フォント、絵文字、チャット背景、オンラインWeb編集に対応 ([カスタムアセットジェネレーター](https://github.com/78/xiaozhi-assets-generator)) ## ハードウェア @@ -122,9 +121,10 @@ Feishuドキュメントチュートリアルをご覧ください： ### 開発者ドキュメント -- [カスタム開発ボードガイド](main/boards/README.md) - シャオジーAI用のカスタム開発ボード作成方法 +- [カスタム開発ボードガイド](docs/custom-board.md) - シャオジーAI用のカスタム開発ボード作成方法 - [MCPプロトコルIoT制御使用法](docs/mcp-usage.md) - MCPプロトコルでIoTデバイスを制御する方法 - [MCPプロトコルインタラクションフロー](docs/mcp-protocol.md) - デバイス側MCPプロトコルの実装方法 +- [MQTT + UDP ハイブリッド通信プロトコルドキュメント](docs/mqtt-udp.md) - [詳細なWebSocket通信プロトコルドキュメント](docs/websocket.md) ## 大規模モデル設定 @@ -145,6 +145,17 @@ Feishuドキュメントチュートリアルをご覧ください： - [huangjunsen0406/py-xiaozhi](https://github.com/huangjunsen0406/py-xiaozhi) Pythonクライアント - [TOM88812/xiaozhi-android-client](https://github.com/TOM88812/xiaozhi-android-client) Androidクライアント +- [100askTeam/xiaozhi-linux](http://github.com/100askTeam/xiaozhi-linux) 百問科技提供のLinuxクライアント +- [78/xiaozhi-sf32](https://github.com/78/xiaozhi-sf32) 思澈科技のBluetoothチップファームウェア +- [QuecPython/solution-xiaozhiAI](https://github.com/QuecPython/solution-xiaozhiAI) 移遠提供のQuecPythonファームウェア + +## プロジェクトについて + +これはエビ兄さんがオープンソースで公開しているESP32プロジェクトで、MITライセンスのもと、誰でも無料で、商用利用も可能です。 + +このプロジェクトを通じて、AIハードウェア開発を理解し、急速に進化する大規模言語モデルを実際のハードウェアデバイスに応用できるようになることを目指しています。 + +ご意見やご提案があれば、いつでもIssueを提出するか、QQグループ：1011329060 にご参加ください。 ## スター履歴 diff --git a/main/boards/README.md b/docs/custom-board.md similarity index 69% rename from main/boards/README.md rename to docs/custom-board.md index f5ba9bee..6349b83d 100644 --- a/main/boards/README.md +++ b/docs/custom-board.md @@ -21,7 +21,7 @@ ### 1. 创建新的开发板目录 -首先在`boards/`目录下创建一个新的目录，例如`my-custom-board/`： +首先在`boards/`目录下创建一个新的目录，命名方式应使用 `[品牌名]-[开发板类型]` 的形式，例如 `m5stack-tab5`： ```bash mkdir main/boards/my-custom-board @@ -87,17 +87,18 @@ mkdir main/boards/my-custom-board #### config.json -在`config.json`中定义编译配置: +在`config.json`中定义编译配置，这个文件用于 `scripts/release.py` 脚本自动化编译： ```json { - "target": "esp32s3", // 目标芯片型号: esp32, esp32s3, esp32c3等 + "target": "esp32s3", // 目标芯片型号: esp32, esp32s3, esp32c3, esp32c6, esp32p4等 "builds": [ { - "name": "my-custom-board", // 开发板名称 + "name": "my-custom-board", // 开发板名称，用于生成固件包 "sdkconfig_append": [ - // 额外需要的编译配置 + // 特别 Flash 大小配置 "CONFIG_ESPTOOLPY_FLASHSIZE_8MB=y", + // 特别分区表配置 "CONFIG_PARTITION_TABLE_CUSTOM_FILENAME=\"partitions/v2/8m.csv\"" ] } @@ -105,6 +106,32 @@ mkdir main/boards/my-custom-board } ``` +**配置项说明：** +- `target`: 目标芯片型号，必须与硬件匹配 +- `name`: 编译输出的固件包名称，建议与目录名一致 +- `sdkconfig_append`: 额外的 sdkconfig 配置项数组，会追加到默认配置中 + +**常用的 sdkconfig_append 配置：** +```json +// Flash 大小 +"CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y" // 4MB Flash +"CONFIG_ESPTOOLPY_FLASHSIZE_8MB=y" // 8MB Flash +"CONFIG_ESPTOOLPY_FLASHSIZE_16MB=y" // 16MB Flash + +// 分区表 +"CONFIG_PARTITION_TABLE_CUSTOM_FILENAME=\"partitions/v2/4m.csv\"" // 4MB 分区表 +"CONFIG_PARTITION_TABLE_CUSTOM_FILENAME=\"partitions/v2/8m.csv\"" // 8MB 分区表 +"CONFIG_PARTITION_TABLE_CUSTOM_FILENAME=\"partitions/v2/16m.csv\"" // 16MB 分区表 + +// 语言配置 +"CONFIG_LANGUAGE_EN_US=y" // 英语 +"CONFIG_LANGUAGE_ZH_CN=y" // 简体中文 + +// 唤醒词配置 +"CONFIG_USE_DEVICE_AEC=y" // 启用设备端 AEC +"CONFIG_WAKE_WORD_DISABLED=y" // 禁用唤醒词 +``` + ### 3. 编写板级初始化代码 创建一个`my_custom_board.cc`文件，实现开发板的所有初始化逻辑。 @@ -260,7 +287,106 @@ public: DECLARE_BOARD(MyCustomBoard); ``` -### 4. 创建README.md +### 4. 添加构建系统配置 + +#### 在 Kconfig.projbuild 中添加开发板选项 + +打开 `main/Kconfig.projbuild` 文件，在 `choice BOARD_TYPE` 部分添加新的开发板配置项： + +```kconfig +choice BOARD_TYPE + prompt "Board Type" + default BOARD_TYPE_BREAD_COMPACT_WIFI + help + Board type. 开发板类型 + + # ... 其他开发板选项 ... + + config BOARD_TYPE_MY_CUSTOM_BOARD + bool "My Custom Board (我的自定义开发板)" + depends on IDF_TARGET_ESP32S3 # 根据你的目标芯片修改 +endchoice +``` + +**注意事项：** +- `BOARD_TYPE_MY_CUSTOM_BOARD` 是配置项名称，需要全大写，使用下划线分隔 +- `depends on` 指定了目标芯片类型（如 `IDF_TARGET_ESP32S3`、`IDF_TARGET_ESP32C3` 等） +- 描述文字可以使用中英文 + +#### 在 CMakeLists.txt 中添加开发板配置 + +打开 `main/CMakeLists.txt` 文件，在开发板类型判断部分添加新的配置： + +```cmake +# 在 elseif 链中添加你的开发板配置 +elseif(CONFIG_BOARD_TYPE_MY_CUSTOM_BOARD) + set(BOARD_TYPE "my-custom-board") # 与目录名一致 + set(BUILTIN_TEXT_FONT font_puhui_basic_20_4) # 根据屏幕大小选择合适的字体 + set(BUILTIN_ICON_FONT font_awesome_20_4) + set(DEFAULT_EMOJI_COLLECTION twemoji_64) # 可选，如果需要表情显示 +endif() +``` + +**字体和表情配置说明：** + +根据屏幕分辨率选择合适的字体大小： +- 小屏幕（128x64 OLED）：`font_puhui_basic_14_1` / `font_awesome_14_1` +- 中小屏幕（240x240）：`font_puhui_basic_16_4` / `font_awesome_16_4` +- 中等屏幕（240x320）：`font_puhui_basic_20_4` / `font_awesome_20_4` +- 大屏幕（480x320+）：`font_puhui_basic_30_4` / `font_awesome_30_4` + +表情集合选项： +- `twemoji_32` - 32x32 像素表情（小屏幕） +- `twemoji_64` - 64x64 像素表情（大屏幕） + +### 5. 配置和编译 + +#### 方法一：使用 idf.py 手动配置 + +1. **设置目标芯片**（首次配置或更换芯片时）： + ```bash + # 对于 ESP32-S3 + idf.py set-target esp32s3 + + # 对于 ESP32-C3 + idf.py set-target esp32c3 + + # 对于 ESP32 + idf.py set-target esp32 + ``` + +2. **清理旧配置**： + ```bash + idf.py fullclean + ``` + +3. **进入配置菜单**： + ```bash + idf.py menuconfig + ``` + + 在菜单中导航到：`Xiaozhi Assistant` -> `Board Type`，选择你的自定义开发板。 + +4. **编译和烧录**： + ```bash + idf.py build + idf.py flash monitor + ``` + +#### 方法二：使用 release.py 脚本（推荐） + +如果你的开发板目录下有 `config.json` 文件，可以使用此脚本自动完成配置和编译： + +```bash +python scripts/release.py my-custom-board +``` + +此脚本会自动： +- 读取 `config.json` 中的 `target` 配置并设置目标芯片 +- 应用 `sdkconfig_append` 中的编译选项 +- 完成编译并打包固件 + +### 6. 创建README.md 在README.md中说明开发板的特性、硬件要求、编译和烧录步骤： diff --git a/main/boards/echoear/README.md b/main/boards/echoear/README.md index 34b1128c..8a2be5fa 100644 --- a/main/boards/echoear/README.md +++ b/main/boards/echoear/README.md @@ -29,31 +29,39 @@ idf.py menuconfig ### UI风格选择 -EchoEar 支持两种不同的UI显示风格，通过修改代码中的宏定义来选择： +EchoEar 支持多种不同的 UI 显示风格，通过 menuconfig 配置选择： -#### 自定义表情显示系统 (推荐) -```c -#define USE_LVGL_DEFAULT 0 -``` +- `Xiaozhi Assistant` → `Select display style` → 选择显示风格 + +#### 可选风格 + +##### 表情动画风格 (Emote animation style) - 推荐 +- **配置选项**: `USE_EMOTE_MESSAGE_STYLE` - **特点**: 使用自定义的 `EmoteDisplay` 表情显示系统 - **功能**: 支持丰富的表情动画、眼睛动画、状态图标显示 - **适用**: 智能助手场景，提供更生动的人机交互体验 -- **类**: `anim::EmoteDisplay` + `anim::EmoteEngine` +- **类**: `emote::EmoteDisplay` -#### LVGL默认显示系统 -```c -#define USE_LVGL_DEFAULT 1 -``` -- **特点**: 使用标准LVGL图形库的显示系统 +**⚠️ 重要**: 选择此风格需要额外配置自定义资源文件： +1. `Xiaozhi Assistant` → `Flash Assets` → 选择 `Flash Custom Assets` +2. `Xiaozhi Assistant` → `Custom Assets File` → 填入资源文件地址： + ``` + https://dl.espressif.com/AE/wn9_nihaoxiaozhi_tts-font_puhui_common_20_4-echoear.bin + ``` + +##### 默认消息风格 (Enable default message style) +- **配置选项**: `USE_DEFAULT_MESSAGE_STYLE` (默认) +- **特点**: 使用标准的消息显示界面 - **功能**: 传统的文本和图标显示界面 -- **适用**: 需要标准GUI控件的应用场景 +- **适用**: 标准的对话场景 - **类**: `SpiLcdDisplay` -#### 如何修改 -1. 打开 `main/boards/echoear/EchoEar.cc` 文件 -2. 找到第29行的宏定义：`#define USE_LVGL_DEFAULT 0` -3. 修改为想要的值（0或1） -4. 重新编译项目 +##### 微信消息风格 (Enable WeChat Message Style) +- **配置选项**: `USE_WECHAT_MESSAGE_STYLE` +- **特点**: 仿微信聊天界面风格 +- **功能**: 类似微信的消息气泡显示 +- **适用**: 喜欢微信风格的用户 +- **类**: `SpiLcdDisplay` > **说明**: EchoEar 使用16MB Flash，需要使用专门的分区表配置来合理分配存储空间给应用程序、OTA更新、资源文件等。 diff --git a/main/boards/echoear/config.json b/main/boards/echoear/config.json index 0ed1a265..cbabd9ff 100644 --- a/main/boards/echoear/config.json +++ b/main/boards/echoear/config.json @@ -4,9 +4,7 @@ { "name": "echoear", "sdkconfig_append": [ - "CONFIG_PARTITION_TABLE_CUSTOM_FILENAME=\"partitions/v2/16m.csv\"", "CONFIG_USE_EMOTE_MESSAGE_STYLE=y", - "CONFIG_BOARD_TYPE_ECHOEAR=y", "CONFIG_FLASH_CUSTOM_ASSETS=y", "CONFIG_CUSTOM_ASSETS_FILE=\"https://dl.espressif.com/AE/wn9_nihaoxiaozhi_tts-font_puhui_common_20_4-echoear.bin\"" ] diff --git a/main/boards/esp-box-3/README.md b/main/boards/esp-box-3/README.md new file mode 100644 index 00000000..103f7323 --- /dev/null +++ b/main/boards/esp-box-3/README.md @@ -0,0 +1,132 @@ +# ESP-BOX-3 + +## 简介 + +
+ ESP-BOX GitHub +
+ +ESP-BOX-3 是乐鑫官方开发的 AIoT 开发套件，搭载 ESP32-S3-WROOM-1 模组，配备 2.4 英寸 320x240 ILI9341 显示屏，双麦克风阵列，支持离线语音唤醒与设备端回声消除（AEC）功能。 + +## 硬件特性 + +- **主控**: ESP32-S3-WROOM-1 (16MB Flash, 8MB PSRAM) +- **显示屏**: 2.4 英寸 IPS LCD (320x240, ILI9341) +- **音频**: ES8311 音频 Codec + ES7210 双麦 ADC +- **音频功能**: 支持设备端 AEC (回声消除) +- **按键**: Boot 按键 (单击/双击功能) +- **其他**: USB-C 供电与通信 + +## 配置、编译命令 + +**配置编译目标为 ESP32S3** + +```bash +idf.py set-target esp32s3 +``` + +**打开 menuconfig 并配置** + +```bash +idf.py menuconfig +``` + +分别配置如下选项： + +### 基本配置 +- `Xiaozhi Assistant` → `Board Type` → 选择 `ESP BOX 3` + +### UI风格选择 + +ESP-BOX-3 支持多种不同的 UI 显示风格，通过 menuconfig 配置选择： + +- `Xiaozhi Assistant` → `Select display style` → 选择显示风格 + +#### 可选风格 + +##### 表情动画风格 (Emote animation style) - 推荐 +- **配置选项**: `USE_EMOTE_MESSAGE_STYLE` +- **特点**: 使用自定义的 `EmoteDisplay` 表情显示系统 +- **功能**: 支持丰富的表情动画、眼睛动画、状态图标显示 +- **适用**: 智能助手场景，提供更生动的人机交互体验 +- **类**: `emote::EmoteDisplay` + +**⚠️ 重要**: 选择此风格需要额外配置自定义资源文件： +1. `Xiaozhi Assistant` → `Flash Assets` → 选择 `Flash Custom Assets` +2. `Xiaozhi Assistant` → `Custom Assets File` → 填入资源文件地址： + ``` + https://dl.espressif.com/AE/wn9_nihaoxiaozhi_tts-font_puhui_common_20_4-esp-box-3.bin + ``` + +##### 默认消息风格 (Enable default message style) +- **配置选项**: `USE_DEFAULT_MESSAGE_STYLE` (默认) +- **特点**: 使用标准的消息显示界面 +- **功能**: 传统的文本和图标显示界面 +- **适用**: 标准的对话场景 +- **类**: `SpiLcdDisplay` + +##### 微信消息风格 (Enable WeChat Message Style) +- **配置选项**: `USE_WECHAT_MESSAGE_STYLE` +- **特点**: 仿微信聊天界面风格 +- **功能**: 类似微信的消息气泡显示 +- **适用**: 喜欢微信风格的用户 +- **类**: `SpiLcdDisplay` + +### 音频功能配置 + +#### 设备端回声消除 (AEC) +- `Xiaozhi Assistant` → `Enable Device-Side AEC` → 启用 + +ESP-BOX-3 硬件支持设备端 AEC 功能，可有效消除扬声器播放声音对麦克风的干扰，提升语音识别准确率。 + +**运行时切换**: 双击 Boot 按键可在运行时开启/关闭 AEC 功能。 + +> **说明**: 设备端 AEC 需要干净的扬声器输出参考路径和良好的麦克风与扬声器物理隔离才能正常工作。ESP-BOX-3 硬件已做优化设计。 + +### 唤醒词配置 + +ESP-BOX-3 支持多种唤醒词实现方式： + +- `Xiaozhi Assistant` → `Wake Word Implementation Type` → 选择唤醒词类型 + +推荐选择： +- **Wakenet model with AFE** (`USE_AFE_WAKE_WORD`) - 支持 AEC 的唤醒词检测 + +按 `S` 保存，按 `Q` 退出。 + +**编译** + +```bash +idf.py build +``` + +**烧录** + +将 ESP-BOX-3 连接至电脑，并运行： + +```bash +idf.py flash +``` + +## 按键说明 + +### Boot 按键功能 + +#### 单击 +- **配网状态**: 进入 WiFi 配置模式 +- **空闲状态**: 开始对话 +- **对话中**: 打断或停止当前对话 + +#### 双击 (需启用设备端 AEC) +- **空闲状态**: 切换 AEC 开启/关闭 + +## 常见问题 + +### 1. 为什么需要设备端 AEC？ +设备端 AEC 可以在本地实时消除扬声器播放声音对麦克风的干扰，在播放音乐或 TTS 回复时仍能准确识别语音指令。 + +### 2. 表情动画风格无法显示？ +请确保已经配置了正确的自定义资源文件地址，并且设备能够访问该 URL 下载资源。 + +### 3. 如何恢复出厂设置？ +长按 Boot 按键 3 秒以上，设备会清除所有配置并重启。 diff --git a/main/boards/esp-box-3/config.json b/main/boards/esp-box-3/config.json index 5c1c53c8..518936d8 100644 --- a/main/boards/esp-box-3/config.json +++ b/main/boards/esp-box-3/config.json @@ -5,9 +5,7 @@ "name": "esp-box-3", "sdkconfig_append": [ "CONFIG_USE_DEVICE_AEC=y", - "CONFIG_PARTITION_TABLE_CUSTOM_FILENAME=\"partitions/v2/16m.csv\"", "CONFIG_USE_EMOTE_MESSAGE_STYLE=y", - "CONFIG_BOARD_TYPE_ESP_BOX_3=y", "CONFIG_FLASH_CUSTOM_ASSETS=y", "CONFIG_CUSTOM_ASSETS_FILE=\"https://dl.espressif.com/AE/wn9_nihaoxiaozhi_tts-font_puhui_common_20_4-esp-box-3.bin\"" ] diff --git a/main/boards/esp-hi/config.json b/main/boards/esp-hi/config.json index 3770f0b9..e136eafe 100644 --- a/main/boards/esp-hi/config.json +++ b/main/boards/esp-hi/config.json @@ -7,7 +7,6 @@ "CONFIG_IDF_TARGET=\"esp32c3\"", "CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y", "CONFIG_PARTITION_TABLE_CUSTOM_FILENAME=\"partitions/v2/4m.csv\"", - "CONFIG_BOARD_TYPE_ESP_HI=y", "CONFIG_ESP_WIFI_STATIC_RX_BUFFER_NUM=3", "CONFIG_ESP_WIFI_DYNAMIC_RX_BUFFER_NUM=4", "CONFIG_ESP_WIFI_AMPDU_TX_ENABLED=n", diff --git a/main/boards/jiuchuan-s3/README.md b/main/boards/jiuchuan-s3/README.md index 2b2d7553..1675ebf1 100644 --- a/main/boards/jiuchuan-s3/README.md +++ b/main/boards/jiuchuan-s3/README.md @@ -13,9 +13,8 @@ 4. 点击 VSCode 右下角提示，生成 [compile_commands.json] 文件； 5. 设置目标设备为 `[esp32s3] -> [JTAG]`； 6. 打开 **SDK Configuration Editor**； -7. 配置自定义分区表路径为：`partitions/v2/16m.csv`； -8. 设置 **Board Type** 为 **九川科技**； -9. 保存配置并开始编译。 +7. 设置 **Board Type** 为 **九川科技**； +8. 保存配置并开始编译。 ## 🔌 烧录步骤 1. 使用数据线连接电脑与音箱； diff --git a/main/boards/lichuang-dev/config.json b/main/boards/lichuang-dev/config.json index 32eedc4e..e2a7090e 100644 --- a/main/boards/lichuang-dev/config.json +++ b/main/boards/lichuang-dev/config.json @@ -4,8 +4,7 @@ { "name": "lichuang-dev", "sdkconfig_append": [ - "CONFIG_USE_DEVICE_AEC=y", - "CONFIG_PARTITION_TABLE_CUSTOM_FILENAME=\"partitions/v2/16m.csv\"" + "CONFIG_USE_DEVICE_AEC=y" ] } ] diff --git a/main/idf_component.yml b/main/idf_component.yml index 166dc543..615c7ef6 100644 --- a/main/idf_component.yml +++ b/main/idf_component.yml @@ -19,7 +19,7 @@ dependencies: 78/esp_lcd_nv3023: ~1.0.0 78/esp-wifi-connect: ~2.5.2 78/esp-opus-encoder: ~2.4.1 - 78/esp-ml307: ~3.3.5 + 78/esp-ml307: ~3.3.6 78/xiaozhi-fonts: ~1.5.3 espressif/led_strip: ~3.0.1 espressif/esp_codec_dev: ~1.4.0