Files

T

gusenkovs be7c60e4dd 3.3.7

2026-05-22 21:52:50 +03:00

8.8 KiB

Raw Permalink Blame History

Matter Water Leak Detector Example

This example demonstrates how to create a Matter-compatible water leak detector device using an ESP32 SoC microcontroller.
The application showcases Matter commissioning, device control via smart home ecosystems, manual control using a physical button, and automatic simulation of water leak detection state changes.

Supported Targets

SoC	Wi-Fi	Thread	BLE Commissioning	LED	Status
ESP32	✅	❌	❌	Required	Fully supported
ESP32-S2	✅	❌	❌	Required	Fully supported
ESP32-S3	✅	❌	✅	Required	Fully supported
ESP32-C3	✅	❌	✅	Required	Fully supported
ESP32-C5	❌	✅	✅	Required	Supported (Thread only)
ESP32-C6	✅	❌	✅	Required	Fully supported
ESP32-H2	❌	✅	✅	Required	Supported (Thread only)

Note on Commissioning:

ESP32 & ESP32-S2 do not support commissioning over Bluetooth LE. For these chips, you must provide Wi-Fi credentials directly in the sketch code so they can connect to your network manually.
ESP32-C6 Although it has Thread support, the ESP32 Arduino Matter Library has been pre compiled using Wi-Fi only. In order to configure it for Thread-only operation it is necessary to build the project using Arduino as an IDF Component and to disable the Matter Wi-Fi station feature.
ESP32-C5 Although it has Wi-Fi 2.4 GHz and 5 GHz support, the ESP32 Arduino Matter Library has been pre compiled using Thread only. In order to configure it for Wi-Fi operation it is necessary to build the project using Arduino as an ESP-IDF component and disable Thread network, keeping only Wi-Fi station.

Features

Matter protocol implementation for a water leak detector device
Support for both Wi-Fi and Thread(*) connectivity
Water leak detection state indication using LED (ON = Detected, OFF = Not Detected)
Automatic simulation of water leak detection state changes every 20 seconds
Button control for toggling water leak detection state and factory reset
Matter commissioning via QR code or manual pairing code
Integration with Apple HomeKit, Amazon Alexa, and Google Home (*) It is necessary to compile the project using Arduino as IDF Component.

Hardware Requirements

ESP32 compatible development board (see supported targets table)
LED connected to GPIO pins (or using built-in LED) to indicate water leak detection state
User button for manual control (uses BOOT button by default)

Pin Configuration

LED: Uses RGB_BUILTIN if defined, otherwise pin 2
Button: Uses BOOT_PIN by default

Software Setup

Prerequisites

Install the Arduino IDE (2.0 or newer recommended)
Install ESP32 Arduino Core with Matter support
ESP32 Arduino libraries:
- Matter
- Wi-Fi (only for ESP32 and ESP32-S2)

Configuration

Before uploading the sketch, configure the following:

Wi-Fi credentials (if not using BLE commissioning - mandatory for 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

LED pin configuration (if not using built-in LED):

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

Button pin configuration (optional): By default, the BOOT button (GPIO 0) is used for the Water Leak Detector state toggle and factory reset. You can change this to a different pin if needed.
```
const uint8_t buttonPin = BOOT_PIN;  // Set your button pin here
```

Building and Flashing

Open the MatterWaterLeakDetector.ino sketch in the Arduino IDE.
Select your ESP32 board from the Tools > Board menu.

Select "Huge APP (3MB No OTA/1MB SPIFFS)" from Tools > Partition Scheme menu.

Enable "Erase All Flash Before Sketch Upload" option from Tools menu.
Connect your ESP32 board to your computer via USB.
Click the Upload button to compile and flash the sketch.

Expected Output

Once the sketch is running, open the Serial Monitor at a baud rate of 115200. The Wi-Fi connection messages will be displayed only for ESP32 and ESP32-S2. Other targets will use Matter CHIPoBLE to automatically setup the IP Network. You should see output similar to the following, which provides the necessary information for commissioning:

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.
User button released. Setting the Water Leak Detector to Detected.
User button released. Setting the Water Leak Detector to Not Detected.

Using the Device

Manual Control

The user button (BOOT button by default) provides manual control:

Short press of the button: Toggle water leak detector state (Not Detected/Detected)
Long press (>5 seconds): Factory reset the device (decommission)

Automatic Simulation

The water leak detector state automatically toggles every 20 seconds to simulate a real water leak detector. The LED will reflect the current state:

LED ON: Water leak is Detected
LED OFF: Water leak is Not Detected

Smart Home Integration

Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon Echo) to commission the device. Check for Matter Water Leak Detector endpoint support within the Matter Controller developer webpage. This endpoint is part of the latest Matter supported device list and it may not be fully supported by your Matter environment. You can also try the Home Assistant Matter feature in order to test it.

Apple Home

Open the Home app on your iOS device
Tap the "+" button > Add Accessory
Scan the QR code displayed in the Serial Monitor, or
Tap "I Don't Have a Code or Cannot Scan" and enter the manual pairing code
Follow the prompts to complete setup
The device will appear as a water leak detector in your Home app
You can monitor the water leak detection state (Detected/Not Detected) and receive notifications when the state changes

Amazon Alexa

Open the Alexa app
Tap More > Add Device > Matter
Select "Scan QR code" or "Enter code manually"
Complete the setup process
The water leak detector will appear in your Alexa app
You can monitor the water leak detection state and set up routines based on state changes

Google Home

Open the Google Home app
Tap "+" > Set up device > New device
Choose "Matter device"
Scan the QR code or enter the manual pairing code
Follow the prompts to complete setup
The water leak detector will appear in your Google Home app

Code Structure

The MatterWaterLeakDetector example consists of the following main components:

setup(): Initializes hardware (button, LED), configures Wi-Fi (if needed), sets up the Matter Water Leak Detector endpoint with initial state (Not Detected), and waits for Matter commissioning.
loop(): Handles button input for toggling water leak detection state and factory reset, and automatically simulates water leak detection state changes every 20 seconds.
simulatedHWWaterLeakDetector(): Simulates a hardware water leak detector by toggling the water leak detection state every 20 seconds.

Troubleshooting

Device not visible during commissioning: Ensure Wi-Fi or Thread connectivity is properly configured
LED not responding: Verify pin configurations and connections
Water leak detector state not updating: Check Serial Monitor output to verify state changes are being processed
Failed to commission: Try factory resetting the device by long-pressing the button. Other option would be to erase the SoC Flash Memory by using Arduino IDE Menu -> Tools -> Erase All Flash Before Sketch Upload: "Enabled" or directly with esptool.py --port <PORT> erase_flash
No serial output: Check baudrate (115200) and USB connection

License

This example is licensed under the Apache License, Version 2.0.

8.8 KiB Raw Permalink Blame History