Skip to content

Commit 9b3364c

Browse files
SuGliderpre-commit-ci-lite[bot]me-no-devCopilot
authored
feat(matter): adds water leak detector ep (#12102)
* feat(matter): adds water leak detector matter endpoint * feat(matter): fix matter.h conflicts * ci(pre-commit): Apply automatic fixes * fix(matter): spelling Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * fix(matter): formatting Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * fix(matter): fix var name - spelling --------- Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com> Co-authored-by: Me No Dev <me-no-dev@users.noreply.github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent 471dcb0 commit 9b3364c

File tree

10 files changed

+648
-0
lines changed

10 files changed

+648
-0
lines changed

‎CMakeLists.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -193,6 +193,7 @@ set(ARDUINO_LIBRARY_Matter_SRCS
193193
libraries/Matter/src/MatterEndpoints/MatterTemperatureSensor.cpp
194194
libraries/Matter/src/MatterEndpoints/MatterHumiditySensor.cpp
195195
libraries/Matter/src/MatterEndpoints/MatterContactSensor.cpp
196+
libraries/Matter/src/MatterEndpoints/MatterWaterLeakDetector.cpp
196197
libraries/Matter/src/MatterEndpoints/MatterWaterFreezeDetector.cpp
197198
libraries/Matter/src/MatterEndpoints/MatterRainSensor.cpp
198199
libraries/Matter/src/MatterEndpoints/MatterPressureSensor.cpp

‎docs/en/matter/ep_water_leak_detector.rst‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
##########################
2+
MatterWaterLeakDetector
3+
##########################
4+
5+
About
6+
-----
7+
8+
The ``MatterWaterLeakDetector`` class provides a water leak detector endpoint for Matter networks. This endpoint implements the Matter water leak detection standard for detecting water leak conditions (detected/not detected states).
9+
10+
**Features:**
11+
* Water leak detection state reporting (detected/not detected)
12+
* Simple boolean state
13+
* Read-only sensor (no control functionality)
14+
* Automatic state updates
15+
* Integration with Apple HomeKit, Amazon Alexa, and Google Home
16+
* Matter standard compliance
17+
18+
**Use Cases:**
19+
* Water leak monitoring
20+
* Basement flood detection
21+
* Appliance leak detection
22+
* Smart home automation triggers
23+
* Preventative maintenance systems
24+
25+
API Reference
26+
-------------
27+
28+
Constructor
29+
***********
30+
31+
MatterWaterLeakDetector
32+
^^^^^^^^^^^^^^^^^^^^^^^^^
33+
34+
Creates a new Matter water leak detector endpoint.
35+
36+
.. code-block:: arduino
37+
38+
MatterWaterLeakDetector();
39+
40+
Initialization
41+
**************
42+
43+
begin
44+
^^^^^
45+
46+
Initializes the Matter water leak detector endpoint with an initial leak detection state.
47+
48+
.. code-block:: arduino
49+
50+
bool begin(bool _leakState = false);
51+
52+
* ``_leakState`` - Initial water leak detection state (``true`` = detected, ``false`` = not detected, default: ``false``)
53+
54+
This function will return ``true`` if successful, ``false`` otherwise.
55+
56+
end
57+
^^^
58+
59+
Stops processing Matter water leak detector events.
60+
61+
.. code-block:: arduino
62+
63+
void end();
64+
65+
Water Leak Detection State Control
66+
***********************************
67+
68+
setLeak
69+
^^^^^^^^
70+
71+
Sets the water leak detection state.
72+
73+
.. code-block:: arduino
74+
75+
bool setLeak(bool _leakState);
76+
77+
* ``_leakState`` - Water leak detection state (``true`` = detected, ``false`` = not detected)
78+
79+
This function will return ``true`` if successful, ``false`` otherwise.
80+
81+
getLeak
82+
^^^^^^^
83+
84+
Gets the current water leak detection state.
85+
86+
.. code-block:: arduino
87+
88+
bool getLeak();
89+
90+
This function will return ``true`` if water leak is detected, ``false`` if not detected.
91+
92+
Operators
93+
*********
94+
95+
bool operator
96+
^^^^^^^^^^^^^
97+
98+
Returns the current water leak detection state.
99+
100+
.. code-block:: arduino
101+
102+
operator bool();
103+
104+
Example:
105+
106+
.. code-block:: arduino
107+
108+
if (myDetector) {
109+
Serial.println("Water leak is detected");
110+
} else {
111+
Serial.println("Water leak is not detected");
112+
}
113+
114+
Assignment operator
115+
^^^^^^^^^^^^^^^^^^^
116+
117+
Sets the water leak detection state.
118+
119+
.. code-block:: arduino
120+
121+
void operator=(bool _leakState);
122+
123+
Example:
124+
125+
.. code-block:: arduino
126+
127+
myDetector = true; // Set water leak detection to detected
128+
myDetector = false; // Set water leak detection to not detected
129+
130+
Example
131+
-------
132+
133+
Water Leak Detector
134+
********************
135+
136+
.. literalinclude:: ../../../libraries/Matter/examples/MatterWaterLeakDetector/MatterWaterLeakDetector.ino
137+
:language: arduino

‎docs/en/matter/matter.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,7 @@ The library provides specialized endpoint classes for different device types. Ea
126126
* ``MatterHumiditySensor``: Humidity sensor (read-only)
127127
* ``MatterPressureSensor``: Pressure sensor (read-only)
128128
* ``MatterContactSensor``: Contact sensor (open/closed state)
129+
* ``MatterWaterLeakDetector``: Water leak detector (detected/not detected state)
129130
* ``MatterWaterFreezeDetector``: Water freeze detector (detected/not detected state)
130131
* ``MatterRainSensor``: Rain sensor (detected/not detected state)
131132
* ``MatterOccupancySensor``: Occupancy sensor (occupied/unoccupied state)

‎libraries/Matter/examples/MatterWaterLeakDetector/MatterWaterLeakDetector.ino‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
// Copyright 2025 Espressif Systems (Shanghai) PTE LTD
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
/*
16+
* This example is an example code that will create a Matter Device which can be
17+
* commissioned and controlled from a Matter Environment APP.
18+
* Additionally the ESP32 will send debug messages indicating the Matter activity.
19+
* Turning DEBUG Level ON may be useful to following Matter Accessory and Controller messages.
20+
*
21+
* The example will create a Matter Water Leak Detector Device.
22+
* The Water Leak Detector state can be toggled by pressing the onboard button.
23+
* The Water Leak Detector state will be indicated by the onboard LED.
24+
* The Water Leak Detector state will be simulated to change every 20 seconds.
25+
*
26+
* The onboard button can be kept pressed for 5 seconds to decommission the Matter Node.
27+
* The example will also show the manual commissioning code and QR code to be used in the Matter environment.
28+
*
29+
*/
30+
31+
// Matter Manager
32+
#include <Matter.h>
33+
#if !CONFIG_ENABLE_CHIPOBLE
34+
// if the device can be commissioned using BLE, WiFi is not used - save flash space
35+
#include <WiFi.h>
36+
#endif
37+
38+
// List of Matter Endpoints for this Node
39+
// Matter Water Leak Detector Endpoint
40+
MatterWaterLeakDetector WaterLeakDetector;
41+
42+
// CONFIG_ENABLE_CHIPOBLE is enabled when BLE is used to commission the Matter Network
43+
#if !CONFIG_ENABLE_CHIPOBLE
44+
// WiFi is manually set and started
45+
const char *ssid = "your-ssid"; // Change this to your WiFi SSID
46+
const char *password = "your-password"; // Change this to your WiFi password
47+
#endif
48+
49+
// LED will be used to indicate the Water Leak Detector state
50+
// set your board RGB LED pin here
51+
#ifdef RGB_BUILTIN
52+
const uint8_t ledPin = RGB_BUILTIN;
53+
#else
54+
const uint8_t ledPin = 2; // Set your pin here if your board has not defined LED_BUILTIN
55+
#warning "Do not forget to set the RGB LED pin"
56+
#endif
57+
58+
// set your board USER BUTTON pin here - decommissioning and Manual Water Leak Detector toggle button
59+
const uint8_t buttonPin = BOOT_PIN; // Set your pin here. Using BOOT Button.
60+
61+
// Button control
62+
uint32_t button_time_stamp = 0; // debouncing control
63+
bool button_state = false; // false = released | true = pressed
64+
const uint32_t debounceTime = 250; // button debouncing time (ms)
65+
const uint32_t decommissioningTimeout = 5000; // keep the button pressed for 5s, or longer, to decommission
66+
67+
void setup() {
68+
// Initialize the USER BUTTON (Boot button) that will be used to decommission the Matter Node
69+
// The button will also be used to manually toggle the Water Leak Detector state
70+
pinMode(buttonPin, INPUT_PULLUP);
71+
// Initialize the LED (light) GPIO and Matter End Point
72+
pinMode(ledPin, OUTPUT);
73+
74+
Serial.begin(115200);
75+
76+
// CONFIG_ENABLE_CHIPOBLE is enabled when BLE is used to commission the Matter Network
77+
#if !CONFIG_ENABLE_CHIPOBLE
78+
// Manually connect to WiFi
79+
WiFi.begin(ssid, password);
80+
// Wait for connection
81+
while (WiFi.status() != WL_CONNECTED) {
82+
delay(500);
83+
Serial.print(".");
84+
}
85+
Serial.println();
86+
#endif
87+
88+
// set initial water leak detector state as false (default)
89+
WaterLeakDetector.begin();
90+
digitalWrite(ledPin, LOW); // LED OFF
91+
92+
// Matter beginning - Last step, after all EndPoints are initialized
93+
Matter.begin();
94+
95+
// Check Matter Accessory Commissioning state, which may change during execution of loop()
96+
if (!Matter.isDeviceCommissioned()) {
97+
Serial.println("");
98+
Serial.println("Matter Node is not commissioned yet.");
99+
Serial.println("Initiate the device discovery in your Matter environment.");
100+
Serial.println("Commission it to your Matter hub with the manual pairing code or QR code");
101+
Serial.printf("Manual pairing code: %s\r\n", Matter.getManualPairingCode().c_str());
102+
Serial.printf("QR code URL: %s\r\n", Matter.getOnboardingQRCodeUrl().c_str());
103+
// waits for Matter Water Leak Detector Commissioning.
104+
uint32_t timeCount = 0;
105+
while (!Matter.isDeviceCommissioned()) {
106+
delay(100);
107+
if ((timeCount++ % 50) == 0) { // 50*100ms = 5 sec
108+
Serial.println("Matter Node not commissioned yet. Waiting for commissioning.");
109+
}
110+
}
111+
Serial.println("Matter Node is commissioned and connected to the network. Ready for use.");
112+
}
113+
}
114+
115+
bool simulatedHWWaterLeakDetector() {
116+
// Simulated Water Leak Detector
117+
static bool leakState = false;
118+
static uint32_t lastTime = 0;
119+
120+
// Simulate a Water Leak Detector state change every 20 seconds
121+
if (millis() - lastTime > 20000) {
122+
leakState = !leakState;
123+
lastTime = millis();
124+
}
125+
return leakState;
126+
}
127+
128+
void loop() {
129+
// Check if the button has been pressed
130+
if (digitalRead(buttonPin) == LOW && !button_state) {
131+
// deals with button debouncing
132+
button_time_stamp = millis(); // record the time while the button is pressed.
133+
button_state = true; // pressed.
134+
}
135+
136+
uint32_t time_diff = millis() - button_time_stamp;
137+
if (button_state && time_diff > debounceTime && digitalRead(buttonPin) == HIGH) {
138+
button_state = false; // released
139+
// button is released - toggle Leak State (Not Detected/Detected)
140+
WaterLeakDetector.setLeak(!WaterLeakDetector.getLeak()); // same as WaterLeakDetector = !WaterLeakDetector;
141+
Serial.printf("User button released. Setting the Water Leak Detector to %s.\r\n", WaterLeakDetector ? "Detected" : "Not Detected");
142+
// LED will indicate the Water Leak Detector state
143+
if (WaterLeakDetector) {
144+
digitalWrite(ledPin, HIGH); // LED ON
145+
} else {
146+
digitalWrite(ledPin, LOW); // LED OFF
147+
}
148+
}
149+
150+
// Onboard User Button is kept pressed for longer than 5 seconds in order to decommission matter node
151+
if (button_state && time_diff > decommissioningTimeout) {
152+
Serial.println("Decommissioning Water Leak Detector Matter Accessory. It shall be commissioned again.");
153+
Matter.decommission();
154+
button_time_stamp = millis(); // avoid running decommissioning again, reboot takes a second or so
155+
}
156+
157+
// Simulated Water Leak Detector
158+
WaterLeakDetector.setLeak(simulatedHWWaterLeakDetector());
159+
160+
delay(50);
161+
}

0 commit comments

Comments
 (0)