diff --git a/components/driver/Kconfig b/components/driver/Kconfig index 68634c78f9..2698ac746a 100644 --- a/components/driver/Kconfig +++ b/components/driver/Kconfig @@ -152,4 +152,15 @@ menu "Driver Configurations" and don't want to see related deprecation warnings, you can enable this option. endmenu # Legacy Temperature Sensor Driver Configurationss + menu "Legacy Touch Sensor Driver Configurations" + depends on SOC_TOUCH_SENSOR_SUPPORTED + config TOUCH_SUPPRESS_DEPRECATE_WARN + bool "Suppress legacy driver deprecated warning" + default n + help + whether to suppress the deprecation warnings when using legacy touch sensor driver + (driver/touch_sensor.h). If you want to continue using the legacy driver, + and don't want to see related deprecation warnings, you can enable this option. + endmenu # Legacy Touch Sensor Driver Configurationss + endmenu # Driver configurations diff --git a/components/driver/test_apps/touch_sensor_v1/main/test_touch_v1.c b/components/driver/test_apps/touch_sensor_v1/main/test_touch_v1.c index 5e7096a399..2580ed1d0c 100644 --- a/components/driver/test_apps/touch_sensor_v1/main/test_touch_v1.c +++ b/components/driver/test_apps/touch_sensor_v1/main/test_touch_v1.c @@ -10,20 +10,19 @@ #include "sdkconfig.h" #include "esp_system.h" -#include "driver/touch_pad.h" #include "unity.h" #include "esp_system.h" #include "freertos/FreeRTOS.h" #include "freertos/task.h" #include "esp_log.h" -#include "soc/rtc_cntl_reg.h" -#include "soc/rtc_cntl_struct.h" +#include "soc/soc_caps.h" #include "soc/sens_reg.h" #include "soc/sens_struct.h" #include "soc/rtc_cntl_reg.h" #include "soc/rtc_cntl_struct.h" #include "soc/rtc_io_reg.h" #include "soc/rtc_io_struct.h" +#include "driver/touch_sensor_legacy.h" #include "esp_rom_sys.h" #if CONFIG_PM_ENABLE #include "esp_pm.h" diff --git a/components/driver/test_apps/touch_sensor_v2/main/test_touch_v2.c b/components/driver/test_apps/touch_sensor_v2/main/test_touch_v2.c index 78b1d78a74..479ffe702f 100644 --- a/components/driver/test_apps/touch_sensor_v2/main/test_touch_v2.c +++ b/components/driver/test_apps/touch_sensor_v2/main/test_touch_v2.c @@ -12,7 +12,6 @@ #include #include #include "esp_system.h" -#include "driver/touch_pad.h" #include "unity.h" #include "esp_system.h" #include "freertos/FreeRTOS.h" @@ -20,8 +19,7 @@ #include "freertos/semphr.h" #include "freertos/queue.h" #include "esp_log.h" -#include "soc/rtc_cntl_reg.h" -#include "soc/rtc_cntl_struct.h" +#include "soc/soc_caps.h" #include "soc/sens_reg.h" #include "soc/sens_struct.h" #include "soc/rtc_cntl_reg.h" @@ -30,6 +28,7 @@ #include "soc/rtc_io_struct.h" #include "soc/syscon_reg.h" #include "driver/rtc_io.h" +#include "driver/touch_sensor_legacy.h" #include "esp_rom_sys.h" static const char *TAG = "test_touch"; diff --git a/components/driver/touch_sensor/esp32/include/driver/touch_sensor.h b/components/driver/touch_sensor/esp32/include/driver/touch_sensor.h index 737faf0249..c6204a6d6d 100644 --- a/components/driver/touch_sensor/esp32/include/driver/touch_sensor.h +++ b/components/driver/touch_sensor/esp32/include/driver/touch_sensor.h @@ -1,385 +1,11 @@ /* - * SPDX-FileCopyrightText: 2019-2021 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2019-2024 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ #pragma once -#ifdef __cplusplus -extern "C" { -#endif +#include "driver/touch_sensor_legacy.h" -#include "driver/touch_sensor_common.h" - -/** - * @brief Configure touch pad interrupt threshold. - * - * @note If FSM mode is set to TOUCH_FSM_MODE_TIMER, this function will be blocked for one measurement cycle and wait for data to be valid. - * - * @param touch_num touch pad index - * @param threshold interrupt threshold, - * - * @return - * - ESP_OK Success - * - ESP_ERR_INVALID_ARG if argument wrong - * - ESP_FAIL if touch pad not initialized - */ -esp_err_t touch_pad_config(touch_pad_t touch_num, uint16_t threshold); - -/** - * @brief get touch sensor counter value. - * Each touch sensor has a counter to count the number of charge/discharge cycles. - * When the pad is not 'touched', we can get a number of the counter. - * When the pad is 'touched', the value in counter will get smaller because of the larger equivalent capacitance. - * - * @note This API requests hardware measurement once. If IIR filter mode is enabled, - * please use 'touch_pad_read_raw_data' interface instead. - * - * @param touch_num touch pad index - * @param touch_value pointer to accept touch sensor value - * - * @return - * - ESP_OK Success - * - ESP_ERR_INVALID_ARG Touch pad parameter error - * - ESP_ERR_INVALID_STATE This touch pad hardware connection is error, the value of "touch_value" is 0. - * - ESP_FAIL Touch pad not initialized - */ -esp_err_t touch_pad_read(touch_pad_t touch_num, uint16_t *touch_value); - -/** - * @brief get filtered touch sensor counter value by IIR filter. - * - * @note touch_pad_filter_start has to be called before calling touch_pad_read_filtered. - * This function can be called from ISR - * - * @param touch_num touch pad index - * @param touch_value pointer to accept touch sensor value - * - * @return - * - ESP_OK Success - * - ESP_ERR_INVALID_ARG Touch pad parameter error - * - ESP_ERR_INVALID_STATE This touch pad hardware connection is error, the value of "touch_value" is 0. - * - ESP_FAIL Touch pad not initialized - */ -esp_err_t touch_pad_read_filtered(touch_pad_t touch_num, uint16_t *touch_value); - -/** - * @brief get raw data (touch sensor counter value) from IIR filter process. - * Need not request hardware measurements. - * - * @note touch_pad_filter_start has to be called before calling touch_pad_read_raw_data. - * This function can be called from ISR - * - * @param touch_num touch pad index - * @param touch_value pointer to accept touch sensor value - * - * @return - * - ESP_OK Success - * - ESP_ERR_INVALID_ARG Touch pad parameter error - * - ESP_ERR_INVALID_STATE This touch pad hardware connection is error, the value of "touch_value" is 0. - * - ESP_FAIL Touch pad not initialized - */ -esp_err_t touch_pad_read_raw_data(touch_pad_t touch_num, uint16_t *touch_value); - -/** - * @brief Callback function that is called after each IIR filter calculation. - * @note This callback is called in timer task in each filtering cycle. - * @note This callback should not be blocked. - * @param raw_value The latest raw data(touch sensor counter value) that - * points to all channels(raw_value[0..TOUCH_PAD_MAX-1]). - * @param filtered_value The latest IIR filtered data(calculated from raw data) that - * points to all channels(filtered_value[0..TOUCH_PAD_MAX-1]). - * - */ -typedef void (* filter_cb_t)(uint16_t *raw_value, uint16_t *filtered_value); - -/** - * @brief Register the callback function that is called after each IIR filter calculation. - * @note The 'read_cb' callback is called in timer task in each filtering cycle. - * @param read_cb Pointer to filtered callback function. - * If the argument passed in is NULL, the callback will stop. - * @return - * - ESP_OK Success - * - ESP_ERR_INVALID_ARG set error - */ -esp_err_t touch_pad_set_filter_read_cb(filter_cb_t read_cb); - -/** - * @brief Register touch-pad ISR. - * The handler will be attached to the same CPU core that this function is running on. - * @param fn Pointer to ISR handler - * @param arg Parameter for ISR - * @return - * - ESP_OK Success ; - * - ESP_ERR_INVALID_ARG GPIO error - * - ESP_ERR_NO_MEM No memory - */ -esp_err_t touch_pad_isr_register(intr_handler_t fn, void *arg); - -/** - * @brief Set the clock cycles of each measurement - * @note This function will specify the clock cycles of each measurement - * and the clock is sourced from SOC_MOD_CLK_RTC_FAST, its default frequency is SOC_CLK_RC_FAST_FREQ_APPROX - * The touch sensor will record the charge and discharge times during these clock cycles as the final result (raw value) - * @note If clock cycles is too small, it may lead to inaccurate results. - * - * @param clock_cycle The clock cycles of each measurement - * measure_time = clock_cycle / SOC_CLK_RC_FAST_FREQ_APPROX, the maximum measure time is 0xffff / SOC_CLK_RC_FAST_FREQ_APPROX - * @return - * - ESP_OK Set the clock cycle success - */ -esp_err_t touch_pad_set_measurement_clock_cycles(uint16_t clock_cycle); - -/** - * @brief Get the clock cycles of each measurement - * - * @param clock_cycle The clock cycles of each measurement - * @return - * - ESP_OK Get the clock cycle success - * - ESP_ERR_INVALID_ARG The input parameter is NULL - */ -esp_err_t touch_pad_get_measurement_clock_cycles(uint16_t *clock_cycle); - -/** - * @brief Set the interval between two measurements - * @note The touch sensor will sleep between two measurements - * This function is to set the interval cycle - * And the interval is clocked from SOC_MOD_CLK_RTC_SLOW, its default frequency is SOC_CLK_RC_SLOW_FREQ_APPROX - * - * @param interval_cycle The interval between two measurements - * sleep_time = interval_cycle / SOC_CLK_RC_SLOW_FREQ_APPROX. - * The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function. - * @return - * - ESP_OK Set interval cycle success - */ -esp_err_t touch_pad_set_measurement_interval(uint16_t interval_cycle); - -/** - * @brief Get the interval between two measurements - * - * @param interval_cycle The interval between two measurements - * @return - * - ESP_OK Get interval cycle success - * - ESP_ERR_INVALID_ARG The input parameter is NULL - */ -esp_err_t touch_pad_get_measurement_interval(uint16_t *interval_cycle); - -/** - * @brief Set touch sensor measurement and sleep time. - * Excessive total time will slow down the touch response. - * Too small measurement time will not be sampled enough, resulting in inaccurate measurements. - * @note The touch sensor will count the number of charge/discharge cycles over a fixed period of time (specified as the second parameter). - * That means the number of cycles (raw value) will decrease as the capacity of the touch pad is increasing. - * @note The greater the duty cycle of the measurement time, the more system power is consumed. - * - * @param sleep_cycle The touch sensor will sleep after each measurement. - * sleep_cycle decide the interval between each measurement. - * t_sleep = sleep_cycle / SOC_CLK_RC_SLOW_FREQ_APPROX. - * The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function. - * @param meas_cycle The duration of the touch sensor measurement. - * t_meas = meas_cycle / SOC_CLK_RC_FAST_FREQ_APPROX, the maximum measure time is 0xffff / SOC_CLK_RC_FAST_FREQ_APPROX - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_cycle) -__attribute__((deprecated("please use 'touch_pad_set_measurement_clock_cycles' and 'touch_pad_set_measurement_interval' instead"))); - -/** - * @brief Get touch sensor measurement and sleep time - * @param sleep_cycle Pointer to accept sleep cycle number - * @param meas_cycle Pointer to accept measurement cycle count. - * @return - * - ESP_OK on success - * - ESP_ERR_INVALID_ARG The input parameter is NULL - */ -esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_cycle) -__attribute__((deprecated("please use 'touch_pad_get_measurement_clock_cycles' and 'touch_pad_get_measurement_interval' instead"))); - -/** - * @brief Trigger a touch sensor measurement, only support in SW mode of FSM - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_sw_start(void); - -/** - * @brief Set touch sensor interrupt threshold - * @param touch_num touch pad index - * @param threshold threshold of touchpad count, refer to touch_pad_set_trigger_mode to see how to set trigger mode. - * @return - * - ESP_OK on success - * - ESP_ERR_INVALID_ARG if argument is wrong - */ -esp_err_t touch_pad_set_thresh(touch_pad_t touch_num, uint16_t threshold); - -/** - * @brief Get touch sensor interrupt threshold - * @param touch_num touch pad index - * @param threshold pointer to accept threshold - * @return - * - ESP_OK on success - * - ESP_ERR_INVALID_ARG if argument is wrong - */ -esp_err_t touch_pad_get_thresh(touch_pad_t touch_num, uint16_t *threshold); - -/** - * @brief Set touch sensor interrupt trigger mode. - * Interrupt can be triggered either when counter result is less than - * threshold or when counter result is more than threshold. - * @param mode touch sensor interrupt trigger mode - * @return - * - ESP_OK on success - * - ESP_ERR_INVALID_ARG if argument is wrong - */ -esp_err_t touch_pad_set_trigger_mode(touch_trigger_mode_t mode); - -/** - * @brief Get touch sensor interrupt trigger mode - * @param mode pointer to accept touch sensor interrupt trigger mode - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_get_trigger_mode(touch_trigger_mode_t *mode); - -/** - * @brief Set touch sensor interrupt trigger source. There are two sets of touch signals. - * Set1 and set2 can be mapped to several touch signals. Either set will be triggered - * if at least one of its touch signal is 'touched'. The interrupt can be configured to be generated - * if set1 is triggered, or only if both sets are triggered. - * @param src touch sensor interrupt trigger source - * @return - * - ESP_OK on success - * - ESP_ERR_INVALID_ARG if argument is wrong - */ -esp_err_t touch_pad_set_trigger_source(touch_trigger_src_t src); - -/** - * @brief Get touch sensor interrupt trigger source - * @param src pointer to accept touch sensor interrupt trigger source - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_get_trigger_source(touch_trigger_src_t *src); - -/** - * @brief Set touch sensor group mask. - * Touch pad module has two sets of signals, 'Touched' signal is triggered only if - * at least one of touch pad in this group is "touched". - * This function will set the register bits according to the given bitmask. - * @param set1_mask bitmask of touch sensor signal group1, it's a 10-bit value - * @param set2_mask bitmask of touch sensor signal group2, it's a 10-bit value - * @param en_mask bitmask of touch sensor work enable, it's a 10-bit value - * @return - * - ESP_OK on success - * - ESP_ERR_INVALID_ARG if argument is wrong - */ -esp_err_t touch_pad_set_group_mask(uint16_t set1_mask, uint16_t set2_mask, uint16_t en_mask); - -/** - * @brief Get touch sensor group mask. - * @param set1_mask pointer to accept bitmask of touch sensor signal group1, it's a 10-bit value - * @param set2_mask pointer to accept bitmask of touch sensor signal group2, it's a 10-bit value - * @param en_mask pointer to accept bitmask of touch sensor work enable, it's a 10-bit value - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_get_group_mask(uint16_t *set1_mask, uint16_t *set2_mask, uint16_t *en_mask); - -/** - * @brief Clear touch sensor group mask. - * Touch pad module has two sets of signals, Interrupt is triggered only if - * at least one of touch pad in this group is "touched". - * This function will clear the register bits according to the given bitmask. - * @param set1_mask bitmask touch sensor signal group1, it's a 10-bit value - * @param set2_mask bitmask touch sensor signal group2, it's a 10-bit value - * @param en_mask bitmask of touch sensor work enable, it's a 10-bit value - * @return - * - ESP_OK on success - * - ESP_ERR_INVALID_ARG if argument is wrong - */ -esp_err_t touch_pad_clear_group_mask(uint16_t set1_mask, uint16_t set2_mask, uint16_t en_mask); - -/** - * @brief To enable touch pad interrupt - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_intr_enable(void); - -/** - * @brief To disable touch pad interrupt - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_intr_disable(void); - -/** - * @brief To clear touch pad interrupt - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_intr_clear(void); - -/** - * @brief set touch pad filter calibration period, in ms. - * Need to call touch_pad_filter_start before all touch filter APIs - * @param new_period_ms filter period, in ms - * @return - * - ESP_OK Success - * - ESP_ERR_INVALID_STATE driver state error - * - ESP_ERR_INVALID_ARG parameter error - */ -esp_err_t touch_pad_set_filter_period(uint32_t new_period_ms); - -/** - * @brief get touch pad filter calibration period, in ms - * Need to call touch_pad_filter_start before all touch filter APIs - * @param p_period_ms pointer to accept period - * @return - * - ESP_OK Success - * - ESP_ERR_INVALID_STATE driver state error - * - ESP_ERR_INVALID_ARG parameter error - */ -esp_err_t touch_pad_get_filter_period(uint32_t *p_period_ms); - -/** - * @brief start touch pad filter function - * This API will start a filter to process the noise in order to prevent false triggering - * when detecting slight change of capacitance. - * Need to call touch_pad_filter_start before all touch filter APIs - * - * @note This filter uses FreeRTOS timer, which is dispatched from a task with - * priority 1 by default on CPU 0. So if some application task with higher priority - * takes a lot of CPU0 time, then the quality of data obtained from this filter will be affected. - * You can adjust FreeRTOS timer task priority in menuconfig. - * @param filter_period_ms filter calibration period, in ms - * @return - * - ESP_OK Success - * - ESP_ERR_INVALID_ARG parameter error - * - ESP_ERR_NO_MEM No memory for driver - * - ESP_ERR_INVALID_STATE driver state error - */ -esp_err_t touch_pad_filter_start(uint32_t filter_period_ms); - -/** - * @brief stop touch pad filter function - * Need to call touch_pad_filter_start before all touch filter APIs - * @return - * - ESP_OK Success - * - ESP_ERR_INVALID_STATE driver state error - */ -esp_err_t touch_pad_filter_stop(void); - -/** - * @brief delete touch pad filter driver and release the memory - * Need to call touch_pad_filter_start before all touch filter APIs - * @return - * - ESP_OK Success - * - ESP_ERR_INVALID_STATE driver state error - */ -esp_err_t touch_pad_filter_delete(void); - -#ifdef __cplusplus -} -#endif +// Keep for compatibility diff --git a/components/driver/touch_sensor/esp32/include/driver/touch_sensor_legacy.h b/components/driver/touch_sensor/esp32/include/driver/touch_sensor_legacy.h new file mode 100644 index 0000000000..c1a6f759f2 --- /dev/null +++ b/components/driver/touch_sensor/esp32/include/driver/touch_sensor_legacy.h @@ -0,0 +1,385 @@ +/* + * SPDX-FileCopyrightText: 2019-2024 Espressif Systems (Shanghai) CO LTD + * + * SPDX-License-Identifier: Apache-2.0 + */ + +#pragma once + +#ifdef __cplusplus +extern "C" { +#endif + +#include "driver/touch_sensor_common.h" + +/** + * @brief Configure touch pad interrupt threshold. + * + * @note If FSM mode is set to TOUCH_FSM_MODE_TIMER, this function will be blocked for one measurement cycle and wait for data to be valid. + * + * @param touch_num touch pad index + * @param threshold interrupt threshold, + * + * @return + * - ESP_OK Success + * - ESP_ERR_INVALID_ARG if argument wrong + * - ESP_FAIL if touch pad not initialized + */ +esp_err_t touch_pad_config(touch_pad_t touch_num, uint16_t threshold); + +/** + * @brief get touch sensor counter value. + * Each touch sensor has a counter to count the number of charge/discharge cycles. + * When the pad is not 'touched', we can get a number of the counter. + * When the pad is 'touched', the value in counter will get smaller because of the larger equivalent capacitance. + * + * @note This API requests hardware measurement once. If IIR filter mode is enabled, + * please use 'touch_pad_read_raw_data' interface instead. + * + * @param touch_num touch pad index + * @param touch_value pointer to accept touch sensor value + * + * @return + * - ESP_OK Success + * - ESP_ERR_INVALID_ARG Touch pad parameter error + * - ESP_ERR_INVALID_STATE This touch pad hardware connection is error, the value of "touch_value" is 0. + * - ESP_FAIL Touch pad not initialized + */ +esp_err_t touch_pad_read(touch_pad_t touch_num, uint16_t *touch_value); + +/** + * @brief get filtered touch sensor counter value by IIR filter. + * + * @note touch_pad_filter_start has to be called before calling touch_pad_read_filtered. + * This function can be called from ISR + * + * @param touch_num touch pad index + * @param touch_value pointer to accept touch sensor value + * + * @return + * - ESP_OK Success + * - ESP_ERR_INVALID_ARG Touch pad parameter error + * - ESP_ERR_INVALID_STATE This touch pad hardware connection is error, the value of "touch_value" is 0. + * - ESP_FAIL Touch pad not initialized + */ +esp_err_t touch_pad_read_filtered(touch_pad_t touch_num, uint16_t *touch_value); + +/** + * @brief get raw data (touch sensor counter value) from IIR filter process. + * Need not request hardware measurements. + * + * @note touch_pad_filter_start has to be called before calling touch_pad_read_raw_data. + * This function can be called from ISR + * + * @param touch_num touch pad index + * @param touch_value pointer to accept touch sensor value + * + * @return + * - ESP_OK Success + * - ESP_ERR_INVALID_ARG Touch pad parameter error + * - ESP_ERR_INVALID_STATE This touch pad hardware connection is error, the value of "touch_value" is 0. + * - ESP_FAIL Touch pad not initialized + */ +esp_err_t touch_pad_read_raw_data(touch_pad_t touch_num, uint16_t *touch_value); + +/** + * @brief Callback function that is called after each IIR filter calculation. + * @note This callback is called in timer task in each filtering cycle. + * @note This callback should not be blocked. + * @param raw_value The latest raw data(touch sensor counter value) that + * points to all channels(raw_value[0..TOUCH_PAD_MAX-1]). + * @param filtered_value The latest IIR filtered data(calculated from raw data) that + * points to all channels(filtered_value[0..TOUCH_PAD_MAX-1]). + * + */ +typedef void (* filter_cb_t)(uint16_t *raw_value, uint16_t *filtered_value); + +/** + * @brief Register the callback function that is called after each IIR filter calculation. + * @note The 'read_cb' callback is called in timer task in each filtering cycle. + * @param read_cb Pointer to filtered callback function. + * If the argument passed in is NULL, the callback will stop. + * @return + * - ESP_OK Success + * - ESP_ERR_INVALID_ARG set error + */ +esp_err_t touch_pad_set_filter_read_cb(filter_cb_t read_cb); + +/** + * @brief Register touch-pad ISR. + * The handler will be attached to the same CPU core that this function is running on. + * @param fn Pointer to ISR handler + * @param arg Parameter for ISR + * @return + * - ESP_OK Success ; + * - ESP_ERR_INVALID_ARG GPIO error + * - ESP_ERR_NO_MEM No memory + */ +esp_err_t touch_pad_isr_register(intr_handler_t fn, void *arg); + +/** + * @brief Set the clock cycles of each measurement + * @note This function will specify the clock cycles of each measurement + * and the clock is sourced from SOC_MOD_CLK_RTC_FAST, its default frequency is SOC_CLK_RC_FAST_FREQ_APPROX + * The touch sensor will record the charge and discharge times during these clock cycles as the final result (raw value) + * @note If clock cycles is too small, it may lead to inaccurate results. + * + * @param clock_cycle The clock cycles of each measurement + * measure_time = clock_cycle / SOC_CLK_RC_FAST_FREQ_APPROX, the maximum measure time is 0xffff / SOC_CLK_RC_FAST_FREQ_APPROX + * @return + * - ESP_OK Set the clock cycle success + */ +esp_err_t touch_pad_set_measurement_clock_cycles(uint16_t clock_cycle); + +/** + * @brief Get the clock cycles of each measurement + * + * @param clock_cycle The clock cycles of each measurement + * @return + * - ESP_OK Get the clock cycle success + * - ESP_ERR_INVALID_ARG The input parameter is NULL + */ +esp_err_t touch_pad_get_measurement_clock_cycles(uint16_t *clock_cycle); + +/** + * @brief Set the interval between two measurements + * @note The touch sensor will sleep between two measurements + * This function is to set the interval cycle + * And the interval is clocked from SOC_MOD_CLK_RTC_SLOW, its default frequency is SOC_CLK_RC_SLOW_FREQ_APPROX + * + * @param interval_cycle The interval between two measurements + * sleep_time = interval_cycle / SOC_CLK_RC_SLOW_FREQ_APPROX. + * The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function. + * @return + * - ESP_OK Set interval cycle success + */ +esp_err_t touch_pad_set_measurement_interval(uint16_t interval_cycle); + +/** + * @brief Get the interval between two measurements + * + * @param interval_cycle The interval between two measurements + * @return + * - ESP_OK Get interval cycle success + * - ESP_ERR_INVALID_ARG The input parameter is NULL + */ +esp_err_t touch_pad_get_measurement_interval(uint16_t *interval_cycle); + +/** + * @brief Set touch sensor measurement and sleep time. + * Excessive total time will slow down the touch response. + * Too small measurement time will not be sampled enough, resulting in inaccurate measurements. + * @note The touch sensor will count the number of charge/discharge cycles over a fixed period of time (specified as the second parameter). + * That means the number of cycles (raw value) will decrease as the capacity of the touch pad is increasing. + * @note The greater the duty cycle of the measurement time, the more system power is consumed. + * + * @param sleep_cycle The touch sensor will sleep after each measurement. + * sleep_cycle decide the interval between each measurement. + * t_sleep = sleep_cycle / SOC_CLK_RC_SLOW_FREQ_APPROX. + * The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function. + * @param meas_cycle The duration of the touch sensor measurement. + * t_meas = meas_cycle / SOC_CLK_RC_FAST_FREQ_APPROX, the maximum measure time is 0xffff / SOC_CLK_RC_FAST_FREQ_APPROX + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_cycle) +__attribute__((deprecated("please use 'touch_pad_set_measurement_clock_cycles' and 'touch_pad_set_measurement_interval' instead"))); + +/** + * @brief Get touch sensor measurement and sleep time + * @param sleep_cycle Pointer to accept sleep cycle number + * @param meas_cycle Pointer to accept measurement cycle count. + * @return + * - ESP_OK on success + * - ESP_ERR_INVALID_ARG The input parameter is NULL + */ +esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_cycle) +__attribute__((deprecated("please use 'touch_pad_get_measurement_clock_cycles' and 'touch_pad_get_measurement_interval' instead"))); + +/** + * @brief Trigger a touch sensor measurement, only support in SW mode of FSM + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_sw_start(void); + +/** + * @brief Set touch sensor interrupt threshold + * @param touch_num touch pad index + * @param threshold threshold of touchpad count, refer to touch_pad_set_trigger_mode to see how to set trigger mode. + * @return + * - ESP_OK on success + * - ESP_ERR_INVALID_ARG if argument is wrong + */ +esp_err_t touch_pad_set_thresh(touch_pad_t touch_num, uint16_t threshold); + +/** + * @brief Get touch sensor interrupt threshold + * @param touch_num touch pad index + * @param threshold pointer to accept threshold + * @return + * - ESP_OK on success + * - ESP_ERR_INVALID_ARG if argument is wrong + */ +esp_err_t touch_pad_get_thresh(touch_pad_t touch_num, uint16_t *threshold); + +/** + * @brief Set touch sensor interrupt trigger mode. + * Interrupt can be triggered either when counter result is less than + * threshold or when counter result is more than threshold. + * @param mode touch sensor interrupt trigger mode + * @return + * - ESP_OK on success + * - ESP_ERR_INVALID_ARG if argument is wrong + */ +esp_err_t touch_pad_set_trigger_mode(touch_trigger_mode_t mode); + +/** + * @brief Get touch sensor interrupt trigger mode + * @param mode pointer to accept touch sensor interrupt trigger mode + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_get_trigger_mode(touch_trigger_mode_t *mode); + +/** + * @brief Set touch sensor interrupt trigger source. There are two sets of touch signals. + * Set1 and set2 can be mapped to several touch signals. Either set will be triggered + * if at least one of its touch signal is 'touched'. The interrupt can be configured to be generated + * if set1 is triggered, or only if both sets are triggered. + * @param src touch sensor interrupt trigger source + * @return + * - ESP_OK on success + * - ESP_ERR_INVALID_ARG if argument is wrong + */ +esp_err_t touch_pad_set_trigger_source(touch_trigger_src_t src); + +/** + * @brief Get touch sensor interrupt trigger source + * @param src pointer to accept touch sensor interrupt trigger source + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_get_trigger_source(touch_trigger_src_t *src); + +/** + * @brief Set touch sensor group mask. + * Touch pad module has two sets of signals, 'Touched' signal is triggered only if + * at least one of touch pad in this group is "touched". + * This function will set the register bits according to the given bitmask. + * @param set1_mask bitmask of touch sensor signal group1, it's a 10-bit value + * @param set2_mask bitmask of touch sensor signal group2, it's a 10-bit value + * @param en_mask bitmask of touch sensor work enable, it's a 10-bit value + * @return + * - ESP_OK on success + * - ESP_ERR_INVALID_ARG if argument is wrong + */ +esp_err_t touch_pad_set_group_mask(uint16_t set1_mask, uint16_t set2_mask, uint16_t en_mask); + +/** + * @brief Get touch sensor group mask. + * @param set1_mask pointer to accept bitmask of touch sensor signal group1, it's a 10-bit value + * @param set2_mask pointer to accept bitmask of touch sensor signal group2, it's a 10-bit value + * @param en_mask pointer to accept bitmask of touch sensor work enable, it's a 10-bit value + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_get_group_mask(uint16_t *set1_mask, uint16_t *set2_mask, uint16_t *en_mask); + +/** + * @brief Clear touch sensor group mask. + * Touch pad module has two sets of signals, Interrupt is triggered only if + * at least one of touch pad in this group is "touched". + * This function will clear the register bits according to the given bitmask. + * @param set1_mask bitmask touch sensor signal group1, it's a 10-bit value + * @param set2_mask bitmask touch sensor signal group2, it's a 10-bit value + * @param en_mask bitmask of touch sensor work enable, it's a 10-bit value + * @return + * - ESP_OK on success + * - ESP_ERR_INVALID_ARG if argument is wrong + */ +esp_err_t touch_pad_clear_group_mask(uint16_t set1_mask, uint16_t set2_mask, uint16_t en_mask); + +/** + * @brief To enable touch pad interrupt + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_intr_enable(void); + +/** + * @brief To disable touch pad interrupt + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_intr_disable(void); + +/** + * @brief To clear touch pad interrupt + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_intr_clear(void); + +/** + * @brief set touch pad filter calibration period, in ms. + * Need to call touch_pad_filter_start before all touch filter APIs + * @param new_period_ms filter period, in ms + * @return + * - ESP_OK Success + * - ESP_ERR_INVALID_STATE driver state error + * - ESP_ERR_INVALID_ARG parameter error + */ +esp_err_t touch_pad_set_filter_period(uint32_t new_period_ms); + +/** + * @brief get touch pad filter calibration period, in ms + * Need to call touch_pad_filter_start before all touch filter APIs + * @param p_period_ms pointer to accept period + * @return + * - ESP_OK Success + * - ESP_ERR_INVALID_STATE driver state error + * - ESP_ERR_INVALID_ARG parameter error + */ +esp_err_t touch_pad_get_filter_period(uint32_t *p_period_ms); + +/** + * @brief start touch pad filter function + * This API will start a filter to process the noise in order to prevent false triggering + * when detecting slight change of capacitance. + * Need to call touch_pad_filter_start before all touch filter APIs + * + * @note This filter uses FreeRTOS timer, which is dispatched from a task with + * priority 1 by default on CPU 0. So if some application task with higher priority + * takes a lot of CPU0 time, then the quality of data obtained from this filter will be affected. + * You can adjust FreeRTOS timer task priority in menuconfig. + * @param filter_period_ms filter calibration period, in ms + * @return + * - ESP_OK Success + * - ESP_ERR_INVALID_ARG parameter error + * - ESP_ERR_NO_MEM No memory for driver + * - ESP_ERR_INVALID_STATE driver state error + */ +esp_err_t touch_pad_filter_start(uint32_t filter_period_ms); + +/** + * @brief stop touch pad filter function + * Need to call touch_pad_filter_start before all touch filter APIs + * @return + * - ESP_OK Success + * - ESP_ERR_INVALID_STATE driver state error + */ +esp_err_t touch_pad_filter_stop(void); + +/** + * @brief delete touch pad filter driver and release the memory + * Need to call touch_pad_filter_start before all touch filter APIs + * @return + * - ESP_OK Success + * - ESP_ERR_INVALID_STATE driver state error + */ +esp_err_t touch_pad_filter_delete(void); + +#ifdef __cplusplus +} +#endif diff --git a/components/driver/touch_sensor/esp32s2/include/driver/touch_sensor.h b/components/driver/touch_sensor/esp32s2/include/driver/touch_sensor.h index 06f835879f..adb40726ae 100644 --- a/components/driver/touch_sensor/esp32s2/include/driver/touch_sensor.h +++ b/components/driver/touch_sensor/esp32s2/include/driver/touch_sensor.h @@ -1,646 +1,17 @@ /* - * SPDX-FileCopyrightText: 2019-2021 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2019-2024 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ #pragma once -#include "driver/touch_sensor_common.h" +#include "sdkconfig.h" +#include "driver/touch_sensor_legacy.h" -#ifdef __cplusplus -extern "C" { -#endif - -/** - * @brief Set touch sensor FSM start - * @note Start FSM after the touch sensor FSM mode is set. - * @note Call this function will reset benchmark of all touch channels. - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_fsm_start(void); - -/** - * @brief Stop touch sensor FSM. - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_fsm_stop(void); - -/** - * @brief Trigger a touch sensor measurement, only support in SW mode of FSM - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_sw_start(void); - -/** - * @brief Set charge and discharge times of each measurement - * @note This function will specify the charge and discharge times in each measurement period - * The clock is sourced from SOC_MOD_CLK_RTC_FAST, and its default frequency is SOC_CLK_RC_FAST_FREQ_APPROX - * The touch sensor will record the total clock cycles of all the charge and discharge cycles as the final result (raw value) - * @note If the charge and discharge times is too small, it may lead to inaccurate results. - * - * @param charge_discharge_times Charge and discharge times, range: 0 ~ 0xffff. - * No exact typical value can be recommended because the capacity is influenced by the hardware design and how finger touches, - * but suggest adjusting this value to make the measurement time around 1 ms. - * @return - * - ESP_OK Set charge and discharge times success - */ -esp_err_t touch_pad_set_charge_discharge_times(uint16_t charge_discharge_times); - -/** - * @brief Get charge and discharge times of each measurement - * - * @param charge_discharge_times Charge and discharge times - * @return - * - ESP_OK Get charge_discharge_times success - * - ESP_ERR_INVALID_ARG The input parameter is NULL - */ -esp_err_t touch_pad_get_charge_discharge_times(uint16_t *charge_discharge_times); - -/** - * @brief Set the interval between two measurements - * @note The touch sensor will sleep between two measurements - * This function is to set the interval cycle - * And the interval is clocked from SOC_MOD_CLK_RTC_SLOW, its default frequency is SOC_CLK_RC_SLOW_FREQ_APPROX - * - * @param interval_cycle The interval between two measurements - * sleep_time = interval_cycle / SOC_CLK_RC_SLOW_FREQ_APPROX. - * The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function. - * @return - * - ESP_OK Set interval cycle success - */ -esp_err_t touch_pad_set_measurement_interval(uint16_t interval_cycle); - -/** - * @brief Get the interval between two measurements - * - * @param interval_cycle The interval between two measurements - * @return - * - ESP_OK Get interval cycle success - * - ESP_ERR_INVALID_ARG The input parameter is NULL - */ -esp_err_t touch_pad_get_measurement_interval(uint16_t *interval_cycle); - -/** - * @brief Set touch sensor times of charge and discharge and sleep time. - * Excessive total time will slow down the touch response. - * Too small measurement time will not be sampled enough, resulting in inaccurate measurements. - * @note The touch sensor will measure time of a fixed number of charge/discharge cycles (specified as the second parameter). - * That means the time (raw value) will increase as the capacity of the touch pad is increasing. - * The time (raw value) here is the number of clock cycles which is sourced from SOC_MOD_CLK_RTC_FAST and at (SOC_CLK_RC_FAST_FREQ_APPROX) Hz as default - * @note The greater the duty cycle of the measurement time, the more system power is consumed. - * - * @param sleep_cycle The touch sensor will sleep after each measurement. - * sleep_cycle decide the interval between each measurement. - * t_sleep = sleep_cycle / SOC_CLK_RC_SLOW_FREQ_APPROX. - * The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function. - * @param meas_times The times of charge and discharge in each measurement of touch channels. Range: 0 ~ 0xffff. - * Recommended typical value: Modify this value to make the measurement time around 1 ms. - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_times) -__attribute__((deprecated("please use 'touch_pad_set_charge_discharge_times' and 'touch_pad_set_measurement_interval' instead"))); - -/** - * @brief Get touch sensor times of charge and discharge and sleep time - * @param sleep_cycle Pointer to accept sleep cycle number - * @param meas_times Pointer to accept measurement times count. - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_times) -__attribute__((deprecated("please use 'touch_pad_get_charge_discharge_times' and 'touch_pad_get_measurement_interval' instead"))); - -/** - * @brief Set the connection type of touch channels in idle status. - * When a channel is in measurement mode, other initialized channels are in idle mode. - * The touch channel is generally adjacent to the trace, so the connection state of the idle channel - * affects the stability and sensitivity of the test channel. - * The `CONN_HIGHZ`(high resistance) setting increases the sensitivity of touch channels. - * The `CONN_GND`(grounding) setting increases the stability of touch channels. - * @param type Select idle channel connect to high resistance state or ground. - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_set_idle_channel_connect(touch_pad_conn_type_t type); - -/** - * @brief Get the connection type of touch channels in idle status. - * When a channel is in measurement mode, other initialized channels are in idle mode. - * The touch channel is generally adjacent to the trace, so the connection state of the idle channel - * affects the stability and sensitivity of the test channel. - * The `CONN_HIGHZ`(high resistance) setting increases the sensitivity of touch channels. - * The `CONN_GND`(grounding) setting increases the stability of touch channels. - * @param type Pointer to connection type. - * @return - * - ESP_OK on success - */ -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 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. - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_set_thresh(touch_pad_t touch_num, uint32_t threshold); - -/** - * @brief Get touch sensor trigger threshold - * @param touch_num touch pad index - * @param threshold pointer to accept threshold - * @return - * - ESP_OK on success - * - ESP_ERR_INVALID_ARG if argument is wrong - */ -esp_err_t touch_pad_get_thresh(touch_pad_t touch_num, uint32_t *threshold); - -/** - * @brief Register touch channel into touch sensor scan group. - * The working mode of the touch sensor is cyclically scanned. - * This function will set the scan bits according to the given bitmask. - * @note If set this mask, the FSM timer should be stop firsty. - * @note The touch sensor that in scan map, should be deinit GPIO function firstly by `touch_pad_io_init`. - * @param enable_mask bitmask of touch sensor scan group. - * e.g. TOUCH_PAD_NUM14 -> BIT(14) - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_set_channel_mask(uint16_t enable_mask); - -/** - * @brief Get the touch sensor scan group bit mask. - * @param enable_mask Pointer to bitmask of touch sensor scan group. - * e.g. TOUCH_PAD_NUM14 -> BIT(14) - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_get_channel_mask(uint16_t *enable_mask); - -/** - * @brief Clear touch channel from touch sensor scan group. - * The working mode of the touch sensor is cyclically scanned. - * This function will clear the scan bits according to the given bitmask. - * @note If clear all mask, the FSM timer should be stop firsty. - * @param enable_mask bitmask of touch sensor scan group. - * e.g. TOUCH_PAD_NUM14 -> BIT(14) - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_clear_channel_mask(uint16_t enable_mask); - -/** - * @brief Configure parameter for each touch channel. - * @note Touch num 0 is denoise channel, please use `touch_pad_denoise_enable` to set denoise function - * @param touch_num touch pad index - * @return - * - ESP_OK Success - * - ESP_ERR_INVALID_ARG if argument wrong - * - ESP_FAIL if touch pad not initialized - */ -esp_err_t touch_pad_config(touch_pad_t touch_num); - -/** - * @brief Reset the FSM of touch module. - * @note Call this function after `touch_pad_fsm_stop`. - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_reset(void); - -/** - * @brief Get the current measure channel. - * @note Should be called when touch sensor measurement is in cyclic scan mode. - * @return - * - touch channel number - */ -touch_pad_t touch_pad_get_current_meas_channel(void); - -/** - * @brief Get the touch sensor interrupt status mask. - * @return - * - touch interrupt bit - */ -uint32_t touch_pad_read_intr_status_mask(void); - -/** - * @brief Enable touch sensor interrupt by bitmask. - * @note This API can be called in ISR handler. - * @param int_mask Pad mask to enable interrupts - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_intr_enable(touch_pad_intr_mask_t int_mask); - -/** - * @brief Disable touch sensor interrupt by bitmask. - * @note This API can be called in ISR handler. - * @param int_mask Pad mask to disable interrupts - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_intr_disable(touch_pad_intr_mask_t int_mask); - -/** - * @brief Clear touch sensor interrupt by bitmask. - * @param int_mask Pad mask to clear interrupts - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_intr_clear(touch_pad_intr_mask_t int_mask); - -/** - * @brief Register touch-pad ISR. - * The handler will be attached to the same CPU core that this function is running on. - * @param fn Pointer to ISR handler - * @param arg Parameter for ISR - * @param intr_mask Enable touch sensor interrupt handler by bitmask. - * @return - * - ESP_OK Success - * - ESP_ERR_INVALID_ARG Arguments error - * - ESP_ERR_NO_MEM No memory - */ -esp_err_t touch_pad_isr_register(intr_handler_t fn, void *arg, touch_pad_intr_mask_t intr_mask); - -/** - * @brief Enable/disable the timeout check and set timeout threshold for all touch sensor channels measurements. - * If enable: When the touch reading of a touch channel exceeds the measurement threshold, a timeout interrupt will be generated. - * If disable: the FSM does not check if the channel under measurement times out. - * - * @note The threshold compared with touch readings. - * @note In order to avoid abnormal short circuit of some touch channels. This function should be turned on. - * Ensure the normal operation of other touch channels. - * - * @param enable true(default): Enable the timeout check; false: Disable the timeout check. - * @param threshold For all channels, the maximum value that will not be exceeded during normal operation. - * -* @return - * - ESP_OK Success - */ -esp_err_t touch_pad_timeout_set(bool enable, uint32_t threshold); - -/** - * @brief Call this interface after timeout to make the touch channel resume normal work. Point on the next channel to measure. - * If this API is not called, the touch FSM will stop the measurement after timeout interrupt. - * - * @note Call this API after finishes the exception handling by user. - * - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_timeout_resume(void); - -/** - * @brief get raw data of touch sensor. - * @note After the initialization is complete, the "raw_data" is max value. You need to wait for a measurement - * cycle before you can read the correct touch value. - * @param touch_num touch pad index - * @param raw_data pointer to accept touch sensor value - * @return - * - ESP_OK Success - * - ESP_FAIL Touch channel 0 haven't this parameter. - */ - -esp_err_t touch_pad_read_raw_data(touch_pad_t touch_num, uint32_t *raw_data); - -/** - * @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 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_read_benchmark(touch_pad_t touch_num, uint32_t *benchmark); - -/** - * @brief Get smoothed data that obtained by filtering the raw data. - * - * @param touch_num touch pad index - * @param smooth pointer to smoothed data - */ -esp_err_t touch_pad_filter_read_smooth(touch_pad_t touch_num, uint32_t *smooth); - -/** - * @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_reset_benchmark(touch_pad_t touch_num); - -/** - * @brief set parameter of touch sensor filter and detection algorithm. - * For more details on the detection algorithm, please refer to the application documentation. - * @param filter_info select filter type and threshold of detection algorithm - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_filter_set_config(const touch_filter_config_t *filter_info); - -/** - * @brief get parameter of touch sensor filter and detection algorithm. - * For more details on the detection algorithm, please refer to the application documentation. - * @param filter_info select filter type and threshold of detection algorithm - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_filter_get_config(touch_filter_config_t *filter_info); - -/** - * @brief enable touch sensor filter for detection algorithm. - * For more details on the detection algorithm, please refer to the application documentation. - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_filter_enable(void); - -/** - * @brief disable touch sensor filter for detection algorithm. - * For more details on the detection algorithm, please refer to the application documentation. - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_filter_disable(void); - -/** - * @brief set parameter of denoise pad (TOUCH_PAD_NUM0). - * T0 is an internal channel that does not have a corresponding external GPIO. - * T0 will work simultaneously with the measured channel Tn. Finally, the actual - * measured value of Tn is the value after subtracting lower bits of T0. - * The noise reduction function filters out interference introduced simultaneously on all channels, - * such as noise introduced by power supplies and external EMI. - * @param denoise parameter of denoise - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_denoise_set_config(const touch_pad_denoise_t *denoise); - -/** - * @brief get parameter of denoise pad (TOUCH_PAD_NUM0). - * @param denoise Pointer to parameter of denoise - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_denoise_get_config(touch_pad_denoise_t *denoise); - -/** - * @brief enable denoise function. - * T0 is an internal channel that does not have a corresponding external GPIO. - * T0 will work simultaneously with the measured channel Tn. Finally, the actual - * measured value of Tn is the value after subtracting lower bits of T0. - * The noise reduction function filters out interference introduced simultaneously on all channels, - * such as noise introduced by power supplies and external EMI. - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_denoise_enable(void); - -/** - * @brief disable denoise function. - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_denoise_disable(void); - -/** - * @brief Get denoise measure value (TOUCH_PAD_NUM0). - * @param data Pointer to receive denoise value - * @return - * - ESP_OK Success - */ -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. - * 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. - * - * @param waterproof parameter of waterproof - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_waterproof_set_config(const touch_pad_waterproof_t *waterproof); - -/** - * @brief get parameter of waterproof function. - * @param waterproof parameter of waterproof - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_waterproof_get_config(touch_pad_waterproof_t *waterproof); - -/** - * @brief Enable parameter of waterproof function. - * Should be called after function ``touch_pad_waterproof_set_config``. - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_waterproof_enable(void); - -/** - * @brief Disable parameter of waterproof function. - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_waterproof_disable(void); - -/** - * @brief Enable/disable proximity function of touch channels. - * The proximity sensor measurement is the accumulation of touch channel measurements. - * - * @note Supports up to three touch channels configured as proximity sensors. - * @param touch_num touch pad index - * @param enabled true: enable the proximity function; false: disable the proximity function - * @return - * - ESP_OK: Configured correctly. - * - ESP_ERR_INVALID_ARG: Touch channel number error. - * - ESP_ERR_NOT_SUPPORTED: Don't support configured. - */ -esp_err_t touch_pad_proximity_enable(touch_pad_t touch_num, bool enabled); - -/** - * @brief Set measure count of proximity channel. - * The proximity sensor measurement is the accumulation of touch channel measurements. - * - * @note All proximity channels use the same `count` value. So please pass the parameter `TOUCH_PAD_MAX`. - * @param touch_num Touch pad index. In this version, pass the parameter `TOUCH_PAD_MAX`. - * @param count The cumulative times of measurements for proximity pad. Range: 0 ~ 255. - * @return - * - ESP_OK: Configured correctly. - * - ESP_ERR_INVALID_ARG: Touch channel number error. - */ -esp_err_t touch_pad_proximity_set_count(touch_pad_t touch_num, uint32_t count); - -/** - * @brief Get measure count of proximity channel. - * The proximity sensor measurement is the accumulation of touch channel measurements. - * - * @note All proximity channels use the same `count` value. So please pass the parameter `TOUCH_PAD_MAX`. - * @param touch_num Touch pad index. In this version, pass the parameter `TOUCH_PAD_MAX`. - * @param count The cumulative times of measurements for proximity pad. Range: 0 ~ 255. - * @return - * - ESP_OK: Configured correctly. - * - ESP_ERR_INVALID_ARG: Touch channel number error. - */ -esp_err_t touch_pad_proximity_get_count(touch_pad_t touch_num, uint32_t *count); - -/** - * @brief Get the accumulated measurement of the proximity sensor. - * The proximity sensor measurement is the accumulation of touch channel measurements. - * @param touch_num touch pad index - * @param measure_out If the accumulation process does not end, the `measure_out` is the process value. - * @return - * - ESP_OK Success - * - ESP_ERR_INVALID_ARG Touch num is not proximity - */ -esp_err_t touch_pad_proximity_get_data(touch_pad_t touch_num, uint32_t *measure_out); - -/** - * @brief Get parameter of touch sensor sleep channel. - * The touch sensor can works in sleep mode to wake up sleep. - * - * @note After the sleep channel is configured, Please use special functions for sleep channel. - * e.g. The user should uses `touch_pad_sleep_channel_read_data` instead of `touch_pad_read_raw_data` to obtain the sleep channel reading. - * - * @param slp_config touch sleep pad config. - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_sleep_channel_get_info(touch_pad_sleep_channel_t *slp_config); - -/** - * @brief Enable/Disable sleep channel function for touch sensor. - * The touch sensor can works in sleep mode to wake up sleep. - * - * @note ESP32S2 only support one sleep channel. - * @note After the sleep channel is configured, Please use special functions for sleep channel. - * e.g. The user should uses `touch_pad_sleep_channel_read_data` instead of `touch_pad_read_raw_data` to obtain the sleep channel reading. - * - * @param pad_num Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode. - * @param enable true: enable sleep pad for touch sensor; false: disable sleep pad for touch sensor; - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_sleep_channel_enable(touch_pad_t pad_num, bool enable); - -/** - * @brief Enable/Disable proximity function for sleep channel. - * The touch sensor can works in sleep mode to wake up sleep. - * - * @note ESP32S2 only support one sleep channel. - * - * @param pad_num Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode. - * @param enable true: enable proximity for sleep channel; false: disable proximity for sleep channel; - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_sleep_channel_enable_proximity(touch_pad_t pad_num, bool enable); - -/** - * @brief Set the trigger threshold of touch sensor in deep sleep. - * The threshold determines the sensitivity of the touch sensor. - * - * @note In general, the touch threshold during sleep can use the threshold parameter parameters before sleep. - * - * @param pad_num Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode. - * @param touch_thres touch sleep pad threshold - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_sleep_set_threshold(touch_pad_t pad_num, uint32_t touch_thres); - -/** - * @brief Get the trigger threshold of touch sensor in deep sleep. - * The threshold determines the sensitivity of the touch sensor. - * - * @note In general, the touch threshold during sleep can use the threshold parameter parameters before sleep. - * - * @param pad_num Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode. - * @param touch_thres touch sleep pad threshold - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_sleep_get_threshold(touch_pad_t pad_num, uint32_t *touch_thres); - -/** - * @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 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_benchmark(touch_pad_t pad_num, uint32_t *benchmark); - -/** - * @brief Read smoothed data of touch sensor sleep channel. - * Smoothed data is filtered from the raw data. - * @param pad_num Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode. - * @param smooth_data pointer to accept touch sensor smoothed data - * @return - * - ESP_OK Success - * - ESP_ERR_INVALID_ARG parameter is NULL - */ -esp_err_t touch_pad_sleep_channel_read_smooth(touch_pad_t pad_num, uint32_t *smooth_data); - -/** - * @brief Read raw data 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 raw_data pointer to accept touch sensor raw data - * @return - * - ESP_OK Success - * - ESP_ERR_INVALID_ARG parameter is NULL - */ -esp_err_t touch_pad_sleep_channel_read_data(touch_pad_t pad_num, uint32_t *raw_data); - -/** - * @brief Reset benchmark of touch sensor sleep channel. - * - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_sleep_channel_reset_benchmark(void); - -/** - * @brief Read proximity count 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 proximity_cnt pointer to accept touch sensor proximity count value - * @return - * - ESP_OK Success - * - ESP_ERR_INVALID_ARG parameter is NULL - */ -esp_err_t touch_pad_sleep_channel_read_proximity_cnt(touch_pad_t pad_num, uint32_t *proximity_cnt); - -/** - * @brief Change the operating frequency of touch pad in deep sleep state. Reducing the operating frequency can effectively reduce power consumption. - * If this function is not called, the working frequency of touch in the deep sleep state is the same as that in the wake-up state. - * - * @param sleep_cycle The touch sensor will sleep after each measurement. - * sleep_cycle decide the interval between each measurement. - * t_sleep = sleep_cycle / (RTC_SLOW_CLK frequency). - * The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function. - * @param meas_times The times of charge and discharge in each measure process of touch channels. - * The timer frequency is 8Mhz. Range: 0 ~ 0xffff. - * Recommended typical value: Modify this value to make the measurement time around 1ms. - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_sleep_channel_set_work_time(uint16_t sleep_cycle, uint16_t meas_times); - -#ifdef __cplusplus -} +#if !CONFIG_TOUCH_SUPPRESS_DEPRECATE_WARN +#warning "This set of Touch APIs has been deprecated, \ +please include 'driver/touch_sens.h' instead. \ +if you want to keep using the old APIs and ignore this warning, \ +you can enable 'Suppress legacy driver deprecated warning' option under 'Touch Configuration' menu in Kconfig" #endif diff --git a/components/driver/touch_sensor/esp32s2/include/driver/touch_sensor_legacy.h b/components/driver/touch_sensor/esp32s2/include/driver/touch_sensor_legacy.h new file mode 100644 index 0000000000..96ce713067 --- /dev/null +++ b/components/driver/touch_sensor/esp32s2/include/driver/touch_sensor_legacy.h @@ -0,0 +1,646 @@ +/* + * SPDX-FileCopyrightText: 2019-2024 Espressif Systems (Shanghai) CO LTD + * + * SPDX-License-Identifier: Apache-2.0 + */ + +#pragma once + +#include "driver/touch_sensor_common.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Set touch sensor FSM start + * @note Start FSM after the touch sensor FSM mode is set. + * @note Call this function will reset benchmark of all touch channels. + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_fsm_start(void); + +/** + * @brief Stop touch sensor FSM. + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_fsm_stop(void); + +/** + * @brief Trigger a touch sensor measurement, only support in SW mode of FSM + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_sw_start(void); + +/** + * @brief Set charge and discharge times of each measurement + * @note This function will specify the charge and discharge times in each measurement period + * The clock is sourced from SOC_MOD_CLK_RTC_FAST, and its default frequency is SOC_CLK_RC_FAST_FREQ_APPROX + * The touch sensor will record the total clock cycles of all the charge and discharge cycles as the final result (raw value) + * @note If the charge and discharge times is too small, it may lead to inaccurate results. + * + * @param charge_discharge_times Charge and discharge times, range: 0 ~ 0xffff. + * No exact typical value can be recommended because the capacity is influenced by the hardware design and how finger touches, + * but suggest adjusting this value to make the measurement time around 1 ms. + * @return + * - ESP_OK Set charge and discharge times success + */ +esp_err_t touch_pad_set_charge_discharge_times(uint16_t charge_discharge_times); + +/** + * @brief Get charge and discharge times of each measurement + * + * @param charge_discharge_times Charge and discharge times + * @return + * - ESP_OK Get charge_discharge_times success + * - ESP_ERR_INVALID_ARG The input parameter is NULL + */ +esp_err_t touch_pad_get_charge_discharge_times(uint16_t *charge_discharge_times); + +/** + * @brief Set the interval between two measurements + * @note The touch sensor will sleep between two measurements + * This function is to set the interval cycle + * And the interval is clocked from SOC_MOD_CLK_RTC_SLOW, its default frequency is SOC_CLK_RC_SLOW_FREQ_APPROX + * + * @param interval_cycle The interval between two measurements + * sleep_time = interval_cycle / SOC_CLK_RC_SLOW_FREQ_APPROX. + * The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function. + * @return + * - ESP_OK Set interval cycle success + */ +esp_err_t touch_pad_set_measurement_interval(uint16_t interval_cycle); + +/** + * @brief Get the interval between two measurements + * + * @param interval_cycle The interval between two measurements + * @return + * - ESP_OK Get interval cycle success + * - ESP_ERR_INVALID_ARG The input parameter is NULL + */ +esp_err_t touch_pad_get_measurement_interval(uint16_t *interval_cycle); + +/** + * @brief Set touch sensor times of charge and discharge and sleep time. + * Excessive total time will slow down the touch response. + * Too small measurement time will not be sampled enough, resulting in inaccurate measurements. + * @note The touch sensor will measure time of a fixed number of charge/discharge cycles (specified as the second parameter). + * That means the time (raw value) will increase as the capacity of the touch pad is increasing. + * The time (raw value) here is the number of clock cycles which is sourced from SOC_MOD_CLK_RTC_FAST and at (SOC_CLK_RC_FAST_FREQ_APPROX) Hz as default + * @note The greater the duty cycle of the measurement time, the more system power is consumed. + * + * @param sleep_cycle The touch sensor will sleep after each measurement. + * sleep_cycle decide the interval between each measurement. + * t_sleep = sleep_cycle / SOC_CLK_RC_SLOW_FREQ_APPROX. + * The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function. + * @param meas_times The times of charge and discharge in each measurement of touch channels. Range: 0 ~ 0xffff. + * Recommended typical value: Modify this value to make the measurement time around 1 ms. + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_times) +__attribute__((deprecated("please use 'touch_pad_set_charge_discharge_times' and 'touch_pad_set_measurement_interval' instead"))); + +/** + * @brief Get touch sensor times of charge and discharge and sleep time + * @param sleep_cycle Pointer to accept sleep cycle number + * @param meas_times Pointer to accept measurement times count. + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_times) +__attribute__((deprecated("please use 'touch_pad_get_charge_discharge_times' and 'touch_pad_get_measurement_interval' instead"))); + +/** + * @brief Set the connection type of touch channels in idle status. + * When a channel is in measurement mode, other initialized channels are in idle mode. + * The touch channel is generally adjacent to the trace, so the connection state of the idle channel + * affects the stability and sensitivity of the test channel. + * The `CONN_HIGHZ`(high resistance) setting increases the sensitivity of touch channels. + * The `CONN_GND`(grounding) setting increases the stability of touch channels. + * @param type Select idle channel connect to high resistance state or ground. + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_set_idle_channel_connect(touch_pad_conn_type_t type); + +/** + * @brief Get the connection type of touch channels in idle status. + * When a channel is in measurement mode, other initialized channels are in idle mode. + * The touch channel is generally adjacent to the trace, so the connection state of the idle channel + * affects the stability and sensitivity of the test channel. + * The `CONN_HIGHZ`(high resistance) setting increases the sensitivity of touch channels. + * The `CONN_GND`(grounding) setting increases the stability of touch channels. + * @param type Pointer to connection type. + * @return + * - ESP_OK on success + */ +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 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. + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_set_thresh(touch_pad_t touch_num, uint32_t threshold); + +/** + * @brief Get touch sensor trigger threshold + * @param touch_num touch pad index + * @param threshold pointer to accept threshold + * @return + * - ESP_OK on success + * - ESP_ERR_INVALID_ARG if argument is wrong + */ +esp_err_t touch_pad_get_thresh(touch_pad_t touch_num, uint32_t *threshold); + +/** + * @brief Register touch channel into touch sensor scan group. + * The working mode of the touch sensor is cyclically scanned. + * This function will set the scan bits according to the given bitmask. + * @note If set this mask, the FSM timer should be stop firsty. + * @note The touch sensor that in scan map, should be deinit GPIO function firstly by `touch_pad_io_init`. + * @param enable_mask bitmask of touch sensor scan group. + * e.g. TOUCH_PAD_NUM14 -> BIT(14) + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_set_channel_mask(uint16_t enable_mask); + +/** + * @brief Get the touch sensor scan group bit mask. + * @param enable_mask Pointer to bitmask of touch sensor scan group. + * e.g. TOUCH_PAD_NUM14 -> BIT(14) + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_get_channel_mask(uint16_t *enable_mask); + +/** + * @brief Clear touch channel from touch sensor scan group. + * The working mode of the touch sensor is cyclically scanned. + * This function will clear the scan bits according to the given bitmask. + * @note If clear all mask, the FSM timer should be stop firsty. + * @param enable_mask bitmask of touch sensor scan group. + * e.g. TOUCH_PAD_NUM14 -> BIT(14) + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_clear_channel_mask(uint16_t enable_mask); + +/** + * @brief Configure parameter for each touch channel. + * @note Touch num 0 is denoise channel, please use `touch_pad_denoise_enable` to set denoise function + * @param touch_num touch pad index + * @return + * - ESP_OK Success + * - ESP_ERR_INVALID_ARG if argument wrong + * - ESP_FAIL if touch pad not initialized + */ +esp_err_t touch_pad_config(touch_pad_t touch_num); + +/** + * @brief Reset the FSM of touch module. + * @note Call this function after `touch_pad_fsm_stop`. + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_reset(void); + +/** + * @brief Get the current measure channel. + * @note Should be called when touch sensor measurement is in cyclic scan mode. + * @return + * - touch channel number + */ +touch_pad_t touch_pad_get_current_meas_channel(void); + +/** + * @brief Get the touch sensor interrupt status mask. + * @return + * - touch interrupt bit + */ +uint32_t touch_pad_read_intr_status_mask(void); + +/** + * @brief Enable touch sensor interrupt by bitmask. + * @note This API can be called in ISR handler. + * @param int_mask Pad mask to enable interrupts + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_intr_enable(touch_pad_intr_mask_t int_mask); + +/** + * @brief Disable touch sensor interrupt by bitmask. + * @note This API can be called in ISR handler. + * @param int_mask Pad mask to disable interrupts + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_intr_disable(touch_pad_intr_mask_t int_mask); + +/** + * @brief Clear touch sensor interrupt by bitmask. + * @param int_mask Pad mask to clear interrupts + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_intr_clear(touch_pad_intr_mask_t int_mask); + +/** + * @brief Register touch-pad ISR. + * The handler will be attached to the same CPU core that this function is running on. + * @param fn Pointer to ISR handler + * @param arg Parameter for ISR + * @param intr_mask Enable touch sensor interrupt handler by bitmask. + * @return + * - ESP_OK Success + * - ESP_ERR_INVALID_ARG Arguments error + * - ESP_ERR_NO_MEM No memory + */ +esp_err_t touch_pad_isr_register(intr_handler_t fn, void *arg, touch_pad_intr_mask_t intr_mask); + +/** + * @brief Enable/disable the timeout check and set timeout threshold for all touch sensor channels measurements. + * If enable: When the touch reading of a touch channel exceeds the measurement threshold, a timeout interrupt will be generated. + * If disable: the FSM does not check if the channel under measurement times out. + * + * @note The threshold compared with touch readings. + * @note In order to avoid abnormal short circuit of some touch channels. This function should be turned on. + * Ensure the normal operation of other touch channels. + * + * @param enable true(default): Enable the timeout check; false: Disable the timeout check. + * @param threshold For all channels, the maximum value that will not be exceeded during normal operation. + * +* @return + * - ESP_OK Success + */ +esp_err_t touch_pad_timeout_set(bool enable, uint32_t threshold); + +/** + * @brief Call this interface after timeout to make the touch channel resume normal work. Point on the next channel to measure. + * If this API is not called, the touch FSM will stop the measurement after timeout interrupt. + * + * @note Call this API after finishes the exception handling by user. + * + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_timeout_resume(void); + +/** + * @brief get raw data of touch sensor. + * @note After the initialization is complete, the "raw_data" is max value. You need to wait for a measurement + * cycle before you can read the correct touch value. + * @param touch_num touch pad index + * @param raw_data pointer to accept touch sensor value + * @return + * - ESP_OK Success + * - ESP_FAIL Touch channel 0 haven't this parameter. + */ + +esp_err_t touch_pad_read_raw_data(touch_pad_t touch_num, uint32_t *raw_data); + +/** + * @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 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_read_benchmark(touch_pad_t touch_num, uint32_t *benchmark); + +/** + * @brief Get smoothed data that obtained by filtering the raw data. + * + * @param touch_num touch pad index + * @param smooth pointer to smoothed data + */ +esp_err_t touch_pad_filter_read_smooth(touch_pad_t touch_num, uint32_t *smooth); + +/** + * @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_reset_benchmark(touch_pad_t touch_num); + +/** + * @brief set parameter of touch sensor filter and detection algorithm. + * For more details on the detection algorithm, please refer to the application documentation. + * @param filter_info select filter type and threshold of detection algorithm + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_filter_set_config(const touch_filter_config_t *filter_info); + +/** + * @brief get parameter of touch sensor filter and detection algorithm. + * For more details on the detection algorithm, please refer to the application documentation. + * @param filter_info select filter type and threshold of detection algorithm + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_filter_get_config(touch_filter_config_t *filter_info); + +/** + * @brief enable touch sensor filter for detection algorithm. + * For more details on the detection algorithm, please refer to the application documentation. + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_filter_enable(void); + +/** + * @brief disable touch sensor filter for detection algorithm. + * For more details on the detection algorithm, please refer to the application documentation. + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_filter_disable(void); + +/** + * @brief set parameter of denoise pad (TOUCH_PAD_NUM0). + * T0 is an internal channel that does not have a corresponding external GPIO. + * T0 will work simultaneously with the measured channel Tn. Finally, the actual + * measured value of Tn is the value after subtracting lower bits of T0. + * The noise reduction function filters out interference introduced simultaneously on all channels, + * such as noise introduced by power supplies and external EMI. + * @param denoise parameter of denoise + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_denoise_set_config(const touch_pad_denoise_t *denoise); + +/** + * @brief get parameter of denoise pad (TOUCH_PAD_NUM0). + * @param denoise Pointer to parameter of denoise + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_denoise_get_config(touch_pad_denoise_t *denoise); + +/** + * @brief enable denoise function. + * T0 is an internal channel that does not have a corresponding external GPIO. + * T0 will work simultaneously with the measured channel Tn. Finally, the actual + * measured value of Tn is the value after subtracting lower bits of T0. + * The noise reduction function filters out interference introduced simultaneously on all channels, + * such as noise introduced by power supplies and external EMI. + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_denoise_enable(void); + +/** + * @brief disable denoise function. + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_denoise_disable(void); + +/** + * @brief Get denoise measure value (TOUCH_PAD_NUM0). + * @param data Pointer to receive denoise value + * @return + * - ESP_OK Success + */ +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. + * 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. + * + * @param waterproof parameter of waterproof + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_waterproof_set_config(const touch_pad_waterproof_t *waterproof); + +/** + * @brief get parameter of waterproof function. + * @param waterproof parameter of waterproof + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_waterproof_get_config(touch_pad_waterproof_t *waterproof); + +/** + * @brief Enable parameter of waterproof function. + * Should be called after function ``touch_pad_waterproof_set_config``. + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_waterproof_enable(void); + +/** + * @brief Disable parameter of waterproof function. + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_waterproof_disable(void); + +/** + * @brief Enable/disable proximity function of touch channels. + * The proximity sensor measurement is the accumulation of touch channel measurements. + * + * @note Supports up to three touch channels configured as proximity sensors. + * @param touch_num touch pad index + * @param enabled true: enable the proximity function; false: disable the proximity function + * @return + * - ESP_OK: Configured correctly. + * - ESP_ERR_INVALID_ARG: Touch channel number error. + * - ESP_ERR_NOT_SUPPORTED: Don't support configured. + */ +esp_err_t touch_pad_proximity_enable(touch_pad_t touch_num, bool enabled); + +/** + * @brief Set measure count of proximity channel. + * The proximity sensor measurement is the accumulation of touch channel measurements. + * + * @note All proximity channels use the same `count` value. So please pass the parameter `TOUCH_PAD_MAX`. + * @param touch_num Touch pad index. In this version, pass the parameter `TOUCH_PAD_MAX`. + * @param count The cumulative times of measurements for proximity pad. Range: 0 ~ 255. + * @return + * - ESP_OK: Configured correctly. + * - ESP_ERR_INVALID_ARG: Touch channel number error. + */ +esp_err_t touch_pad_proximity_set_count(touch_pad_t touch_num, uint32_t count); + +/** + * @brief Get measure count of proximity channel. + * The proximity sensor measurement is the accumulation of touch channel measurements. + * + * @note All proximity channels use the same `count` value. So please pass the parameter `TOUCH_PAD_MAX`. + * @param touch_num Touch pad index. In this version, pass the parameter `TOUCH_PAD_MAX`. + * @param count The cumulative times of measurements for proximity pad. Range: 0 ~ 255. + * @return + * - ESP_OK: Configured correctly. + * - ESP_ERR_INVALID_ARG: Touch channel number error. + */ +esp_err_t touch_pad_proximity_get_count(touch_pad_t touch_num, uint32_t *count); + +/** + * @brief Get the accumulated measurement of the proximity sensor. + * The proximity sensor measurement is the accumulation of touch channel measurements. + * @param touch_num touch pad index + * @param measure_out If the accumulation process does not end, the `measure_out` is the process value. + * @return + * - ESP_OK Success + * - ESP_ERR_INVALID_ARG Touch num is not proximity + */ +esp_err_t touch_pad_proximity_get_data(touch_pad_t touch_num, uint32_t *measure_out); + +/** + * @brief Get parameter of touch sensor sleep channel. + * The touch sensor can works in sleep mode to wake up sleep. + * + * @note After the sleep channel is configured, Please use special functions for sleep channel. + * e.g. The user should uses `touch_pad_sleep_channel_read_data` instead of `touch_pad_read_raw_data` to obtain the sleep channel reading. + * + * @param slp_config touch sleep pad config. + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_sleep_channel_get_info(touch_pad_sleep_channel_t *slp_config); + +/** + * @brief Enable/Disable sleep channel function for touch sensor. + * The touch sensor can works in sleep mode to wake up sleep. + * + * @note ESP32S2 only support one sleep channel. + * @note After the sleep channel is configured, Please use special functions for sleep channel. + * e.g. The user should uses `touch_pad_sleep_channel_read_data` instead of `touch_pad_read_raw_data` to obtain the sleep channel reading. + * + * @param pad_num Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode. + * @param enable true: enable sleep pad for touch sensor; false: disable sleep pad for touch sensor; + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_sleep_channel_enable(touch_pad_t pad_num, bool enable); + +/** + * @brief Enable/Disable proximity function for sleep channel. + * The touch sensor can works in sleep mode to wake up sleep. + * + * @note ESP32S2 only support one sleep channel. + * + * @param pad_num Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode. + * @param enable true: enable proximity for sleep channel; false: disable proximity for sleep channel; + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_sleep_channel_enable_proximity(touch_pad_t pad_num, bool enable); + +/** + * @brief Set the trigger threshold of touch sensor in deep sleep. + * The threshold determines the sensitivity of the touch sensor. + * + * @note In general, the touch threshold during sleep can use the threshold parameter parameters before sleep. + * + * @param pad_num Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode. + * @param touch_thres touch sleep pad threshold + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_sleep_set_threshold(touch_pad_t pad_num, uint32_t touch_thres); + +/** + * @brief Get the trigger threshold of touch sensor in deep sleep. + * The threshold determines the sensitivity of the touch sensor. + * + * @note In general, the touch threshold during sleep can use the threshold parameter parameters before sleep. + * + * @param pad_num Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode. + * @param touch_thres touch sleep pad threshold + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_sleep_get_threshold(touch_pad_t pad_num, uint32_t *touch_thres); + +/** + * @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 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_benchmark(touch_pad_t pad_num, uint32_t *benchmark); + +/** + * @brief Read smoothed data of touch sensor sleep channel. + * Smoothed data is filtered from the raw data. + * @param pad_num Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode. + * @param smooth_data pointer to accept touch sensor smoothed data + * @return + * - ESP_OK Success + * - ESP_ERR_INVALID_ARG parameter is NULL + */ +esp_err_t touch_pad_sleep_channel_read_smooth(touch_pad_t pad_num, uint32_t *smooth_data); + +/** + * @brief Read raw data 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 raw_data pointer to accept touch sensor raw data + * @return + * - ESP_OK Success + * - ESP_ERR_INVALID_ARG parameter is NULL + */ +esp_err_t touch_pad_sleep_channel_read_data(touch_pad_t pad_num, uint32_t *raw_data); + +/** + * @brief Reset benchmark of touch sensor sleep channel. + * + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_sleep_channel_reset_benchmark(void); + +/** + * @brief Read proximity count 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 proximity_cnt pointer to accept touch sensor proximity count value + * @return + * - ESP_OK Success + * - ESP_ERR_INVALID_ARG parameter is NULL + */ +esp_err_t touch_pad_sleep_channel_read_proximity_cnt(touch_pad_t pad_num, uint32_t *proximity_cnt); + +/** + * @brief Change the operating frequency of touch pad in deep sleep state. Reducing the operating frequency can effectively reduce power consumption. + * If this function is not called, the working frequency of touch in the deep sleep state is the same as that in the wake-up state. + * + * @param sleep_cycle The touch sensor will sleep after each measurement. + * sleep_cycle decide the interval between each measurement. + * t_sleep = sleep_cycle / (RTC_SLOW_CLK frequency). + * The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function. + * @param meas_times The times of charge and discharge in each measure process of touch channels. + * The timer frequency is 8Mhz. Range: 0 ~ 0xffff. + * Recommended typical value: Modify this value to make the measurement time around 1ms. + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_sleep_channel_set_work_time(uint16_t sleep_cycle, uint16_t meas_times); + +#ifdef __cplusplus +} +#endif diff --git a/components/driver/touch_sensor/esp32s2/touch_sensor.c b/components/driver/touch_sensor/esp32s2/touch_sensor.c index 42ed7c6291..72c232742d 100644 --- a/components/driver/touch_sensor/esp32s2/touch_sensor.c +++ b/components/driver/touch_sensor/esp32s2/touch_sensor.c @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2016-2022 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2016-2024 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ @@ -16,7 +16,7 @@ #include "freertos/timers.h" #include "esp_intr_alloc.h" #include "driver/rtc_io.h" -#include "driver/touch_pad.h" +#include "driver/touch_sensor_common.h" #include "esp_private/rtc_ctrl.h" #include "driver/gpio.h" #include "sdkconfig.h" @@ -405,7 +405,7 @@ esp_err_t touch_pad_filter_get_config(touch_filter_config_t *filter_info) esp_err_t touch_pad_filter_enable(void) { TOUCH_ENTER_CRITICAL(); - touch_hal_filter_enable(); + touch_hal_filter_enable(true); TOUCH_EXIT_CRITICAL(); return ESP_OK; } @@ -413,7 +413,7 @@ esp_err_t touch_pad_filter_enable(void) esp_err_t touch_pad_filter_disable(void) { TOUCH_ENTER_CRITICAL(); - touch_hal_filter_disable(); + touch_hal_filter_enable(false); TOUCH_EXIT_CRITICAL(); return ESP_OK; } @@ -596,9 +596,9 @@ esp_err_t touch_pad_sleep_channel_enable_proximity(touch_pad_t pad_num, bool ena TOUCH_ENTER_CRITICAL(); if (enable) { - touch_hal_sleep_enable_approach(); + touch_hal_sleep_enable_approach(true); } else { - touch_hal_sleep_disable_approach(); + touch_hal_sleep_enable_approach(false); } TOUCH_EXIT_CRITICAL(); return ESP_OK; @@ -684,3 +684,17 @@ esp_err_t touch_pad_sleep_channel_set_work_time(uint16_t sleep_cycle, uint16_t m touch_hal_sleep_channel_set_work_time(sleep_cycle, meas_times); return ESP_OK; } + +/** + * @brief This function will be called during start up, to check that the new touch driver is not running along with the legacy touch driver + */ +static __attribute__((constructor)) void check_touch_driver_conflict(void) +{ + extern __attribute__((weak)) esp_err_t touch_del_channel(void *handle); + /* If the new I2S driver is linked, the weak function will point to the actual function in the new driver, otherwise it is NULL*/ + if ((void *)touch_del_channel != NULL) { + ESP_EARLY_LOGE("legacy_touch_driver", "CONFLICT! The new touch driver can't work along with the legacy touch driver"); + abort(); + } + ESP_EARLY_LOGW("legacy_touch_driver", "legacy touch driver is deprecated, please migrate to use driver/touch_sens.h"); +} diff --git a/components/driver/touch_sensor/esp32s3/include/driver/touch_sensor.h b/components/driver/touch_sensor/esp32s3/include/driver/touch_sensor.h index 06f835879f..adb40726ae 100644 --- a/components/driver/touch_sensor/esp32s3/include/driver/touch_sensor.h +++ b/components/driver/touch_sensor/esp32s3/include/driver/touch_sensor.h @@ -1,646 +1,17 @@ /* - * SPDX-FileCopyrightText: 2019-2021 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2019-2024 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ #pragma once -#include "driver/touch_sensor_common.h" +#include "sdkconfig.h" +#include "driver/touch_sensor_legacy.h" -#ifdef __cplusplus -extern "C" { -#endif - -/** - * @brief Set touch sensor FSM start - * @note Start FSM after the touch sensor FSM mode is set. - * @note Call this function will reset benchmark of all touch channels. - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_fsm_start(void); - -/** - * @brief Stop touch sensor FSM. - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_fsm_stop(void); - -/** - * @brief Trigger a touch sensor measurement, only support in SW mode of FSM - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_sw_start(void); - -/** - * @brief Set charge and discharge times of each measurement - * @note This function will specify the charge and discharge times in each measurement period - * The clock is sourced from SOC_MOD_CLK_RTC_FAST, and its default frequency is SOC_CLK_RC_FAST_FREQ_APPROX - * The touch sensor will record the total clock cycles of all the charge and discharge cycles as the final result (raw value) - * @note If the charge and discharge times is too small, it may lead to inaccurate results. - * - * @param charge_discharge_times Charge and discharge times, range: 0 ~ 0xffff. - * No exact typical value can be recommended because the capacity is influenced by the hardware design and how finger touches, - * but suggest adjusting this value to make the measurement time around 1 ms. - * @return - * - ESP_OK Set charge and discharge times success - */ -esp_err_t touch_pad_set_charge_discharge_times(uint16_t charge_discharge_times); - -/** - * @brief Get charge and discharge times of each measurement - * - * @param charge_discharge_times Charge and discharge times - * @return - * - ESP_OK Get charge_discharge_times success - * - ESP_ERR_INVALID_ARG The input parameter is NULL - */ -esp_err_t touch_pad_get_charge_discharge_times(uint16_t *charge_discharge_times); - -/** - * @brief Set the interval between two measurements - * @note The touch sensor will sleep between two measurements - * This function is to set the interval cycle - * And the interval is clocked from SOC_MOD_CLK_RTC_SLOW, its default frequency is SOC_CLK_RC_SLOW_FREQ_APPROX - * - * @param interval_cycle The interval between two measurements - * sleep_time = interval_cycle / SOC_CLK_RC_SLOW_FREQ_APPROX. - * The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function. - * @return - * - ESP_OK Set interval cycle success - */ -esp_err_t touch_pad_set_measurement_interval(uint16_t interval_cycle); - -/** - * @brief Get the interval between two measurements - * - * @param interval_cycle The interval between two measurements - * @return - * - ESP_OK Get interval cycle success - * - ESP_ERR_INVALID_ARG The input parameter is NULL - */ -esp_err_t touch_pad_get_measurement_interval(uint16_t *interval_cycle); - -/** - * @brief Set touch sensor times of charge and discharge and sleep time. - * Excessive total time will slow down the touch response. - * Too small measurement time will not be sampled enough, resulting in inaccurate measurements. - * @note The touch sensor will measure time of a fixed number of charge/discharge cycles (specified as the second parameter). - * That means the time (raw value) will increase as the capacity of the touch pad is increasing. - * The time (raw value) here is the number of clock cycles which is sourced from SOC_MOD_CLK_RTC_FAST and at (SOC_CLK_RC_FAST_FREQ_APPROX) Hz as default - * @note The greater the duty cycle of the measurement time, the more system power is consumed. - * - * @param sleep_cycle The touch sensor will sleep after each measurement. - * sleep_cycle decide the interval between each measurement. - * t_sleep = sleep_cycle / SOC_CLK_RC_SLOW_FREQ_APPROX. - * The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function. - * @param meas_times The times of charge and discharge in each measurement of touch channels. Range: 0 ~ 0xffff. - * Recommended typical value: Modify this value to make the measurement time around 1 ms. - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_times) -__attribute__((deprecated("please use 'touch_pad_set_charge_discharge_times' and 'touch_pad_set_measurement_interval' instead"))); - -/** - * @brief Get touch sensor times of charge and discharge and sleep time - * @param sleep_cycle Pointer to accept sleep cycle number - * @param meas_times Pointer to accept measurement times count. - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_times) -__attribute__((deprecated("please use 'touch_pad_get_charge_discharge_times' and 'touch_pad_get_measurement_interval' instead"))); - -/** - * @brief Set the connection type of touch channels in idle status. - * When a channel is in measurement mode, other initialized channels are in idle mode. - * The touch channel is generally adjacent to the trace, so the connection state of the idle channel - * affects the stability and sensitivity of the test channel. - * The `CONN_HIGHZ`(high resistance) setting increases the sensitivity of touch channels. - * The `CONN_GND`(grounding) setting increases the stability of touch channels. - * @param type Select idle channel connect to high resistance state or ground. - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_set_idle_channel_connect(touch_pad_conn_type_t type); - -/** - * @brief Get the connection type of touch channels in idle status. - * When a channel is in measurement mode, other initialized channels are in idle mode. - * The touch channel is generally adjacent to the trace, so the connection state of the idle channel - * affects the stability and sensitivity of the test channel. - * The `CONN_HIGHZ`(high resistance) setting increases the sensitivity of touch channels. - * The `CONN_GND`(grounding) setting increases the stability of touch channels. - * @param type Pointer to connection type. - * @return - * - ESP_OK on success - */ -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 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. - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_set_thresh(touch_pad_t touch_num, uint32_t threshold); - -/** - * @brief Get touch sensor trigger threshold - * @param touch_num touch pad index - * @param threshold pointer to accept threshold - * @return - * - ESP_OK on success - * - ESP_ERR_INVALID_ARG if argument is wrong - */ -esp_err_t touch_pad_get_thresh(touch_pad_t touch_num, uint32_t *threshold); - -/** - * @brief Register touch channel into touch sensor scan group. - * The working mode of the touch sensor is cyclically scanned. - * This function will set the scan bits according to the given bitmask. - * @note If set this mask, the FSM timer should be stop firsty. - * @note The touch sensor that in scan map, should be deinit GPIO function firstly by `touch_pad_io_init`. - * @param enable_mask bitmask of touch sensor scan group. - * e.g. TOUCH_PAD_NUM14 -> BIT(14) - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_set_channel_mask(uint16_t enable_mask); - -/** - * @brief Get the touch sensor scan group bit mask. - * @param enable_mask Pointer to bitmask of touch sensor scan group. - * e.g. TOUCH_PAD_NUM14 -> BIT(14) - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_get_channel_mask(uint16_t *enable_mask); - -/** - * @brief Clear touch channel from touch sensor scan group. - * The working mode of the touch sensor is cyclically scanned. - * This function will clear the scan bits according to the given bitmask. - * @note If clear all mask, the FSM timer should be stop firsty. - * @param enable_mask bitmask of touch sensor scan group. - * e.g. TOUCH_PAD_NUM14 -> BIT(14) - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_clear_channel_mask(uint16_t enable_mask); - -/** - * @brief Configure parameter for each touch channel. - * @note Touch num 0 is denoise channel, please use `touch_pad_denoise_enable` to set denoise function - * @param touch_num touch pad index - * @return - * - ESP_OK Success - * - ESP_ERR_INVALID_ARG if argument wrong - * - ESP_FAIL if touch pad not initialized - */ -esp_err_t touch_pad_config(touch_pad_t touch_num); - -/** - * @brief Reset the FSM of touch module. - * @note Call this function after `touch_pad_fsm_stop`. - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_reset(void); - -/** - * @brief Get the current measure channel. - * @note Should be called when touch sensor measurement is in cyclic scan mode. - * @return - * - touch channel number - */ -touch_pad_t touch_pad_get_current_meas_channel(void); - -/** - * @brief Get the touch sensor interrupt status mask. - * @return - * - touch interrupt bit - */ -uint32_t touch_pad_read_intr_status_mask(void); - -/** - * @brief Enable touch sensor interrupt by bitmask. - * @note This API can be called in ISR handler. - * @param int_mask Pad mask to enable interrupts - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_intr_enable(touch_pad_intr_mask_t int_mask); - -/** - * @brief Disable touch sensor interrupt by bitmask. - * @note This API can be called in ISR handler. - * @param int_mask Pad mask to disable interrupts - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_intr_disable(touch_pad_intr_mask_t int_mask); - -/** - * @brief Clear touch sensor interrupt by bitmask. - * @param int_mask Pad mask to clear interrupts - * @return - * - ESP_OK on success - */ -esp_err_t touch_pad_intr_clear(touch_pad_intr_mask_t int_mask); - -/** - * @brief Register touch-pad ISR. - * The handler will be attached to the same CPU core that this function is running on. - * @param fn Pointer to ISR handler - * @param arg Parameter for ISR - * @param intr_mask Enable touch sensor interrupt handler by bitmask. - * @return - * - ESP_OK Success - * - ESP_ERR_INVALID_ARG Arguments error - * - ESP_ERR_NO_MEM No memory - */ -esp_err_t touch_pad_isr_register(intr_handler_t fn, void *arg, touch_pad_intr_mask_t intr_mask); - -/** - * @brief Enable/disable the timeout check and set timeout threshold for all touch sensor channels measurements. - * If enable: When the touch reading of a touch channel exceeds the measurement threshold, a timeout interrupt will be generated. - * If disable: the FSM does not check if the channel under measurement times out. - * - * @note The threshold compared with touch readings. - * @note In order to avoid abnormal short circuit of some touch channels. This function should be turned on. - * Ensure the normal operation of other touch channels. - * - * @param enable true(default): Enable the timeout check; false: Disable the timeout check. - * @param threshold For all channels, the maximum value that will not be exceeded during normal operation. - * -* @return - * - ESP_OK Success - */ -esp_err_t touch_pad_timeout_set(bool enable, uint32_t threshold); - -/** - * @brief Call this interface after timeout to make the touch channel resume normal work. Point on the next channel to measure. - * If this API is not called, the touch FSM will stop the measurement after timeout interrupt. - * - * @note Call this API after finishes the exception handling by user. - * - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_timeout_resume(void); - -/** - * @brief get raw data of touch sensor. - * @note After the initialization is complete, the "raw_data" is max value. You need to wait for a measurement - * cycle before you can read the correct touch value. - * @param touch_num touch pad index - * @param raw_data pointer to accept touch sensor value - * @return - * - ESP_OK Success - * - ESP_FAIL Touch channel 0 haven't this parameter. - */ - -esp_err_t touch_pad_read_raw_data(touch_pad_t touch_num, uint32_t *raw_data); - -/** - * @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 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_read_benchmark(touch_pad_t touch_num, uint32_t *benchmark); - -/** - * @brief Get smoothed data that obtained by filtering the raw data. - * - * @param touch_num touch pad index - * @param smooth pointer to smoothed data - */ -esp_err_t touch_pad_filter_read_smooth(touch_pad_t touch_num, uint32_t *smooth); - -/** - * @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_reset_benchmark(touch_pad_t touch_num); - -/** - * @brief set parameter of touch sensor filter and detection algorithm. - * For more details on the detection algorithm, please refer to the application documentation. - * @param filter_info select filter type and threshold of detection algorithm - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_filter_set_config(const touch_filter_config_t *filter_info); - -/** - * @brief get parameter of touch sensor filter and detection algorithm. - * For more details on the detection algorithm, please refer to the application documentation. - * @param filter_info select filter type and threshold of detection algorithm - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_filter_get_config(touch_filter_config_t *filter_info); - -/** - * @brief enable touch sensor filter for detection algorithm. - * For more details on the detection algorithm, please refer to the application documentation. - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_filter_enable(void); - -/** - * @brief disable touch sensor filter for detection algorithm. - * For more details on the detection algorithm, please refer to the application documentation. - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_filter_disable(void); - -/** - * @brief set parameter of denoise pad (TOUCH_PAD_NUM0). - * T0 is an internal channel that does not have a corresponding external GPIO. - * T0 will work simultaneously with the measured channel Tn. Finally, the actual - * measured value of Tn is the value after subtracting lower bits of T0. - * The noise reduction function filters out interference introduced simultaneously on all channels, - * such as noise introduced by power supplies and external EMI. - * @param denoise parameter of denoise - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_denoise_set_config(const touch_pad_denoise_t *denoise); - -/** - * @brief get parameter of denoise pad (TOUCH_PAD_NUM0). - * @param denoise Pointer to parameter of denoise - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_denoise_get_config(touch_pad_denoise_t *denoise); - -/** - * @brief enable denoise function. - * T0 is an internal channel that does not have a corresponding external GPIO. - * T0 will work simultaneously with the measured channel Tn. Finally, the actual - * measured value of Tn is the value after subtracting lower bits of T0. - * The noise reduction function filters out interference introduced simultaneously on all channels, - * such as noise introduced by power supplies and external EMI. - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_denoise_enable(void); - -/** - * @brief disable denoise function. - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_denoise_disable(void); - -/** - * @brief Get denoise measure value (TOUCH_PAD_NUM0). - * @param data Pointer to receive denoise value - * @return - * - ESP_OK Success - */ -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. - * 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. - * - * @param waterproof parameter of waterproof - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_waterproof_set_config(const touch_pad_waterproof_t *waterproof); - -/** - * @brief get parameter of waterproof function. - * @param waterproof parameter of waterproof - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_waterproof_get_config(touch_pad_waterproof_t *waterproof); - -/** - * @brief Enable parameter of waterproof function. - * Should be called after function ``touch_pad_waterproof_set_config``. - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_waterproof_enable(void); - -/** - * @brief Disable parameter of waterproof function. - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_waterproof_disable(void); - -/** - * @brief Enable/disable proximity function of touch channels. - * The proximity sensor measurement is the accumulation of touch channel measurements. - * - * @note Supports up to three touch channels configured as proximity sensors. - * @param touch_num touch pad index - * @param enabled true: enable the proximity function; false: disable the proximity function - * @return - * - ESP_OK: Configured correctly. - * - ESP_ERR_INVALID_ARG: Touch channel number error. - * - ESP_ERR_NOT_SUPPORTED: Don't support configured. - */ -esp_err_t touch_pad_proximity_enable(touch_pad_t touch_num, bool enabled); - -/** - * @brief Set measure count of proximity channel. - * The proximity sensor measurement is the accumulation of touch channel measurements. - * - * @note All proximity channels use the same `count` value. So please pass the parameter `TOUCH_PAD_MAX`. - * @param touch_num Touch pad index. In this version, pass the parameter `TOUCH_PAD_MAX`. - * @param count The cumulative times of measurements for proximity pad. Range: 0 ~ 255. - * @return - * - ESP_OK: Configured correctly. - * - ESP_ERR_INVALID_ARG: Touch channel number error. - */ -esp_err_t touch_pad_proximity_set_count(touch_pad_t touch_num, uint32_t count); - -/** - * @brief Get measure count of proximity channel. - * The proximity sensor measurement is the accumulation of touch channel measurements. - * - * @note All proximity channels use the same `count` value. So please pass the parameter `TOUCH_PAD_MAX`. - * @param touch_num Touch pad index. In this version, pass the parameter `TOUCH_PAD_MAX`. - * @param count The cumulative times of measurements for proximity pad. Range: 0 ~ 255. - * @return - * - ESP_OK: Configured correctly. - * - ESP_ERR_INVALID_ARG: Touch channel number error. - */ -esp_err_t touch_pad_proximity_get_count(touch_pad_t touch_num, uint32_t *count); - -/** - * @brief Get the accumulated measurement of the proximity sensor. - * The proximity sensor measurement is the accumulation of touch channel measurements. - * @param touch_num touch pad index - * @param measure_out If the accumulation process does not end, the `measure_out` is the process value. - * @return - * - ESP_OK Success - * - ESP_ERR_INVALID_ARG Touch num is not proximity - */ -esp_err_t touch_pad_proximity_get_data(touch_pad_t touch_num, uint32_t *measure_out); - -/** - * @brief Get parameter of touch sensor sleep channel. - * The touch sensor can works in sleep mode to wake up sleep. - * - * @note After the sleep channel is configured, Please use special functions for sleep channel. - * e.g. The user should uses `touch_pad_sleep_channel_read_data` instead of `touch_pad_read_raw_data` to obtain the sleep channel reading. - * - * @param slp_config touch sleep pad config. - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_sleep_channel_get_info(touch_pad_sleep_channel_t *slp_config); - -/** - * @brief Enable/Disable sleep channel function for touch sensor. - * The touch sensor can works in sleep mode to wake up sleep. - * - * @note ESP32S2 only support one sleep channel. - * @note After the sleep channel is configured, Please use special functions for sleep channel. - * e.g. The user should uses `touch_pad_sleep_channel_read_data` instead of `touch_pad_read_raw_data` to obtain the sleep channel reading. - * - * @param pad_num Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode. - * @param enable true: enable sleep pad for touch sensor; false: disable sleep pad for touch sensor; - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_sleep_channel_enable(touch_pad_t pad_num, bool enable); - -/** - * @brief Enable/Disable proximity function for sleep channel. - * The touch sensor can works in sleep mode to wake up sleep. - * - * @note ESP32S2 only support one sleep channel. - * - * @param pad_num Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode. - * @param enable true: enable proximity for sleep channel; false: disable proximity for sleep channel; - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_sleep_channel_enable_proximity(touch_pad_t pad_num, bool enable); - -/** - * @brief Set the trigger threshold of touch sensor in deep sleep. - * The threshold determines the sensitivity of the touch sensor. - * - * @note In general, the touch threshold during sleep can use the threshold parameter parameters before sleep. - * - * @param pad_num Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode. - * @param touch_thres touch sleep pad threshold - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_sleep_set_threshold(touch_pad_t pad_num, uint32_t touch_thres); - -/** - * @brief Get the trigger threshold of touch sensor in deep sleep. - * The threshold determines the sensitivity of the touch sensor. - * - * @note In general, the touch threshold during sleep can use the threshold parameter parameters before sleep. - * - * @param pad_num Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode. - * @param touch_thres touch sleep pad threshold - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_sleep_get_threshold(touch_pad_t pad_num, uint32_t *touch_thres); - -/** - * @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 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_benchmark(touch_pad_t pad_num, uint32_t *benchmark); - -/** - * @brief Read smoothed data of touch sensor sleep channel. - * Smoothed data is filtered from the raw data. - * @param pad_num Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode. - * @param smooth_data pointer to accept touch sensor smoothed data - * @return - * - ESP_OK Success - * - ESP_ERR_INVALID_ARG parameter is NULL - */ -esp_err_t touch_pad_sleep_channel_read_smooth(touch_pad_t pad_num, uint32_t *smooth_data); - -/** - * @brief Read raw data 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 raw_data pointer to accept touch sensor raw data - * @return - * - ESP_OK Success - * - ESP_ERR_INVALID_ARG parameter is NULL - */ -esp_err_t touch_pad_sleep_channel_read_data(touch_pad_t pad_num, uint32_t *raw_data); - -/** - * @brief Reset benchmark of touch sensor sleep channel. - * - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_sleep_channel_reset_benchmark(void); - -/** - * @brief Read proximity count 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 proximity_cnt pointer to accept touch sensor proximity count value - * @return - * - ESP_OK Success - * - ESP_ERR_INVALID_ARG parameter is NULL - */ -esp_err_t touch_pad_sleep_channel_read_proximity_cnt(touch_pad_t pad_num, uint32_t *proximity_cnt); - -/** - * @brief Change the operating frequency of touch pad in deep sleep state. Reducing the operating frequency can effectively reduce power consumption. - * If this function is not called, the working frequency of touch in the deep sleep state is the same as that in the wake-up state. - * - * @param sleep_cycle The touch sensor will sleep after each measurement. - * sleep_cycle decide the interval between each measurement. - * t_sleep = sleep_cycle / (RTC_SLOW_CLK frequency). - * The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function. - * @param meas_times The times of charge and discharge in each measure process of touch channels. - * The timer frequency is 8Mhz. Range: 0 ~ 0xffff. - * Recommended typical value: Modify this value to make the measurement time around 1ms. - * @return - * - ESP_OK Success - */ -esp_err_t touch_pad_sleep_channel_set_work_time(uint16_t sleep_cycle, uint16_t meas_times); - -#ifdef __cplusplus -} +#if !CONFIG_TOUCH_SUPPRESS_DEPRECATE_WARN +#warning "This set of Touch APIs has been deprecated, \ +please include 'driver/touch_sens.h' instead. \ +if you want to keep using the old APIs and ignore this warning, \ +you can enable 'Suppress legacy driver deprecated warning' option under 'Touch Configuration' menu in Kconfig" #endif diff --git a/components/driver/touch_sensor/esp32s3/include/driver/touch_sensor_legacy.h b/components/driver/touch_sensor/esp32s3/include/driver/touch_sensor_legacy.h new file mode 100644 index 0000000000..96ce713067 --- /dev/null +++ b/components/driver/touch_sensor/esp32s3/include/driver/touch_sensor_legacy.h @@ -0,0 +1,646 @@ +/* + * SPDX-FileCopyrightText: 2019-2024 Espressif Systems (Shanghai) CO LTD + * + * SPDX-License-Identifier: Apache-2.0 + */ + +#pragma once + +#include "driver/touch_sensor_common.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Set touch sensor FSM start + * @note Start FSM after the touch sensor FSM mode is set. + * @note Call this function will reset benchmark of all touch channels. + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_fsm_start(void); + +/** + * @brief Stop touch sensor FSM. + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_fsm_stop(void); + +/** + * @brief Trigger a touch sensor measurement, only support in SW mode of FSM + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_sw_start(void); + +/** + * @brief Set charge and discharge times of each measurement + * @note This function will specify the charge and discharge times in each measurement period + * The clock is sourced from SOC_MOD_CLK_RTC_FAST, and its default frequency is SOC_CLK_RC_FAST_FREQ_APPROX + * The touch sensor will record the total clock cycles of all the charge and discharge cycles as the final result (raw value) + * @note If the charge and discharge times is too small, it may lead to inaccurate results. + * + * @param charge_discharge_times Charge and discharge times, range: 0 ~ 0xffff. + * No exact typical value can be recommended because the capacity is influenced by the hardware design and how finger touches, + * but suggest adjusting this value to make the measurement time around 1 ms. + * @return + * - ESP_OK Set charge and discharge times success + */ +esp_err_t touch_pad_set_charge_discharge_times(uint16_t charge_discharge_times); + +/** + * @brief Get charge and discharge times of each measurement + * + * @param charge_discharge_times Charge and discharge times + * @return + * - ESP_OK Get charge_discharge_times success + * - ESP_ERR_INVALID_ARG The input parameter is NULL + */ +esp_err_t touch_pad_get_charge_discharge_times(uint16_t *charge_discharge_times); + +/** + * @brief Set the interval between two measurements + * @note The touch sensor will sleep between two measurements + * This function is to set the interval cycle + * And the interval is clocked from SOC_MOD_CLK_RTC_SLOW, its default frequency is SOC_CLK_RC_SLOW_FREQ_APPROX + * + * @param interval_cycle The interval between two measurements + * sleep_time = interval_cycle / SOC_CLK_RC_SLOW_FREQ_APPROX. + * The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function. + * @return + * - ESP_OK Set interval cycle success + */ +esp_err_t touch_pad_set_measurement_interval(uint16_t interval_cycle); + +/** + * @brief Get the interval between two measurements + * + * @param interval_cycle The interval between two measurements + * @return + * - ESP_OK Get interval cycle success + * - ESP_ERR_INVALID_ARG The input parameter is NULL + */ +esp_err_t touch_pad_get_measurement_interval(uint16_t *interval_cycle); + +/** + * @brief Set touch sensor times of charge and discharge and sleep time. + * Excessive total time will slow down the touch response. + * Too small measurement time will not be sampled enough, resulting in inaccurate measurements. + * @note The touch sensor will measure time of a fixed number of charge/discharge cycles (specified as the second parameter). + * That means the time (raw value) will increase as the capacity of the touch pad is increasing. + * The time (raw value) here is the number of clock cycles which is sourced from SOC_MOD_CLK_RTC_FAST and at (SOC_CLK_RC_FAST_FREQ_APPROX) Hz as default + * @note The greater the duty cycle of the measurement time, the more system power is consumed. + * + * @param sleep_cycle The touch sensor will sleep after each measurement. + * sleep_cycle decide the interval between each measurement. + * t_sleep = sleep_cycle / SOC_CLK_RC_SLOW_FREQ_APPROX. + * The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function. + * @param meas_times The times of charge and discharge in each measurement of touch channels. Range: 0 ~ 0xffff. + * Recommended typical value: Modify this value to make the measurement time around 1 ms. + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_times) +__attribute__((deprecated("please use 'touch_pad_set_charge_discharge_times' and 'touch_pad_set_measurement_interval' instead"))); + +/** + * @brief Get touch sensor times of charge and discharge and sleep time + * @param sleep_cycle Pointer to accept sleep cycle number + * @param meas_times Pointer to accept measurement times count. + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_times) +__attribute__((deprecated("please use 'touch_pad_get_charge_discharge_times' and 'touch_pad_get_measurement_interval' instead"))); + +/** + * @brief Set the connection type of touch channels in idle status. + * When a channel is in measurement mode, other initialized channels are in idle mode. + * The touch channel is generally adjacent to the trace, so the connection state of the idle channel + * affects the stability and sensitivity of the test channel. + * The `CONN_HIGHZ`(high resistance) setting increases the sensitivity of touch channels. + * The `CONN_GND`(grounding) setting increases the stability of touch channels. + * @param type Select idle channel connect to high resistance state or ground. + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_set_idle_channel_connect(touch_pad_conn_type_t type); + +/** + * @brief Get the connection type of touch channels in idle status. + * When a channel is in measurement mode, other initialized channels are in idle mode. + * The touch channel is generally adjacent to the trace, so the connection state of the idle channel + * affects the stability and sensitivity of the test channel. + * The `CONN_HIGHZ`(high resistance) setting increases the sensitivity of touch channels. + * The `CONN_GND`(grounding) setting increases the stability of touch channels. + * @param type Pointer to connection type. + * @return + * - ESP_OK on success + */ +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 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. + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_set_thresh(touch_pad_t touch_num, uint32_t threshold); + +/** + * @brief Get touch sensor trigger threshold + * @param touch_num touch pad index + * @param threshold pointer to accept threshold + * @return + * - ESP_OK on success + * - ESP_ERR_INVALID_ARG if argument is wrong + */ +esp_err_t touch_pad_get_thresh(touch_pad_t touch_num, uint32_t *threshold); + +/** + * @brief Register touch channel into touch sensor scan group. + * The working mode of the touch sensor is cyclically scanned. + * This function will set the scan bits according to the given bitmask. + * @note If set this mask, the FSM timer should be stop firsty. + * @note The touch sensor that in scan map, should be deinit GPIO function firstly by `touch_pad_io_init`. + * @param enable_mask bitmask of touch sensor scan group. + * e.g. TOUCH_PAD_NUM14 -> BIT(14) + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_set_channel_mask(uint16_t enable_mask); + +/** + * @brief Get the touch sensor scan group bit mask. + * @param enable_mask Pointer to bitmask of touch sensor scan group. + * e.g. TOUCH_PAD_NUM14 -> BIT(14) + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_get_channel_mask(uint16_t *enable_mask); + +/** + * @brief Clear touch channel from touch sensor scan group. + * The working mode of the touch sensor is cyclically scanned. + * This function will clear the scan bits according to the given bitmask. + * @note If clear all mask, the FSM timer should be stop firsty. + * @param enable_mask bitmask of touch sensor scan group. + * e.g. TOUCH_PAD_NUM14 -> BIT(14) + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_clear_channel_mask(uint16_t enable_mask); + +/** + * @brief Configure parameter for each touch channel. + * @note Touch num 0 is denoise channel, please use `touch_pad_denoise_enable` to set denoise function + * @param touch_num touch pad index + * @return + * - ESP_OK Success + * - ESP_ERR_INVALID_ARG if argument wrong + * - ESP_FAIL if touch pad not initialized + */ +esp_err_t touch_pad_config(touch_pad_t touch_num); + +/** + * @brief Reset the FSM of touch module. + * @note Call this function after `touch_pad_fsm_stop`. + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_reset(void); + +/** + * @brief Get the current measure channel. + * @note Should be called when touch sensor measurement is in cyclic scan mode. + * @return + * - touch channel number + */ +touch_pad_t touch_pad_get_current_meas_channel(void); + +/** + * @brief Get the touch sensor interrupt status mask. + * @return + * - touch interrupt bit + */ +uint32_t touch_pad_read_intr_status_mask(void); + +/** + * @brief Enable touch sensor interrupt by bitmask. + * @note This API can be called in ISR handler. + * @param int_mask Pad mask to enable interrupts + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_intr_enable(touch_pad_intr_mask_t int_mask); + +/** + * @brief Disable touch sensor interrupt by bitmask. + * @note This API can be called in ISR handler. + * @param int_mask Pad mask to disable interrupts + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_intr_disable(touch_pad_intr_mask_t int_mask); + +/** + * @brief Clear touch sensor interrupt by bitmask. + * @param int_mask Pad mask to clear interrupts + * @return + * - ESP_OK on success + */ +esp_err_t touch_pad_intr_clear(touch_pad_intr_mask_t int_mask); + +/** + * @brief Register touch-pad ISR. + * The handler will be attached to the same CPU core that this function is running on. + * @param fn Pointer to ISR handler + * @param arg Parameter for ISR + * @param intr_mask Enable touch sensor interrupt handler by bitmask. + * @return + * - ESP_OK Success + * - ESP_ERR_INVALID_ARG Arguments error + * - ESP_ERR_NO_MEM No memory + */ +esp_err_t touch_pad_isr_register(intr_handler_t fn, void *arg, touch_pad_intr_mask_t intr_mask); + +/** + * @brief Enable/disable the timeout check and set timeout threshold for all touch sensor channels measurements. + * If enable: When the touch reading of a touch channel exceeds the measurement threshold, a timeout interrupt will be generated. + * If disable: the FSM does not check if the channel under measurement times out. + * + * @note The threshold compared with touch readings. + * @note In order to avoid abnormal short circuit of some touch channels. This function should be turned on. + * Ensure the normal operation of other touch channels. + * + * @param enable true(default): Enable the timeout check; false: Disable the timeout check. + * @param threshold For all channels, the maximum value that will not be exceeded during normal operation. + * +* @return + * - ESP_OK Success + */ +esp_err_t touch_pad_timeout_set(bool enable, uint32_t threshold); + +/** + * @brief Call this interface after timeout to make the touch channel resume normal work. Point on the next channel to measure. + * If this API is not called, the touch FSM will stop the measurement after timeout interrupt. + * + * @note Call this API after finishes the exception handling by user. + * + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_timeout_resume(void); + +/** + * @brief get raw data of touch sensor. + * @note After the initialization is complete, the "raw_data" is max value. You need to wait for a measurement + * cycle before you can read the correct touch value. + * @param touch_num touch pad index + * @param raw_data pointer to accept touch sensor value + * @return + * - ESP_OK Success + * - ESP_FAIL Touch channel 0 haven't this parameter. + */ + +esp_err_t touch_pad_read_raw_data(touch_pad_t touch_num, uint32_t *raw_data); + +/** + * @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 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_read_benchmark(touch_pad_t touch_num, uint32_t *benchmark); + +/** + * @brief Get smoothed data that obtained by filtering the raw data. + * + * @param touch_num touch pad index + * @param smooth pointer to smoothed data + */ +esp_err_t touch_pad_filter_read_smooth(touch_pad_t touch_num, uint32_t *smooth); + +/** + * @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_reset_benchmark(touch_pad_t touch_num); + +/** + * @brief set parameter of touch sensor filter and detection algorithm. + * For more details on the detection algorithm, please refer to the application documentation. + * @param filter_info select filter type and threshold of detection algorithm + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_filter_set_config(const touch_filter_config_t *filter_info); + +/** + * @brief get parameter of touch sensor filter and detection algorithm. + * For more details on the detection algorithm, please refer to the application documentation. + * @param filter_info select filter type and threshold of detection algorithm + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_filter_get_config(touch_filter_config_t *filter_info); + +/** + * @brief enable touch sensor filter for detection algorithm. + * For more details on the detection algorithm, please refer to the application documentation. + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_filter_enable(void); + +/** + * @brief disable touch sensor filter for detection algorithm. + * For more details on the detection algorithm, please refer to the application documentation. + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_filter_disable(void); + +/** + * @brief set parameter of denoise pad (TOUCH_PAD_NUM0). + * T0 is an internal channel that does not have a corresponding external GPIO. + * T0 will work simultaneously with the measured channel Tn. Finally, the actual + * measured value of Tn is the value after subtracting lower bits of T0. + * The noise reduction function filters out interference introduced simultaneously on all channels, + * such as noise introduced by power supplies and external EMI. + * @param denoise parameter of denoise + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_denoise_set_config(const touch_pad_denoise_t *denoise); + +/** + * @brief get parameter of denoise pad (TOUCH_PAD_NUM0). + * @param denoise Pointer to parameter of denoise + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_denoise_get_config(touch_pad_denoise_t *denoise); + +/** + * @brief enable denoise function. + * T0 is an internal channel that does not have a corresponding external GPIO. + * T0 will work simultaneously with the measured channel Tn. Finally, the actual + * measured value of Tn is the value after subtracting lower bits of T0. + * The noise reduction function filters out interference introduced simultaneously on all channels, + * such as noise introduced by power supplies and external EMI. + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_denoise_enable(void); + +/** + * @brief disable denoise function. + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_denoise_disable(void); + +/** + * @brief Get denoise measure value (TOUCH_PAD_NUM0). + * @param data Pointer to receive denoise value + * @return + * - ESP_OK Success + */ +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. + * 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. + * + * @param waterproof parameter of waterproof + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_waterproof_set_config(const touch_pad_waterproof_t *waterproof); + +/** + * @brief get parameter of waterproof function. + * @param waterproof parameter of waterproof + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_waterproof_get_config(touch_pad_waterproof_t *waterproof); + +/** + * @brief Enable parameter of waterproof function. + * Should be called after function ``touch_pad_waterproof_set_config``. + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_waterproof_enable(void); + +/** + * @brief Disable parameter of waterproof function. + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_waterproof_disable(void); + +/** + * @brief Enable/disable proximity function of touch channels. + * The proximity sensor measurement is the accumulation of touch channel measurements. + * + * @note Supports up to three touch channels configured as proximity sensors. + * @param touch_num touch pad index + * @param enabled true: enable the proximity function; false: disable the proximity function + * @return + * - ESP_OK: Configured correctly. + * - ESP_ERR_INVALID_ARG: Touch channel number error. + * - ESP_ERR_NOT_SUPPORTED: Don't support configured. + */ +esp_err_t touch_pad_proximity_enable(touch_pad_t touch_num, bool enabled); + +/** + * @brief Set measure count of proximity channel. + * The proximity sensor measurement is the accumulation of touch channel measurements. + * + * @note All proximity channels use the same `count` value. So please pass the parameter `TOUCH_PAD_MAX`. + * @param touch_num Touch pad index. In this version, pass the parameter `TOUCH_PAD_MAX`. + * @param count The cumulative times of measurements for proximity pad. Range: 0 ~ 255. + * @return + * - ESP_OK: Configured correctly. + * - ESP_ERR_INVALID_ARG: Touch channel number error. + */ +esp_err_t touch_pad_proximity_set_count(touch_pad_t touch_num, uint32_t count); + +/** + * @brief Get measure count of proximity channel. + * The proximity sensor measurement is the accumulation of touch channel measurements. + * + * @note All proximity channels use the same `count` value. So please pass the parameter `TOUCH_PAD_MAX`. + * @param touch_num Touch pad index. In this version, pass the parameter `TOUCH_PAD_MAX`. + * @param count The cumulative times of measurements for proximity pad. Range: 0 ~ 255. + * @return + * - ESP_OK: Configured correctly. + * - ESP_ERR_INVALID_ARG: Touch channel number error. + */ +esp_err_t touch_pad_proximity_get_count(touch_pad_t touch_num, uint32_t *count); + +/** + * @brief Get the accumulated measurement of the proximity sensor. + * The proximity sensor measurement is the accumulation of touch channel measurements. + * @param touch_num touch pad index + * @param measure_out If the accumulation process does not end, the `measure_out` is the process value. + * @return + * - ESP_OK Success + * - ESP_ERR_INVALID_ARG Touch num is not proximity + */ +esp_err_t touch_pad_proximity_get_data(touch_pad_t touch_num, uint32_t *measure_out); + +/** + * @brief Get parameter of touch sensor sleep channel. + * The touch sensor can works in sleep mode to wake up sleep. + * + * @note After the sleep channel is configured, Please use special functions for sleep channel. + * e.g. The user should uses `touch_pad_sleep_channel_read_data` instead of `touch_pad_read_raw_data` to obtain the sleep channel reading. + * + * @param slp_config touch sleep pad config. + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_sleep_channel_get_info(touch_pad_sleep_channel_t *slp_config); + +/** + * @brief Enable/Disable sleep channel function for touch sensor. + * The touch sensor can works in sleep mode to wake up sleep. + * + * @note ESP32S2 only support one sleep channel. + * @note After the sleep channel is configured, Please use special functions for sleep channel. + * e.g. The user should uses `touch_pad_sleep_channel_read_data` instead of `touch_pad_read_raw_data` to obtain the sleep channel reading. + * + * @param pad_num Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode. + * @param enable true: enable sleep pad for touch sensor; false: disable sleep pad for touch sensor; + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_sleep_channel_enable(touch_pad_t pad_num, bool enable); + +/** + * @brief Enable/Disable proximity function for sleep channel. + * The touch sensor can works in sleep mode to wake up sleep. + * + * @note ESP32S2 only support one sleep channel. + * + * @param pad_num Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode. + * @param enable true: enable proximity for sleep channel; false: disable proximity for sleep channel; + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_sleep_channel_enable_proximity(touch_pad_t pad_num, bool enable); + +/** + * @brief Set the trigger threshold of touch sensor in deep sleep. + * The threshold determines the sensitivity of the touch sensor. + * + * @note In general, the touch threshold during sleep can use the threshold parameter parameters before sleep. + * + * @param pad_num Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode. + * @param touch_thres touch sleep pad threshold + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_sleep_set_threshold(touch_pad_t pad_num, uint32_t touch_thres); + +/** + * @brief Get the trigger threshold of touch sensor in deep sleep. + * The threshold determines the sensitivity of the touch sensor. + * + * @note In general, the touch threshold during sleep can use the threshold parameter parameters before sleep. + * + * @param pad_num Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode. + * @param touch_thres touch sleep pad threshold + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_sleep_get_threshold(touch_pad_t pad_num, uint32_t *touch_thres); + +/** + * @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 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_benchmark(touch_pad_t pad_num, uint32_t *benchmark); + +/** + * @brief Read smoothed data of touch sensor sleep channel. + * Smoothed data is filtered from the raw data. + * @param pad_num Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode. + * @param smooth_data pointer to accept touch sensor smoothed data + * @return + * - ESP_OK Success + * - ESP_ERR_INVALID_ARG parameter is NULL + */ +esp_err_t touch_pad_sleep_channel_read_smooth(touch_pad_t pad_num, uint32_t *smooth_data); + +/** + * @brief Read raw data 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 raw_data pointer to accept touch sensor raw data + * @return + * - ESP_OK Success + * - ESP_ERR_INVALID_ARG parameter is NULL + */ +esp_err_t touch_pad_sleep_channel_read_data(touch_pad_t pad_num, uint32_t *raw_data); + +/** + * @brief Reset benchmark of touch sensor sleep channel. + * + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_sleep_channel_reset_benchmark(void); + +/** + * @brief Read proximity count 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 proximity_cnt pointer to accept touch sensor proximity count value + * @return + * - ESP_OK Success + * - ESP_ERR_INVALID_ARG parameter is NULL + */ +esp_err_t touch_pad_sleep_channel_read_proximity_cnt(touch_pad_t pad_num, uint32_t *proximity_cnt); + +/** + * @brief Change the operating frequency of touch pad in deep sleep state. Reducing the operating frequency can effectively reduce power consumption. + * If this function is not called, the working frequency of touch in the deep sleep state is the same as that in the wake-up state. + * + * @param sleep_cycle The touch sensor will sleep after each measurement. + * sleep_cycle decide the interval between each measurement. + * t_sleep = sleep_cycle / (RTC_SLOW_CLK frequency). + * The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function. + * @param meas_times The times of charge and discharge in each measure process of touch channels. + * The timer frequency is 8Mhz. Range: 0 ~ 0xffff. + * Recommended typical value: Modify this value to make the measurement time around 1ms. + * @return + * - ESP_OK Success + */ +esp_err_t touch_pad_sleep_channel_set_work_time(uint16_t sleep_cycle, uint16_t meas_times); + +#ifdef __cplusplus +} +#endif diff --git a/components/driver/touch_sensor/esp32s3/touch_sensor.c b/components/driver/touch_sensor/esp32s3/touch_sensor.c index d749996017..3a2e645d7f 100644 --- a/components/driver/touch_sensor/esp32s3/touch_sensor.c +++ b/components/driver/touch_sensor/esp32s3/touch_sensor.c @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2016-2022 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2016-2024 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ @@ -16,7 +16,7 @@ #include "freertos/timers.h" #include "esp_intr_alloc.h" #include "driver/rtc_io.h" -#include "driver/touch_pad.h" +#include "driver/touch_sensor_common.h" #include "esp_private/rtc_ctrl.h" #include "driver/gpio.h" #include "sdkconfig.h" @@ -379,7 +379,7 @@ esp_err_t touch_pad_filter_get_config(touch_filter_config_t *filter_info) esp_err_t touch_pad_filter_enable(void) { TOUCH_ENTER_CRITICAL(); - touch_hal_filter_enable(); + touch_hal_filter_enable(true); TOUCH_EXIT_CRITICAL(); return ESP_OK; } @@ -387,7 +387,7 @@ esp_err_t touch_pad_filter_enable(void) esp_err_t touch_pad_filter_disable(void) { TOUCH_ENTER_CRITICAL(); - touch_hal_filter_disable(); + touch_hal_filter_enable(false); TOUCH_EXIT_CRITICAL(); return ESP_OK; } @@ -569,9 +569,9 @@ esp_err_t touch_pad_sleep_channel_enable_proximity(touch_pad_t pad_num, bool ena TOUCH_ENTER_CRITICAL(); if (enable) { - touch_hal_sleep_enable_approach(); + touch_hal_sleep_enable_approach(true); } else { - touch_hal_sleep_disable_approach(); + touch_hal_sleep_enable_approach(false); } TOUCH_EXIT_CRITICAL(); return ESP_OK; @@ -656,3 +656,17 @@ esp_err_t touch_pad_sleep_channel_set_work_time(uint16_t sleep_cycle, uint16_t m touch_hal_sleep_channel_set_work_time(sleep_cycle, meas_times); return ESP_OK; } + +/** + * @brief This function will be called during start up, to check that the new touch driver is not running along with the legacy touch driver + */ +static __attribute__((constructor)) void check_touch_driver_conflict(void) +{ + extern __attribute__((weak)) esp_err_t touch_del_channel(void *handle); + /* If the new I2S driver is linked, the weak function will point to the actual function in the new driver, otherwise it is NULL*/ + if ((void *)touch_del_channel != NULL) { + ESP_EARLY_LOGE("legacy_touch_driver", "CONFLICT! The new touch driver can't work along with the legacy touch driver"); + abort(); + } + ESP_EARLY_LOGW("legacy_touch_driver", "legacy touch driver is deprecated, please migrate to use driver/touch_sens.h"); +} diff --git a/components/driver/touch_sensor/touch_sensor_common.c b/components/driver/touch_sensor/touch_sensor_common.c index cbe1d4dced..b2846d473d 100644 --- a/components/driver/touch_sensor/touch_sensor_common.c +++ b/components/driver/touch_sensor/touch_sensor_common.c @@ -16,7 +16,6 @@ #include "freertos/timers.h" #include "esp_intr_alloc.h" #include "driver/rtc_io.h" -#include "driver/touch_pad.h" #include "esp_private/rtc_ctrl.h" #include "driver/gpio.h" #include "hal/touch_sensor_types.h" diff --git a/components/touch_element/include/touch_element/touch_element.h b/components/touch_element/include/touch_element/touch_element.h index 902c23e94b..fa32d8f42c 100644 --- a/components/touch_element/include/touch_element/touch_element.h +++ b/components/touch_element/include/touch_element/touch_element.h @@ -1,12 +1,12 @@ /* - * SPDX-FileCopyrightText: 2016-2022 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2016-2024 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ #pragma once -#include "driver/touch_sensor.h" +#include "driver/touch_sensor_legacy.h" #ifdef __cplusplus extern "C" { @@ -274,9 +274,9 @@ esp_err_t touch_element_waterproof_remove(touch_elem_handle_t element_handle); * @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_INVALID_ARG: inputted 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_NOT_SUPPORTED: inputted 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); @@ -305,9 +305,9 @@ esp_err_t touch_element_disable_light_sleep(void); * @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_INVALID_ARG: inputted 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_NOT_SUPPORTED: inputted 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);