feat(matter): organize examples, keywords and fix init error

Author: SuGlider

docs/en/matter/ep_temperature_controlled_cabinet.rst

@@ -279,15 +279,15 @@ Example
 Temperature Controlled Cabinet
 ******************************
 
-The example demonstrates the temperature_number mode with dynamic temperature updates. The temperature setpoint automatically cycles between the minimum and maximum limits every 1 second using the configured step value, allowing Matter controllers to observe real-time changes.
+The example demonstrates the temperature_number mode with dynamic temperature updates. The temperature setpoint automatically cycles between the minimum and maximum limits every 1 second using the configured step value, allowing Matter controllers to observe real-time changes. The example also monitors and logs when the initial setpoint is reached or overpassed in each direction.
 
 .. literalinclude:: ../../../libraries/Matter/examples/MatterTemperatureControlledCabinet/MatterTemperatureControlledCabinet.ino
     :language: arduino
 
 Temperature Controlled Cabinet (Level Mode)
 ********************************************
 
-A separate example demonstrates the temperature_level mode with dynamic level updates. The temperature level automatically cycles through all supported levels every 1 second, allowing Matter controllers to observe real-time changes.
+A separate example demonstrates the temperature_level mode with dynamic level updates. The temperature level automatically cycles through all supported levels every 1 second in both directions (increasing and decreasing), allowing Matter controllers to observe real-time changes. The example also monitors and logs when the initial level is reached or overpassed in each direction.
 
 See ``MatterTemperatureControlledCabinetLevels`` example for the temperature level mode implementation.
 

libraries/Matter/examples/MatterTemperatureControlledCabinet/MatterTemperatureControlledCabinet.ino

@@ -3,7 +3,7 @@
 // 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
@@ -53,6 +53,119 @@ uint32_t button_time_stamp = 0;                // debouncing control
 bool button_state = false;                     // false = released | true = pressed
 const uint32_t decommissioningTimeout = 5000;  // keep the button pressed for 5s, or longer, to decommission
 
+// Temperature control state
+struct TemperatureControlState {
+  bool initialized;
+  bool increasing;
+  double currentSetpoint;
+  double initialSetpoint;
+  bool setpointReachedIncreasing;
+  bool setpointReachedDecreasing;
+};
+
+static TemperatureControlState tempState = {
+  .initialized = false,
+  .increasing = true,
+  .currentSetpoint = 0.0,
+  .initialSetpoint = 0.0,
+  .setpointReachedIncreasing = false,
+  .setpointReachedDecreasing = false
+};
+
+// Initialize temperature control state
+void initTemperatureControl() {
+  if (!tempState.initialized) {
+    tempState.currentSetpoint = TemperatureCabinet.getTemperatureSetpoint();
+    tempState.initialSetpoint = tempState.currentSetpoint;
+    tempState.initialized = true;
+  }
+}
+
+// Check and log when initial setpoint is reached/overpassed
+void checkSetpointReached(double newSetpoint, bool isIncreasing, bool directionChanged) {
+  if (directionChanged) {
+    // Reset flags when direction changes
+    tempState.setpointReachedIncreasing = false;
+    tempState.setpointReachedDecreasing = false;
+    return;
+  }
+
+  if (isIncreasing && !tempState.setpointReachedIncreasing && newSetpoint >= tempState.initialSetpoint) {
+    Serial.printf("*** Temperature setpoint %.02f°C reached/overpassed while increasing ***\r\n", tempState.initialSetpoint);
+    tempState.setpointReachedIncreasing = true;
+  } else if (!isIncreasing && !tempState.setpointReachedDecreasing && newSetpoint <= tempState.initialSetpoint) {
+    Serial.printf("*** Temperature setpoint %.02f°C reached/overpassed while decreasing ***\r\n", tempState.initialSetpoint);
+    tempState.setpointReachedDecreasing = true;
+  }
+}
+
+// Update temperature setpoint with cycling logic
+void updateTemperatureSetpoint() {
+  double minTemp = TemperatureCabinet.getMinTemperature();
+  double maxTemp = TemperatureCabinet.getMaxTemperature();
+  double step = TemperatureCabinet.getStep();
+  
+  // Calculate next setpoint based on direction and step
+  bool directionChanged = false;
+  
+  if (tempState.increasing) {
+    tempState.currentSetpoint += step;
+    if (tempState.currentSetpoint >= maxTemp) {
+      tempState.currentSetpoint = maxTemp;
+      tempState.increasing = false;  // Reverse direction
+      directionChanged = true;
+    }
+  } else {
+    tempState.currentSetpoint -= step;
+    if (tempState.currentSetpoint <= minTemp) {
+      tempState.currentSetpoint = minTemp;
+      tempState.increasing = true;  // Reverse direction
+      directionChanged = true;
+    }
+  }
+  
+  // Check if setpoint has been reached or overpassed
+  checkSetpointReached(tempState.currentSetpoint, tempState.increasing, directionChanged);
+  
+  // Update the temperature setpoint
+  if (TemperatureCabinet.setTemperatureSetpoint(tempState.currentSetpoint)) {
+    Serial.printf("Temperature setpoint updated to: %.02f°C (Range: %.02f°C to %.02f°C)\r\n", 
+                  tempState.currentSetpoint, minTemp, maxTemp);
+  } else {
+    Serial.printf("Failed to update temperature setpoint to: %.02f°C\r\n", tempState.currentSetpoint);
+  }
+}
+
+// Print current temperature status
+void printTemperatureStatus() {
+  Serial.printf("Current Temperature Setpoint: %.02f°C (Range: %.02f°C to %.02f°C)\r\n", 
+                TemperatureCabinet.getTemperatureSetpoint(),
+                TemperatureCabinet.getMinTemperature(),
+                TemperatureCabinet.getMaxTemperature());
+}
+
+// Handle button press for decommissioning
+void handleButtonPress() {
+  // 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.
+  }
+
+  if (digitalRead(buttonPin) == HIGH && button_state) {
+    button_state = false;  // released
+  }
+
+  // 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 Temperature Controlled Cabinet Matter Accessory. It shall be commissioned again.");
+    Matter.decommission();
+    button_time_stamp = millis();  // avoid running decommissining again, reboot takes a second or so
+  }
+}
+
 void setup() {
   // Initialize the USER BUTTON (Boot button) that will be used to decommission the Matter Node
   pinMode(buttonPin, INPUT_PULLUP);
@@ -111,77 +224,24 @@ void setup() {
 void loop() {
   static uint32_t timeCounter = 0;
   static uint32_t lastUpdateTime = 0;
-  static bool initialized = false;
-  static bool increasing = true;  // Direction of temperature change
-  static double currentSetpoint = 0.0;  // Will be initialized from actual setpoint
-
-  // Initialize currentSetpoint from actual setpoint on first run
-  if (!initialized) {
-    currentSetpoint = TemperatureCabinet.getTemperatureSetpoint();
-    initialized = true;
-  }
+
+  // Initialize temperature control state on first run
+  initTemperatureControl();
 
   // Update temperature setpoint dynamically every 1 second
   uint32_t currentTime = millis();
   if (currentTime - lastUpdateTime >= 1000) {  // 1 second interval
     lastUpdateTime = currentTime;
-    
-    double minTemp = TemperatureCabinet.getMinTemperature();
-    double maxTemp = TemperatureCabinet.getMaxTemperature();
-    double step = TemperatureCabinet.getStep();
-    
-    // Calculate next setpoint based on direction and step
-    if (increasing) {
-      currentSetpoint += step;
-      if (currentSetpoint >= maxTemp) {
-        currentSetpoint = maxTemp;
-        increasing = false;  // Reverse direction
-      }
-    } else {
-      currentSetpoint -= step;
-      if (currentSetpoint <= minTemp) {
-        currentSetpoint = minTemp;
-        increasing = true;  // Reverse direction
-      }
-    }
-    
-    // Update the temperature setpoint
-    if (TemperatureCabinet.setTemperatureSetpoint(currentSetpoint)) {
-      Serial.printf("Temperature setpoint updated to: %.02f°C (Range: %.02f°C to %.02f°C)\r\n", 
-                    currentSetpoint, minTemp, maxTemp);
-    } else {
-      Serial.printf("Failed to update temperature setpoint to: %.02f°C\r\n", currentSetpoint);
-    }
+    updateTemperatureSetpoint();
   }
 
   // Print the current temperature setpoint every 5s
   if (!(timeCounter++ % 10)) {  // delaying for 500ms x 10 = 5s
-    // Print the current temperature setpoint value
-    Serial.printf("Current Temperature Setpoint: %.02f°C (Range: %.02f°C to %.02f°C)\r\n", 
-                  TemperatureCabinet.getTemperatureSetpoint(),
-                  TemperatureCabinet.getMinTemperature(),
-                  TemperatureCabinet.getMaxTemperature());
+    printTemperatureStatus();
   }
 
-  // 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.
-  }
-
-  if (digitalRead(buttonPin) == HIGH && button_state) {
-    button_state = false;  // released
-  }
-
-  // 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 Temperature Controlled Cabinet Matter Accessory. It shall be commissioned again.");
-    Matter.decommission();
-    button_time_stamp = millis();  // avoid running decommissining again, reboot takes a second or so
-  }
+  // Handle button press for decommissioning
+  handleButtonPress();
 
   delay(500);
 }
-

libraries/Matter/examples/MatterTemperatureControlledCabinet/README.md

@@ -115,10 +115,14 @@ Temperature Controlled Cabinet Configuration:
   Max Temperature: 10.00°C
   Step: 0.50°C
 Temperature setpoint updated to: 4.50°C (Range: -10.00°C to 10.00°C)
+*** Temperature setpoint 4.00°C reached/overpassed while increasing ***
 Temperature setpoint updated to: 5.00°C (Range: -10.00°C to 10.00°C)
 Temperature setpoint updated to: 5.50°C (Range: -10.00°C to 10.00°C)
 ...
 Current Temperature Setpoint: 6.00°C (Range: -10.00°C to 10.00°C)
+...
+*** Temperature setpoint 4.00°C reached/overpassed while decreasing ***
+Temperature setpoint updated to: 3.50°C (Range: -10.00°C to 10.00°C)
 ```
 
 ## Using the Device
@@ -167,11 +171,20 @@ Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon E
 The MatterTemperatureControlledCabinet example consists of the following main components:
 
 1. **`setup()`**: Initializes hardware (button), configures Wi-Fi (if needed), sets up the Matter Temperature Controlled Cabinet endpoint with initial temperature configuration, and waits for Matter commissioning.
+
 2. **`loop()`**: 
    - **Dynamic Temperature Updates**: Automatically changes the temperature setpoint every 1 second, cycling between the minimum and maximum temperature limits using the configured step value. This demonstrates the temperature control functionality and allows Matter controllers to observe real-time changes.
+   - **Setpoint Reached Detection**: Monitors when the initial setpoint is reached or overpassed in each direction and prints a notification message once per direction.
    - Periodically prints the current temperature setpoint (every 5 seconds)
    - Handles button input for factory reset
 
+3. **Helper Functions**:
+   - `initTemperatureControl()`: Initializes the temperature control state from the current setpoint
+   - `checkSetpointReached()`: Checks and logs when the initial setpoint is reached/overpassed
+   - `updateTemperatureSetpoint()`: Updates the temperature setpoint with cycling logic and boundary detection
+   - `printTemperatureStatus()`: Prints the current temperature status
+   - `handleButtonPress()`: Handles button press detection and factory reset functionality
+
 ## API Usage
 
 The example demonstrates the following API methods: