arduino-esp32 Matter 增强智能按钮MatterEnhancedSmartButton实战指南短按、长按与多按手势的完整实现【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32导读本指南围绕 arduino-esp32 仓库中的MatterEnhancedSmartButton官方示例展开讲解如何在 ESP32 系列芯片上用 Arduino 编程方式把一个普通物理按钮接入 Matter 智能家居网络实现完整的开关簇Switch Cluster瞬时手势事件——短按、长按、双击/三击等多按序列。读完本文你将掌握MatterGenericSwitch端点类的 FeatureMap 配置、事件生成 API 的调用时机、状态机与去抖逻辑、配网与烧录流程以及如何让 Home Assistant 等中枢识别独立的短按/长按/多按自动化触发器。示例概览从单按到全手势MatterEnhancedSmartButton是 MatterSmartButton仅支持短按的完整版升级示例位于 libraries/Matter/examples/MatterEnhancedSmartButton包含MatterEnhancedSmartButton.ino——完整的示例程序可直接在 Arduino IDE 打开README.md——官方使用说明ci.yml——持续集成配置。示例以 MatterGeneric Switch通用开关设备类型实现了一个 Matter 智能按钮并把物理按钮动作映射为 Matter Switch 簇的全部瞬时momentary事件即使用FEATURE_ALL开启全部手势特性短按InitialPressShortRelease长按默认阈值 1 秒LongPressLongRelease多按默认 300 ms 窗口、最多 5 次MultiPressOngoingMultiPressComplete长按 5 秒执行工厂复位解除配对属于配网管理动作而非 Matter 事件每次手势均通过串口打印日志便于调试支持的芯片目标SoCWi-FiThreadBLE 配网状态ESP32✅❌❌完全支持ESP32-S2✅❌❌完全支持ESP32-S3✅❌✅完全支持ESP32-C3✅❌✅完全支持ESP32-C6✅❌✅完全支持ESP32-C5❌✅✅支持仅 ThreadESP32-H2❌✅✅支持仅 Thread从表格可见Matter 设备底层传输既可以是 Wi-Fi也可以是 Thread802.15.4。CONFIG_ENABLE_CHIPOBLE决定是否通过 BLE 完成配网BLE 配网可用时无需手动配置 Wi-Fi可省 Flash 空间否则程序会走WiFi.begin(ssid, password)主动连接网络。MatterGenericSwitch 端点类与 FeatureMap示例的核心是 MatterGenericSwitch 端点类。它实现了 MatterSwitch 簇是一个“瞬时智能按钮”把按压手势上报给 Matter 控制器Controller。Switch 簇通过FeatureMap位掩码声明设备支持的手势能力类中给出了与 Matter 规范一致的常量常量位值启用的事件FEATURE_MOMENTARY0x02InitialPressFEATURE_RELEASE0x04ShortReleaseFEATURE_LONG_PRESS0x08LongPress、LongReleaseFEATURE_MULTI_PRESS0x10MultiPressOngoing、MultiPressComplete预设组合FEATURE_SIMPLE默认FEATURE_MOMENTARY | FEATURE_RELEASE即短按FEATURE_ALL 上述全部瞬时手势即 0x02 | 0x04 | 0x08 | 0x10 0x1E特性依赖约束源码在begin()中有明确校验见 MatterGenericSwitch.cppFEATURE_LONG_PRESS依赖FEATURE_RELEASEFEATURE_MULTI_PRESS依赖FEATURE_RELEASE缺少FEATURE_MOMENTARY时begin()直接返回falsemultiPressMax小于 2 时会被自动修正为 2。在 begin() 的实现中featureFlags会写入 Switch 簇配置的feature_flags字段multiPressMax则写入momentary_switch_multi_press.multi_press_max随后通过generic_switch::create()创建端点并附加 Groups、Fixed Label、User Label 簇以及 TagList 支持启用失败仅告警不影响按钮基本功能。手势事件 API 与事件流MatterGenericSwitch为每种 Matter 事件提供了独立方法示例代码通过按钮驱动在恰当的时机调用它们方法声明见 MatterGenericSwitch.hpress()——发送InitialPress按下release()——发送ShortRelease短按释放longPress()——发送LongPress按住超过阈值longRelease()——发送LongRelease长按后释放multiPressOngoing(count)——多按窗口内的再次按下multiPressComplete(count)——多按窗口超时结束click()——便捷方法发送InitialPress后若启用了FEATURE_RELEASE再发ShortRelease在 MatterGenericSwitch.cpp 中可以看到每个事件方法都先检查started状态与对应 Feature 位再通过chip::DeviceLayer::SystemLayer().ScheduleLambda(...)调度到 Matter 事件循环中执行更新 Switch 簇的CurrentPosition属性按下为pressPosition 1释放回到idlePosition 0并调用switch_cluster::event::send_xxx()发送对应事件。multiPressComplete()还会做count multiPressMax的边界保护超限置 0。标准手势事件流一次正确的短按会发送两个事件按下 →InitialPress松开 →ShortRelease长按在此基础上增加按住期间 →LongPress释放时 →LongRelease。多按双击/三击遵循 ESP-Matter generic switch 的既有模式第一次按下 →InitialPress第一次释放 →ShortRelease窗口内第二次按下 →MultiPressOngoingcount 2第二次释放 →ShortRelease窗口超时 →MultiPressComplete总次数这与示例 README 的手势映射表 完全对应InitialPress/ShortRelease对应首次按下/短释放LongPress/LongRelease对应按住≥1 秒及其释放MultiPressOngoing/MultiPressComplete对应窗口内的再次按下与窗口结束。示例程序逐段剖析全局对象与配置常量// List of Matter Endpoints for this Node MatterGenericSwitch SmartButton; #if !CONFIG_ENABLE_CHIPOBLE // WiFi is manually set and started const char *ssid your-ssid; // 改为你的 WiFi SSID const char *password your-password; // 改为你的 WiFi 密码 #endif // set your board USER BUTTON pin here const uint8_t buttonPin BOOT_PIN; // 默认使用板载 BOOT 按键 // Timing (adjust to match your hub / use case) const uint32_t debounceMs 50; // 按键去抖时间 (ms) const uint32_t longPressMs 1000; // 触发 LongPress 的按住时长 (ms) const uint32_t multiPressWindowMs 300; // 多按判定窗口两次点击的最大间隔 (ms) const uint32_t decommissioningTimeout 5000; // 按住 5 秒或更久触发解除配对 const uint8_t multiPressMax 5; // 上报给 Matter 的最大按压次数 (2–255)这些常量位于程序顶部可根据你的中枢Hub习惯与使用场景调整debounceMs机械抖动消除时间过小会误判抖动过大则手感迟钝longPressMs长按阈值达到该时长即发送LongPressmultiPressWindowMs两次点击之间的最大间隔超过则认为多按序列结束multiPressMax多按可上报的最大次数需在 2–255 之间begin()会强制下限为 2decommissioningTimeout解除配对的按住时长独立于 Matter 长按手势。状态变量与去抖/状态机程序维护了一组按钮状态变量bool buttonPressed false; // 去抖后的原始状态false释放 | true按下 bool stablePressed false; // 去抖后的稳定按压状态 uint32_t lastChangeMs 0; // 去抖控制 uint32_t pressStartMs 0; // 本次按压的开始时刻 bool longPressSent false; // 本次按住期间是否已发送 LongPress // 多按序列状态与 esp-matter generic_switch 示例保持一致 bool inMultiPressSequence false; // 多按序列是否进行中 uint8_t pressesInSequence 0; // 当前序列已计数的按压次数 uint32_t multiPressDeadlineMs 0; // 多按窗口到期时刻主循环loop()中的按键处理分为四个阶段原始电平读取readButtonPressed()返回digitalRead(buttonPin) LOW按钮按下为低电平配合INPUT_PULLUP。软件去抖只有当rawPressed ! buttonPressed且距上次变化超过debounceMs时才更新状态并将stablePressed的边沿翻译成handlePressDown()/handlePressUp()。长按检测checkLongPress()在按住且millis() - pressStartMs longPressMs且未发送过LongPress时发送一次longPressSent置位防止重复。多按结束检测checkMultiPressComplete()在无按键按下、窗口已到期且序列进行中时发送MultiPressComplete并重置序列状态。按下与释放的事件派发handlePressDown()决定本次按下是序列首按还是追加按if (inMultiPressSequence millis() multiPressDeadlineMs pressesInSequence 1) { uint8_t count pressesInSequence 1; SmartButton.multiPressOngoing(count); // 窗口内追加按下 → MultiPressOngoing } else { pressesInSequence 0; inMultiPressSequence true; SmartButton.press(); // 新序列首按 → InitialPress }handlePressUp()则区分长按释放与短按释放if (longPressSent) { SmartButton.longRelease(); // 长按后释放 → LongRelease // 重置序列状态 return; } SmartButton.release(); // 短按释放 → ShortRelease pressesInSequence; multiPressDeadlineMs millis() multiPressWindowMs; // 刷新多按窗口这里体现了长按与多按的互斥关系一旦长按已发送释放时直接走LongRelease分支并结束当前序列只有短释放才累计次数并刷新多按窗口。配网流程setupsetup()中的流程与 Matter 库的标准用法一致pinMode(buttonPin, INPUT_PULLUP); Serial.begin(115200); #if !CONFIG_ENABLE_CHIPOBLE // 手动连接 WiFi 并等待 WL_CONNECTED WiFi.begin(ssid, password); while (WiFi.status() ! WL_CONNECTED) { delay(500); ... } #endif // 初始化 Matter 端点FEATURE_ALL 开启全部瞬时手势 SmartButton.begin(MatterGenericSwitch::FEATURE_ALL, multiPressMax); // 最后一步初始化整个 Matter 节点 Matter.begin(); if (Matter.isDeviceCommissioned()) { ... }loop()开头会检查配网状态未配网时通过Matter.getManualPairingCode()和Matter.getOnboardingQRCodeUrl()打印手动配对码与 QR 码 URL并阻塞等待配网完成约每 5 秒打印一次提示。配网完成后即可正常响应按钮手势。工厂复位解除配对loop()末尾的独立逻辑处理解除配对——它与 Matter 长按手势无关是配网管理动作if (buttonPressed (millis() - pressStartMs decommissioningTimeout)) { Matter.decommission(); // 解除配对设备需重新配网 pressStartMs millis(); // 防止重复触发重启约需一秒 }构建与烧录步骤与 MatterSmartButton 示例完全一致在 Arduino IDE 中打开MatterEnhancedSmartButton.ino选择你的开发板并选用Huge APP3 MB No OTA / 1 MB SPIFFS分区方案——Matter 固件体积较大默认分区无法容纳勾选Erase All Flash Before Sketch Upload上传前擦除全部 Flash首次烧录与配网信息异常时尤其必要上传固件打开串口监视器波特率 115200观察配网与手势日志。需要说明的是Matter 支持是通过编译期配置CONFIG_ESP_MATTER_ENABLE_DATA_MODEL启用的见 MatterGenericSwitch.h 的条件编译因此烧录环境必须带有 Matter 数据模型支持。预期串口输出按下 BOOT 键依次执行“单击、双击、长按”后串口监视器应输出类似内容Initial press Short release Multi-press complete (count1) Initial press Short release Multi-press ongoing (count2) Short release Multi-press complete (count2) Initial press Long press Long release示例程序实际打印的日志文本略有差异如User button pressed. Sending InitialPress to the Matter Controller!但事件语义与此一致。若输出缺失某类事件优先检查对应 Feature 位是否开启、multiPressMax是否≥2、以及longPressMs/multiPressWindowMs是否符合预期。智能家居集成与多按钮场景中枢Hub会读取 Switch 簇的FeatureMap判断设备支持的手势。使用FEATURE_ALLFeatureMap 0x1E时Home Assistant 等控制器可分别为短按、长按、多按暴露独立的自动化触发器从而实现“单按开灯、双击切换场景、长按调色”等组合控制。如果你的节点需要多个按钮例如“开 / 关 / 自定义场景”三键面板可以创建多个MatterGenericSwitch端点。但由于兄弟端点共享同一 Matter 设备类型控制器仅凭设备类型无法区分它们——此时应在begin()之后、Matter.begin()之前调用MatterEndPoint::setTagList()写入 Descriptor 簇的TagList属性使用 MatterTags::Switches 中的预置标签On、Off、Toggle、Up、Down、Next、Previous、Select或createCustomTag(Scene 1)自定义标签。仓库中的 MatterSmartButtonsTagList 示例演示了完整的“On / Off / Scene 1”三按钮 TagList 实现官方端点文档见 ep_generic_switch.rst 与 matter_ep.rst。小结MatterEnhancedSmartButton展示了 arduino-esp32 Matter 库中 Generic Switch 端点的完整用法通过FEATURE_ALL开启全部瞬时手势、用去抖状态机把物理按压翻译成InitialPress/ShortRelease/LongPress/LongRelease/MultiPressOngoing/MultiPressComplete事件、并在配网与解除配对流程上与标准 Matter 节点保持一致。阅读 MatterGenericSwitch.h 与 MatterGenericSwitch.cpp 的源码可以进一步理解 FeatureMap 校验、CurrentPosition属性更新与事件调度ScheduleLambda等底层细节。以此为模板你可以轻松扩展出支持任意按键组合的 Matter 场景控制器。【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 arduino-esp32 Matter 增强智能按钮（MatterEnhancedSmartButton）实战指南：短按、长按与多按手势的完整实现
arduino-esp32 Matter 增强智能按钮MatterEnhancedSmartButton实战指南短按、长按与多按手势的完整实现【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32导读本指南围绕 arduino-esp32 仓库中的MatterEnhancedSmartButton官方示例展开讲解如何在 ESP32 系列芯片上用 Arduino 编程方式把一个普通物理按钮接入 Matter 智能家居网络实现完整的开关簇Switch Cluster瞬时手势事件——短按、长按、双击/三击等多按序列。读完本文你将掌握MatterGenericSwitch端点类的 FeatureMap 配置、事件生成 API 的调用时机、状态机与去抖逻辑、配网与烧录流程以及如何让 Home Assistant 等中枢识别独立的短按/长按/多按自动化触发器。示例概览从单按到全手势MatterEnhancedSmartButton是 MatterSmartButton仅支持短按的完整版升级示例位于 libraries/Matter/examples/MatterEnhancedSmartButton包含MatterEnhancedSmartButton.ino——完整的示例程序可直接在 Arduino IDE 打开README.md——官方使用说明ci.yml——持续集成配置。示例以 MatterGeneric Switch通用开关设备类型实现了一个 Matter 智能按钮并把物理按钮动作映射为 Matter Switch 簇的全部瞬时momentary事件即使用FEATURE_ALL开启全部手势特性短按InitialPressShortRelease长按默认阈值 1 秒LongPressLongRelease多按默认 300 ms 窗口、最多 5 次MultiPressOngoingMultiPressComplete长按 5 秒执行工厂复位解除配对属于配网管理动作而非 Matter 事件每次手势均通过串口打印日志便于调试支持的芯片目标SoCWi-FiThreadBLE 配网状态ESP32✅❌❌完全支持ESP32-S2✅❌❌完全支持ESP32-S3✅❌✅完全支持ESP32-C3✅❌✅完全支持ESP32-C6✅❌✅完全支持ESP32-C5❌✅✅支持仅 ThreadESP32-H2❌✅✅支持仅 Thread从表格可见Matter 设备底层传输既可以是 Wi-Fi也可以是 Thread802.15.4。CONFIG_ENABLE_CHIPOBLE决定是否通过 BLE 完成配网BLE 配网可用时无需手动配置 Wi-Fi可省 Flash 空间否则程序会走WiFi.begin(ssid, password)主动连接网络。MatterGenericSwitch 端点类与 FeatureMap示例的核心是 MatterGenericSwitch 端点类。它实现了 MatterSwitch 簇是一个“瞬时智能按钮”把按压手势上报给 Matter 控制器Controller。Switch 簇通过FeatureMap位掩码声明设备支持的手势能力类中给出了与 Matter 规范一致的常量常量位值启用的事件FEATURE_MOMENTARY0x02InitialPressFEATURE_RELEASE0x04ShortReleaseFEATURE_LONG_PRESS0x08LongPress、LongReleaseFEATURE_MULTI_PRESS0x10MultiPressOngoing、MultiPressComplete预设组合FEATURE_SIMPLE默认FEATURE_MOMENTARY | FEATURE_RELEASE即短按FEATURE_ALL 上述全部瞬时手势即 0x02 | 0x04 | 0x08 | 0x10 0x1E特性依赖约束源码在begin()中有明确校验见 MatterGenericSwitch.cppFEATURE_LONG_PRESS依赖FEATURE_RELEASEFEATURE_MULTI_PRESS依赖FEATURE_RELEASE缺少FEATURE_MOMENTARY时begin()直接返回falsemultiPressMax小于 2 时会被自动修正为 2。在 begin() 的实现中featureFlags会写入 Switch 簇配置的feature_flags字段multiPressMax则写入momentary_switch_multi_press.multi_press_max随后通过generic_switch::create()创建端点并附加 Groups、Fixed Label、User Label 簇以及 TagList 支持启用失败仅告警不影响按钮基本功能。手势事件 API 与事件流MatterGenericSwitch为每种 Matter 事件提供了独立方法示例代码通过按钮驱动在恰当的时机调用它们方法声明见 MatterGenericSwitch.hpress()——发送InitialPress按下release()——发送ShortRelease短按释放longPress()——发送LongPress按住超过阈值longRelease()——发送LongRelease长按后释放multiPressOngoing(count)——多按窗口内的再次按下multiPressComplete(count)——多按窗口超时结束click()——便捷方法发送InitialPress后若启用了FEATURE_RELEASE再发ShortRelease在 MatterGenericSwitch.cpp 中可以看到每个事件方法都先检查started状态与对应 Feature 位再通过chip::DeviceLayer::SystemLayer().ScheduleLambda(...)调度到 Matter 事件循环中执行更新 Switch 簇的CurrentPosition属性按下为pressPosition 1释放回到idlePosition 0并调用switch_cluster::event::send_xxx()发送对应事件。multiPressComplete()还会做count multiPressMax的边界保护超限置 0。标准手势事件流一次正确的短按会发送两个事件按下 →InitialPress松开 →ShortRelease长按在此基础上增加按住期间 →LongPress释放时 →LongRelease。多按双击/三击遵循 ESP-Matter generic switch 的既有模式第一次按下 →InitialPress第一次释放 →ShortRelease窗口内第二次按下 →MultiPressOngoingcount 2第二次释放 →ShortRelease窗口超时 →MultiPressComplete总次数这与示例 README 的手势映射表 完全对应InitialPress/ShortRelease对应首次按下/短释放LongPress/LongRelease对应按住≥1 秒及其释放MultiPressOngoing/MultiPressComplete对应窗口内的再次按下与窗口结束。示例程序逐段剖析全局对象与配置常量// List of Matter Endpoints for this Node MatterGenericSwitch SmartButton; #if !CONFIG_ENABLE_CHIPOBLE // WiFi is manually set and started const char *ssid your-ssid; // 改为你的 WiFi SSID const char *password your-password; // 改为你的 WiFi 密码 #endif // set your board USER BUTTON pin here const uint8_t buttonPin BOOT_PIN; // 默认使用板载 BOOT 按键 // Timing (adjust to match your hub / use case) const uint32_t debounceMs 50; // 按键去抖时间 (ms) const uint32_t longPressMs 1000; // 触发 LongPress 的按住时长 (ms) const uint32_t multiPressWindowMs 300; // 多按判定窗口两次点击的最大间隔 (ms) const uint32_t decommissioningTimeout 5000; // 按住 5 秒或更久触发解除配对 const uint8_t multiPressMax 5; // 上报给 Matter 的最大按压次数 (2–255)这些常量位于程序顶部可根据你的中枢Hub习惯与使用场景调整debounceMs机械抖动消除时间过小会误判抖动过大则手感迟钝longPressMs长按阈值达到该时长即发送LongPressmultiPressWindowMs两次点击之间的最大间隔超过则认为多按序列结束multiPressMax多按可上报的最大次数需在 2–255 之间begin()会强制下限为 2decommissioningTimeout解除配对的按住时长独立于 Matter 长按手势。状态变量与去抖/状态机程序维护了一组按钮状态变量bool buttonPressed false; // 去抖后的原始状态false释放 | true按下 bool stablePressed false; // 去抖后的稳定按压状态 uint32_t lastChangeMs 0; // 去抖控制 uint32_t pressStartMs 0; // 本次按压的开始时刻 bool longPressSent false; // 本次按住期间是否已发送 LongPress // 多按序列状态与 esp-matter generic_switch 示例保持一致 bool inMultiPressSequence false; // 多按序列是否进行中 uint8_t pressesInSequence 0; // 当前序列已计数的按压次数 uint32_t multiPressDeadlineMs 0; // 多按窗口到期时刻主循环loop()中的按键处理分为四个阶段原始电平读取readButtonPressed()返回digitalRead(buttonPin) LOW按钮按下为低电平配合INPUT_PULLUP。软件去抖只有当rawPressed ! buttonPressed且距上次变化超过debounceMs时才更新状态并将stablePressed的边沿翻译成handlePressDown()/handlePressUp()。长按检测checkLongPress()在按住且millis() - pressStartMs longPressMs且未发送过LongPress时发送一次longPressSent置位防止重复。多按结束检测checkMultiPressComplete()在无按键按下、窗口已到期且序列进行中时发送MultiPressComplete并重置序列状态。按下与释放的事件派发handlePressDown()决定本次按下是序列首按还是追加按if (inMultiPressSequence millis() multiPressDeadlineMs pressesInSequence 1) { uint8_t count pressesInSequence 1; SmartButton.multiPressOngoing(count); // 窗口内追加按下 → MultiPressOngoing } else { pressesInSequence 0; inMultiPressSequence true; SmartButton.press(); // 新序列首按 → InitialPress }handlePressUp()则区分长按释放与短按释放if (longPressSent) { SmartButton.longRelease(); // 长按后释放 → LongRelease // 重置序列状态 return; } SmartButton.release(); // 短按释放 → ShortRelease pressesInSequence; multiPressDeadlineMs millis() multiPressWindowMs; // 刷新多按窗口这里体现了长按与多按的互斥关系一旦长按已发送释放时直接走LongRelease分支并结束当前序列只有短释放才累计次数并刷新多按窗口。配网流程setupsetup()中的流程与 Matter 库的标准用法一致pinMode(buttonPin, INPUT_PULLUP); Serial.begin(115200); #if !CONFIG_ENABLE_CHIPOBLE // 手动连接 WiFi 并等待 WL_CONNECTED WiFi.begin(ssid, password); while (WiFi.status() ! WL_CONNECTED) { delay(500); ... } #endif // 初始化 Matter 端点FEATURE_ALL 开启全部瞬时手势 SmartButton.begin(MatterGenericSwitch::FEATURE_ALL, multiPressMax); // 最后一步初始化整个 Matter 节点 Matter.begin(); if (Matter.isDeviceCommissioned()) { ... }loop()开头会检查配网状态未配网时通过Matter.getManualPairingCode()和Matter.getOnboardingQRCodeUrl()打印手动配对码与 QR 码 URL并阻塞等待配网完成约每 5 秒打印一次提示。配网完成后即可正常响应按钮手势。工厂复位解除配对loop()末尾的独立逻辑处理解除配对——它与 Matter 长按手势无关是配网管理动作if (buttonPressed (millis() - pressStartMs decommissioningTimeout)) { Matter.decommission(); // 解除配对设备需重新配网 pressStartMs millis(); // 防止重复触发重启约需一秒 }构建与烧录步骤与 MatterSmartButton 示例完全一致在 Arduino IDE 中打开MatterEnhancedSmartButton.ino选择你的开发板并选用Huge APP3 MB No OTA / 1 MB SPIFFS分区方案——Matter 固件体积较大默认分区无法容纳勾选Erase All Flash Before Sketch Upload上传前擦除全部 Flash首次烧录与配网信息异常时尤其必要上传固件打开串口监视器波特率 115200观察配网与手势日志。需要说明的是Matter 支持是通过编译期配置CONFIG_ESP_MATTER_ENABLE_DATA_MODEL启用的见 MatterGenericSwitch.h 的条件编译因此烧录环境必须带有 Matter 数据模型支持。预期串口输出按下 BOOT 键依次执行“单击、双击、长按”后串口监视器应输出类似内容Initial press Short release Multi-press complete (count1) Initial press Short release Multi-press ongoing (count2) Short release Multi-press complete (count2) Initial press Long press Long release示例程序实际打印的日志文本略有差异如User button pressed. Sending InitialPress to the Matter Controller!但事件语义与此一致。若输出缺失某类事件优先检查对应 Feature 位是否开启、multiPressMax是否≥2、以及longPressMs/multiPressWindowMs是否符合预期。智能家居集成与多按钮场景中枢Hub会读取 Switch 簇的FeatureMap判断设备支持的手势。使用FEATURE_ALLFeatureMap 0x1E时Home Assistant 等控制器可分别为短按、长按、多按暴露独立的自动化触发器从而实现“单按开灯、双击切换场景、长按调色”等组合控制。如果你的节点需要多个按钮例如“开 / 关 / 自定义场景”三键面板可以创建多个MatterGenericSwitch端点。但由于兄弟端点共享同一 Matter 设备类型控制器仅凭设备类型无法区分它们——此时应在begin()之后、Matter.begin()之前调用MatterEndPoint::setTagList()写入 Descriptor 簇的TagList属性使用 MatterTags::Switches 中的预置标签On、Off、Toggle、Up、Down、Next、Previous、Select或createCustomTag(Scene 1)自定义标签。仓库中的 MatterSmartButtonsTagList 示例演示了完整的“On / Off / Scene 1”三按钮 TagList 实现官方端点文档见 ep_generic_switch.rst 与 matter_ep.rst。小结MatterEnhancedSmartButton展示了 arduino-esp32 Matter 库中 Generic Switch 端点的完整用法通过FEATURE_ALL开启全部瞬时手势、用去抖状态机把物理按压翻译成InitialPress/ShortRelease/LongPress/LongRelease/MultiPressOngoing/MultiPressComplete事件、并在配网与解除配对流程上与标准 Matter 节点保持一致。阅读 MatterGenericSwitch.h 与 MatterGenericSwitch.cpp 的源码可以进一步理解 FeatureMap 校验、CurrentPosition属性更新与事件调度ScheduleLambda等底层细节。以此为模板你可以轻松扩展出支持任意按键组合的 Matter 场景控制器。【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考