Merge branch 'feature/touch_element_sleep' into 'master'

touch_element: add low-power support and example into touch element

Closes IDF-3027 and IDF-4353

See merge request espressif/esp-idf!13001

components/esp_hw_support/sleep_modes.c

@@ -23,6 +23,7 @@
 #include "soc/soc_caps.h"
 #include "driver/rtc_io.h"
 #include "hal/rtc_io_hal.h"
+#include "hal/rtc_cntl_ll.h"
 
 #include "driver/uart.h"
 

components/hal/esp32/include/hal/rtc_cntl_ll.h

@@ -47,6 +47,11 @@ static inline void rtc_cntl_ll_ulp_int_clear(void)
     REG_SET_BIT(RTC_CNTL_INT_CLR_REG, RTC_CNTL_SAR_INT_CLR);
 }
 
+static inline void rtc_cntl_ll_timer2_set_touch_wait_cycle(uint32_t wait_cycle)
+{
+    REG_SET_FIELD(RTC_CNTL_TIMER2_REG, RTC_CNTL_ULPCP_TOUCH_START_WAIT, wait_cycle);
+}
+
 #ifdef __cplusplus
 }
 #endif

components/hal/esp32s2/include/hal/rtc_cntl_ll.h

@@ -47,6 +47,11 @@ static inline void rtc_cntl_ll_ulp_int_clear(void)
     REG_SET_BIT(RTC_CNTL_INT_CLR_REG, RTC_CNTL_COCPU_TRAP_INT_CLR);
 }
 
+static inline void rtc_cntl_ll_timer2_set_touch_wait_cycle(uint32_t wait_cycle)
+{
+    REG_SET_FIELD(RTC_CNTL_TIMER2_REG, RTC_CNTL_ULPCP_TOUCH_START_WAIT, wait_cycle);
+}
+
 #ifdef __cplusplus
 }
 #endif

components/hal/esp32s3/include/hal/rtc_cntl_ll.h

@@ -127,6 +127,11 @@ static inline void rtc_cntl_ll_ulp_int_clear(void)
     REG_SET_BIT(RTC_CNTL_INT_CLR_REG, RTC_CNTL_COCPU_TRAP_INT_CLR);
 }
 
+static inline void rtc_cntl_ll_timer2_set_touch_wait_cycle(uint32_t wait_cycle)
+{
+    REG_SET_FIELD(RTC_CNTL_TIMER2_REG, RTC_CNTL_ULPCP_TOUCH_START_WAIT, wait_cycle);
+}
+
 #ifdef __cplusplus
 }
 #endif

components/soc/esp32s2/include/soc/soc_caps.h

@@ -292,7 +292,7 @@
 /*-------------------------- TOUCH SENSOR CAPS -------------------------------*/
 #define SOC_TOUCH_VERSION_2                 (1)     /*!<Hardware version of touch sensor */
 #define SOC_TOUCH_SENSOR_NUM                (15)    /*!<15 Touch channels */
-#define SOC_TOUCH_PROXIMITY_CHANNEL_NUM     (3)     /* Sopport touch proximity channel number. */
+#define SOC_TOUCH_PROXIMITY_CHANNEL_NUM     (3)     /*!<Support touch proximity channel number. */
 
 #define SOC_TOUCH_PAD_THRESHOLD_MAX         (0x1FFFFF)  /*!<If set touch threshold max value, The touch sensor can't be in touched status */
 #define SOC_TOUCH_PAD_MEASURE_WAIT_MAX      (0xFF)  /*!<The timer frequency is 8Mhz, the max value is 0xff */

components/touch_element/include/touch_element/touch_element.h

@@ -94,6 +94,14 @@ typedef struct {
     touch_pad_t guard_channel;     //!< Waterproof Guard-Sensor channel number (index)
     float guard_sensitivity;       //!< Waterproof Guard-Sensor sensitivity
 } touch_elem_waterproof_config_t;
+
+/**
+ * @brief   Touch element sleep configuration passed to touch_element_enable_light_sleep or touch_element_enable_deep_sleep
+*/
+typedef struct {
+    uint16_t sample_count;                     //!< scan times in every measurement, normally equal to the 'sample_count' field in 'touch_elem_hw_config_t'.
+    uint16_t sleep_cycle;                    //!< sleep_cycle decide the interval between two measurements， t_sleep = sleep_cycle / (RTC_SLOW_CLK frequency), normally equal to the 'sleep_cycle' field in 'touch_elem_hw_config_t'.
+} touch_elem_sleep_config_t;
 /* ------------------------------------------------------------------------------------------------------------------ */
 typedef void *touch_elem_handle_t;        //!< Touch element handle type
 typedef uint32_t touch_elem_event_t;      //!< Touch element event type
@@ -256,6 +264,75 @@ esp_err_t touch_element_waterproof_add(touch_elem_handle_t element_handle);
  */
 esp_err_t touch_element_waterproof_remove(touch_elem_handle_t element_handle);
 
+/**
+ * @brief   Touch element light sleep initialization
+ *
+ * @note    It should be called after touch button element installed.
+ *          Any of installed touch element can wake up from the light sleep
+ *
+ * @param[in] sleep_config Sleep configurations, set NULL to use default config
+ * @return
+ *      - ESP_OK: Successfully initialized touch sleep
+ *      - ESP_ERR_INVALID_STATE: Touch element is not installed or touch sleep has been installed
+ *      - ESP_ERR_INVALID_ARG: inputed argument is NULL
+ *      - ESP_ERR_NO_MEM: no memory for touch sleep struct
+ *      - ESP_ERR_NOT_SUPPORTED: inputed wakeup_elem_handle is not touch_button_handle_t type, currently only touch_button_handle_t supported
+ */
+esp_err_t touch_element_enable_light_sleep(const touch_elem_sleep_config_t *sleep_config);
+
+/**
+ * @brief   Release the resources that allocated by touch_element_enable_deep_sleep()
+ *
+ * This function will also disable the touch sensor to wake up the device
+ *
+ * @return
+ *      - ESP_OK: uninstall success
+ *      - ESP_ERR_INVALID_STATE: touch sleep has not been installed
+ */
+esp_err_t touch_element_disable_light_sleep(void);
+
+/**
+ * @brief   Touch element deep sleep initialization
+ *
+ * This function will enable the device wake-up from deep sleep or light sleep by touch sensor
+ *
+ * @note    It should be called after touch button element installed.
+ *          Only one touch button can be registered as the deep sleep wake-up button
+ *
+ * @param[in] wakeup_elem_handle    Touch element instance handle for waking up the device, only support button element
+ * @param[in] sleep_config          Sleep configurations, set NULL to use default config
+ *
+ * @return
+ *      - ESP_OK: Successfully initialized touch sleep
+ *      - ESP_ERR_INVALID_STATE: Touch element is not installed or touch sleep has been installed
+ *      - ESP_ERR_INVALID_ARG: inputed argument is NULL
+ *      - ESP_ERR_NO_MEM: no memory for touch sleep struct
+ *      - ESP_ERR_NOT_SUPPORTED: inputed wakeup_elem_handle is not touch_button_handle_t type, currently only touch_button_handle_t supported
+ */
+esp_err_t touch_element_enable_deep_sleep(touch_elem_handle_t wakeup_elem_handle, const touch_elem_sleep_config_t *sleep_config);
+
+/**
+ * @brief   Release the resources that allocated by touch_element_enable_deep_sleep()
+ *
+ * This function will also disable the touch sensor to wake up the device
+ *
+ * @return
+ *      - ESP_OK: uninstall success
+ *      - ESP_ERR_INVALID_STATE: touch sleep has not been installed
+ */
+esp_err_t touch_element_disable_deep_sleep(void);
+
+/**
+ * @brief   Touch element wake up calibrations
+ *
+ * This function will also disable the touch sensor to wake up the device
+ *
+ * @return
+ *      - ESP_OK: uninstall success
+ *      - ESP_ERR_INVALID_STATE: touch sleep has not been installed
+ */
+esp_err_t touch_element_sleep_enable_wakeup_calibration(touch_elem_handle_t element_handle, bool en);
+
 #ifdef __cplusplus
 }
 #endif

components/touch_element/include/touch_element/touch_element_private.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2016-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2016-2021 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -10,6 +10,8 @@
 #include "touch_element/touch_button.h"
 #include "touch_element/touch_slider.h"
 #include "touch_element/touch_matrix.h"
+#include "esp_pm.h"
+#include "sdkconfig.h"
 
 #ifdef __cplusplus
 extern "C" {
@@ -54,6 +56,7 @@ typedef struct {
     touch_pad_t channel;          //!< Touch channel number(index)
     te_dev_type_t type;           //!< Touch channel type  TODO: need to refactor as te_class_type_t
     te_dev_state_t state;         //!< Touch channel current state
+    bool is_use_last_threshold;
 } te_dev_t;
 
 typedef enum {
@@ -79,6 +82,16 @@ struct te_waterproof_s {
     bool is_shield_level_set;                   //Waterproof shield level setting bit
 };
 typedef struct te_waterproof_s* te_waterproof_handle_t;
+/* -------------------------------------------- Sleep basic type --------------------------------------------- */
+struct te_sleep_s {
+    touch_elem_handle_t wakeup_handle;
+#ifdef CONFIG_PM_ENABLE
+    esp_pm_lock_handle_t pm_lock;
+#endif
+    uint32_t *non_volatile_threshold;
+};
+
+typedef struct te_sleep_s* te_sleep_handle_t;
 /* -------------------------------------------- Button basic type --------------------------------------------- */
 typedef struct {
     touch_elem_dispatch_t dispatch_method;      //Button dispatch method
@@ -170,6 +183,16 @@ void te_object_method_register(te_object_methods_t *object_methods, te_class_typ
 void te_object_method_unregister(te_class_type_t object_type);
 bool te_object_check_channel(const touch_pad_t *channel_array, uint8_t channel_sum);
 bool waterproof_check_mask_handle(touch_elem_handle_t te_handle);
+bool te_is_touch_dsleep_wakeup(void);
+touch_pad_t te_get_sleep_channel(void);
+
+bool is_button_object_handle(touch_elem_handle_t element_handle);
+bool is_slider_object_handle(touch_elem_handle_t element_handle);
+bool is_matrix_object_handle(touch_elem_handle_t element_handle);
+
+void button_enable_wakeup_calibration(te_button_handle_t button_handle, bool en);
+void slider_enable_wakeup_calibration(te_slider_handle_t slider_handle, bool en);
+void matrix_enable_wakeup_calibration(te_matrix_handle_t matrix_handle, bool en);
 /* ------------------------------------------------------------------------------------------------------------------ */
 
 #ifdef __cplusplus

components/touch_element/touch_button.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2016-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -296,6 +296,20 @@ static esp_err_t button_object_remove_instance(te_button_handle_t button_handle)
     return ret;
 }
 
+bool is_button_object_handle(touch_elem_handle_t element_handle)
+{
+    te_button_handle_list_t *item;
+    xSemaphoreTake(s_te_btn_obj->mutex, portMAX_DELAY);
+    SLIST_FOREACH(item, &s_te_btn_obj->handle_list, next) {
+        if (element_handle == item->button_handle) {
+            xSemaphoreGive(s_te_btn_obj->mutex);
+            return true;
+        }
+    }
+    xSemaphoreGive(s_te_btn_obj->mutex);
+    return false;
+}
+
 static bool button_channel_check(te_button_handle_t button_handle, touch_pad_t channel_num)
 {
     return (channel_num == button_handle->device->channel);
@@ -346,6 +360,11 @@ static inline void button_dispatch(te_button_handle_t button_handle, touch_elem_
     }
 }
 
+void button_enable_wakeup_calibration(te_button_handle_t button_handle, bool en)
+{
+    button_handle->device->is_use_last_threshold = !en;
+}
+
 /**
  * @brief Button process
  *