基于 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通过 BLECHIPoBLE或直连 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 配网三种能力的组合SoCWi-FiThreadBLE CommissioningRelay/DimmerStatusESP32✅❌❌RequiredFully supportedESP32-S2✅❌❌RequiredFully supportedESP32-S3✅❌✅RequiredFully supportedESP32-C3✅❌✅RequiredFully supportedESP32-C5❌✅✅RequiredSupported (Thread only)ESP32-C6✅❌✅RequiredFully supportedESP32-H2❌✅✅RequiredSupported (Thread only)配网方式的重要注意事项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集成。硬件上需要准备一块符合上表支持的 ESP32 开发板电源继电器/调光模块或用于可视化测试的RGB LED示例优先使用板载 RGB LED 演示用于手动控制的用户按键默认使用 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安装 Arduino IDE推荐 2.0 及以上版本安装带 Matter 支持的 ESP32 Arduino Core即本仓库 arduino-esp32需要以下 Arduino 库MatterPreferencesWi-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可改为其他引脚编译与烧录步骤在 Arduino IDE 中打开MatterDimmablePlugin.ino从工具 开发板菜单中选择你的 ESP32 开发板从工具 Partition Scheme中选择Huge APP (3MB No OTA/1MB SPIFFS)分区方案在工具菜单中启用Erase All Flash Before Sketch Upload上传前擦除全部 Flash通过 USB 连接 ESP32 开发板点击上传按钮编译并烧录。为什么必须用 Huge APP 分区并擦除 FlashMatter 协议栈体积较大普通默认分区放不下编译产物。这一点在示例的 CI 配置 ci.yml 中也有印证它通过fqbn_append: PartitionSchemehuge_app强制使用 huge_app 分区并要求CONFIG_ESP_MATTER_ENABLE_DATA_MODELy启用 Matter 数据模型——这也是MatterDimmablePlugin类在 MatterDimmablePlugin.h 中整体被#ifdef CONFIG_ESP_MATTER_ENABLE_DATA_MODEL包裹的原因。首次烧录擦除全部 Flash 则可以清除可能残留的旧配网信息避免配网异常。预期串口输出以115200波特率打开串口监视器。仅 ESP32 与 ESP32-S2 会打印 Wi-Fi 连接过程其他目标芯片通过 Matter CHIPoBLEBLE 配网通道自动建立 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?dataMT%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、等级 6425%配网完成后 Matter 控制器会被通知恢复后的状态继电器/调光器会同步反映恢复的状态与等级。状态写入发生在回调setPluginState()中每次状态/等级变化都会putUChar/putBool落盘这保证了“重启后恢复上次状态”的可靠性。值得一提的是底层端点 MatterDimmablePlugin.cpp 还对CurrentLevel属性调用了attribute::set_deferred_persistence()即对可能快速变化的等级属性启用延迟持久化避免频繁写入 Flash。继电器 / 调光模块接入方式一PWM 调光控制接线调光模块 VCC → ESP32 3.3 V 或 5 V以模块规格为准GND → ESP32 GNDPWM/Control → ESP32 支持 PWM 的 GPIO即pluginPin修改 sketchconst uint8_t pluginPin 2; // 你的 PWM 调光控制引脚等级0-255将映射为调光模块输出功率0% - 100%。方式二继电器开关控制仅 On/Off接线继电器 VCC → ESP32 3.3 V 或 5 VGND → ESP32 GNDIN → ESP32 GPIO即pluginPin修改 sketchconst uint8_t pluginPin 2; // 你的继电器控制引脚注意使用继电器时等级控制依然生效但继电器只根据开关状态切换通断。通过 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()初始化链路初始化硬件按键INPUT_PULLUP与继电器/调光引脚先置 LOW保证上电默认关闭初始化串口115200无 BLE 配网时手动连接 Wi-Fi初始化PreferencesmatterPref.begin(MatterPrefs, false)读取上次状态调用DimmablePlugin.begin(lastOnOffState, lastLevel)创建 Matter 端点注册三类回调onChange(setPluginState)、onChangeOnOff(...)、onChangeLevel(...)最后调用Matter.begin()启动 Matter 协议栈必须在所有端点初始化完成后若设备已配网Matter.isDeviceCommissioned()打印初始状态并调用DimmablePlugin.updateAccessory()让物理输出同步到已保存状态。从底层实现看begin()见 MatterDimmablePlugin.cpp实际调用了esp_matter的dimmable_plug_in_unit::create()创建 Matter 端点并配置 OnOff 与 LevelControl 两个集群的初始属性。begin()的默认参数为initialState false、level 64对应 README 中“默认 OFF、等级 6425%”的说明。loop()配网等待与按键处理loop()完成三件事检查配网状态未配网时打印手动配对码与 QR 码 URLMatter.getManualPairingCode()/Matter.getOnboardingQRCodeUrl()并以 5 秒为周期打印等待提示直到配网完成按键消抖与短按切换DimmablePlugin.toggle()长按 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.cppMatter 内部事件处理器在收到控制器写入的属性值时会按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方法签名说明构造MatterDimmablePlugin()创建可调光插座端点初始化bool begin(bool initialState false, uint8_t level 64)初始化端点默认关、等级 6425%停止void end()停止处理 Matter 事件开关bool setOnOff(bool newState)设置开关状态开关bool getOnOff()读取当前开关状态开关bool toggle()翻转开关状态等级bool setLevel(uint8_t newLevel)设置功率等级0-2550关255最大等级uint8_t getLevel()读取当前等级常量static const uint8_t MAX_LEVEL 255最大等级常量布尔运算符operator bool()返回当前开关状态可写if (myPlugin)赋值运算符void operator(bool state)直接开关myPlugin true;事件void onChange(EndPointCB cb)任意参数变化回调签名bool cb(bool newState, uint8_t newLevel)事件void onChangeOnOff(EndPointOnOffCB cb)开关变化回调签名bool cb(bool newState)事件void onChangeLevel(EndPointLevelCB cb)等级变化回调签名bool cb(uint8_t newLevel)同步void updateAccessory()用当前内部状态调用已注册回调用于启动时同步物理输出故障排查Troubleshooting配网时设备不可见确认 Wi-Fi 或 Thread 连接配置正确继电器/调光器无响应检查引脚配置与接线。调光模块必须使用支持 PWManalogWrite的引脚继电器模块注意供电与接线正确等级控制无效确认引脚支持 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考