企业官网建设流程全解析

基于 ESP32 Arduino Core 的 Matter 可调光插座（Dimmable Plugin）示例实战指南

【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32

本指南以仓库中 MatterDimmablePlugin 示例 为主体，系统讲解如何在 ESP32 系列 SoC 上，使用 Arduino 环境构建一个支持 Matter 协议的可调光插头单元（power outlet with level control，即带功率等级控制的电源插座/调光器）设备。文章完整覆盖支持的芯片选型、硬件接线、Arduino IDE 编译烧录、Matter 配网（commissioning）、状态持久化、手动按键控制、继电器/调光模块接入以及 Apple Home / Amazon Alexa / Google Home 三大智能家居生态的接入步骤，并结合 MatterDimmablePlugin.ino 与 MatterDimmablePlugin 端点源码 深入讲解其底层实现原理。

读完本文，你将能够：用一块 ESP32 开发板在 30 分钟内跑通一个可被主流智能家居中枢发现与控制的 Matter 调光插座原型，理解MatterDimmablePlugin端点的完整 API 用法，并掌握状态持久化、出厂重置（decommission）与故障排查的完整套路。

示例概述：什么是 Matter Dimmable Plugin 设备

Matter（原 Project Connected Home over IP / CHIP）是由连接标准联盟推动的智能家居互联协议。本示例在 ESP32 上实现的是 Matter 标准中的dimmable plug-in unit设备类型：它既可以像普通智能插座那样做开关（on/off），又支持 0-255 共 256 级功率/亮度调节（level control），因此非常适合智能调光插座、可调功率输出、智能调光插头等场景。

示例同时展示了 Matter 的几项关键能力：

• Matter 配网（commissioning）：通过 BLE（CHIPoBLE）或直连 Wi-Fi 方式将设备加入 Matter 网络；
• 设备控制：被智能家居中枢（如 Apple HomePod、Google Nest Hub、Amazon Echo）发现和控制；
• 状态持久化：利用 Arduino 的Preferences库在断电/重启后恢复上次的开关状态与功率等级；
• 本地物理控制：通过板载 BOOT 按键手动切换开关与触发出厂重置。

对应的端点封装类MatterDimmablePlugin位于 libraries/Matter/src/MatterEndpoints/MatterDimmablePlugin.h，其完整 API 参考见 docs/en/matter/ep_dimmable_plugin.rst。

支持的芯片目标（Supported Targets）

示例官方支持以下 ESP32 系列 SoC，覆盖 Wi-Fi、Thread 与 BLE 配网三种能力的组合：

配网方式的重要注意事项

• ESP32 与 ESP32-S2 不支持 BLE 配网。这两个芯片必须把 Wi-Fi 凭据直接写入 sketch 代码，手动连接网络（即下面的“Wi-Fi credentials”配置节）。
• ESP32-C6：虽然硬件支持 Thread，但本仓库中 ESP32 Arduino Matter 库默认按Wi-Fi only预编译。若要配置为 Thread-only 运行，需要将 Arduino 作为 ESP-IDF 组件方式构建工程，并禁用 Matter Wi-Fi station 功能。
• ESP32-C5：虽然芯片本身支持 Wi-Fi 2.4 GHz 与 5 GHz，但本仓库中 ESP32 Arduino Matter 库默认按Thread only预编译。若要启用 Wi-Fi 运行，需要将 Arduino 作为 ESP-IDF 组件方式构建，禁用 Thread 网络、仅保留 Wi-Fi station。

这种“预编译能力与芯片原生能力不一致”的情况，与 Matter.h 中提供的isWiFiStationEnabled()、isThreadEnabled()、isBLECommissioningEnabled()等能力查询接口直接相关——实际生效的协议栈由库的编译配置决定，而非单纯由芯片型号决定。

功能特性与硬件需求

示例具备以下功能点：

• 基于 Matter 协议的dimmable plugin unit（可调光插座）设备实现；
• 同时支持Wi-Fi 与 Thread(*)两种连接方式（* 需将 Arduino 作为 IDF 组件编译）；
• 开关控制与功率等级控制（0-255 级）；
• 使用Preferences库实现状态持久化；
• 按键控制：切换插座开关与出厂重置；
• 通过QR 码或手动配对码进行 Matter 配网；
• 可与Apple HomeKit、Amazon Alexa、Google Home集成。

硬件上需要准备：

1. 一块符合上表支持的 ESP32 开发板；
2. 电源继电器/调光模块，或用于可视化测试的RGB LED（示例优先使用板载 RGB LED 演示）；
3. 用于手动控制的用户按键（默认使用 BOOT 按键）。

引脚配置说明

示例中的引脚定义位于 MatterDimmablePlugin.ino 头部：

#ifdef RGB_BUILTIN const uint8_t pluginPin = RGB_BUILTIN; // 使用板载 RGB LED 做可视化 #else const uint8_t pluginPin = 2; // 未定义 RGB_BUILTIN 时默认使用引脚 2 #warning "Do not forget to set the RGB LED pin" #endif const uint8_t buttonPin = BOOT_PIN; // 默认使用 BOOT 按键

• RGB LED / 继电器 / 调光引脚：若开发板定义了RGB_BUILTIN（例如 ESP32-S3、ESP32-C3 等带板载 RGB LED 的型号，见 variants/esp32s3/pins_arduino.h 中#define RGB_BUILTIN LED_BUILTIN），则优先使用它来可视化展示等级变化（亮度随 0-255 等级变化）；否则回退到普通引脚 2。生产环境应改为连接到调光模块/继电器的 PWM 能力引脚。
• 按键引脚：默认使用BOOT_PIN（即 GPIO 0 的 BOOT 按键）作为开关控制与出厂重置按键。

软件准备与配置

环境前置（Prerequisites）

1. 安装 Arduino IDE（推荐 2.0 及以上版本）；
2. 安装带 Matter 支持的 ESP32 Arduino Core（即本仓库 arduino-esp32）；
3. 需要以下 Arduino 库：
   • Matter
   • Preferences
   • Wi-Fi（仅 ESP32 与 ESP32-S2 需要）

上传 sketch 前，需要按需修改三处配置。

1. Wi-Fi 凭据（不使用 BLE 配网时必须配置——对 ESP32 / ESP32-S2 是强制的）：

const char *ssid = "your-ssid"; // 改成你的 Wi-Fi SSID const char *password = "your-password"; // 改成你的 Wi-Fi 密码

在源码中，这段配置被#if !CONFIG_ENABLE_CHIPOBLE条件编译包裹：当 Matter 库启用了 BLE 配网（CONFIG_ENABLE_CHIPOBLE）时，Wi-Fi 由 Matter 配网流程自动建立，从而节省 Flash 空间；只有不支持 BLE 配网的芯片才手动启动 Wi-Fi。

2. 继电器/调光引脚配置（不使用板载 LED 时）：

const uint8_t pluginPin = 2; // 调光控制请设为支持 PWM 的引脚

注意：示例在板载RGB_BUILTIN可用时（如 ESP32-S3、ESP32-C3）会用rgbLedWrite()把 RGB LED 亮度映射到功率等级（0-255）做可视化；无 RGB LED 的板子则回退到普通 PWM 引脚。

3. 按键引脚配置（可选）：

const uint8_t buttonPin = BOOT_PIN; // 默认 BOOT 按键（GPIO 0），可改为其他引脚

编译与烧录步骤

1. 在 Arduino IDE 中打开MatterDimmablePlugin.ino；
2. 从工具 > 开发板菜单中选择你的 ESP32 开发板；
3. 从工具 > Partition Scheme中选择"Huge APP (3MB No OTA/1MB SPIFFS)"分区方案；
4. 在工具菜单中启用"Erase All Flash Before Sketch Upload"（上传前擦除全部 Flash）；
5. 通过 USB 连接 ESP32 开发板；
6. 点击上传按钮编译并烧录。

为什么必须用 Huge APP 分区并擦除 Flash？Matter 协议栈体积较大，普通默认分区放不下编译产物。这一点在示例的 CI 配置 ci.yml 中也有印证：它通过fqbn_append: PartitionScheme=huge_app强制使用 huge_app 分区，并要求CONFIG_ESP_MATTER_ENABLE_DATA_MODEL=y启用 Matter 数据模型——这也是MatterDimmablePlugin类在 MatterDimmablePlugin.h 中整体被#ifdef CONFIG_ESP_MATTER_ENABLE_DATA_MODEL包裹的原因。首次烧录擦除全部 Flash 则可以清除可能残留的旧配网信息，避免配网异常。

预期串口输出

以115200波特率打开串口监视器。仅 ESP32 与 ESP32-S2 会打印 Wi-Fi 连接过程；其他目标芯片通过 Matter CHIPoBLE（BLE 配网通道）自动建立 IP 网络。正常输出类似：

Connecting to your-wifi-ssid ....... Wi-Fi connected IP address: 192.168.1.100 Matter Node is not commissioned yet. Initiate the device discovery in your Matter environment. Commission it to your Matter hub with the manual pairing code or QR code Manual pairing code: 34970112332 QR code URL: https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3A6FCJ142C00KA0648G00 Matter Node not commissioned yet. Waiting for commissioning. Matter Node not commissioned yet. Waiting for commissioning. ... Initial state: OFF | level: 64 Matter Node is commissioned and connected to the network. Ready for use. Plugin OnOff changed to ON Plugin Level changed to 128 User Callback :: New Plugin State = ON, Level = 128

其中Manual pairing code与QR code URL分别来自 Matter.h 中声明的Matter.getManualPairingCode()与Matter.getOnboardingQRCodeUrl()，它们是配网必需的两种方式（手动输入 11 位配对码，或用 QR 码 URL 生成二维码扫码）。User Callback行则来自示例中注册的回调setPluginState()的打印。

设备使用指南

手动按键控制

用户按键（默认 BOOT 按键）提供两种操作：

• 短按：切换插座开关（on/off）；
• 长按（超过 5 秒）：出厂重置设备（decommission，即从 Matter 网络中移除）。

从源码看，按键逻辑包含消抖处理：debounceTime = 250毫秒用于过滤抖动，decommissioningTimeout = 5000毫秒判定长按。短按释放时调用DimmablePlugin.toggle()，该调用会同步更新 Matter 属性，因此 Matter 控制器也能看到状态变化；长按时依次调用DimmablePlugin = false（关断输出）与Matter.decommission()完成配网信息清除。

状态持久化（State Persistence）

设备使用Preferences库保存最后一次的开关状态与功率等级。具体实现：

matterPref.begin("MatterPrefs", false); bool lastOnOffState = matterPref.getBool(onOffPrefKey, false); // 默认 OFF uint8_t lastLevel = matterPref.getUChar(levelPrefKey, 64); // 默认 64（约 25%） DimmablePlugin.begin(lastOnOffState, lastLevel);

断电或重启后：

• 设备恢复到最后保存的状态（ON 或 OFF）与功率等级；
• 若无历史状态，默认恢复为OFF、等级 64（25%）；
• 配网完成后 Matter 控制器会被通知恢复后的状态；
• 继电器/调光器会同步反映恢复的状态与等级。

状态写入发生在回调setPluginState()中（每次状态/等级变化都会putUChar/putBool落盘），这保证了“重启后恢复上次状态”的可靠性。值得一提的是，底层端点 MatterDimmablePlugin.cpp 还对CurrentLevel属性调用了attribute::set_deferred_persistence()，即对可能快速变化的等级属性启用延迟持久化，避免频繁写入 Flash。

继电器 / 调光模块接入

方式一：PWM 调光控制

1. 接线：调光模块 VCC → ESP32 3.3 V 或 5 V（以模块规格为准）；GND → ESP32 GND；PWM/Control → ESP32 支持 PWM 的 GPIO（即pluginPin）；
2. 修改 sketch：

const uint8_t pluginPin = 2; // 你的 PWM 调光控制引脚

3. 等级（0-255）将映射为调光模块输出功率（0% - 100%）。

方式二：继电器开关控制（仅 On/Off）

1. 接线：继电器 VCC → ESP32 3.3 V 或 5 V；GND → ESP32 GND；IN → ESP32 GPIO（即pluginPin）；
2. 修改 sketch：

const uint8_t pluginPin = 2; // 你的继电器控制引脚

3. 注意：使用继电器时，等级控制依然生效，但继电器只根据开关状态切换通断。

4. 通过 Matter App 测试继电器/调光器——设备应对 on/off 与等级变化同时做出响应。

从实现上看，输出逻辑集中在回调setPluginState()：打开时对带RGB_BUILTIN的板子调用rgbLedWrite(pluginPin, level, level, level)，否则调用analogWrite(pluginPin, level)；关闭时先pinMode(pluginPin, OUTPUT)（因为analogWrite()之后需先把 GPIO 切回数字模式）再digitalWrite(pluginPin, LOW)。

智能家居生态接入

使用支持 Matter 的中枢（如 Apple HomePod、Google Nest Hub、Amazon Echo）配网设备。

Apple Home：打开 iOS 上的“家庭”App → 点“+”→ 添加配件 → 扫描串口输出的 QR 码，或点“我没有代码或无法扫描”后输入手动配对码 → 按提示完成设置 → 设备将以可调光插座/开关形式出现在家庭 App 中，可同时控制开关状态与功率等级（0-100%）。

Amazon Alexa：打开 Alexa App → 更多 → 添加设备 → Matter → 选择“扫描 QR 码”或“手动输入代码” → 完成设置 → 可调光插座出现在 Alexa App 中，可用语音控制功率，例如 “Alexa, set outlet to 50 percent”。

Google Home：打开 Google Home App → “+”→ 设置设备 → 新设备 → 选择“Matter 设备” → 扫描 QR 码或输入手动配对码 → 按提示完成 → 可在 App 中通过滑杆或语音控制功率等级。

代码结构与源码级原理

示例由 MatterDimmablePlugin.ino 中的三个核心部分组成，其对应的端点封装类是MatterDimmablePlugin（继承自MatterEndPoint，见 MatterDimmablePlugin.h）。

setup()：初始化链路

1. 初始化硬件：按键（INPUT_PULLUP）与继电器/调光引脚（先置 LOW，保证上电默认关闭）；
2. 初始化串口（115200）；
3. 无 BLE 配网时手动连接 Wi-Fi；
4. 初始化Preferences（matterPref.begin("MatterPrefs", false)），读取上次状态；
5. 调用DimmablePlugin.begin(lastOnOffState, lastLevel)创建 Matter 端点；
6. 注册三类回调：onChange(setPluginState)、onChangeOnOff(...)、onChangeLevel(...)；
7. 最后调用Matter.begin()启动 Matter 协议栈（必须在所有端点初始化完成后）；
8. 若设备已配网（Matter.isDeviceCommissioned()），打印初始状态并调用DimmablePlugin.updateAccessory()让物理输出同步到已保存状态。

从底层实现看，begin()（见 MatterDimmablePlugin.cpp）实际调用了esp_matter的dimmable_plug_in_unit::create()创建 Matter 端点，并配置 OnOff 与 LevelControl 两个集群的初始属性。begin()的默认参数为initialState = false、level = 64，对应 README 中“默认 OFF、等级 64（25%）”的说明。

loop()：配网等待与按键处理

loop()完成三件事：

1. 检查配网状态：未配网时打印手动配对码与 QR 码 URL（Matter.getManualPairingCode()/Matter.getOnboardingQRCodeUrl()），并以 5 秒为周期打印等待提示，直到配网完成；
2. 按键消抖与短按切换：DimmablePlugin.toggle()；
3. 长按 5 秒触发Matter.decommission()出厂重置。

回调机制：从 Matter 属性变化到物理输出

示例注册了三个回调，对应 MatterDimmablePlugin.h 中定义的三种回调类型：

• setPluginState(bool state, uint8_t level)：通过onChange()注册，是核心物理输出回调——控制继电器/调光器/RGB LED 输出，并把状态写入Preferences持久化，最后返回true告知 Matter 核心本次变更处理成功；
• onChangeOnOff([](bool state){...})：开关属性变化通知（打印日志）；
• onChangeLevel([](uint8_t level){...})：等级属性变化通知（打印日志）。

底层调度逻辑在attributeChangeCB()（见 MatterDimmablePlugin.cpp）：Matter 内部事件处理器在收到控制器写入的属性值时，会按cluster_id分发到 OnOff 集群（OnOff::Attributes::OnOff）或 LevelControl 集群（LevelControl::Attributes::CurrentLevel），依次调用对应的_onChangeOnOffCB/_onChangeLevelCB与_onChangeCB，只有所有回调都返回true时，新的属性值才会被提交到内部状态（onOffState/level）。这也是为什么示例回调必须返回布尔值——它是 Matter 属性变更事务的一部分。

MatterDimmablePlugin 类 API 速览

该类对外提供的完整接口（完整参考见 docs/en/matter/ep_dimmable_plugin.rst）：

故障排查（Troubleshooting）

• 配网时设备不可见：确认 Wi-Fi 或 Thread 连接配置正确；
• 继电器/调光器无响应：检查引脚配置与接线。调光模块必须使用支持 PWM（analogWrite）的引脚；继电器模块注意供电与接线正确；
• 等级控制无效：确认引脚支持 PWM，检查analogWrite()或rgbLedWrite()（RGB LED）在板子上是否正常工作；带 RGB LED 的板子亮度应随 0-255 等级变化；
• 状态未持久化：检查Preferences库是否正确初始化、Flash 是否损坏；
• 继电器不切换：核对控制信号电平是否满足继电器模块要求（部分继电器需要 5 V，部分 3.3 V 即可）；
• 配网失败：可长按按键出厂重置；或通过 Arduino IDE 菜单工具 > Erase All Flash Before Sketch Upload启用擦除，或直接用esptool.py --port <PORT> erase_flash擦除 SoC Flash；
• 无串口输出：检查波特率（115200）与 USB 连接。

相关文档

• Matter 总览
• Matter 端点基类说明
• MatterDimmablePlugin 端点 API 参考
• 示例源码 MatterDimmablePlugin.ino

许可

本示例基于 Apache License 2.0 开源许可发布。

【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32