feat(matter): adds rain sensor matter endpoint (#12100)

* feat(matter): adds rain sensor matter endpoint

* feat(matter): adds source code to CMakeLists.txt

* ci(pre-commit): Apply automatic fixes

---------

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

Author: SuGlider

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/MatterRainSensor.cpp
   libraries/Matter/src/MatterEndpoints/MatterPressureSensor.cpp
   libraries/Matter/src/MatterEndpoints/MatterOccupancySensor.cpp
   libraries/Matter/src/MatterEndpoints/MatterOnOffPlugin.cpp

docs/en/matter/ep_rain_sensor.rst

@@ -0,0 +1,137 @@
+###################
+MatterRainSensor
+###################
+
+About
+-----
+
+The ``MatterRainSensor`` class provides a rain sensor endpoint for Matter networks. This endpoint implements the Matter rain sensing standard for detecting rain presence (detected/not detected states).
+
+**Features:**
+* Rain 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:**
+* Weather monitoring systems
+* Irrigation control systems
+* Outdoor sensor networks
+* Smart home automation triggers
+* Rain detection for automated systems
+
+API Reference
+-------------
+
+Constructor
+***********
+
+MatterRainSensor
+^^^^^^^^^^^^^^^^
+
+Creates a new Matter rain sensor endpoint.
+
+.. code-block:: arduino
+
+    MatterRainSensor();
+
+Initialization
+**************
+
+begin
+^^^^^
+
+Initializes the Matter rain sensor endpoint with an initial rain detection state.
+
+.. code-block:: arduino
+
+    bool begin(bool _rainState = false);
+
+* ``_rainState`` - Initial rain detection state (``true`` = detected, ``false`` = not detected, default: ``false``)
+
+This function will return ``true`` if successful, ``false`` otherwise.
+
+end
+^^^
+
+Stops processing Matter rain sensor events.
+
+.. code-block:: arduino
+
+    void end();
+
+Rain Detection State Control
+****************************
+
+setRain
+^^^^^^^
+
+Sets the rain detection state.
+
+.. code-block:: arduino
+
+    bool setRain(bool _rainState);
+
+* ``_rainState`` - Rain detection state (``true`` = detected, ``false`` = not detected)
+
+This function will return ``true`` if successful, ``false`` otherwise.
+
+getRain
+^^^^^^^
+
+Gets the current rain detection state.
+
+.. code-block:: arduino
+
+    bool getRain();
+
+This function will return ``true`` if rain is detected, ``false`` if not detected.
+
+Operators
+*********
+
+bool operator
+^^^^^^^^^^^^^
+
+Returns the current rain detection state.
+
+.. code-block:: arduino
+
+    operator bool();
+
+Example:
+
+.. code-block:: arduino
+
+    if (mySensor) {
+        Serial.println("Rain is detected");
+    } else {
+        Serial.println("Rain is not detected");
+    }
+
+Assignment operator
+^^^^^^^^^^^^^^^^^^^
+
+Sets the rain detection state.
+
+.. code-block:: arduino
+
+    void operator=(bool _rainState);
+
+Example:
+
+.. code-block:: arduino
+
+    mySensor = true;   // Set rain detection to detected
+    mySensor = false;  // Set rain detection to not detected
+
+Example
+-------
+
+Rain Sensor
+***********
+
+.. literalinclude:: ../../../libraries/Matter/examples/MatterRainSensor/MatterRainSensor.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)
+* ``MatterRainSensor``: Rain sensor (detected/not detected state)
 * ``MatterOccupancySensor``: Occupancy sensor (occupied/unoccupied state)
 
 **Control Endpoints:**

libraries/Matter/examples/MatterRainSensor/MatterRainSensor.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 Rain Sensor Device.
+ * The Rain Sensor state can be toggled by pressing the onboard button.
+ * The Rain Sensor state will be indicated by the onboard LED.
+ * The Rain Sensor 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 Rain Sensor Endpoint
+MatterRainSensor RainSensor;
+
+// 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 Rain Sensor 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 Rain Sensor 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 Rain Sensor 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 rain sensor state as false (default)
+  RainSensor.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 Rain Sensor 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 simulatedHWRainSensor() {
+  // Simulated Rain Sensor
+  static bool rainState = false;
+  static uint32_t lastTime = 0;
+
+  // Simulate a Rain Sensor state change every 20 seconds
+  if (millis() - lastTime > 20000) {
+    rainState = !rainState;
+    lastTime = millis();
+  }
+  return rainState;
+}
+
+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 Rain State (Not Detected/Detected)
+    RainSensor.setRain(!RainSensor.getRain());  // same as RainSensor = !RainSensor;
+    Serial.printf("User button released. Setting the Rain Sensor to %s.\r\n", RainSensor ? "Detected" : "Not Detected");
+    // LED will indicate the Rain Sensor state
+    if (RainSensor) {
+      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 Rain Sensor Matter Accessory. It shall be commissioned again.");
+    Matter.decommission();
+    button_time_stamp = millis();  // avoid running decommissining again, reboot takes a second or so
+  }
+
+  // Simulated Rain Sensor
+  RainSensor.setRain(simulatedHWRainSensor());
+
+  delay(50);
+}