Update README (#1251)

* Upgrade to the latest ml307 component

* update README
This commit is contained in:
Xiaoxia
2025-10-02 03:29:16 +08:00
committed by GitHub
parent 68b0e225a2
commit 911fee2d85
13 changed files with 366 additions and 76 deletions

View File

@ -1,326 +0,0 @@
# 自定义开发板指南
本指南介绍如何为小智AI语音聊天机器人项目定制一个新的开发板初始化程序。小智AI支持70多种ESP32系列开发板每个开发板的初始化代码都放在对应的目录下。
## 重要提示
> **警告**: 对于自定义开发板当IO配置与原有开发板不同时切勿直接覆盖原有开发板的配置编译固件。必须创建新的开发板类型或者通过config.json文件中的builds配置不同的name和sdkconfig宏定义来区分。使用 `python scripts/release.py [开发板目录名字]` 来编译打包固件。
>
> 如果直接覆盖原有配置将来OTA升级时您的自定义固件可能会被原有开发板的标准固件覆盖导致您的设备无法正常工作。每个开发板有唯一的标识和对应的固件升级通道保持开发板标识的唯一性非常重要。
## 目录结构
每个开发板的目录结构通常包含以下文件:
- `xxx_board.cc` - 主要的板级初始化代码,实现了板子相关的初始化和功能
- `config.h` - 板级配置文件,定义了硬件管脚映射和其他配置项
- `config.json` - 编译配置,指定目标芯片和特殊的编译选项
- `README.md` - 开发板相关的说明文档
## 定制开发板步骤
### 1. 创建新的开发板目录
首先在`boards/`目录下创建一个新的目录,例如`my-custom-board/`
```bash
mkdir main/boards/my-custom-board
```
### 2. 创建配置文件
#### config.h
`config.h`中定义所有的硬件配置,包括:
- 音频采样率和I2S引脚配置
- 音频编解码芯片地址和I2C引脚配置
- 按钮和LED引脚配置
- 显示屏参数和引脚配置
参考示例来自lichuang-c3-dev
```c
#ifndef _BOARD_CONFIG_H_
#define _BOARD_CONFIG_H_
#include <driver/gpio.h>
// 音频配置
#define AUDIO_INPUT_SAMPLE_RATE 24000
#define AUDIO_OUTPUT_SAMPLE_RATE 24000
#define AUDIO_I2S_GPIO_MCLK GPIO_NUM_10
#define AUDIO_I2S_GPIO_WS GPIO_NUM_12
#define AUDIO_I2S_GPIO_BCLK GPIO_NUM_8
#define AUDIO_I2S_GPIO_DIN GPIO_NUM_7
#define AUDIO_I2S_GPIO_DOUT GPIO_NUM_11
#define AUDIO_CODEC_PA_PIN GPIO_NUM_13
#define AUDIO_CODEC_I2C_SDA_PIN GPIO_NUM_0
#define AUDIO_CODEC_I2C_SCL_PIN GPIO_NUM_1
#define AUDIO_CODEC_ES8311_ADDR ES8311_CODEC_DEFAULT_ADDR
// 按钮配置
#define BOOT_BUTTON_GPIO GPIO_NUM_9
// 显示屏配置
#define DISPLAY_SPI_SCK_PIN GPIO_NUM_3
#define DISPLAY_SPI_MOSI_PIN GPIO_NUM_5
#define DISPLAY_DC_PIN GPIO_NUM_6
#define DISPLAY_SPI_CS_PIN GPIO_NUM_4
#define DISPLAY_WIDTH 320
#define DISPLAY_HEIGHT 240
#define DISPLAY_MIRROR_X true
#define DISPLAY_MIRROR_Y false
#define DISPLAY_SWAP_XY true
#define DISPLAY_OFFSET_X 0
#define DISPLAY_OFFSET_Y 0
#define DISPLAY_BACKLIGHT_PIN GPIO_NUM_2
#define DISPLAY_BACKLIGHT_OUTPUT_INVERT true
#endif // _BOARD_CONFIG_H_
```
#### config.json
`config.json`中定义编译配置:
```json
{
"target": "esp32s3", // 目标芯片型号: esp32, esp32s3, esp32c3等
"builds": [
{
"name": "my-custom-board", // 开发板名称
"sdkconfig_append": [
// 额外需要的编译配置
"CONFIG_ESPTOOLPY_FLASHSIZE_8MB=y",
"CONFIG_PARTITION_TABLE_CUSTOM_FILENAME=\"partitions/v2/8m.csv\""
]
}
]
}
```
### 3. 编写板级初始化代码
创建一个`my_custom_board.cc`文件,实现开发板的所有初始化逻辑。
一个基本的开发板类定义包含以下几个部分:
1. **类定义**:继承自`WifiBoard``Ml307Board`
2. **初始化函数**包括I2C、显示屏、按钮、IoT等组件的初始化
3. **虚函数重写**:如`GetAudioCodec()``GetDisplay()``GetBacklight()`
4. **注册开发板**:使用`DECLARE_BOARD`宏注册开发板
```cpp
#include "wifi_board.h"
#include "codecs/es8311_audio_codec.h"
#include "display/lcd_display.h"
#include "application.h"
#include "button.h"
#include "config.h"
#include "mcp_server.h"
#include <esp_log.h>
#include <driver/i2c_master.h>
#include <driver/spi_common.h>
#define TAG "MyCustomBoard"
class MyCustomBoard : public WifiBoard {
private:
i2c_master_bus_handle_t codec_i2c_bus_;
Button boot_button_;
LcdDisplay* display_;
// I2C初始化
void InitializeI2c() {
i2c_master_bus_config_t i2c_bus_cfg = {
.i2c_port = I2C_NUM_0,
.sda_io_num = AUDIO_CODEC_I2C_SDA_PIN,
.scl_io_num = AUDIO_CODEC_I2C_SCL_PIN,
.clk_source = I2C_CLK_SRC_DEFAULT,
.glitch_ignore_cnt = 7,
.intr_priority = 0,
.trans_queue_depth = 0,
.flags = {
.enable_internal_pullup = 1,
},
};
ESP_ERROR_CHECK(i2c_new_master_bus(&i2c_bus_cfg, &codec_i2c_bus_));
}
// SPI初始化用于显示屏
void InitializeSpi() {
spi_bus_config_t buscfg = {};
buscfg.mosi_io_num = DISPLAY_SPI_MOSI_PIN;
buscfg.miso_io_num = GPIO_NUM_NC;
buscfg.sclk_io_num = DISPLAY_SPI_SCK_PIN;
buscfg.quadwp_io_num = GPIO_NUM_NC;
buscfg.quadhd_io_num = GPIO_NUM_NC;
buscfg.max_transfer_sz = DISPLAY_WIDTH * DISPLAY_HEIGHT * sizeof(uint16_t);
ESP_ERROR_CHECK(spi_bus_initialize(SPI2_HOST, &buscfg, SPI_DMA_CH_AUTO));
}
// 按钮初始化
void InitializeButtons() {
boot_button_.OnClick([this]() {
auto& app = Application::GetInstance();
if (app.GetDeviceState() == kDeviceStateStarting && !WifiStation::GetInstance().IsConnected()) {
ResetWifiConfiguration();
}
app.ToggleChatState();
});
}
// 显示屏初始化以ST7789为例
void InitializeDisplay() {
esp_lcd_panel_io_handle_t panel_io = nullptr;
esp_lcd_panel_handle_t panel = nullptr;
esp_lcd_panel_io_spi_config_t io_config = {};
io_config.cs_gpio_num = DISPLAY_SPI_CS_PIN;
io_config.dc_gpio_num = DISPLAY_DC_PIN;
io_config.spi_mode = 2;
io_config.pclk_hz = 80 * 1000 * 1000;
io_config.trans_queue_depth = 10;
io_config.lcd_cmd_bits = 8;
io_config.lcd_param_bits = 8;
ESP_ERROR_CHECK(esp_lcd_new_panel_io_spi(SPI2_HOST, &io_config, &panel_io));
esp_lcd_panel_dev_config_t panel_config = {};
panel_config.reset_gpio_num = GPIO_NUM_NC;
panel_config.rgb_ele_order = LCD_RGB_ELEMENT_ORDER_RGB;
panel_config.bits_per_pixel = 16;
ESP_ERROR_CHECK(esp_lcd_new_panel_st7789(panel_io, &panel_config, &panel));
esp_lcd_panel_reset(panel);
esp_lcd_panel_init(panel);
esp_lcd_panel_invert_color(panel, true);
esp_lcd_panel_swap_xy(panel, DISPLAY_SWAP_XY);
esp_lcd_panel_mirror(panel, DISPLAY_MIRROR_X, DISPLAY_MIRROR_Y);
// 创建显示屏对象
display_ = new SpiLcdDisplay(panel_io, panel,
DISPLAY_WIDTH, DISPLAY_HEIGHT,
DISPLAY_OFFSET_X, DISPLAY_OFFSET_Y,
DISPLAY_MIRROR_X, DISPLAY_MIRROR_Y, DISPLAY_SWAP_XY);
}
// MCP Tools 初始化
void InitializeTools() {
// 参考 MCP 文档
}
public:
// 构造函数
MyCustomBoard() : boot_button_(BOOT_BUTTON_GPIO) {
InitializeI2c();
InitializeSpi();
InitializeDisplay();
InitializeButtons();
InitializeTools();
GetBacklight()->SetBrightness(100);
}
// 获取音频编解码器
virtual AudioCodec* GetAudioCodec() override {
static Es8311AudioCodec audio_codec(
codec_i2c_bus_,
I2C_NUM_0,
AUDIO_INPUT_SAMPLE_RATE,
AUDIO_OUTPUT_SAMPLE_RATE,
AUDIO_I2S_GPIO_MCLK,
AUDIO_I2S_GPIO_BCLK,
AUDIO_I2S_GPIO_WS,
AUDIO_I2S_GPIO_DOUT,
AUDIO_I2S_GPIO_DIN,
AUDIO_CODEC_PA_PIN,
AUDIO_CODEC_ES8311_ADDR);
return &audio_codec;
}
// 获取显示屏
virtual Display* GetDisplay() override {
return display_;
}
// 获取背光控制
virtual Backlight* GetBacklight() override {
static PwmBacklight backlight(DISPLAY_BACKLIGHT_PIN, DISPLAY_BACKLIGHT_OUTPUT_INVERT);
return &backlight;
}
};
// 注册开发板
DECLARE_BOARD(MyCustomBoard);
```
### 4. 创建README.md
在README.md中说明开发板的特性、硬件要求、编译和烧录步骤
## 常见开发板组件
### 1. 显示屏
项目支持多种显示屏驱动,包括:
- ST7789 (SPI)
- ILI9341 (SPI)
- SH8601 (QSPI)
- 等...
### 2. 音频编解码器
支持的编解码器包括:
- ES8311 (常用)
- ES7210 (麦克风阵列)
- AW88298 (功放)
- 等...
### 3. 电源管理
一些开发板使用电源管理芯片:
- AXP2101
- 其他可用的PMIC
### 4. MCP设备控制
可以添加各种MCP工具让AI能够使用:
- Speaker (扬声器控制)
- Screen (屏幕亮度调节)
- Battery (电池电量读取)
- Light (灯光控制)
- 等...
## 开发板类继承关系
- `Board` - 基础板级类
- `WifiBoard` - Wi-Fi连接的开发板
- `Ml307Board` - 使用4G模块的开发板
- `DualNetworkBoard` - 支持Wi-Fi与4G网络切换的开发板
## 开发技巧
1. **参考相似的开发板**:如果您的新开发板与现有开发板有相似之处,可以参考现有实现
2. **分步调试**:先实现基础功能(如显示),再添加更复杂的功能(如音频)
3. **管脚映射**确保在config.h中正确配置所有管脚映射
4. **检查硬件兼容性**:确认所有芯片和驱动程序的兼容性
## 可能遇到的问题
1. **显示屏不正常**检查SPI配置、镜像设置和颜色反转设置
2. **音频无输出**检查I2S配置、PA使能引脚和编解码器地址
3. **无法连接网络**检查Wi-Fi凭据和网络配置
4. **无法与服务器通信**检查MQTT或WebSocket配置
## 参考资料
- ESP-IDF 文档: https://docs.espressif.com/projects/esp-idf/
- LVGL 文档: https://docs.lvgl.io/
- ESP-SR 文档: https://github.com/espressif/esp-sr

View File

@ -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更新、资源文件等。

View File

@ -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\""
]

View File

@ -0,0 +1,132 @@
# ESP-BOX-3
## 简介
<div align="center">
<a href="https://github.com/espressif/esp-box"><b> ESP-BOX GitHub </b></a>
</div>
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 秒以上,设备会清除所有配置并重启。

View File

@ -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\""
]

View File

@ -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",

View File

@ -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. 使用数据线连接电脑与音箱;

View File

@ -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"
]
}
]

View File

@ -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