Merge branch 'bugfix/fix_touch_sensor_api' into 'master'

driver(touch): fix touch sensor driver redundancy

Closes IDF-1850

See merge request espressif/esp-idf!9273

Author: ginkgm

components/driver/esp32s2/include/driver/touch_sensor.h

@@ -22,7 +22,7 @@ extern "C" {
 /**
  * @brief Set touch sensor FSM start
  * @note  Start FSM after the touch sensor FSM mode is set.
- * @note  Call this function will reset baseline of all touch channels.
+ * @note  Call this function will reset benchmark of all touch channels.
  * @return
  *      - ESP_OK on success
  */
@@ -98,7 +98,7 @@ esp_err_t touch_pad_get_idle_channel_connect(touch_pad_conn_type_t *type);
 /**
  * @brief Set the trigger threshold of touch sensor.
  *        The threshold determines the sensitivity of the touch sensor.
- *        The threshold is the original value of the trigger state minus the baseline value.
+ *        The threshold is the original value of the trigger state minus the benchmark value.
  * @note  If set "TOUCH_PAD_THRESHOLD_MAX", the touch is never be triggered.
  * @param touch_num touch pad index
  * @param threshold threshold of touch sensor. Should be less than the max change value of touch.
@@ -264,15 +264,15 @@ esp_err_t touch_pad_timeout_resume(void);
 esp_err_t touch_pad_read_raw_data(touch_pad_t touch_num, uint32_t *raw_data);
 
 /**
- * @brief get baseline of touch sensor.
- * @note After initialization, the baseline value is the maximum during the first measurement period.
+ * @brief get benchmark of touch sensor.
+ * @note After initialization, the benchmark value is the maximum during the first measurement period.
  * @param touch_num touch pad index
- * @param basedata pointer to accept touch sensor baseline value
+ * @param benchmark pointer to accept touch sensor benchmark value
  * @return
  *     - ESP_OK Success
  *     - ESP_ERR_INVALID_ARG Touch channel 0 haven't this parameter.
  */
-esp_err_t touch_pad_filter_read_baseline(touch_pad_t touch_num, uint32_t *basedata);
+esp_err_t touch_pad_read_benchmark(touch_pad_t touch_num, uint32_t *benchmark);
 
 /**
  * @brief Get smoothed data that obtained by filtering the raw data.
@@ -283,13 +283,13 @@ esp_err_t touch_pad_filter_read_baseline(touch_pad_t touch_num, uint32_t *baseda
 esp_err_t touch_pad_filter_read_smooth(touch_pad_t touch_num, uint32_t *smooth);
 
 /**
- * @brief Force reset baseline to raw data of touch sensor.
+ * @brief Force reset benchmark to raw data of touch sensor.
  * @param touch_num touch pad index
  *                  - TOUCH_PAD_MAX Reset basaline of all channels
  * @return
  *     - ESP_OK Success
  */
-esp_err_t touch_pad_filter_reset_baseline(touch_pad_t touch_num);
+esp_err_t touch_pad_reset_benchmark(touch_pad_t touch_num);
 
 /**
  * @brief set parameter of touch sensor filter and detection algorithm.
@@ -375,11 +375,12 @@ esp_err_t touch_pad_denoise_read_data(uint32_t *data);
 
 /**
  * @brief set parameter of waterproof function.
+ *
  *        The waterproof function includes a shielded channel (TOUCH_PAD_NUM14) and a guard channel.
- *        The shielded channel outputs the same signal as the channel being measured.
+ *        Guard pad is used to detect the large area of water covering the touch panel.
+ *        Shield pad is used to shield the influence of water droplets covering the touch panel.
  *        It is generally designed as a grid and is placed around the touch buttons.
- *        The shielded channel does not follow the measurement signal of the protection channel.
- *        So that the guard channel can detect a large area of water.
+ *
  * @param waterproof parameter of waterproof
  * @return
  *     - ESP_OK Success
@@ -396,23 +397,14 @@ esp_err_t touch_pad_waterproof_get_config(touch_pad_waterproof_t *waterproof);
 
 /**
  * @brief Enable parameter of waterproof function.
- *        The waterproof function includes a shielded channel (TOUCH_PAD_NUM14) and a guard channel.
- *        The shielded channel outputs the same signal as the channel being measured.
- *        It is generally designed as a grid and is placed around the touch buttons.
- *        The shielded channel does not follow the measurement signal of the protection channel.
- *        So that the guard channel can detect a large area of water.
+ *        Should be called after function ``touch_pad_waterproof_set_config``.
  * @return
  *     - ESP_OK Success
  */
 esp_err_t touch_pad_waterproof_enable(void);
 
 /**
- * @brief Enable parameter of waterproof function.
- *        The waterproof function includes a shielded channel (TOUCH_PAD_NUM14) and a guard channel.
- *        The shielded channel outputs the same signal as the channel being measured.
- *        It is generally designed as a grid and is placed around the touch buttons.
- *        The shielded channel does not follow the measurement signal of the protection channel.
- *        So that the guard channel can detect a large area of water.
+ * @brief Disable parameter of waterproof function.
  * @return
  *     - ESP_OK Success
  */
@@ -537,14 +529,14 @@ esp_err_t touch_pad_sleep_set_threshold(touch_pad_t pad_num, uint32_t touch_thre
 esp_err_t touch_pad_sleep_get_threshold(touch_pad_t pad_num, uint32_t *touch_thres);
 
 /**
- * @brief Read baseline of touch sensor sleep channel.
+ * @brief Read benchmark of touch sensor sleep channel.
  * @param pad_num Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode.
- * @param baseline pointer to accept touch sensor baseline value
+ * @param benchmark pointer to accept touch sensor benchmark value
  * @return
  *     - ESP_OK Success
  *     - ESP_ERR_INVALID_ARG parameter is NULL
  */
-esp_err_t touch_pad_sleep_channel_read_baseline(touch_pad_t pad_num, uint32_t *baseline);
+esp_err_t touch_pad_sleep_channel_read_benchmark(touch_pad_t pad_num, uint32_t *benchmark);
 
 /**
  * @brief Read smoothed data of touch sensor sleep channel.
@@ -568,12 +560,12 @@ esp_err_t touch_pad_sleep_channel_read_smooth(touch_pad_t pad_num, uint32_t *smo
 esp_err_t touch_pad_sleep_channel_read_data(touch_pad_t pad_num, uint32_t *raw_data);
 
 /**
- * @brief Reset baseline of touch sensor sleep channel.
+ * @brief Reset benchmark of touch sensor sleep channel.
  *
  * @return
  *     - ESP_OK Success
  */
-esp_err_t touch_pad_sleep_channel_reset_baseline(void);
+esp_err_t touch_pad_sleep_channel_reset_benchmark(void);
 
 /**
  * @brief Read proximity count of touch sensor sleep channel.

components/driver/esp32s2/touch_sensor.c

@@ -322,21 +322,21 @@ esp_err_t IRAM_ATTR touch_pad_filter_read_smooth(touch_pad_t touch_num, uint32_t
     return ESP_OK;
 }
 
-esp_err_t IRAM_ATTR touch_pad_filter_read_baseline(touch_pad_t touch_num, uint32_t *basedata)
+esp_err_t IRAM_ATTR touch_pad_read_benchmark(touch_pad_t touch_num, uint32_t *benchmark)
 {
     TOUCH_CHANNEL_CHECK(touch_num);
     TOUCH_ENTER_CRITICAL_SAFE();
-    touch_hal_filter_read_baseline(touch_num, basedata);
+    touch_hal_read_benchmark(touch_num, benchmark);
     TOUCH_EXIT_CRITICAL_SAFE();
     return ESP_OK;
 }
 
 /* Should be call after clk enable and filter enable. */
-esp_err_t touch_pad_filter_reset_baseline(touch_pad_t touch_num)
+esp_err_t touch_pad_reset_benchmark(touch_pad_t touch_num)
 {
     TOUCH_CHECK(touch_num <= TOUCH_PAD_MAX && touch_num >= 0, "Touch channel error", ESP_ERR_INVALID_ARG);
     TOUCH_ENTER_CRITICAL();
-    touch_hal_filter_reset_baseline(touch_num);
+    touch_hal_reset_benchmark(touch_num);
     TOUCH_EXIT_CRITICAL();
     return ESP_OK;
 }
@@ -345,10 +345,7 @@ esp_err_t touch_pad_filter_set_config(touch_filter_config_t *filter_info)
 {
     TOUCH_CHECK(filter_info->mode < TOUCH_PAD_FILTER_MAX, TOUCH_PARAM_CHECK_STR("mode"), ESP_ERR_INVALID_ARG);
     TOUCH_CHECK(filter_info->debounce_cnt <= TOUCH_DEBOUNCE_CNT_MAX, TOUCH_PARAM_CHECK_STR("debounce"), ESP_ERR_INVALID_ARG);
-    TOUCH_CHECK(filter_info->hysteresis_thr <= TOUCH_HYSTERESIS_THR_MAX, TOUCH_PARAM_CHECK_STR("hysteresis"), ESP_ERR_INVALID_ARG);
     TOUCH_CHECK(filter_info->noise_thr <= TOUCH_NOISE_THR_MAX, TOUCH_PARAM_CHECK_STR("noise"), ESP_ERR_INVALID_ARG);
-    TOUCH_CHECK(filter_info->noise_neg_thr <= TOUCH_NOISE_NEG_THR_MAX, TOUCH_PARAM_CHECK_STR("noise"), ESP_ERR_INVALID_ARG);
-    TOUCH_CHECK(filter_info->neg_noise_limit <= TOUCH_NEG_NOISE_CNT_LIMIT, TOUCH_PARAM_CHECK_STR("noise_limit"), ESP_ERR_INVALID_ARG);
     TOUCH_CHECK(filter_info->jitter_step <= TOUCH_JITTER_STEP_MAX, TOUCH_PARAM_CHECK_STR("jitter_step"), ESP_ERR_INVALID_ARG);
     TOUCH_CHECK(filter_info->smh_lvl < TOUCH_PAD_SMOOTH_MAX, TOUCH_PARAM_CHECK_STR("smooth level"), ESP_ERR_INVALID_ARG);
 
@@ -522,7 +519,7 @@ esp_err_t touch_pad_proximity_get_data(touch_pad_t touch_num, uint32_t *measure_
 {
     TOUCH_CHECK(touch_hal_proximity_pad_check(touch_num), "touch num is not proximity", ESP_ERR_INVALID_ARG);
     TOUCH_ENTER_CRITICAL_SAFE();
-    touch_hal_filter_read_baseline(touch_num, measure_out);
+    touch_hal_read_benchmark(touch_num, measure_out);
     TOUCH_EXIT_CRITICAL_SAFE();
     return ESP_OK;
 }
@@ -585,10 +582,10 @@ esp_err_t touch_pad_sleep_get_threshold(touch_pad_t pad_num, uint32_t *touch_thr
     return ESP_OK;
 }
 
-esp_err_t touch_pad_sleep_channel_read_baseline(touch_pad_t pad_num, uint32_t *baseline)
+esp_err_t touch_pad_sleep_channel_read_benchmark(touch_pad_t pad_num, uint32_t *benchmark)
 {
     TOUCH_ENTER_CRITICAL_SAFE();
-    touch_hal_sleep_read_baseline(baseline);
+    touch_hal_sleep_read_benchmark(benchmark);
     TOUCH_EXIT_CRITICAL_SAFE();
     return ESP_OK;
 }
@@ -609,10 +606,10 @@ esp_err_t touch_pad_sleep_channel_read_data(touch_pad_t pad_num, uint32_t *raw_d
     return ESP_OK;
 }
 
-esp_err_t touch_pad_sleep_channel_reset_baseline(void)
+esp_err_t touch_pad_sleep_channel_reset_benchmark(void)
 {
     TOUCH_ENTER_CRITICAL();
-    touch_hal_sleep_reset_baseline();
+    touch_hal_sleep_reset_benchmark();
     TOUCH_EXIT_CRITICAL();
     return ESP_OK;
 }