【全网抢先】小智开发实战：从灯控到云端MQTT联动的完整指南

本文链接：https://blog.csdn.net/zhoutan001/article/details/146178338

开发环境：💻 ESP-IDF 5.4，Windows

ESP-IDF安装教程：📚 参考公众号往期教程

MQTT同款源码获取：🔑 公众号“代码随心敲”内回复：小智

小智开源代码地址：

🌐 https://github.com/wdmomoxx/xiaozhi-esp32

一、从零实现灯控设备开发 🛠️

1.1 设备逻辑开发（核心代码精讲）💡

在 D:\xiaozhi-esp32-1.4.6\main\iot\things 目录下创建 lamp.cc 文件，实现以下关键功能：

// 设备属性注册（重点）📝
properties_.AddBooleanProperty(
    "power",                    // 云端可见属性名
    "灯开关状态",               // 中文描述
    [this]() -> bool {          // 状态获取闭包
        return power_;          // 返回GPIO真实状态
    });

// 远程方法绑定（核心）🔗
methods_.AddMethod(
    "TurnOn",                   // 云端调用方法名
    "开启灯光控制",
    ParameterList(),            // 无需参数
    [this](const auto& params){
        gpio_set_level(gpio_num_, 1); // GPIO高电平触发
        power_ = true;          // 状态同步更新
    });

1.2 设备注册流程 📋

在开发板配置文件中添加设备实例
D:\xiaozhi-esp32-1.4.6\main\boards\esp32-cgc\esp32_cgc_board.cc

void InitializeIot() {
    // 现有设备列表
    thing_manager.AddThing(CreateThing("Speaker"));
    thing_manager.AddThing(CreateThing("Backlight"));

    // 新增灯具设备（关键步骤）✨
    thing_manager.AddThing(iot::CreateThing("Lamp")); 
}

注意：在 boards 目录下有许多开发板，因为我使用的芯片型号类型为 ESP32 老款芯片，所以我在 esp32-cgc 这个目录下进行代码编写。

1.3 设备描述文件配置 📄

在文件：sample_interface.json 中添加设备元数据
D:\xiaozhi-esp32-1.4.6\main\iot\sample_interface.json

{
    "name": "lamp",
    "description": "智能照明设备",
    "properties": {
        "power": {
            "type": "boolean",
            "description": "灯光开关状态（true=开启）"
        }
    },
    "methods": {
        "TurnOn": {
            "description": "执行开灯操作"
        },
        "TurnOff": {
            "description": "执行关灯操作"
        }
    }
}

二、MQTT云端接入实战 ☁️

在上一章节中，我们实现了通过 ESP32 开发板直接控制 LED 灯的本地操作（示意图1）。现在，让我们将控制距离从 “指尖到开发板” 扩展到 “云端到客厅”，通过 MQTT 协议实现真正的远程智能家居控制。

我的 MQTT 服务器是自己搭建的，部署在局域网内，各位也可以自己搭建 MQTT 服务器或者用别人的 MQTT 服务器。关于 MQTT 服务器的搭建以及 MQTT 如何使用我就不多说了，大家可以自行去搜索学习。

2.1 连接配置核心代码 🧑‍💻

这是一个关于小智 MQTT 的实战代码，提供给大家参考学习，如需要详细的代码请在公众号内回复 “小智” 领取。

namespace iot {
// 智能家居设备类
class SmartHome : public Thing {
private:
    bool livingroom_led_state = false; // 客厅灯状态
public:
    // 构造函数
    SmartHome() : Thing("SmartHome", "智慧家") {
        // 注册WiFi事件回调
        esp_event_handler_register(WIFI_EVENT, ESP_EVENT_ANY_ID, 
                                 &wifi_event_handler, NULL);
        esp_event_handler_register(IP_EVENT, IP_EVENT_STA_GOT_IP, 
                                 &wifi_event_handler, NULL);
        // 创建MQTT管理任务
        xTaskCreate(
            mqtt_task,      // 任务入口函数
            "mqtt_task",    // 任务名称
            4096,           // 堆栈大小（字节）
            NULL,           // 参数传递
            5,              // 任务优先级（中等）
            NULL            // 任务句柄
        );
        // 注册物模型属性
        properties_.AddBooleanProperty(
            "livingroom_led_state",     // 属性名
            "客厅灯状态",              // 描述
            [this]{ return livingroom_led_state; } // 状态获取回调
        );
        // 注册远程控制方法 - 开灯
        methods_.AddMethod(
            "turn_on_livingroom_led_state", // 方法名
            "打开客厅灯",                  // 描述
            ParameterList(),               // 空参数列表
            [this](const ParameterList& parameters) {
                SetLightState(1); // 调用状态设置
            });
        // 注册远程控制方法 - 关灯
        methods_.AddMethod(
            "turn_off_livingroom_led_state", 
            "关闭客厅灯",
            ParameterList(), 
            [this](const ParameterList& parameters) {
                SetLightState(0);
            });
    }
    // 灯光状态控制（带状态同步）
    void SetLightState(bool state) {
        if (livingroom_led_state != state) { // 状态变化检测
            livingroom_led_state = state;
            // 发布MQTT状态更新（QoS 0）
            mqtt_client->Publish(MQTT_TOPIC, state ? "1" : "0");
            ESP_LOGI(TAG, "灯光状态已更新: %s", state ? "ON" : "OFF");
        }
    }
};
} // namespace iot
// 向物联网框架注册设备类型
DECLARE_THING(SmartHome);

三、一键编译烧录指南 🔥

打开安装好的 ESP-IDF 5.4 PowerShell 🖥️
利用 CD 命令进入项目源码的路径 📂
根据下方的命令一条一条执行，我们就完成了从配置到编译到烧录的所有过程。

# 配置编译目标为 ESP32 🎯
idf.py set-target esp32

# 打开 menuconfig ⚙️
idf.py menuconfig

# 选择板子 🧩
Xiaozhi Assistant -> Board Type -> ESP32 CGC

# 选择屏幕类型 🖼️
Xiaozhi Assistant -> LCD Type -> "ST7735, 分辨率128*128"

# 修改 flash 大小 📏
Serial flasher config -> Flash size -> 4 MB

# 修改分区表 📊
Partition Table -> Custom partition CSV file -> partitions_4M.csv

# 编译 🔧
idf.py build flash monitor