Merge branch 'master' into feat/zibee-sensor-default-value

Author: lucasssvaz

cores/esp32/esp32-hal-adc.c

@@ -20,6 +20,7 @@
 #include "esp_adc/adc_oneshot.h"
 #include "esp_adc/adc_continuous.h"
 #include "esp_adc/adc_cali_scheme.h"
+#include "esp_heap_caps.h"
 
 #if CONFIG_IDF_TARGET_ESP32P4 && CONFIG_ESP32P4_REV_MIN_FULL >= 300
 // NOTE: These weak definitions allow successful linkage if the real efuse calibration functions are missing.
@@ -403,43 +404,40 @@ adc_continuous_result_t *adc_result = NULL;
 static bool adcContinuousDetachBus(void *adc_unit_number) {
   adc_unit_t adc_unit = (adc_unit_t)adc_unit_number - 1;
 
+  // Guard against double-cleanup: check if already cleaned up
   if (adc_handle[adc_unit].adc_continuous_handle == NULL) {
     return true;
-  } else {
-    esp_err_t err = adc_continuous_deinit(adc_handle[adc_unit].adc_continuous_handle);
+  }
+
+  // Clean up ADC driver
+  esp_err_t err = adc_continuous_deinit(adc_handle[adc_unit].adc_continuous_handle);
+  if (err != ESP_OK) {
+    return false;
+  }
+  adc_handle[adc_unit].adc_continuous_handle = NULL;
+
+  // Clean up calibration handle if exists
+  if (adc_handle[adc_unit].adc_cali_handle != NULL) {
+#if ADC_CALI_SCHEME_CURVE_FITTING_SUPPORTED
+    err = adc_cali_delete_scheme_curve_fitting(adc_handle[adc_unit].adc_cali_handle);
     if (err != ESP_OK) {
       return false;
     }
-    adc_handle[adc_unit].adc_continuous_handle = NULL;
-    if (adc_handle[adc_unit].adc_cali_handle != NULL) {
-#if ADC_CALI_SCHEME_CURVE_FITTING_SUPPORTED
-      err = adc_cali_delete_scheme_curve_fitting(adc_handle[adc_unit].adc_cali_handle);
-      if (err != ESP_OK) {
-        return false;
-      }
 #elif ADC_CALI_SCHEME_LINE_FITTING_SUPPORTED
-      err = adc_cali_delete_scheme_line_fitting(adc_handle[adc_unit].adc_cali_handle);
-      if (err != ESP_OK) {
-        return false;
-      }
-#else
-      log_e("ADC Calibration scheme is not supported!");
+    err = adc_cali_delete_scheme_line_fitting(adc_handle[adc_unit].adc_cali_handle);
+    if (err != ESP_OK) {
       return false;
-#endif
     }
+#else
+    log_e("ADC Calibration scheme is not supported!");
+    return false;
+#endif
     adc_handle[adc_unit].adc_cali_handle = NULL;
-
-    //set all used pins to INIT state
-    for (uint8_t channel = 0; channel < SOC_ADC_CHANNEL_NUM(adc_unit); channel++) {
-      int io_pin;
-      adc_oneshot_channel_to_io(adc_unit, channel, &io_pin);
-      if (perimanGetPinBusType(io_pin) == ESP32_BUS_TYPE_ADC_CONT) {
-        if (!perimanClearPinBus(io_pin)) {
-          return false;
-        }
-      }
-    }
   }
+
+  // Don't call perimanClearPinBus() here - the peripheral manager already handles it.
+  // This callback is only responsible for cleaning up the IDF's ADC driver and calibration handles.
+  // It does NOT free the adc_result buffer. The caller is responsible for freeing adc_result.
   return true;
 }
 
@@ -549,6 +547,14 @@ bool analogContinuous(const uint8_t pins[], size_t pins_count, uint32_t conversi
   }
 #endif
 
+#if CONFIG_IDF_TARGET_ESP32P4
+  // Align conversion frame size to cache line size (required for DMA on targets with cache)
+  uint32_t alignment_remainder = adc_handle[adc_unit].conversion_frame_size % CONFIG_CACHE_L1_CACHE_LINE_SIZE;
+  if (alignment_remainder != 0) {
+    adc_handle[adc_unit].conversion_frame_size += (CONFIG_CACHE_L1_CACHE_LINE_SIZE - alignment_remainder);
+  }
+#endif
+
   adc_handle[adc_unit].buffer_size = adc_handle[adc_unit].conversion_frame_size * 2;
 
   //Conversion frame size buffer cant be bigger than 4092 bytes
@@ -626,8 +632,21 @@ bool analogContinuousRead(adc_continuous_result_t **buffer, uint32_t timeout_ms)
     uint32_t bytes_read = 0;
     uint32_t read_raw[used_adc_channels];
     uint32_t read_count[used_adc_channels];
-    uint8_t adc_read[adc_handle[ADC_UNIT_1].conversion_frame_size];
-    memset(adc_read, 0xcc, sizeof(adc_read));
+
+    // Allocate DMA buffer with cache line alignment (required for ESP32-P4 and other targets with cache)
+    size_t buffer_size = adc_handle[ADC_UNIT_1].conversion_frame_size;
+#if CONFIG_IDF_TARGET_ESP32P4
+    uint8_t *adc_read = (uint8_t *)heap_caps_aligned_alloc(CONFIG_CACHE_L1_CACHE_LINE_SIZE, buffer_size, MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL);
+#else
+    uint8_t *adc_read = (uint8_t *)heap_caps_malloc(buffer_size, MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL);
+#endif
+    if (adc_read == NULL) {
+      log_e("Failed to allocate DMA buffer");
+      *buffer = NULL;
+      return false;
+    }
+
+    memset(adc_read, 0xcc, buffer_size);
     memset(read_raw, 0, sizeof(read_raw));
     memset(read_count, 0, sizeof(read_count));
 
@@ -638,6 +657,8 @@ bool analogContinuousRead(adc_continuous_result_t **buffer, uint32_t timeout_ms)
       } else {
         log_e("Reading data failed with error: %X", err);
       }
+      free(adc_read);
+      adc_read = NULL;
       *buffer = NULL;
       return false;
     }
@@ -676,6 +697,8 @@ bool analogContinuousRead(adc_continuous_result_t **buffer, uint32_t timeout_ms)
       }
     }
 
+    free(adc_read);
+    adc_read = NULL;
     *buffer = adc_result;
     return true;
 
@@ -708,16 +731,29 @@ bool analogContinuousStop() {
 }
 
 bool analogContinuousDeinit() {
-  if (adc_handle[ADC_UNIT_1].adc_continuous_handle != NULL) {
-    esp_err_t err = adc_continuous_deinit(adc_handle[ADC_UNIT_1].adc_continuous_handle);
-    if (err != ESP_OK) {
-      return false;
+  if (adc_handle[ADC_UNIT_1].adc_continuous_handle == NULL) {
+    log_i("ADC Continuous was not initialized");
+    return true;
+  }
+
+  // Clear all used pins from peripheral manager
+  // This will trigger adcContinuousDetachBus() callback which cleans up the ADC driver
+  for (uint8_t channel = 0; channel < SOC_ADC_CHANNEL_NUM(ADC_UNIT_1); channel++) {
+    int io_pin;
+    adc_oneshot_channel_to_io(ADC_UNIT_1, channel, &io_pin);
+    if (perimanGetPinBusType(io_pin) == ESP32_BUS_TYPE_ADC_CONT) {
+      if (!perimanClearPinBus(io_pin)) {
+        return false;
+      }
     }
+  }
+
+  // Free the result buffer (callback doesn't do this)
+  if (adc_result != NULL) {
     free(adc_result);
-    adc_handle[ADC_UNIT_1].adc_continuous_handle = NULL;
-  } else {
-    log_i("ADC Continuous was not initialized");
+    adc_result = NULL;
   }
+
   return true;
 }
 

docs/en/matter/ep_occupancy_sensor.rst

@@ -10,6 +10,9 @@ The ``MatterOccupancySensor`` class provides an occupancy sensor endpoint for Ma
 **Features:**
 * Occupancy state reporting (occupied/unoccupied)
 * Multiple sensor type support (PIR, Ultrasonic, Physical Contact)
+* HoldTime attribute for configuring how long the sensor holds the "occupied" state
+* HoldTimeLimits (min, max, default) for validation and controller guidance
+* HoldTime change callback for real-time updates from Matter controllers
 * Simple boolean state
 * Read-only sensor (no control functionality)
 * Automatic state updates
@@ -104,6 +107,83 @@ Gets the current occupancy state.
 
 This function will return ``true`` if occupied, ``false`` if unoccupied.
 
+HoldTime Control
+****************
+
+setHoldTime
+^^^^^^^^^^^
+
+Sets the HoldTime value (in seconds). The HoldTime determines how long the sensor maintains the "occupied" state after the last detection.
+
+.. code-block:: arduino
+
+    bool setHoldTime(uint16_t _holdTime_seconds);
+
+* ``_holdTime_seconds`` - HoldTime value in seconds
+
+**Important:** This function must be called after ``Matter.begin()`` has been called, as it requires the Matter event loop to be running.
+
+This function will return ``true`` if successful, ``false`` otherwise.
+
+getHoldTime
+^^^^^^^^^^^
+
+Gets the current HoldTime value (in seconds).
+
+.. code-block:: arduino
+
+    uint16_t getHoldTime();
+
+This function will return the current HoldTime value in seconds.
+
+setHoldTimeLimits
+^^^^^^^^^^^^^^^^^
+
+Sets the HoldTime limits (minimum, maximum, and default values). These limits define the valid range for HoldTime values and provide metadata for Matter controllers.
+
+.. code-block:: arduino
+
+    bool setHoldTimeLimits(uint16_t _holdTimeMin_seconds, uint16_t _holdTimeMax_seconds, uint16_t _holdTimeDefault_seconds);
+
+* ``_holdTimeMin_seconds`` - Minimum HoldTime value in seconds
+* ``_holdTimeMax_seconds`` - Maximum HoldTime value in seconds
+* ``_holdTimeDefault_seconds`` - Default/recommended HoldTime value in seconds (informational metadata for controllers)
+
+**Important:**
+* This function must be called after ``Matter.begin()`` has been called, as it requires the Matter event loop to be running.
+* The ``holdTimeDefault_seconds`` parameter is informational metadata for Matter controllers (recommended default value). It does NOT automatically set the HoldTime attribute - use ``setHoldTime()`` to set the actual value.
+* If the current HoldTime value is outside the new limits, it will be automatically adjusted to the nearest limit (minimum or maximum).
+
+This function will return ``true`` if successful, ``false`` otherwise.
+
+onHoldTimeChange
+^^^^^^^^^^^^^^^^
+
+Sets a callback function that will be called when the HoldTime value is changed by a Matter Controller.
+
+.. code-block:: arduino
+
+    void onHoldTimeChange(HoldTimeChangeCB onHoldTimeChangeCB);
+
+* ``onHoldTimeChangeCB`` - Callback function of type ``HoldTimeChangeCB``
+
+The callback function signature is:
+
+.. code-block:: arduino
+
+    using HoldTimeChangeCB = std::function<bool(uint16_t holdTime_seconds)>;
+
+The callback receives the new HoldTime value and can return ``true`` to accept the change or ``false`` to reject it.
+
+Example:
+
+.. code-block:: arduino
+
+    OccupancySensor.onHoldTimeChange([](uint16_t holdTime_seconds) -> bool {
+        Serial.printf("HoldTime changed to %u seconds\n", holdTime_seconds);
+        return true;  // Accept the change
+    });
+
 Operators
 *********
 
@@ -145,8 +225,22 @@ Example:
 Example
 -------
 
-Occupancy Sensor
-****************
+Basic Occupancy Sensor
+**********************
 
 .. literalinclude:: ../../../libraries/Matter/examples/MatterOccupancySensor/MatterOccupancySensor.ino
     :language: arduino
+
+Occupancy Sensor with HoldTime
+*******************************
+
+For an example that demonstrates HoldTime functionality, see:
+
+.. literalinclude:: ../../../libraries/Matter/examples/MatterOccupancyWithHoldTime/MatterOccupancyWithHoldTime.ino
+    :language: arduino
+
+This example shows:
+* How to configure HoldTimeLimits after ``Matter.begin()``
+* How to set and persist HoldTime values
+* How to use the ``onHoldTimeChange()`` callback
+* How to implement HoldTime expiration logic in sensor simulation

docs/en/matter/matter.rst

@@ -205,6 +205,7 @@ The Matter library includes a comprehensive set of examples demonstrating variou
 * **Matter Pressure Sensor** - Creates a Matter-compatible pressure sensor device with automatic simulation of pressure readings. `View Matter Pressure Sensor code on GitHub <https://github.com/espressif/arduino-esp32/tree/master/libraries/Matter/examples/MatterPressureSensor>`_
 * **Matter Contact Sensor** - Creates a Matter-compatible contact sensor device (open/closed state). `View Matter Contact Sensor code on GitHub <https://github.com/espressif/arduino-esp32/tree/master/libraries/Matter/examples/MatterContactSensor>`_
 * **Matter Occupancy Sensor** - Creates a Matter-compatible occupancy sensor device with automatic simulation of occupancy state changes. `View Matter Occupancy Sensor code on GitHub <https://github.com/espressif/arduino-esp32/tree/master/libraries/Matter/examples/MatterOccupancySensor>`_
+* **Matter Occupancy Sensor with HoldTime** - Creates a Matter-compatible occupancy sensor device with HoldTime functionality, automatic simulation of occupancy state changes, HoldTime configuration with persistence across reboots, and HoldTime change callback for real-time updates from Matter controllers. `View Matter Occupancy Sensor with HoldTime code on GitHub <https://github.com/espressif/arduino-esp32/tree/master/libraries/Matter/examples/MatterOccupancyWithHoldTime>`_
 * **Matter Water Leak Detector** - Creates a Matter-compatible water leak detector device with automatic simulation of water leak detection state changes. `View Matter Water Leak Detector code on GitHub <https://github.com/espressif/arduino-esp32/tree/master/libraries/Matter/examples/MatterWaterLeakDetector>`_
 * **Matter Water Freeze Detector** - Creates a Matter-compatible water freeze detector device with automatic simulation of water freeze detection state changes. `View Matter Water Freeze Detector code on GitHub <https://github.com/espressif/arduino-esp32/tree/master/libraries/Matter/examples/MatterWaterFreezeDetector>`_
 * **Matter Rain Sensor** - Creates a Matter-compatible rain sensor device with automatic simulation of rain detection state changes. `View Matter Rain Sensor code on GitHub <https://github.com/espressif/arduino-esp32/tree/master/libraries/Matter/examples/MatterRainSensor>`_