Feat(matter) adds matter water freeze detector endpoint (espressif#12101)

* feat(matter): adds water freeze detector matter endpoint

* fix(matter): mixed branches

* ci(pre-commit): Apply automatic fixes

---------

Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com>
Co-authored-by: Me No Dev <[email protected]>

Author: 3 people

CMakeLists.txt

@@ -193,6 +193,7 @@ set(ARDUINO_LIBRARY_Matter_SRCS
   libraries/Matter/src/MatterEndpoints/MatterTemperatureSensor.cpp
   libraries/Matter/src/MatterEndpoints/MatterHumiditySensor.cpp
   libraries/Matter/src/MatterEndpoints/MatterContactSensor.cpp
+  libraries/Matter/src/MatterEndpoints/MatterWaterFreezeDetector.cpp
   libraries/Matter/src/MatterEndpoints/MatterRainSensor.cpp
   libraries/Matter/src/MatterEndpoints/MatterPressureSensor.cpp
   libraries/Matter/src/MatterEndpoints/MatterOccupancySensor.cpp

docs/en/matter/ep_water_freeze_detector.rst

@@ -0,0 +1,137 @@
+###########################
+MatterWaterFreezeDetector
+###########################
+
+About
+-----
+
+The ``MatterWaterFreezeDetector`` class provides a water freeze detector endpoint for Matter networks. This endpoint implements the Matter water freeze detection standard for detecting water freeze conditions (detected/not detected states).
+
+**Features:**
+* Water freeze detection state reporting (detected/not detected)
+* Simple boolean state
+* Read-only sensor (no control functionality)
+* Automatic state updates
+* Integration with Apple HomeKit, Amazon Alexa, and Google Home
+* Matter standard compliance
+
+**Use Cases:**
+* Water pipe freeze monitoring
+* Outdoor water system protection
+* HVAC freeze detection
+* Smart home automation triggers
+* Preventative maintenance systems
+
+API Reference
+-------------
+
+Constructor
+***********
+
+MatterWaterFreezeDetector
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Creates a new Matter water freeze detector endpoint.
+
+.. code-block:: arduino
+
+    MatterWaterFreezeDetector();
+
+Initialization
+**************
+
+begin
+^^^^^
+
+Initializes the Matter water freeze detector endpoint with an initial freeze detection state.
+
+.. code-block:: arduino
+
+    bool begin(bool _freezeState = false);
+
+* ``_freezeState`` - Initial water freeze detection state (``true`` = detected, ``false`` = not detected, default: ``false``)
+
+This function will return ``true`` if successful, ``false`` otherwise.
+
+end
+^^^
+
+Stops processing Matter water freeze detector events.
+
+.. code-block:: arduino
+
+    void end();
+
+Water Freeze Detection State Control
+************************************
+
+setFreeze
+^^^^^^^^^
+
+Sets the water freeze detection state.
+
+.. code-block:: arduino
+
+    bool setFreeze(bool _freezeState);
+
+* ``_freezeState`` - Water freeze detection state (``true`` = detected, ``false`` = not detected)
+
+This function will return ``true`` if successful, ``false`` otherwise.
+
+getFreeze
+^^^^^^^^^
+
+Gets the current water freeze detection state.
+
+.. code-block:: arduino
+
+    bool getFreeze();
+
+This function will return ``true`` if water freeze is detected, ``false`` if not detected.
+
+Operators
+*********
+
+bool operator
+^^^^^^^^^^^^^
+
+Returns the current water freeze detection state.
+
+.. code-block:: arduino
+
+    operator bool();
+
+Example:
+
+.. code-block:: arduino
+
+    if (myDetector) {
+        Serial.println("Water freeze is detected");
+    } else {
+        Serial.println("Water freeze is not detected");
+    }
+
+Assignment operator
+^^^^^^^^^^^^^^^^^^^
+
+Sets the water freeze detection state.
+
+.. code-block:: arduino
+
+    void operator=(bool _freezeState);
+
+Example:
+
+.. code-block:: arduino
+
+    myDetector = true;   // Set water freeze detection to detected
+    myDetector = false;  // Set water freeze detection to not detected
+
+Example
+-------
+
+Water Freeze Detector
+*********************
+
+.. literalinclude:: ../../../libraries/Matter/examples/MatterWaterFreezeDetector/MatterWaterFreezeDetector.ino
+    :language: arduino

docs/en/matter/matter.rst

@@ -126,6 +126,7 @@ The library provides specialized endpoint classes for different device types. Ea
 * ``MatterHumiditySensor``: Humidity sensor (read-only)
 * ``MatterPressureSensor``: Pressure sensor (read-only)
 * ``MatterContactSensor``: Contact sensor (open/closed state)
+* ``MatterWaterFreezeDetector``: Water freeze detector (detected/not detected state)
 * ``MatterRainSensor``: Rain sensor (detected/not detected state)
 * ``MatterOccupancySensor``: Occupancy sensor (occupied/unoccupied state)
 

libraries/Matter/examples/MatterWaterFreezeDetector/MatterWaterFreezeDetector.ino

@@ -0,0 +1,161 @@
+// Copyright 2025 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/*
+ * This example is an example code that will create a Matter Device which can be
+ * commissioned and controlled from a Matter Environment APP.
+ * Additionally the ESP32 will send debug messages indicating the Matter activity.
+ * Turning DEBUG Level ON may be useful to following Matter Accessory and Controller messages.
+ *
+ * The example will create a Matter Water Freeze Detector Device.
+ * The Water Freeze Detector state can be toggled by pressing the onboard button.
+ * The Water Freeze Detector state will be indicated by the onboard LED.
+ * The Water Freeze Detector state will be simulated to change every 20 seconds.
+ *
+ * The onboard button can be kept pressed for 5 seconds to decommission the Matter Node.
+ * The example will also show the manual commissioning code and QR code to be used in the Matter environment.
+ *
+ */
+
+// Matter Manager
+#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
+
+// List of Matter Endpoints for this Node
+// Matter Water Freeze Detector Endpoint
+MatterWaterFreezeDetector WaterFreezeDetector;
+
+// CONFIG_ENABLE_CHIPOBLE is enabled when BLE is used to commission the Matter Network
+#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
+
+// LED will be used to indicate the Water Freeze 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 and Manual Water Freeze Detector toggle button
+const uint8_t buttonPin = BOOT_PIN;  // Set your pin here. Using BOOT Button.
+
+// Button control
+uint32_t button_time_stamp = 0;                // debouncing control
+bool button_state = false;                     // false = released | true = pressed
+const uint32_t debouceTime = 250;              // button debouncing time (ms)
+const uint32_t decommissioningTimeout = 5000;  // keep the button pressed for 5s, or longer, to decommission
+
+void setup() {
+  // Initialize the USER BUTTON (Boot button) that will be used to decommission the Matter Node
+  // The button will also be used to manually toggle the Water Freeze Detector state
+  pinMode(buttonPin, INPUT_PULLUP);
+  // Initialize the LED (light) GPIO and Matter End Point
+  pinMode(ledPin, OUTPUT);
+
+  Serial.begin(115200);
+
+// CONFIG_ENABLE_CHIPOBLE is enabled when BLE is used to commission the Matter Network
+#if !CONFIG_ENABLE_CHIPOBLE
+  // Manually connect to WiFi
+  WiFi.begin(ssid, password);
+  // Wait for connection
+  while (WiFi.status() != WL_CONNECTED) {
+    delay(500);
+    Serial.print(".");
+  }
+  Serial.println();
+#endif
+
+  // set initial water freeze detector state as false (default)
+  WaterFreezeDetector.begin();
+  digitalWrite(ledPin, LOW);  // LED OFF
+
+  // Matter beginning - Last step, after all EndPoints are initialized
+  Matter.begin();
+
+  // Check Matter Accessory Commissioning state, which may change during execution of loop()
+  if (!Matter.isDeviceCommissioned()) {
+    Serial.println("");
+    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 Freeze 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.");
+  }
+}
+
+bool simulatedHWWaterFreezeDetector() {
+  // Simulated Water Freeze Detector
+  static bool freezeState = false;
+  static uint32_t lastTime = 0;
+
+  // Simulate a Water Freeze Detector state change every 20 seconds
+  if (millis() - lastTime > 20000) {
+    freezeState = !freezeState;
+    lastTime = millis();
+  }
+  return freezeState;
+}
+
+void loop() {
+  // Check if the button has been pressed
+  if (digitalRead(buttonPin) == LOW && !button_state) {
+    // deals with button debouncing
+    button_time_stamp = millis();  // record the time while the button is pressed.
+    button_state = true;           // pressed.
+  }
+
+  uint32_t time_diff = millis() - button_time_stamp;
+  if (button_state && time_diff > debouceTime && digitalRead(buttonPin) == HIGH) {
+    button_state = false;  // released
+    // button is released - toggle Freeze State (Not Detected/Detected)
+    WaterFreezeDetector.setFreeze(!WaterFreezeDetector.getFreeze());  // same as WaterFreezeDetector = !WaterFreezeDetector;
+    Serial.printf("User button released. Setting the Water Freeze Detector to %s.\r\n", WaterFreezeDetector ? "Detected" : "Not Detected");
+    // LED will indicate the Water Freeze Detector state
+    if (WaterFreezeDetector) {
+      digitalWrite(ledPin, HIGH);  // LED ON
+    } else {
+      digitalWrite(ledPin, LOW);  // LED OFF
+    }
+  }
+
+  // Onboard User Button is kept pressed for longer than 5 seconds in order to decommission matter node
+  if (button_state && time_diff > decommissioningTimeout) {
+    Serial.println("Decommissioning Water Freeze Detector Matter Accessory. It shall be commissioned again.");
+    Matter.decommission();
+    button_time_stamp = millis();  // avoid running decommissining again, reboot takes a second or so
+  }
+
+  // Simulated Water Freeze Detector
+  WaterFreezeDetector.setFreeze(simulatedHWWaterFreezeDetector());
+
+  delay(50);
+}