mirror of
https://github.com/78/xiaozhi-esp32.git
synced 2025-05-17 07:08:03 +08:00
更新开发者文档（自定义开发板、IoT设备）
This commit is contained in:
Xiaoxia
13
README.md
13
README.md
@ -2,7 +2,7 @@
|
||||
|
||||
（中文 | [English](README_en.md) | [日本語](README_ja.md)）
|
||||
|
||||
这是虾哥的第一个硬件作品。
|
||||
## 视频介绍
|
||||
|
||||
👉 [ESP32+SenseVoice+Qwen72B打造你的AI聊天伴侣！【bilibili】](https://www.bilibili.com/video/BV11msTenEH3/)
|
||||
|
||||
@ -12,7 +12,7 @@
|
||||
|
||||
## 项目目的
|
||||
|
||||
本项目是一个开源项目，以 MIT 许可证发布，允许任何人免费使用，并可以用于商业用途。
|
||||
本项目是由虾哥开源的一个开源项目，以 MIT 许可证发布，允许任何人免费使用，并可以用于商业用途。
|
||||
|
||||
我们希望通过这个项目，能够帮助更多人入门 AI 硬件开发，了解如何将当下飞速发展的大语言模型应用到实际的硬件设备中。无论你是对 AI 感兴趣的学生，还是想要探索新技术的开发者，都可以通过这个项目获得宝贵的学习经验。
|
||||
|
||||
@ -62,7 +62,6 @@
|
||||
- <a href="https://oshwhub.com/movecall/moji-xiaozhi-ai-derivative-editi" target="_blank" title="Movecall Moji ESP32S3">Moji 小智AI衍生版</a>
|
||||
- <a href="https://oshwhub.com/movecall/cuican-ai-pendant-lights-up-y" target="_blank" title="Movecall CuiCan ESP32S3">璀璨·AI吊坠</a>
|
||||
- <a href="https://github.com/WMnologo/xingzhi-ai" target="_blank" title="无名科技Nologo-星智-1.54">无名科技Nologo-星智-1.54TFT</a>
|
||||
- <a href="https://github.com/WMnologo/xingzhi-ai" target="_blank" title="无名科技Nologo-星智-0.96">无名科技Nologo-星智-0.96TFT</a>
|
||||
- <a href="https://www.seeedstudio.com/SenseCAP-Watcher-W1-A-p-5979.html" target="_blank" title="SenseCAP Watcher">SenseCAP Watcher</a>
|
||||
<div style="display: flex; justify-content: space-between;">
|
||||
<a href="docs/v1/lichuang-s3.jpg" target="_blank" title="立创·实战派 ESP32-S3 开发板">
|
||||
@ -98,9 +97,6 @@
|
||||
<a href="docs/v1/wmnologo_xingzhi_1.54.jpg" target="_blank" title="无名科技Nologo-星智-1.54">
|
||||
<img src="docs/v1/wmnologo_xingzhi_1.54.jpg" width="240" />
|
||||
</a>
|
||||
<a href="docs/v1/wmnologo_xingzhi_0.96.jpg" target="_blank" title="无名科技Nologo-星智-0.96">
|
||||
<img src="docs/v1/wmnologo_xingzhi_0.96.jpg" width="240" />
|
||||
</a>
|
||||
<a href="docs/v1/sensecap_watcher.jpg" target="_blank" title="SenseCAP Watcher">
|
||||
<img src="docs/v1/sensecap_watcher.jpg" width="240" />
|
||||
</a>
|
||||
@ -124,6 +120,11 @@
|
||||
- Linux 比 Windows 更好，编译速度快，也免去驱动问题的困扰
|
||||
- 使用 Google C++ 代码风格，提交代码时请确保符合规范
|
||||
|
||||
### 开发者文档
|
||||
|
||||
- [开发板定制指南](main/boards/README.md) - 学习如何为小智创建自定义开发板适配
|
||||
- [物联网控制模块](main/iot/README.md) - 了解如何通过AI语音控制物联网设备
|
||||
|
||||
|
||||
## 智能体配置
|
||||
|
||||
|
||||
11
README_en.md
11
README_en.md
@ -2,7 +2,7 @@
|
||||
|
||||
([中文](README.md) | English | [日本語](README_ja.md))
|
||||
|
||||
This is Terrence's first hardware project.
|
||||
## Introduction
|
||||
|
||||
👉 [Build your AI chat companion with ESP32+SenseVoice+Qwen72B!【bilibili】](https://www.bilibili.com/video/BV11msTenEH3/)
|
||||
|
||||
@ -61,6 +61,7 @@ Breadboard demonstration:
|
||||
- <a href="https://oshwhub.com/tenclass01/xmini_c3" target="_blank" title="XiaGe Mini C3">XiaGe Mini C3</a>
|
||||
- <a href="https://oshwhub.com/movecall/moji-xiaozhi-ai-derivative-editi" target="_blank" title="Movecall Moji ESP32S3">Moji XiaoZhi AI Derivative Version</a>
|
||||
- <a href="https://oshwhub.com/movecall/cuican-ai-pendant-lights-up-y" target="_blank" title="Movecall CuiCan ESP32S3">CuiCan AI pendant</a>
|
||||
- <a href="https://github.com/WMnologo/xingzhi-ai" target="_blank" title="WMnologo-Xingzhi-1.54">WMnologo-Xingzhi-1.54TFT</a>
|
||||
- <a href="https://www.seeedstudio.com/SenseCAP-Watcher-W1-A-p-5979.html" target="_blank" title="SenseCAP Watcher">SenseCAP Watcher</a>
|
||||
|
||||
<div style="display: flex; justify-content: space-between;">
|
||||
@ -97,6 +98,9 @@ Breadboard demonstration:
|
||||
<a href="docs/v1/movecall-cuican-esp32s3.jpg" target="_blank" title="CuiCan">
|
||||
<img src="docs/v1/movecall-cuican-esp32s3.jpg" width="240" />
|
||||
</a>
|
||||
<a href="docs/v1/wmnologo_xingzhi_1.54.jpg" target="_blank" title="WMnologo-Xingzhi-1.54">
|
||||
<img src="docs/v1/wmnologo_xingzhi_1.54.jpg" width="240" />
|
||||
</a>
|
||||
<a href="docs/v1/sensecap_watcher.jpg" target="_blank" title="SenseCAP Watcher">
|
||||
<img src="docs/v1/sensecap_watcher.jpg" width="240" />
|
||||
</a>
|
||||
@ -119,6 +123,11 @@ The firmware connects to the official [xiaozhi.me](https://xiaozhi.me) server by
|
||||
- Linux is preferred over Windows for faster compilation and fewer driver issues
|
||||
- Use Google C++ code style, 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
|
||||
|
||||
## AI Agent Configuration
|
||||
|
||||
If you already have a XiaoZhi AI chatbot device, you can configure it through the [xiaozhi.me](https://xiaozhi.me) console.
|
||||
|
||||
11
README_ja.md
11
README_ja.md
@ -2,7 +2,7 @@
|
||||
|
||||
([中文](README.md) | [English](README_en.md) | 日本語)
|
||||
|
||||
これは シャーガー（Terrence）の最初のハードウェア作品です。
|
||||
## プロジェクト紹介
|
||||
|
||||
👉 [ESP32+SenseVoice+Qwen72Bで AI チャット仲間を作ろう！【bilibili】](https://www.bilibili.com/video/BV11msTenEH3/)
|
||||
|
||||
@ -61,6 +61,7 @@ Feishu ドキュメントチュートリアルをご覧ください：
|
||||
- <a href="https://oshwhub.com/tenclass01/xmini_c3" target="_blank" title="XiaGe Mini C3">XiaGe Mini C3</a>
|
||||
- <a href="https://oshwhub.com/movecall/moji-xiaozhi-ai-derivative-editi" target="_blank" title="Movecall Moji ESP32S3">Moji シャオジー AI 派生版</a>
|
||||
- <a href="https://oshwhub.com/movecall/cuican-ai-pendant-lights-up-y" target="_blank" title="Movecall CuiCan ESP32S3">Cuican AI ペンダント</a>
|
||||
- <a href="https://github.com/WMnologo/xingzhi-ai" target="_blank" title="無名科技Nologo-星智-1.54">無名科技Nologo-星智-1.54TFT</a>
|
||||
- <a href="https://www.seeedstudio.com/SenseCAP-Watcher-W1-A-p-5979.html" target="_blank" title="SenseCAP Watcher">SenseCAP Watcher</a>
|
||||
|
||||
<div style="display: flex; justify-content: space-between;">
|
||||
@ -94,6 +95,9 @@ Feishu ドキュメントチュートリアルをご覧ください：
|
||||
<a href="docs/v1/movecall-cuican-esp32s3.jpg" target="_blank" title="CuiCan">
|
||||
<img src="docs/v1/movecall-cuican-esp32s3.jpg" width="240" />
|
||||
</a>
|
||||
<a href="docs/v1/wmnologo_xingzhi_1.54.jpg" target="_blank" title="無名科技Nologo-星智-1.54">
|
||||
<img src="docs/v1/wmnologo_xingzhi_1.54.jpg" width="240" />
|
||||
</a>
|
||||
<a href="docs/v1/sensecap_watcher.jpg" target="_blank" title="SenseCAP Watcher">
|
||||
<img src="docs/v1/sensecap_watcher.jpg" width="240" />
|
||||
</a>
|
||||
@ -116,6 +120,11 @@ Feishu ドキュメントチュートリアルをご覧ください：
|
||||
- Linux は Windows より好ましい（コンパイルが速く、ドライバーの問題も少ない）
|
||||
- Google C++ コードスタイルを使用、コード提出時にはコンプライアンスを確認
|
||||
|
||||
### 開発者ドキュメント
|
||||
|
||||
- [ボードカスタマイズガイド](main/boards/README.md) - シャオジー向けのカスタムボード適応を作成する方法を学ぶ
|
||||
- [IoT 制御モジュール](main/iot/README.md) - AI 音声コマンドでIoTデバイスを制御する方法を理解する
|
||||
|
||||
## AI エージェント設定
|
||||
|
||||
シャオジー AI チャットボットデバイスをお持ちの場合は、[xiaozhi.me](https://xiaozhi.me) コンソールで設定できます。
|
||||
|
||||
337
main/boards/README.md
Normal file
337
main/boards/README.md
Normal file
@ -0,0 +1,337 @@
|
||||
# 自定义开发板指南
|
||||
|
||||
本指南介绍如何为小智AI语音聊天机器人项目定制一个新的开发板初始化程序。小智AI支持50多种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_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 "audio_codecs/es8311_audio_codec.h"
|
||||
#include "display/lcd_display.h"
|
||||
#include "application.h"
|
||||
#include "button.h"
|
||||
#include "config.h"
|
||||
#include "iot/thing_manager.h"
|
||||
|
||||
#include <esp_log.h>
|
||||
#include <driver/i2c_master.h>
|
||||
#include <driver/spi_common.h>
|
||||
|
||||
#define TAG "MyCustomBoard"
|
||||
|
||||
// 声明字体
|
||||
LV_FONT_DECLARE(font_puhui_16_4);
|
||||
LV_FONT_DECLARE(font_awesome_16_4);
|
||||
|
||||
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,
|
||||
{
|
||||
.text_font = &font_puhui_16_4,
|
||||
.icon_font = &font_awesome_16_4,
|
||||
.emoji_font = font_emoji_32_init(),
|
||||
});
|
||||
}
|
||||
|
||||
// IoT设备初始化
|
||||
void InitializeIot() {
|
||||
auto& thing_manager = iot::ThingManager::GetInstance();
|
||||
thing_manager.AddThing(iot::CreateThing("Speaker"));
|
||||
thing_manager.AddThing(iot::CreateThing("Screen"));
|
||||
// 可以添加更多IoT设备
|
||||
}
|
||||
|
||||
public:
|
||||
// 构造函数
|
||||
MyCustomBoard() : boot_button_(BOOT_BUTTON_GPIO) {
|
||||
InitializeI2c();
|
||||
InitializeSpi();
|
||||
InitializeDisplay();
|
||||
InitializeButtons();
|
||||
InitializeIot();
|
||||
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. IoT设备
|
||||
|
||||
可以添加各种IoT设备，让AI能够"看到"和控制:
|
||||
- Speaker (扬声器)
|
||||
- Screen (屏幕)
|
||||
- Battery (电池)
|
||||
- Light (灯光)
|
||||
- 等...
|
||||
|
||||
## 开发板类继承关系
|
||||
|
||||
- `Board` - 基础板级类
|
||||
- `WifiBoard` - WiFi连接的开发板
|
||||
- `ML307Board` - 使用4G模块的开发板
|
||||
|
||||
## 开发技巧
|
||||
|
||||
1. **参考相似的开发板**：如果您的新开发板与现有开发板有相似之处，可以参考现有实现
|
||||
2. **分步调试**：先实现基础功能（如显示），再添加更复杂的功能（如音频）
|
||||
3. **管脚映射**：确保在config.h中正确配置所有管脚映射
|
||||
4. **检查硬件兼容性**：确认所有芯片和驱动程序的兼容性
|
||||
|
||||
## 可能遇到的问题
|
||||
|
||||
1. **显示屏不正常**：检查SPI配置、镜像设置和颜色反转设置
|
||||
2. **音频无输出**：检查I2S配置、PA使能引脚和编解码器地址
|
||||
3. **无法连接网络**：检查WiFi凭据和网络配置
|
||||
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
|
||||
209
main/iot/README.md
Normal file
209
main/iot/README.md
Normal file
@ -0,0 +1,209 @@
|
||||
# 物联网控制模块
|
||||
|
||||
本模块实现了小智AI语音聊天机器人的物联网控制功能，使用户可以通过语音指令控制接入到ESP32开发板的各种物联网设备。
|
||||
|
||||
## 工作原理
|
||||
|
||||
整个物联网控制模块的工作流程如下：
|
||||
|
||||
1. **设备注册**：在开发板初始化阶段（如在`compact_wifi_board.cc`中），各种物联网设备通过`ThingManager`注册到系统中
|
||||
2. **设备描述**：系统将设备描述信息（包括名称、属性、方法等）通过通信协议（如MQTT或WebSocket）发送给AI服务器
|
||||
3. **用户交互**：用户通过语音与小智AI对话，表达控制物联网设备的意图
|
||||
4. **命令执行**：AI服务器解析用户意图，生成控制命令，通过协议发送回ESP32，由`ThingManager`分发给对应的设备执行
|
||||
5. **状态更新**：设备执行命令后，状态变化会通过`ThingManager`收集并发送回AI服务器，保持状态同步
|
||||
|
||||
## 核心组件
|
||||
|
||||
### ThingManager
|
||||
|
||||
`ThingManager`是物联网控制模块的核心管理类，采用单例模式实现：
|
||||
|
||||
- `AddThing`：注册物联网设备
|
||||
- `GetDescriptorsJson`：获取所有设备的描述信息，用于向AI服务器报告设备能力
|
||||
- `GetStatesJson`：获取所有设备的当前状态，可以选择只返回变化的部分
|
||||
- `Invoke`：根据AI服务器下发的命令，调用对应设备的方法
|
||||
|
||||
### Thing
|
||||
|
||||
`Thing`是所有物联网设备的基类，提供了以下核心功能：
|
||||
|
||||
- 属性管理：通过`PropertyList`定义设备的可查询状态
|
||||
- 方法管理：通过`MethodList`定义设备可执行的操作
|
||||
- JSON序列化：将设备描述和状态转换为JSON格式，便于网络传输
|
||||
- 命令执行：解析和执行来自AI服务器的指令
|
||||
|
||||
## 设备设计示例
|
||||
|
||||
### 灯（Lamp）
|
||||
|
||||
灯是一个简单的物联网设备示例，通过GPIO控制LED的开关状态：
|
||||
|
||||
```cpp
|
||||
class Lamp : public Thing {
|
||||
private:
|
||||
gpio_num_t gpio_num_ = GPIO_NUM_18; // GPIO引脚
|
||||
bool power_ = false; // 灯的开关状态
|
||||
|
||||
public:
|
||||
Lamp() : Thing("Lamp", "一个测试用的灯") {
|
||||
// 初始化GPIO
|
||||
InitializeGpio();
|
||||
|
||||
// 定义属性：power（表示灯的开关状态）
|
||||
properties_.AddBooleanProperty("power", "灯是否打开", [this]() -> bool {
|
||||
return power_;
|
||||
});
|
||||
|
||||
// 定义方法：TurnOn（打开灯）
|
||||
methods_.AddMethod("TurnOn", "打开灯", ParameterList(), [this](const ParameterList& parameters) {
|
||||
power_ = true;
|
||||
gpio_set_level(gpio_num_, 1);
|
||||
});
|
||||
|
||||
// 定义方法：TurnOff（关闭灯）
|
||||
methods_.AddMethod("TurnOff", "关闭灯", ParameterList(), [this](const ParameterList& parameters) {
|
||||
power_ = false;
|
||||
gpio_set_level(gpio_num_, 0);
|
||||
});
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
用户可以通过语音指令如"小智，请打开灯"来控制灯的开关。
|
||||
|
||||
### 扬声器（Speaker）
|
||||
|
||||
扬声器控制实现了音量调节功能：
|
||||
|
||||
```cpp
|
||||
class Speaker : public Thing {
|
||||
public:
|
||||
Speaker() : Thing("Speaker", "扬声器") {
|
||||
// 定义属性：volume（当前音量值）
|
||||
properties_.AddNumberProperty("volume", "当前音量值", [this]() -> int {
|
||||
auto codec = Board::GetInstance().GetAudioCodec();
|
||||
return codec->output_volume();
|
||||
});
|
||||
|
||||
// 定义方法：SetVolume（设置音量）
|
||||
methods_.AddMethod("SetVolume", "设置音量", ParameterList({
|
||||
Parameter("volume", "0到100之间的整数", kValueTypeNumber, true)
|
||||
}), [this](const ParameterList& parameters) {
|
||||
auto codec = Board::GetInstance().GetAudioCodec();
|
||||
codec->SetOutputVolume(static_cast<uint8_t>(parameters["volume"].number()));
|
||||
});
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
用户可以通过语音指令如"小智，把音量调到50"来控制扬声器的音量。
|
||||
|
||||
## 设计自定义物联网设备
|
||||
|
||||
要设计一个新的物联网设备，需要以下步骤：
|
||||
|
||||
1. **创建设备类**：继承`Thing`基类
|
||||
2. **定义属性**：使用`properties_`添加设备的可查询状态
|
||||
3. **定义方法**：使用`methods_`添加设备可执行的操作
|
||||
4. **实现硬件控制**：在方法回调中实现对硬件的控制
|
||||
5. **注册设备**：注册设备有两种方式（见下文），并在板级初始化中添加设备实例
|
||||
|
||||
### 两种设备注册方式
|
||||
|
||||
1. **使用DECLARE_THING宏**：适合通用设备类型
|
||||
```cpp
|
||||
// 在设备实现文件末尾添加
|
||||
DECLARE_THING(MyDevice);
|
||||
|
||||
// 然后在板级初始化中
|
||||
thing_manager.AddThing(iot::CreateThing("MyDevice"));
|
||||
```
|
||||
|
||||
2. **直接创建设备实例**：适合特定于板级的设备
|
||||
```cpp
|
||||
// 在板级初始化中
|
||||
auto my_device = new iot::MyDevice();
|
||||
thing_manager.AddThing(my_device);
|
||||
```
|
||||
|
||||
### 设备实现位置建议
|
||||
|
||||
您可以根据设备的通用性选择不同的实现位置：
|
||||
|
||||
1. **通用设备**：放在`main/iot/things/`目录下，使用`DECLARE_THING`注册
|
||||
2. **板级特定设备**：直接在板级目录(如`main/boards/your_board/`)中实现，使用直接创建实例的方式注册
|
||||
|
||||
这种灵活性允许您为不同的板设计特定的设备实现，同时保持通用设备的可重用性。
|
||||
|
||||
### 属性类型
|
||||
|
||||
物联网设备支持以下属性类型：
|
||||
|
||||
- **布尔值**（`kValueTypeBoolean`）：开关状态等
|
||||
- **数值**（`kValueTypeNumber`）：温度、音量等
|
||||
- **字符串**（`kValueTypeString`）：设备名称、状态描述等
|
||||
|
||||
### 方法参数
|
||||
|
||||
设备方法可以定义参数，支持以下参数类型：
|
||||
|
||||
- **布尔值**：开关等
|
||||
- **数值**：温度、音量等
|
||||
- **字符串**：命令、模式等
|
||||
|
||||
## 使用示例
|
||||
|
||||
在板级初始化代码（如`compact_wifi_board.cc`）中注册物联网设备：
|
||||
|
||||
```cpp
|
||||
void InitializeIot() {
|
||||
auto& thing_manager = iot::ThingManager::GetInstance();
|
||||
thing_manager.AddThing(iot::CreateThing("Speaker"));
|
||||
thing_manager.AddThing(iot::CreateThing("Lamp"));
|
||||
}
|
||||
```
|
||||
|
||||
之后，用户可以通过语音指令控制这些设备，例如：
|
||||
|
||||
- "小智，打开灯"
|
||||
- "我要睡觉了，帮我关灯"
|
||||
- "音量有点太小了"
|
||||
- "把音量设置为80%"
|
||||
|
||||
AI服务器会将这些语音指令解析为对应的设备控制命令，通过协议发送给ESP32执行。
|
||||
|
||||
## 注意事项
|
||||
|
||||
### 大模型控制的随机性
|
||||
|
||||
由于语音控制由大型语言模型(LLM)处理，控制过程可能存在一定的随机性和不确定性。为了增强安全性和可靠性，请考虑以下建议：
|
||||
|
||||
1. **关键操作添加警示信息**：对于潜在危险或不可逆的操作，在方法描述中添加警示信息
|
||||
```cpp
|
||||
methods_.AddMethod("PowerOff", "关闭系统电源[警告:此操作将导致设备完全关闭，请慎重使用]",
|
||||
ParameterList(), [this](const ParameterList& parameters) {
|
||||
// 关闭电源的实现
|
||||
});
|
||||
```
|
||||
|
||||
2. **二次确认机制**：重要操作应在描述中明确要求二次确认
|
||||
```cpp
|
||||
methods_.AddMethod("ResetToFactory", "恢复出厂设置[必须要用户二次确认]",
|
||||
ParameterList(), [this](const ParameterList& parameters) {
|
||||
// 恢复出厂设置的实现
|
||||
});
|
||||
```
|
||||
|
||||
### 通信协议限制
|
||||
|
||||
当前IoT协议(1.0版本)存在以下限制：
|
||||
|
||||
1. **单向控制流**：大模型只能下发指令，无法立即获取指令执行结果
|
||||
2. **状态更新延迟**：设备状态变更需要等到下一轮对话时，通过读取property属性值才能获知
|
||||
3. **异步反馈**：如果需要操作结果反馈，必须通过设备属性的方式间接实现
|
||||
|
||||
### 最佳实践
|
||||
|
||||
1. **使用有意义的属性名称**：属性名称应清晰表达其含义，便于大模型理解和使用
|
||||
|
||||
2. **不产生歧义的方法描述**：为每个方法提供明确的自然语言描述，帮助大模型更准确地理解和调用
|
||||
@ -1,38 +0,0 @@
|
||||
[
|
||||
{
|
||||
"name": "lamp",
|
||||
"description": "A lamp",
|
||||
"properties": {
|
||||
"power": {
|
||||
"type": "boolean",
|
||||
"description": "Whether the lamp is on or off"
|
||||
}
|
||||
},
|
||||
"methods": {
|
||||
"TurnOn": {
|
||||
"description": "Turns the lamp on"
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "speaker",
|
||||
"description": "当前 AI 机器人的扬声器",
|
||||
"properties": {
|
||||
"volume": {
|
||||
"type": "number",
|
||||
"description": "当前扬声器的音量（0-100）"
|
||||
}
|
||||
},
|
||||
"methods": {
|
||||
"SetVolume": {
|
||||
"description": "设置当前扬声器的音量",
|
||||
"parameters": {
|
||||
"volume": {
|
||||
"type": "number",
|
||||
"description": "The volume of the speaker (0-100)"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
Reference in New Issue
Block a user