-
- 
-
@@ -124,6 +120,11 @@
- Linux 比 Windows 更好，编译速度快，也免去驱动问题的困扰
- 使用 Google C++ 代码风格，提交代码时请确保符合规范
+### 开发者文档
+
+- [开发板定制指南](main/boards/README.md) - 学习如何为小智创建自定义开发板适配
+- [物联网控制模块](main/iot/README.md) - 了解如何通过AI语音控制物联网设备
+
## 智能体配置
diff --git a/README_en.md b/README_en.md
index ad5f80e..6c1b82e 100644
--- a/README_en.md
+++ b/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:
- XiaGe Mini C3
- Moji XiaoZhi AI Derivative Version
- CuiCan AI pendant
+- WMnologo-Xingzhi-1.54TFT
- SenseCAP Watcher
@@ -97,6 +98,9 @@ Breadboard demonstration:
+
+
+
@@ -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.
diff --git a/README_ja.md b/README_ja.md
index b190a54..bda3050 100644
--- a/README_ja.md
+++ b/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 ドキュメントチュートリアルをご覧ください：
- XiaGe Mini C3
- Moji シャオジー AI 派生版
- Cuican AI ペンダント
+- 無名科技Nologo-星智-1.54TFT
- SenseCAP Watcher
+
+
+
@@ -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.
diff --git a/README_ja.md b/README_ja.md
index b190a54..bda3050 100644
--- a/README_ja.md
+++ b/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 ドキュメントチュートリアルをご覧ください：
- XiaGe Mini C3
- Moji シャオジー AI 派生版
- Cuican AI ペンダント
+- 無名科技Nologo-星智-1.54TFT
- SenseCAP Watcher
@@ -94,6 +95,9 @@ Feishu ドキュメントチュートリアルをご覧ください：
+
+
+
@@ -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) コンソールで設定できます。
diff --git a/main/boards/README.md b/main/boards/README.md
new file mode 100644
index 0000000..3f10780
--- /dev/null
+++ b/main/boards/README.md
@@ -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
+
+// 音频配置
+#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
+#include
+#include
+
+#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
\ No newline at end of file
diff --git a/main/iot/README.md b/main/iot/README.md
new file mode 100644
index 0000000..7bbfd52
--- /dev/null
+++ b/main/iot/README.md
@@ -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(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. **不产生歧义的方法描述**：为每个方法提供明确的自然语言描述，帮助大模型更准确地理解和调用
\ No newline at end of file
diff --git a/main/iot/sample_interface.json b/main/iot/sample_interface.json
deleted file mode 100644
index 3dcd303..0000000
--- a/main/iot/sample_interface.json
+++ /dev/null
@@ -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)"
- }
- }
- }
- }
- }
-]
\ No newline at end of file
+
+
+
@@ -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) コンソールで設定できます。
diff --git a/main/boards/README.md b/main/boards/README.md
new file mode 100644
index 0000000..3f10780
--- /dev/null
+++ b/main/boards/README.md
@@ -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