更新开发者文档（自定义开发板、IoT设备）

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语音控制物联网设备
+
 
 ## 智能体配置
 

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.

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) コンソールで設定できます。

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

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<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. **不产生歧义的方法描述**：为每个方法提供明确的自然语言描述，帮助大模型更准确地理解和调用

main/iot/sample_interface.json

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