企业官网建设流程全解析

ESP32 Arduino Matter 水浸传感器（Water Leak Detector）示例完整指南：从端点上电到智能家居接入

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

本指南以 ESP32 Arduino Core（arduino-esp32）仓库中的 MatterWaterLeakDetector 示例 为主体，系统讲解如何基于 ESP32 系列 SoC 构建一个 Matter 兼容的水浸检测（Water Leak Detector）设备，涵盖支持的芯片平台、端点上电流程、Wi-Fi/Thread 配网、传感器状态模拟、LED 指示、按键恢复出厂（decommission）以及 Apple Home / Amazon Alexa / Google Home 的接入方法。读完本文，你将掌握 Matter Water Leak Detector 端点的完整使用链路：begin()创建端点 →Matter.begin()启动 Matter → 配网（commissioning）→setLeak()上报真实或模拟的检测状态 →getLeak()驱动本地指示，并能独立将示例移植到真实漏水探头硬件上。

示例概览：一个完整的 Matter 水浸检测器

Matter 是由连接标准联盟（CSA）推动的智能家居互联协议，ESP32 Arduino Core 通过 Matter 库 将其封装为面向 Arduino 的 API。本示例在 ESP32 上创建了一个 Matter 水浸检测设备，其核心能力包括：

• 基于 Matter 协议实现 Water Leak Detector（水浸检测器）设备类型；
• 同时支持 Wi-Fi 与 Thread（Thread 需要以 Arduino 作为 ESP-IDF 组件编译，详见下文"配网方式说明"）两种底层网络；
• 使用 LED 指示水浸检测状态（LED 亮 = 检测到漏水，LED 灭 = 未检测到漏水）；
• 内置传感器模拟器：每simulatedSensorInterval（默认 20 秒）自动切换一次检测状态；
• 按键长按 5 秒触发恢复出厂（decommission），用于重新配网；
• 支持通过 QR 码或手动配对码完成 Matter 配网；
• 可接入 Apple HomeKit、Amazon Alexa、Google Home 等 Matter 生态；
• 端点创建与状态上报分离：begin()只创建端点（初始状态为 Not Detected），必须在Matter.begin()之后调用setLeak()写入真实或模拟的传感器读数。

从源码层面看，该示例由三部分构成：示例主程序 MatterWaterLeakDetector.ino、端点类实现 MatterWaterLeakDetector.cpp 与 端点类头文件 MatterWaterLeakDetector.h，后者继承自所有 Matter 端点共用的基类 MatterEndPoint。示例的持续集成配置见 ci.yml。

支持的芯片平台与配网方式

示例 README 给出了完整的支持矩阵。下表说明各 SoC 的 Wi-Fi、Thread、BLE 配网支持情况：

配网方式说明

• ESP32 与 ESP32-S2：不支持通过低功耗蓝牙（BLE）配网。必须直接在 sketch 中写入 Wi-Fi 凭据，由设备手动连接到你的网络。
• ESP32-C6：虽然芯片本身支持 Thread，但 ESP32 Arduino Matter 库预编译版本仅启用了 Wi-Fi。如需配置为纯 Thread 运行，必须使用 Arduino 作为 IDF 组件的方式构建工程，并禁用 Matter 的 Wi-Fi Station 功能。
• ESP32-C5：虽然芯片支持 2.4 GHz 与 5 GHz Wi-Fi，但 ESP32 Arduino Matter 库预编译版本仅启用了 Thread。如需配置为 Wi-Fi 运行，必须使用 Arduino 作为 ESP-IDF 组件的方式构建工程，并禁用 Thread 网络，仅保留 Wi-Fi Station。

这一逻辑与示例源码的预处理分支完全对应。在 MatterWaterLeakDetector.ino 中：

#include <Arduino.h> #include <Matter.h> #if !CONFIG_ENABLE_CHIPOBLE // if the device can be commissioned using BLE, WiFi is not used - save flash space #include <WiFi.h> #endif ... #if !CONFIG_ENABLE_CHIPOBLE // WiFi is manually set and started const char *ssid = "your-ssid"; // Change this to your WiFi SSID const char *password = "your-password"; // Change this to your WiFi password #endif

CONFIG_ENABLE_CHIPOBLE是编译期配置宏：当它被启用（即设备支持 BLE 配网）时，Wi-Fi 库不会被链接，从而节省 Flash 空间；当它未启用（ESP32 / ESP32-S2）时，代码会手动调用WiFi.begin(ssid, password)建立 Wi-Fi 连接。此外，Matter.h 还提供了运行时查询能力的方法：isWiFiStationEnabled()、isWiFiAccessPointEnabled()、isThreadEnabled()、isBLECommissioningEnabled()，用于在应用层判断当前固件实际启用了哪些网络与配网能力。

硬件要求与引脚配置

硬件清单

• 一块兼容 ESP32 的开发板（参见上表支持矩阵）；
• 一个 LED，连接到 GPIO 引脚（或使用板载 LED），用于指示水浸检测状态；
• 一个用户按键用于恢复出厂（默认使用 BOOT 按键）。

引脚定义

• LED：优先使用RGB_BUILTIN（若已定义），否则默认使用 GPIO 2；
• 按键：默认使用BOOT_PIN（通常为 GPIO 0）。

对应源码（MatterWaterLeakDetector.ino）：

// LED will be used to indicate the Water Leak Detector state // set your board RGB LED pin here #ifdef RGB_BUILTIN const uint8_t ledPin = RGB_BUILTIN; #else const uint8_t ledPin = 2; // Set your pin here if your board has not defined LED_BUILTIN #warning "Do not forget to set the RGB LED pin" #endif // set your board USER BUTTON pin here - decommissioning only const uint8_t buttonPin = BOOT_PIN; // Set your pin here. Using BOOT Button.

注意：当板卡未定义RGB_BUILTIN时，编译器会通过#warning提示开发者务必自行确认 LED 引脚。

软件环境准备

前置条件

1. 安装 Arduino IDE（推荐 2.0 或更新版本）；
2. 安装支持 Matter 的 ESP32 Arduino Core；
3. 安装 ESP32 Arduino 库：
   • Matter
   • Wi-Fi（仅 ESP32 与 ESP32-S2 需要）

上传前的配置项

在烧录前，根据你的硬件情况修改以下配置：

1. Wi-Fi 凭据（不使用 BLE 配网时必须配置，ESP32 / ESP32-S2 为强制项）：

const char *ssid = "your-ssid"; // Change to your Wi-Fi SSID const char *password = "your-password"; // Change to your Wi-Fi password

2. LED 引脚（不使用板载 LED 时）：

const uint8_t ledPin = 2; // Set your LED pin here

3. 按键引脚（可选）：默认使用 BOOT 按键（GPIO 0）执行恢复出厂，可按需改为其他引脚：

const uint8_t buttonPin = BOOT_PIN; // Set your button pin here

4. 模拟传感器间隔（可选）：控制模拟硬件状态翻转的频率。当接入真实探头后，用真实读取替换simulatedHWWaterLeakDetector()：

const uint32_t simulatedSensorInterval = 20000; // 20 seconds

编译与烧录步骤

1. 在 Arduino IDE 中打开MatterWaterLeakDetector.inosketch；
2. 在Tools > Board菜单中选择你的 ESP32 开发板；
3. 在Tools > Partition Scheme菜单中选择"Huge APP (3MB No OTA/1MB SPIFFS)"；
4. 在Tools菜单中启用"Erase All Flash Before Sketch Upload"（烧录前擦除全部 Flash）；
5. 通过 USB 将 ESP32 开发板连接到电脑；
6. 点击Upload按钮编译并烧录。

这里的分区方案选择并非随意之举：Matter 固件体积较大，需要 "Huge APP" 分区才能容纳完整的 Matter 协议栈与数据模型。该要求同样体现在示例的持续集成配置 ci.yml 中：

fqbn_append: PartitionScheme=huge_app requires: - CONFIG_ESP_MATTER_ENABLE_DATA_MODEL=y

其中CONFIG_ESP_MATTER_ENABLE_DATA_MODEL=y是 Matter 数据模型（Data Model）的编译开关——端点类如 MatterWaterLeakDetector.h 的完整实现都包裹在#ifdef CONFIG_ESP_MATTER_ENABLE_DATA_MODEL中，关闭该选项则端点类不会参与编译。

预期串口输出与配网

烧录完成后，以115200波特率打开串口监视器。只有 ESP32 与 ESP32-S2 会显示 Wi-Fi 连接日志；其余目标芯片会通过 Matter CHIPoBLE（基于 BLE 的 Matter 配网通道）自动完成 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. ... Matter Node is commissioned and connected to the network. Ready for use. Water Leak Detector is Detected. Water Leak Detector is Not Detected.

配网完成后，模拟传感器每simulatedSensorInterval（默认 20 秒）翻转一次状态，setLeak()将该读数上报给 Matter 网络，同时 LED 跟随getLeak()变化。

串口中的配对码与 QR 码由 Matter 管理器生成。在 MatterWaterLeakDetector.ino 中，设备通过以下 API 等待并展示配网信息：

if (!Matter.isDeviceCommissioned()) { Serial.println("Matter Node is not commissioned yet."); Serial.println("Initiate the device discovery in your Matter environment."); Serial.println("Commission it to your Matter hub with the manual pairing code or QR code"); Serial.printf("Manual pairing code: %s\r\n", Matter.getManualPairingCode().c_str()); Serial.printf("QR code URL: %s\r\n", Matter.getOnboardingQRCodeUrl().c_str()); // waits for Matter Water Leak Detector Commissioning. uint32_t timeCount = 0; while (!Matter.isDeviceCommissioned()) { delay(100); if ((timeCount++ % 50) == 0) { // 50*100ms = 5 sec Serial.println("Matter Node not commissioned yet. Waiting for commissioning."); } } Serial.println("Matter Node is commissioned and connected to the network. Ready for use."); }

这些静态 API 定义于 Matter.h：getManualPairingCode()与getOnboardingQRCodeUrl()在Matter.begin()之后由 CommissionableDataProvider 生成（在此之前调用会打印警告并返回空字符串）；isDeviceCommissioned()用于查询设备是否已完成配网；decommission()用于解除配网（恢复出厂）。开发者也可以在Matter.begin()之前调用setSetupDiscriminator()与setSetupPasscode()自定义配网判别码与配对码（测试默认值为0xF00/20202021）。

设备使用详解

手动控制：按键恢复出厂

用户按键（默认 BOOT 按键）提供恢复出厂功能：

• 长按（> 5 秒）：恢复设备出厂设置（解除 Matter 配网，decommission）。

对应实现（MatterWaterLeakDetector.ino）包含按键消抖逻辑：按下时记录时间戳，松开时复位状态；当按键保持按下超过decommissioningTimeout（5000 ms）时调用Matter.decommission()，并重置时间戳以避免重复触发：

// Onboard User Button is kept pressed for longer than 5 seconds in order to decommission matter node uint32_t time_diff = millis() - button_time_stamp; if (button_state && time_diff > decommissioningTimeout) { Serial.println("Decommissioning Water Leak Detector Matter Accessory. It shall be commissioned again."); Matter.decommission(); button_time_stamp = millis(); // avoid running decommissioning again, reboot takes a second or so }

传感器模拟与状态上报

示例内置了一个模拟水浸检测器，其行为特点：

• 初始状态为未检测（false）；
• 每simulatedSensorInterval（默认 20 秒）翻转一次；
• 它是 Matter 状态的唯一写入方：loop()中调用setLeak(simulatedHWWaterLeakDetector())；
• LED 由 Matter 上报状态驱动（getLeak()）。

LED 指示约定：

• LED 亮：检测到漏水（Detected）
• LED 灭：未检测到漏水（Not Detected）

模拟函数实现如下（MatterWaterLeakDetector.ino）：

bool simulatedHWWaterLeakDetector() { // Simulated Water Leak Detector. Replace this body with a real sensor, e.g. return digitalRead(leakPin); static bool leakState = false; static uint32_t lastTime = millis(); if (millis() - lastTime > simulatedSensorInterval) { leakState = !leakState; lastTime = millis(); } return leakState; }

接入真实传感器：将simulatedHWWaterLeakDetector()的函数体替换为你的探头读取即可，例如return digitalRead(leakPin);。

loop()中的上报与 LED 驱动逻辑（MatterWaterLeakDetector.ino）：

// Report simulated (or real) hardware to Matter. First call after Matter.begin() applies the current reading. bool previous = WaterLeakDetector.getLeak(); WaterLeakDetector.setLeak(simulatedHWWaterLeakDetector()); if (WaterLeakDetector.getLeak() != previous) { Serial.printf("Water Leak Detector is %s.\r\n", WaterLeakDetector ? "Detected" : "Not Detected"); } digitalWrite(ledPin, WaterLeakDetector ? HIGH : LOW);

注意这里WaterLeakDetector对象直接用于布尔上下文（WaterLeakDetector ? ... : ...），这是端点类提供的operator bool()转换操作符的用法，见 MatterWaterLeakDetector.h。

端点类的底层原理

WaterLeakDetector 端点类 完整封装了 Water Leak Detector 设备类型。其关键实现：

• begin()：初始化 Matter（ArduinoMatter::_init()），创建water_leak_detector::config_t配置结构并调用water_leak_detector::create()在 Matter 节点上创建端点，初始state_value为false，随后记录端点 ID 并将started置为true。源码注释特别指出：CHIP 的 BooleanStateCluster 无论该字段如何设置，初始值都从false开始，因此真正的传感器读数必须通过setLeak()在Matter.begin()之后写入。
• setLeak(bool)：状态变化检测与上报。若状态未变化直接返回true；否则通过setBooleanStateValue(_leakState)更新 Matter 属性并同步本地leakState。注意 MatterEndPoint.h 中的说明：BooleanState 的StateValue在 ESP Matter 1.5+ 中由代码驱动管理，attribute::update()会返回ESP_ERR_NOT_SUPPORTED（错误码 262），因此必须使用集群 settersetBooleanStateValue()而不是通用的属性更新接口。
• getLeak()：返回当前缓存的漏状态（MatterWaterLeakDetector.h）。
• attributeChangeCB()：Matter 内部事件处理器回调，当控制器修改端点属性时被触发。默认实现仅记录日志并返回true，应用可按需覆写（MatterWaterLeakDetector.cpp）。

该端点类与其余 20 余种端点（如 MatterContactSensor、MatterTemperatureSensor）一样继承自 MatterEndPoint 基类，共享端点 ID 管理、属性读写、Identify Cluster 回调、Descriptor TagList 等通用机制，因此本示例的端点上电与配网流程可平滑复用到其他传感器类 Matter 设备。

智能家居生态接入

使用 Matter 兼容的中枢设备（如 Apple HomePod、Google Nest Hub 或 Amazon Echo）即可对设备执行配网。配网前请确认 Matter Controller 侧支持 Water Leak Detector 端点——该端点属于 Matter 最新的受支持设备列表，你的 Matter 环境可能尚未完全支持它。也可以尝试使用 Home Assistant 的 Matter 功能进行测试。

Apple Home

1. 打开 iOS 设备上的 Home（家庭）App；
2. 点击 "+" 按钮 > 添加配件（Add Accessory）；
3. 扫描串口监视器中显示的 QR 码，或者
4. 点击"我没有代码或无法扫描"，输入手动配对码；
5. 按照提示完成设置；
6. 设备将作为水浸检测器出现在 Home App 中；
7. 你可以查看水浸检测状态（Detected / Not Detected），并在状态变化时接收通知。

Amazon Alexa

1. 打开 Alexa App；
2. 依次点击 More（更多）> Add Device（添加设备）> Matter；
3. 选择"扫描 QR 码"或"手动输入代码"；
4. 完成设置流程；
5. 水浸检测器将出现在 Alexa App 中；
6. 你可以查看水浸检测状态，并基于状态变化设置例程（routines）。

Google Home

1. 打开 Google Home App；
2. 点击 "+" > 设置设备（Set up device）> 新设备（New device）；
3. 选择 "Matter 设备"（Matter device）；
4. 扫描 QR 码或输入手动配对码；
5. 按照提示完成设置；
6. 水浸检测器将出现在 Google Home App 中。

代码结构总览

MatterWaterLeakDetector 示例由以下核心组件构成：

1. setup()：初始化硬件（按键、LED），按需配置 Wi-Fi（仅 ESP32 / ESP32-S2），通过WaterLeakDetector.begin()创建 Water Leak Detector 端点（fabric 状态初始为 Not Detected），随后调用Matter.begin()启动 Matter，并等待配网完成。
2. loop()：仅处理按键的恢复出厂逻辑；在Matter.begin()之后用setLeak()上报模拟（或真实）传感器读数；用getLeak()更新 LED 状态。
3. simulatedHWWaterLeakDetector()：模拟硬件水浸检测器，每simulatedSensorInterval翻转一次状态。接入真实传感器时替换该函数即可。

常见问题排查（Troubleshooting）

• 配网时设备不可见：确认 Wi-Fi 或 Thread 连接已正确配置。
• LED 无响应：检查引脚配置与实际接线。
• 水浸检测状态不更新：setLeak()必须在Matter.begin()之后调用——begin()只创建端点，不接收初始状态。模拟传感器每simulatedSensorInterval（默认 20 秒）翻转一次，可通过串口监视器输出确认状态变化是否被处理。
• 配网失败：尝试长按按键恢复出厂设置；另一种方式是擦除 SoC Flash：在 Arduino IDE 菜单Tools > Erase All Flash Before Sketch Upload中启用 "Enabled"，或直接执行esptool.py --port <PORT> erase_flash。
• 无串口输出：检查波特率是否为 115200，并确认 USB 连接正常。

扩展阅读

• Matter 端点基类 MatterEndPoint：端点 ID、属性读写、Identify 回调与 TagList 等通用机制；
• Matter Water Leak Detector 端点类：本示例的端点底层实现；
• Matter 管理器 API（Matter.h）：配网码、配对码、设备状态查询与 decommission 等静态接口；
• Matter 库其他端点：接触传感器、温度传感器等同族传感器端点实现；
• 更多 Matter 使用方式可参考仓库 libraries/Matter/examples 下的其他示例。

许可说明

本示例基于 Apache License, Version 2.0 许可发布（见 示例源码文件头）。

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