2026/5/28 嵌入式开发

ESP32 实现 Matter 智能灯泡实战 2026：从 SDK 到配网全流程

625,97,629,474,631

title: “ESP32 实现 Matter 智能灯泡实战 2026：从 SDK 到配网全流程” cover: “https://res.makeronsite.com/generated/568d61cf-15fe-9fb3-a58a-0c350fb0c212_0.png?e=1779944930&token=MLG70fqTQIfVNKyKs7c6RSYIj0XOq4Kt20arRvy7:uB34GI0C9y6RsvVk89WvjLxJu4M=” date: 2026-05-28 tags: [“Matter”, “ESP32”, “ESP-IDF”, “智能家居”, “IoT”] categories: [“IoT/硬件”] description: “手把手教你用 ESP32 开发板和 Matter SDK 实现一个 Matter 协议的智能灯泡，包含完整的代码示例、配网流程和 HomeKit/Google Home 集成教程。”

昨天我们聊了 Matter 协议的全貌——它是什么、为什么重要、各大生态怎么接入。但看完协议规范不等于会写代码，对吧？

今天这期，我们直接上手：用一块 ESP32 开发板，实现一个 Matter 协议的智能灯泡。不是模拟，不是 demo 玩具，而是一个真正能被 HomeKit、Google Home、Alexa 同时控制的 Matter 设备。

环境准备

开发 Matter 设备，你需要以下工具链：

  • ESP-IDF v5.2+ — Espressif 官方 SDK，已内置 Matter 支持
  • Connected Home IP (CHIP) SDK — Matter 协议栈的核心实现
  • Linux 或 macOS 主机 — Windows 也可以但配置更麻烦
  • ESP32-C3 或 ESP32-S3 开发板 — 推荐带 RGB LED 的板子，方便调试

获取 Matter SDK

Espressif 提供了预编译的 Matter SDK 分支，不用手动拉取 CHIP 仓库：

# 克隆 Espressif 的 Matter SDK 分支
git clone --recursive https://github.com/espressif/esp-matter.git
cd esp-matter

# 安装工具链（会自动下载 ESP-IDF 和 Matter 依赖）
./install.sh

这个过程大约需要 10-20 分钟，取决于网络速度。esp-matter 已经把 CHIP SDK 作为 submodule 管理好了，省去不少麻烦。

安装完成后激活环境：

. ./export.sh

第一个 Matter 设备：On/Off 灯泡

项目结构

esp-matter 提供了一个开箱即用的 light 示例：

esp-matter/examples/light/
├── CMakeLists.txt          # 项目构建配置
├── sdkconfig.defaults      # Matter 默认配置
├── main/
│   ├── CMakeLists.txt
│   └── app_main.cpp        # 入口代码

核心代码解析

让我们看看 app_main.cpp 里的关键部分：

#include 
#include 
#include 
#include 
#include 

using namespace esp_matter;
using namespace esp_matter::attribute;
using namespace esp_matter::endpoint;

static constexpr const char *TAG = "app_main";

// 1. 初始化 Matter 协议栈
extern "C" void app_main()
{
    // 初始化驱动
    led_driver_init();
    
    // 创建 Matter 端点（Endpoint）
    // Endpoint 0 是根节点，自动创建
    // Endpoint 1 是 On/Off Light
    endpoint_t *ep = lightbulb::create(NULL, 0, 
        ENDPOINT_FLAG_NONE, NULL);
    if (!ep) {
        ESP_LOGE(TAG, "Matter create endpoint failed");
        return;
    }
    
    // 2. 配置 On/Off 集群属性
    cluster_t *onoff_cluster = on_off::create(ep, 
        CLUSTER_FLAG_SERVER, NULL);
    
    // 设置设备名称
    cluster_t *basic_cluster = cluster::get(ep, 
        chip::EndpointId(0), chip::Clusters::BasicInformation::Id);
    update(basic_cluster, basic_information::Attributes::NodeLabel::Id, 
        ESP_MATTER_CHAR_STR("Matter Lightbulb"));
    
    // 3. 启动 Matter 协议栈
    config_t matter_config = {
        .vendor_id = 0xFFF1,  // 测试厂商 ID
        .product_id = 0x8001,  // 测试产品 ID
        .device_version = 1,
        .setup_passcode = 12345678,  // 配网配对码
        .setup_discriminator = 3840,
    };
    
    controller::start(&matter_config);
    client::start();
    
    ESP_LOGI(TAG, "Matter Light started");
}

这段代码的核心逻辑只有三步：

  1. 创建端点 — 用 lightbulb::create() 创建一个 On/Off Light 端点
  2. 绑定集群 — 添加 on_off 集群（开/关控制）
  3. 启动协议栈 — 调用 controller::start() 广播 Matter 服务

硬件 LED 控制

实际项目中你需要一个 LED 驱动。这里用一个简单的 GPIO 控制：

// lightbulb_driver.h
#pragma once

#define LED_PIN GPIO_NUM_8

void led_driver_init(void)
{
    gpio_config_t io_conf = {
        .pin_bit_mask = (1ULL << LED_PIN),
        .mode = GPIO_MODE_OUTPUT,
        .pull_up_en = GPIO_PULLUP_DISABLE,
        .pull_down_en = GPIO_PULLDOWN_DISABLE,
        .intr_type = GPIO_INTR_DISABLE,
    };
    gpio_config(&io_conf);
    gpio_set_level(LED_PIN, 0);  // 默认关闭
}

// Matter 回调：当 On/Off 状态改变时调用
void app_driver_on_off_update(bool state)
{
    gpio_set_level(LED_PIN, state ? 1 : 0);
    ESP_LOGI(TAG, "Light %s", state ? "ON" : "OFF");
}

编译和烧录

# 进入 light 示例目录
cd examples/light

# 配置目标芯片（ESP32-C3 或 ESP32-S3）
idf.py set-target esp32c3

# 编译
idf.py build

# 烧录（替换 /dev/ttyUSB0 为你的串口）
idf.py -p /dev/ttyUSB0 flash monitor

烧录成功后，串口会输出类似这样的信息：

I (1234) app_main: Matter Light started
I (1345) CHIP: Matter server started
I (1456) CHIP-SV: BLE listening for commissioning

这意味着设备已经进入 配网等待模式，BLE 广播正在等待 commissioner 连接。

Matter 配网（Commissioning）

这是 Matter 设备上线的关键一步。有三种方式可以配网：

方式一：用 ESP Matter 手机 App（最简单）

Espressif 提供了官方的配网工具：

  1. 手机安装 ESP Matter Commissioning Tool（Android/iOS）
  2. 打开 App，扫描设备上的 QR 码（或手动输入配网码）
  3. App 自动通过 BLE 连接设备，发送 WiFi 凭证
  4. 设备连上 WiFi 后，Matter 服务通过 mDNS 广播
  5. 配网完成 ✅

方式二：用 chip-tool 命令行

如果你更熟悉命令行，可以用 chip-tool：

# 编译 chip-tool
cd esp-matter/connectedhomeip/connectedhomeip
./scripts/examples/gn_build_example.sh \
  examples/chip-tool/ out/chip-tool

# 通过 BLE 配网
./out/chip-tool pairing ble-wifi 0x1 \
  "你的WiFi名称" "WiFi密码" \
  12345678 3840

配网成功后，设备会分配到 Node ID（如 0x0000000000000002），之后就可以通过 IP 控制了。

方式三：HomeKit 配网

如果你的 ESP32 固件包含了 HomeKit 支持（需要在 sdkconfig 中启用 CONFIG_ESP_MATTER_HOMEKIT_ENABLE=y），你可以直接用 iPhone 的”家庭”App 配网：

  1. 打开”家庭”App → 添加配件
  2. 扫描 Matter QR 码
  3. 设备自动加入 HomeKit，无需额外桥接

控制你的 Matter 灯泡

配网完成后，你有多种方式控制它：

用 chip-tool 控制

# 开灯
./out/chip-tool onoff on 0x1 0x1

# 关灯
./out/chip-tool onoff off 0x1 0x1

# 查询状态
./out/chip-tool onoff read on-off 0x1 0x1

用 HomeKit 控制

在 iPhone”家庭”App 中，它会显示为一个普通的 HomeKit 灯泡——开关、Siri 语音、自动化全部可用。

用 Google Home 控制

Google Home 同样原生支持 Matter On/Off Light 设备，无需额外集成。

进阶：添加调光和色温支持

On/Off 灯泡只是入门。现实中的智能灯泡通常支持调光和色温。

添加 Level Control（调光）

在端点中添加 level_control 集群：

// 添加调光集群
cluster_t *level_cluster = level_control::create(ep, 
    CLUSTER_FLAG_SERVER, NULL);

// 设置默认亮度（0-254）
update(level_cluster, 
    level_control::Attributes::CurrentLevel::Id, 
    ESP_MATTER_UINT8(127));  // 约 50% 亮度

添加 Color Control（色温）

// 添加色温控制集群
cluster_t *color_cluster = color_control::create(ep, 
    CLUSTER_FLAG_SERVER, NULL);

// 设置色温范围（Mired 单位）
update(color_cluster, 
    color_control::Attributes::ColorTemperatureMireds::Id, 
    ESP_MATTER_UINT16(2700));  // 暖白光

添加这些集群后，你的设备类型需要从 ON_OFF_LIGHT 升级为 DIMMABLE_LIGHT 或 COLOR_TEMPERATURE_LIGHT，Matter 规范对每种设备类型有明确的集群要求。

量产注意事项

如果你打算把这个项目变成产品，有几个坑要提前知道：

1. Vendor ID 和 Product ID

示例代码用的 0xFFF1 是测试用的 CSA 保留 ID，不能用于商业产品。

正式版需要：

  • 向 CSA（Connectivity Standards Alliance）申请 Vendor ID
  • 年费约 $7,000（非营利组织有折扣）
  • 每个产品分配独立的 Product ID

2. DAC（设备认证证书）

Matter 设备需要 DAC（Device Attestation Certificate）才能被生态平台信任：

  • PAA（产品认证机构）— 根证书，由 CSA 签发
  • PAI（产品中间体）— 厂商中间证书
  • DAC（设备证书）— 每个设备唯一

Espressif 提供了测试用的 DAC，量产时需要自己搭建 PAI/DAC 签发流程。

3. 内存占用

Matter 协议栈在 ESP32 上大约占用：

  • Flash：~1.2MB（含协议栈和应用）
  • RAM：~150KB（运行时）

ESP32-C3（4MB Flash / 400KB RAM）是最小可用配置，推荐 ESP32-S3（8MB Flash / 512KB PSRAM）。

总结

用 ESP32 实现 Matter 设备的流程其实很直接：

  1. 搭建 esp-matter 开发环境 — 一键安装脚本
  2. 创建端点和集群 — 用官方 API 定义设备能力
  3. 编译烧录 — 标准 ESP-IDF 流程
  4. 配网上线 — BLE + WiFi 凭证注入
  5. 生态集成 — HomeKit/Google Home/Alexa 原生支持

不需要桥接器、不需要云服务中转、不需要为每个平台写适配代码——一套固件，所有生态通用。这就是 Matter 的价值。

下一篇，我们会深入 Matter 的安全机制——设备认证、DAC 证书链、以及如何在量产中管理证书。如果你对设备认证有疑问，评论区见。

推荐阅读

USB 设备开发入门：用 CH559 制作自定义 HID 设备
嵌入式开发

USB 设备开发入门：用 CH559 制作自定义 HID 设备

 CAN 总线分析仪实战：汽车诊断工具 DIY，读懂车轮上的网络
嵌入式开发

CAN 总线分析仪实战：汽车诊断工具 DIY，读懂车轮上的网络

 Git 在硬件项目中的使用：原理图/PCB 版本管理实战指南
嵌入式开发

Git 在硬件项目中的使用：原理图/PCB 版本管理实战指南