blackbeard420/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf synced 2025-03-09 09:09:10 -04:00
Code Issues Projects Releases Wiki Activity

feat(touch): update doc and example for touch version 2

Browse Source
This commit is contained in:
laokaiyao 2024-10-17 18:23:22 +08:00 committed by Kevin (Lao Kaiyao)
parent 1ccb534dc7
commit c007ec5f17
78 changed files with 1308 additions and 1285 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
components/driver/test_apps/touch_sensor_v1/main/test_touch_v1.c
View File

@ -22,7 +22,7 @@
#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 "driver/touch_sensor.h"
#include "esp_rom_sys.h"
#if CONFIG_PM_ENABLE
#include "esp_pm.h"

378
components/driver/touch_sensor/esp32/include/driver/touch_sensor.h
View File

@ -6,6 +6,380 @@
#pragma once
#include "driver/touch_sensor_legacy.h"
#ifdef __cplusplus
extern "C" {
#endif
// Keep for compatibility
#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

385
components/driver/touch_sensor/esp32/include/driver/touch_sensor_legacy.h
View File

@ -1,385 +0,0 @@
/*
* 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

2
components/driver/touch_sensor/esp32/touch_sensor.c
View File

@ -27,7 +27,7 @@
#define INVARIANTS
#endif
#include "sys/queue.h"
#include "hal/touch_sensor_types.h"
#include "hal/touch_sensor_legacy_types.h"
#include "hal/touch_sensor_hal.h"
typedef struct {

8
components/driver/touch_sensor/esp32s2/touch_sensor.c
View File

@ -22,7 +22,7 @@
#include "sdkconfig.h"
#include "esp_check.h"
#include "hal/touch_sensor_types.h"
#include "hal/touch_sensor_legacy_types.h"
#include "hal/touch_sensor_hal.h"
#ifndef NDEBUG
@ -690,9 +690,9 @@ esp_err_t touch_pad_sleep_channel_set_work_time(uint16_t sleep_cycle, uint16_t m
*/
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) {
extern __attribute__((weak)) esp_err_t touch_sensor_new_controller(const void*, void *);
/* If the new Touch driver is linked, the weak function will point to the actual function in the new driver, otherwise it is NULL*/
if ((void *)touch_sensor_new_controller != NULL) {
ESP_EARLY_LOGE("legacy_touch_driver", "CONFLICT! The new touch driver can't work along with the legacy touch driver");
abort();
}

8
components/driver/touch_sensor/esp32s3/touch_sensor.c
View File

@ -22,7 +22,7 @@
#include "sdkconfig.h"
#include "esp_check.h"
#include "hal/touch_sensor_types.h"
#include "hal/touch_sensor_legacy_types.h"
#include "hal/touch_sensor_hal.h"
#ifndef NDEBUG
@ -662,9 +662,9 @@ esp_err_t touch_pad_sleep_channel_set_work_time(uint16_t sleep_cycle, uint16_t m
*/
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) {
extern __attribute__((weak)) esp_err_t touch_sensor_new_controller(const void*, void *);
/* If the new Touch driver is linked, the weak function will point to the actual function in the new driver, otherwise it is NULL*/
if ((void *)touch_sensor_new_controller != NULL) {
ESP_EARLY_LOGE("legacy_touch_driver", "CONFLICT! The new touch driver can't work along with the legacy touch driver");
abort();
}

2
components/driver/touch_sensor/include/driver/touch_sensor_common.h
View File

@ -8,7 +8,7 @@
#include "esp_err.h"
#include "esp_intr_alloc.h"
#include "hal/touch_sensor_types.h"
#include "hal/touch_sensor_legacy_types.h"
#ifdef __cplusplus
extern "C" {

2
components/driver/touch_sensor/touch_sensor_common.c
View File

@ -18,7 +18,7 @@
#include "driver/rtc_io.h"
#include "esp_private/rtc_ctrl.h"
#include "driver/gpio.h"
#include "hal/touch_sensor_types.h"
#include "hal/touch_sensor_legacy_types.h"
#include "hal/touch_sensor_hal.h"
static const char *TOUCH_TAG = "TOUCH_SENSOR";

43
components/esp_driver_touch_sens/common/touch_sens_common.c
View File

@ -28,6 +28,7 @@
// Set the maximum log level for this source file
#define LOG_LOCAL_LEVEL ESP_LOG_DEBUG
#endif
#include "esp_log.h"
#include "esp_check.h"
#include "touch_sens_private.h"
@ -73,7 +74,7 @@ esp_err_t touch_sensor_new_controller(const touch_sensor_config_t *sens_cfg, tou
g_touch = (touch_sensor_handle_t)heap_caps_calloc(1, sizeof(struct touch_sensor_s), TOUCH_MEM_ALLOC_CAPS);
ESP_RETURN_ON_FALSE(g_touch, ESP_ERR_NO_MEM, TAG, "No memory for touch sensor struct");
g_touch->mutex = xSemaphoreCreateMutexWithCaps(TOUCH_MEM_ALLOC_CAPS);
g_touch->mutex = xSemaphoreCreateRecursiveMutexWithCaps(TOUCH_MEM_ALLOC_CAPS);
ESP_GOTO_ON_FALSE(g_touch->mutex, ESP_ERR_NO_MEM, err, TAG, "No memory for mutex semaphore");
touch_priv_enable_module(true);
@ -100,7 +101,7 @@ esp_err_t touch_sensor_del_controller(touch_sensor_handle_t sens_handle)
esp_err_t ret = ESP_OK;
// Take the semaphore to make sure the touch has stopped
xSemaphoreTake(sens_handle->mutex, portMAX_DELAY);
xSemaphoreTakeRecursive(sens_handle->mutex, portMAX_DELAY);
ESP_GOTO_ON_FALSE(!sens_handle->is_enabled, ESP_ERR_INVALID_STATE, err, TAG, "Touch sensor has not disabled");
FOR_EACH_TOUCH_CHANNEL(i) {
ESP_GOTO_ON_FALSE(!sens_handle->ch[i], ESP_ERR_INVALID_STATE, err, TAG, "There are still some touch channels not deleted");
@ -121,7 +122,7 @@ esp_err_t touch_sensor_del_controller(touch_sensor_handle_t sens_handle)
s_touch_free_resource(sens_handle);
err:
if (g_touch && g_touch->mutex) {
xSemaphoreGive(g_touch->mutex);
xSemaphoreGiveRecursive(g_touch->mutex);
}
return ret;
}
@ -138,7 +139,7 @@ esp_err_t touch_sensor_new_channel(touch_sensor_handle_t sens_handle, int chan_i
ESP_RETURN_ON_FALSE(g_touch == sens_handle, ESP_ERR_INVALID_ARG, TAG, "The input touch sensor handle is unmatched");
esp_err_t ret = ESP_OK;
xSemaphoreTake(sens_handle->mutex, portMAX_DELAY);
xSemaphoreTakeRecursive(sens_handle->mutex, portMAX_DELAY);
ESP_GOTO_ON_FALSE(!sens_handle->is_enabled, ESP_ERR_INVALID_STATE, err2, TAG, "Please disable the touch sensor first");
ESP_GOTO_ON_FALSE(!sens_handle->ch[chan_id], ESP_ERR_INVALID_STATE, err2, TAG, "The channel %d has been registered", chan_id);
@ -163,13 +164,13 @@ esp_err_t touch_sensor_new_channel(touch_sensor_handle_t sens_handle, int chan_i
*ret_chan_handle = sens_handle->ch[chan_id];
xSemaphoreGive(sens_handle->mutex);
xSemaphoreGiveRecursive(sens_handle->mutex);
return ret;
err1:
free(sens_handle->ch[chan_id]);
sens_handle->ch[chan_id] = NULL;
err2:
xSemaphoreGive(sens_handle->mutex);
xSemaphoreGiveRecursive(sens_handle->mutex);
return ret;
}
@ -179,7 +180,7 @@ esp_err_t touch_sensor_del_channel(touch_channel_handle_t chan_handle)
esp_err_t ret = ESP_OK;
touch_sensor_handle_t sens_handle = chan_handle->base;
xSemaphoreTake(sens_handle->mutex, portMAX_DELAY);
xSemaphoreTakeRecursive(sens_handle->mutex, portMAX_DELAY);
ESP_GOTO_ON_FALSE(!sens_handle->is_enabled, ESP_ERR_INVALID_STATE, err, TAG, "Please disable the touch sensor first");
#if SOC_TOUCH_SUPPORT_WATERPROOF
@ -213,7 +214,7 @@ esp_err_t touch_sensor_del_channel(touch_channel_handle_t chan_handle)
free(g_touch->ch[id]);
g_touch->ch[id] = NULL;
err:
xSemaphoreGive(sens_handle->mutex);
xSemaphoreGiveRecursive(sens_handle->mutex);
return ret;
}
@ -224,13 +225,13 @@ esp_err_t touch_sensor_reconfig_controller(touch_sensor_handle_t sens_handle, co
ESP_RETURN_ON_FALSE(sens_cfg->meas_interval_us >= 0, ESP_ERR_INVALID_ARG, TAG, "interval_us should be a positive value");
esp_err_t ret = ESP_OK;
xSemaphoreTake(sens_handle->mutex, portMAX_DELAY);
xSemaphoreTakeRecursive(sens_handle->mutex, portMAX_DELAY);
ESP_GOTO_ON_FALSE(!sens_handle->is_enabled, ESP_ERR_INVALID_STATE, err, TAG, "Please disable the touch sensor first");
ESP_GOTO_ON_ERROR(touch_priv_config_controller(sens_handle, sens_cfg), err, TAG, "Configure touch controller failed");
err:
xSemaphoreGive(sens_handle->mutex);
xSemaphoreGiveRecursive(sens_handle->mutex);
return ret;
}
@ -270,7 +271,7 @@ esp_err_t touch_sensor_disable(touch_sensor_handle_t sens_handle)
TOUCH_NULL_POINTER_CHECK(sens_handle);
esp_err_t ret = ESP_OK;
xSemaphoreTake(sens_handle->mutex, portMAX_DELAY);
xSemaphoreTakeRecursive(sens_handle->mutex, portMAX_DELAY);
ESP_GOTO_ON_FALSE(sens_handle->is_enabled, ESP_ERR_INVALID_STATE, err, TAG, "Touch sensor has not enabled");
TOUCH_ENTER_CRITICAL(TOUCH_PERIPH_LOCK);
@ -280,7 +281,7 @@ esp_err_t touch_sensor_disable(touch_sensor_handle_t sens_handle)
sens_handle->is_enabled = false;
err:
xSemaphoreGive(sens_handle->mutex);
xSemaphoreGiveRecursive(sens_handle->mutex);
return ret;
}
@ -291,13 +292,13 @@ esp_err_t touch_sensor_reconfig_channel(touch_channel_handle_t chan_handle, cons
esp_err_t ret = ESP_OK;
touch_sensor_handle_t sens_handle = chan_handle->base;
xSemaphoreTake(sens_handle->mutex, portMAX_DELAY);
xSemaphoreTakeRecursive(sens_handle->mutex, portMAX_DELAY);
ESP_GOTO_ON_FALSE(!sens_handle->is_enabled, ESP_ERR_INVALID_STATE, err, TAG, "Please disable the touch sensor first");
ESP_GOTO_ON_ERROR(touch_priv_config_channel(chan_handle, chan_cfg), err, TAG, "Configure touch channel failed");
err:
xSemaphoreGive(sens_handle->mutex);
xSemaphoreGiveRecursive(sens_handle->mutex);
return ret;
}
@ -357,7 +358,7 @@ esp_err_t touch_sensor_trigger_oneshot_scanning(touch_sensor_handle_t sens_handl
ticks = 1;
}
}
xSemaphoreTake(sens_handle->mutex, ticks);
xSemaphoreTakeRecursive(sens_handle->mutex, ticks);
TickType_t end_tick = xTaskGetTickCount() + ticks;
TOUCH_ENTER_CRITICAL(TOUCH_PERIPH_LOCK);
touch_ll_enable_fsm_timer(false);
@ -386,7 +387,7 @@ esp_err_t touch_sensor_trigger_oneshot_scanning(touch_sensor_handle_t sens_handl
TOUCH_EXIT_CRITICAL(TOUCH_PERIPH_LOCK);
err:
xSemaphoreGive(sens_handle->mutex);
xSemaphoreGiveRecursive(sens_handle->mutex);
TOUCH_ENTER_CRITICAL(TOUCH_PERIPH_LOCK);
sens_handle->is_started = false;
TOUCH_EXIT_CRITICAL(TOUCH_PERIPH_LOCK);
@ -407,7 +408,7 @@ esp_err_t touch_sensor_register_callbacks(touch_sensor_handle_t sens_handle, con
#endif
esp_err_t ret = ESP_OK;
xSemaphoreTake(sens_handle->mutex, portMAX_DELAY);
xSemaphoreTakeRecursive(sens_handle->mutex, portMAX_DELAY);
ESP_GOTO_ON_FALSE(!sens_handle->is_enabled, ESP_ERR_INVALID_STATE, err, TAG, "Please disable the touch sensor first");
@ -415,7 +416,7 @@ esp_err_t touch_sensor_register_callbacks(touch_sensor_handle_t sens_handle, con
sens_handle->user_ctx = user_ctx;
err:
xSemaphoreGive(sens_handle->mutex);
xSemaphoreGiveRecursive(sens_handle->mutex);
return ret;
}
@ -441,13 +442,13 @@ esp_err_t touch_sensor_get_channel_info(touch_channel_handle_t chan_handle, touc
{
TOUCH_NULL_POINTER_CHECK(chan_handle);
TOUCH_NULL_POINTER_CHECK(chan_info);
xSemaphoreTake(chan_handle->base->mutex, portMAX_DELAY);
xSemaphoreTakeRecursive(chan_handle->base->mutex, portMAX_DELAY);
chan_info->chan_id = chan_handle->id;
chan_info->chan_gpio = touch_sensor_channel_io_map[chan_handle->id];
chan_info->flags.is_dp_slp = chan_handle == chan_handle->base->deep_slp_chan;
chan_info->flags.can_wake_dp_slp = chan_handle == chan_handle->base->deep_slp_chan;
chan_info->flags.is_proxi = chan_handle->prox_id > 0;
chan_info->flags.is_guard = chan_handle == chan_handle->base->guard_chan;
chan_info->flags.is_shield = chan_handle == chan_handle->base->shield_chan;
xSemaphoreGive(chan_handle->base->mutex);
xSemaphoreGiveRecursive(chan_handle->base->mutex);
return ESP_OK;
}

12
components/esp_driver_touch_sens/common/touch_sens_private.h
View File

@ -32,13 +32,19 @@ extern "C" {
/* IRAM safe caps */
#if CONFIG_TOUCH_ISR_IRAM_SAFE || CONFIG_TOUCH_CTRL_FUNC_IN_IRAM
#define TOUCH_INTR_ALLOC_FLAGS (ESP_INTR_FLAG_IRAM | ESP_INTR_FLAG_SHARED | ESP_INTR_FLAG_LOWMED)
#define TOUCH_MEM_ALLOC_CAPS (MALLOC_CAP_INTERNAL | MALLOC_CAP_8BIT)
#define _TOUCH_INTR_ALLOC_FLAGS (ESP_INTR_FLAG_IRAM | ESP_INTR_FLAG_LOWMED)
#define TOUCH_MEM_ALLOC_CAPS (MALLOC_CAP_INTERNAL | MALLOC_CAP_8BIT)
#else
#define TOUCH_INTR_ALLOC_FLAGS (ESP_INTR_FLAG_SHARED | ESP_INTR_FLAG_LOWMED)
#define _TOUCH_INTR_ALLOC_FLAGS (ESP_INTR_FLAG_LOWMED)
#define TOUCH_MEM_ALLOC_CAPS MALLOC_CAP_DEFAULT
#endif //CONFIG_TOUCH_ISR_IRAM_SAFE
#if SOC_TOUCH_SENSOR_VERSION == 3
#define TOUCH_INTR_ALLOC_FLAGS (_TOUCH_INTR_ALLOC_FLAGS)
#else
#define TOUCH_INTR_ALLOC_FLAGS (_TOUCH_INTR_ALLOC_FLAGS | ESP_INTR_FLAG_SHARED)
#endif
/* DMA caps */
#define TOUCH_DMA_ALLOC_CAPS (MALLOC_CAP_INTERNAL | MALLOC_CAP_DMA)

10
components/esp_driver_touch_sens/hw_ver2/include/driver/touch_version_types.h
View File

@ -88,12 +88,12 @@ typedef enum {
*/
typedef struct {
uint32_t charge_times; /*!< The charge and discharge times of this sample configuration, the read data are positive correlation to the charge_times */
touch_volt_lim_h_t charge_volt_lim_h; /*!< The upper voltage limit while charging a touch pad */
touch_volt_lim_l_t charge_volt_lim_l; /*!< The lower voltage limit while charging a touch pad */
touch_volt_lim_h_t charge_volt_lim_h; /*!< The upper voltage limit while charging a touch pad. i.e., the touch controller won't charge the touch pad higher than this high voltage limitation. */
touch_volt_lim_l_t charge_volt_lim_l; /*!< The lower voltage limit while discharging a touch pad. i.e., the touch controller won't discharge the touch pad lower than this low voltage limitation. */
touch_idle_conn_t idle_conn; /*!< The connection of the idle touch channels.
* The idle touch channel is a channel which is enabled but not under measuring.
* The idle touch channel is a channel which is enabled and power-on but not under measuring.
*/
touch_bias_type_t bias_type; /*!< The type of the touch sensor bias */
touch_bias_type_t bias_type; /*!< The type of the touch sensor bias. Which affects the charge/discharge stability and power consumption */
} touch_sensor_sample_config_t;
/**
@ -241,7 +241,7 @@ typedef struct {
touch_charge_speed_t charge_speed; /*!< The speed of charging and discharging the denoise touch channel, the higher the speed, the faster charging and discharging */
touch_init_charge_volt_t init_charge_volt; /*!< The initial voltage before starting charging/discharging the denoise channel */
touch_denoise_chan_cap_t ref_cap; /*!< The reference capacitance of the denoise channel. */
touch_denoise_chan_res_t resolution; /*!< The noise suppression resolution of the denoise channel.
touch_denoise_chan_resolution_t resolution; /*!< The noise suppression resolution of the denoise channel.
* The higher the resolution, the better the suppression effect,
* but at the same time, the attenuation of other touch channel sampling values also increases.
*/

23
components/esp_driver_touch_sens/hw_ver2/touch_version_specific.c
View File

@ -29,6 +29,7 @@
// Set the maximum log level for this source file
#define LOG_LOCAL_LEVEL ESP_LOG_DEBUG
#endif
#include "esp_log.h"
#include "esp_check.h"
#define TOUCH_DENOISE_CHAN_ID 0 /*!< The touch channel that can be used as the denoise channel */
@ -223,7 +224,7 @@ esp_err_t touch_priv_deinit_controller(touch_sensor_handle_t sens_handle)
return ESP_OK;
}
esp_err_t IRAM_ATTR touch_priv_channel_read_data(touch_channel_handle_t chan_handle, touch_chan_data_type_t type, uint32_t *data)
esp_err_t touch_priv_channel_read_data(touch_channel_handle_t chan_handle, touch_chan_data_type_t type, uint32_t *data)
{
ESP_RETURN_ON_FALSE_ISR(type >= TOUCH_CHAN_DATA_TYPE_RAW && type <= TOUCH_CHAN_DATA_TYPE_PROXIMITY,
ESP_ERR_INVALID_ARG, TAG, "The channel data type is invalid");
@ -270,7 +271,7 @@ esp_err_t touch_sensor_config_filter(touch_sensor_handle_t sens_handle, const to
}
esp_err_t ret = ESP_OK;
xSemaphoreTake(sens_handle->mutex, portMAX_DELAY);
xSemaphoreTakeRecursive(sens_handle->mutex, portMAX_DELAY);
TOUCH_ENTER_CRITICAL(TOUCH_PERIPH_LOCK);
if (filter_cfg) {
@ -290,7 +291,7 @@ esp_err_t touch_sensor_config_filter(touch_sensor_handle_t sens_handle, const to
}
TOUCH_EXIT_CRITICAL(TOUCH_PERIPH_LOCK);
xSemaphoreGive(sens_handle->mutex);
xSemaphoreGiveRecursive(sens_handle->mutex);
return ret;
}
@ -303,7 +304,7 @@ esp_err_t touch_sensor_config_sleep_wakeup(touch_sensor_handle_t sens_handle, co
touch_hal_config_t hal_cfg = {};
touch_hal_config_t *hal_cfg_ptr = NULL;
xSemaphoreTake(sens_handle->mutex, portMAX_DELAY);
xSemaphoreTakeRecursive(sens_handle->mutex, portMAX_DELAY);
ESP_GOTO_ON_FALSE(!sens_handle->is_enabled, ESP_ERR_INVALID_STATE, err, TAG, "Please disable the touch sensor first");
if (sleep_cfg) {
@ -351,7 +352,7 @@ esp_err_t touch_sensor_config_sleep_wakeup(touch_sensor_handle_t sens_handle, co
TOUCH_EXIT_CRITICAL(TOUCH_PERIPH_LOCK);
err:
xSemaphoreGive(sens_handle->mutex);
xSemaphoreGiveRecursive(sens_handle->mutex);
return ret;
}
@ -361,7 +362,7 @@ esp_err_t touch_sensor_config_waterproof(touch_sensor_handle_t sens_handle, cons
TOUCH_NULL_POINTER_CHECK(sens_handle);
esp_err_t ret = ESP_OK;
xSemaphoreTake(sens_handle->mutex, portMAX_DELAY);
xSemaphoreTakeRecursive(sens_handle->mutex, portMAX_DELAY);
ESP_GOTO_ON_FALSE(!sens_handle->is_enabled, ESP_ERR_INVALID_STATE, err, TAG, "Please disable the touch sensor first");
@ -391,7 +392,7 @@ esp_err_t touch_sensor_config_waterproof(touch_sensor_handle_t sens_handle, cons
TOUCH_EXIT_CRITICAL(TOUCH_PERIPH_LOCK);
}
err:
xSemaphoreGive(sens_handle->mutex);
xSemaphoreGiveRecursive(sens_handle->mutex);
return ret;
}
@ -400,7 +401,7 @@ esp_err_t touch_sensor_config_proximity_sensing(touch_sensor_handle_t sens_handl
TOUCH_NULL_POINTER_CHECK(sens_handle);
esp_err_t ret = ESP_OK;
xSemaphoreTake(sens_handle->mutex, portMAX_DELAY);
xSemaphoreTakeRecursive(sens_handle->mutex, portMAX_DELAY);
ESP_GOTO_ON_FALSE(!sens_handle->is_enabled, ESP_ERR_INVALID_STATE, err, TAG, "Please disable the touch sensor first");
@ -435,7 +436,7 @@ esp_err_t touch_sensor_config_proximity_sensing(touch_sensor_handle_t sens_handl
TOUCH_EXIT_CRITICAL(TOUCH_PERIPH_LOCK);
err:
xSemaphoreGive(sens_handle->mutex);
xSemaphoreGiveRecursive(sens_handle->mutex);
return ret;
}
@ -443,7 +444,7 @@ esp_err_t touch_sensor_config_denoise_channel(touch_sensor_handle_t sens_handle,
{
TOUCH_NULL_POINTER_CHECK(sens_handle);
esp_err_t ret = ESP_OK;
xSemaphoreTake(sens_handle->mutex, portMAX_DELAY);
xSemaphoreTakeRecursive(sens_handle->mutex, portMAX_DELAY);
ESP_GOTO_ON_FALSE(!sens_handle->is_enabled, ESP_ERR_INVALID_STATE, err, TAG, "Please disable the touch sensor first");
@ -465,6 +466,6 @@ esp_err_t touch_sensor_config_denoise_channel(touch_sensor_handle_t sens_handle,
TOUCH_EXIT_CRITICAL(TOUCH_PERIPH_LOCK);
}
err:
xSemaphoreGive(sens_handle->mutex);
xSemaphoreGiveRecursive(sens_handle->mutex);
return ret;
}

4
components/esp_driver_touch_sens/hw_ver3/include/driver/touch_version_types.h
View File

@ -89,7 +89,9 @@ typedef enum {
*
*/
typedef struct {
uint32_t div_num; /*!< Division of the touch output pulse, `touch_out_pulse / div_num = charge_times` */
uint32_t div_num; /*!< Division of the touch output pulse.
* It is proportional to the gain of the read data, the greater the div_num, the higher gain of the read data.
* If the read data is exceeded the maximum range, please reduce the div_num. */
uint32_t charge_times; /*!< The charge and discharge times of this sample configuration, the read data are positive correlation to the charge_times */
uint8_t rc_filter_res; /*!< The resistance of the RC filter of this sample configuration, range [0, 3], while 0 = 0K, 1 = 1.5K, 2 = 3K, 3 = 4.5K */
uint8_t rc_filter_cap; /*!< The capacitance of the RC filter of this sample configuration, range [0, 127], while 0 = 0pF, 1 = 20fF, ..., 127 = 2.54pF */

17
components/esp_driver_touch_sens/hw_ver3/touch_version_specific.c
View File

@ -29,6 +29,7 @@
// Set the maximum log level for this source file
#define LOG_LOCAL_LEVEL ESP_LOG_DEBUG
#endif
#include "esp_log.h"
#include "esp_check.h"
static const char *TAG = "touch";
@ -283,7 +284,7 @@ esp_err_t touch_sensor_config_filter(touch_sensor_handle_t sens_handle, const to
}
esp_err_t ret = ESP_OK;
xSemaphoreTake(sens_handle->mutex, portMAX_DELAY);
xSemaphoreTakeRecursive(sens_handle->mutex, portMAX_DELAY);
TOUCH_ENTER_CRITICAL(TOUCH_PERIPH_LOCK);
if (filter_cfg) {
@ -303,7 +304,7 @@ esp_err_t touch_sensor_config_filter(touch_sensor_handle_t sens_handle, const to
}
TOUCH_EXIT_CRITICAL(TOUCH_PERIPH_LOCK);
xSemaphoreGive(sens_handle->mutex);
xSemaphoreGiveRecursive(sens_handle->mutex);
return ret;
}
@ -319,7 +320,7 @@ esp_err_t touch_sensor_config_sleep_wakeup(touch_sensor_handle_t sens_handle, co
};
touch_hal_config_t *hal_cfg_ptr = NULL;
xSemaphoreTake(sens_handle->mutex, portMAX_DELAY);
xSemaphoreTakeRecursive(sens_handle->mutex, portMAX_DELAY);
ESP_GOTO_ON_FALSE(!sens_handle->is_enabled, ESP_ERR_INVALID_STATE, err, TAG, "Please disable the touch sensor first");
if (sleep_cfg) {
@ -370,7 +371,7 @@ esp_err_t touch_sensor_config_sleep_wakeup(touch_sensor_handle_t sens_handle, co
TOUCH_EXIT_CRITICAL(TOUCH_PERIPH_LOCK);
err:
xSemaphoreGive(sens_handle->mutex);
xSemaphoreGiveRecursive(sens_handle->mutex);
return ret;
}
@ -380,7 +381,7 @@ esp_err_t touch_sensor_config_waterproof(touch_sensor_handle_t sens_handle, cons
TOUCH_NULL_POINTER_CHECK(sens_handle);
esp_err_t ret = ESP_OK;
xSemaphoreTake(sens_handle->mutex, portMAX_DELAY);
xSemaphoreTakeRecursive(sens_handle->mutex, portMAX_DELAY);
ESP_GOTO_ON_FALSE(!sens_handle->is_enabled, ESP_ERR_INVALID_STATE, err, TAG, "Please disable the touch sensor first");
@ -415,7 +416,7 @@ esp_err_t touch_sensor_config_waterproof(touch_sensor_handle_t sens_handle, cons
TOUCH_EXIT_CRITICAL(TOUCH_PERIPH_LOCK);
}
err:
xSemaphoreGive(sens_handle->mutex);
xSemaphoreGiveRecursive(sens_handle->mutex);
return ret;
}
@ -424,7 +425,7 @@ esp_err_t touch_sensor_config_proximity_sensing(touch_sensor_handle_t sens_handl
TOUCH_NULL_POINTER_CHECK(sens_handle);
esp_err_t ret = ESP_OK;
xSemaphoreTake(sens_handle->mutex, portMAX_DELAY);
xSemaphoreTakeRecursive(sens_handle->mutex, portMAX_DELAY);
ESP_GOTO_ON_FALSE(!sens_handle->is_enabled, ESP_ERR_INVALID_STATE, err, TAG, "Please disable the touch sensor first");
@ -465,6 +466,6 @@ esp_err_t touch_sensor_config_proximity_sensing(touch_sensor_handle_t sens_handl
TOUCH_EXIT_CRITICAL(TOUCH_PERIPH_LOCK);
err:
xSemaphoreGive(sens_handle->mutex);
xSemaphoreGiveRecursive(sens_handle->mutex);
return ret;
}

56
components/esp_driver_touch_sens/include/driver/touch_sens_types.h
View File

@ -31,62 +31,6 @@ typedef enum {
TOUCH_DEEP_SLEEP_WAKEUP, /*!< Enable the touch sensor to wake up the chip from deep sleep or light sleep */
} touch_sleep_wakeup_level_t;
/**
* @brief Touch sensor shield channel drive capability level
*
*/
typedef enum {
TOUCH_SHIELD_CAP_40PF, /*!< The max equivalent capacitance in shield channel is 40pf */
TOUCH_SHIELD_CAP_80PF, /*!< The max equivalent capacitance in shield channel is 80pf */
TOUCH_SHIELD_CAP_120PF, /*!< The max equivalent capacitance in shield channel is 120pf */
TOUCH_SHIELD_CAP_160PF, /*!< The max equivalent capacitance in shield channel is 160pf */
TOUCH_SHIELD_CAP_200PF, /*!< The max equivalent capacitance in shield channel is 200pf */
TOUCH_SHIELD_CAP_240PF, /*!< The max equivalent capacitance in shield channel is 240pf */
TOUCH_SHIELD_CAP_280PF, /*!< The max equivalent capacitance in shield channel is 280pf */
TOUCH_SHIELD_CAP_320PF, /*!< The max equivalent capacitance in shield channel is 320pf */
} touch_chan_shield_cap_t;
/**
* @brief Touch channel Infinite Impulse Response (IIR) filter or Jitter filter for benchmark
* @note Recommended filter coefficient selection is `IIR_16`.
*/
typedef enum {
TOUCH_BM_IIR_FILTER_4, /*!< IIR Filter for benchmark, 1/4 raw_value + 3/4 benchmark */
TOUCH_BM_IIR_FILTER_8, /*!< IIR Filter for benchmark, 1/8 raw_value + 7/8 benchmark */
TOUCH_BM_IIR_FILTER_16, /*!< IIR Filter for benchmark, 1/16 raw_value + 15/16 benchmark (typical) */
TOUCH_BM_IIR_FILTER_32, /*!< IIR Filter for benchmark, 1/32 raw_value + 31/32 benchmark */
TOUCH_BM_IIR_FILTER_64, /*!< IIR Filter for benchmark, 1/64 raw_value + 63/64 benchmark */
TOUCH_BM_IIR_FILTER_128, /*!< IIR Filter for benchmark, 1/128 raw_value + 127/128 benchmark */
#if SOC_TOUCH_SENSOR_VERSION == 2
TOUCH_BM_IIR_FILTER_256, /*!< IIR Filter for benchmark, 1/256 raw_value + 255/256 benchmark */
#endif
TOUCH_BM_JITTER_FILTER, /*!< Jitter Filter for benchmark, raw value +/- jitter_step */
} touch_benchmark_filter_mode_t;
/**
* @brief Touch channel Infinite Impulse Response (IIR) filter for smooth data
*
*/
typedef enum {
TOUCH_SMOOTH_NO_FILTER, /*!< No filter adopted for smooth data, smooth data equals raw data */
TOUCH_SMOOTH_IIR_FILTER_2, /*!< IIR filter adopted for smooth data, smooth data equals 1/2 raw data + 1/2 last smooth data (typical) */
TOUCH_SMOOTH_IIR_FILTER_4, /*!< IIR filter adopted for smooth data, smooth data equals 1/4 raw data + 3/4 last smooth data */
TOUCH_SMOOTH_IIR_FILTER_8, /*!< IIR filter adopted for smooth data, smooth data equals 1/8 raw data + 7/8 last smooth data */
} touch_smooth_filter_mode_t;
/**
* @brief Interrupt events
*
*/
typedef enum {
TOUCH_INTR_EVENT_ACTIVE, /*!< Touch channel active event */
TOUCH_INTR_EVENT_INACTIVE, /*!< Touch channel inactive event */
TOUCH_INTR_EVENT_MEASURE_DONE, /*!< Touch channel measure done event */
TOUCH_INTR_EVENT_SCAN_DONE, /*!< All touch channels scan done event */
TOUCH_INTR_EVENT_TIMEOUT, /*!< Touch channel measurement timeout event */
TOUCH_INTR_EVENT_PROXIMITY_DONE, /*!< Proximity channel measurement done event */
} touch_intr_event_t;
typedef struct touch_sensor_s *touch_sensor_handle_t; /*!< The handle of touch sensor controller */
typedef struct touch_channel_s *touch_channel_handle_t; /*!< The handle of touch channel */

2
components/esp_driver_touch_sens/include/esp_private/touch_sens_helper.h
View File

@ -22,7 +22,7 @@ typedef struct {
int chan_id; /*!< Touch channel number */
int chan_gpio; /*!< Corresponding GPIO of this channel */
struct {
uint32_t is_dp_slp: 1; /*!< Whether this channel can wakeup from deep sleep */
uint32_t can_wake_dp_slp: 1;/*!< Whether this channel can wakeup from deep sleep */
uint32_t is_proxi: 1; /*!< Whether this channel is used for proximity sensing */
uint32_t is_guard: 1; /*!< Whether this channel is used for waterproof guard channel */
uint32_t is_shield: 1; /*!< Whether this channel is used for waterproof shield channel */

10
components/esp_driver_touch_sens/test_apps/touch_sens/main/test_touch_sens_common.c
View File

@ -55,20 +55,20 @@ TEST_CASE("touch_sens_install_uninstall_test", "[touch]")
touch_sensor_filter_config_t filter_cfg = TOUCH_SENSOR_DEFAULT_FILTER_CONFIG();
TEST_ESP_OK(touch_sensor_config_filter(touch, &filter_cfg));
for (int i = 0; i < TOUCH_TOTAL_CHAN_NUM; i++) {
for (int i = TOUCH_MIN_CHAN_ID; i <= TOUCH_MAX_CHAN_ID; i++) {
TEST_ESP_OK(touch_sensor_new_channel(touch, i, &s_chan_cfg, &touch_chan[i]));
}
touch_channel_handle_t fault_chan = NULL;
TEST_ASSERT(touch_sensor_new_channel(touch, TOUCH_TOTAL_CHAN_NUM, &s_chan_cfg, &fault_chan) == ESP_ERR_INVALID_ARG);
TEST_ASSERT(touch_sensor_new_channel(touch, 0, &s_chan_cfg, &fault_chan) == ESP_ERR_INVALID_STATE);
TEST_ASSERT(touch_sensor_new_channel(touch, TOUCH_MIN_CHAN_ID, &s_chan_cfg, &fault_chan) == ESP_ERR_INVALID_STATE);
TEST_ESP_OK(touch_sensor_enable(touch));
TEST_ASSERT(touch_sensor_del_channel(touch_chan[0]) == ESP_ERR_INVALID_STATE);
TEST_ASSERT(touch_sensor_del_channel(touch_chan[TOUCH_MIN_CHAN_ID]) == ESP_ERR_INVALID_STATE);
TEST_ESP_OK(touch_sensor_disable(touch));
TEST_ASSERT(touch_sensor_del_controller(touch) == ESP_ERR_INVALID_STATE);
for (int i = 0; i < TOUCH_TOTAL_CHAN_NUM; i++) {
for (int i = TOUCH_MIN_CHAN_ID; i <= TOUCH_MAX_CHAN_ID; i++) {
TEST_ESP_OK(touch_sensor_del_channel(touch_chan[i]));
}
TEST_ESP_OK(touch_sensor_del_controller(touch));
@ -159,7 +159,7 @@ TEST_CASE("touch_sens_active_inactive_test", "[touch]")
/* Configuring the filter */
touch_sensor_filter_config_t filter_cfg = TOUCH_SENSOR_DEFAULT_FILTER_CONFIG();
TEST_ESP_OK(touch_sensor_config_filter(touch, &filter_cfg));
TEST_ESP_OK(touch_sensor_new_channel(touch, 1, &s_chan_cfg, &touch_chan));
TEST_ESP_OK(touch_sensor_new_channel(touch, TOUCH_MIN_CHAN_ID, &s_chan_cfg, &touch_chan));
#if SOC_TOUCH_SENSOR_VERSION == 3
/* Connect the touch channels to the internal capacitor */
touch_ll_enable_internal_capacitor(true);

2
components/esp_hw_support/include/esp_sleep.h
View File

@ -9,7 +9,7 @@
#include <stdint.h>
#include "esp_err.h"
#include "hal/touch_sensor_types.h"
#include "hal/touch_sensor_legacy_types.h"
#include "hal/gpio_types.h"
#include "soc/soc_caps.h"

2
components/hal/esp32/include/hal/touch_sensor_hal.h
View File

@ -15,7 +15,7 @@
#pragma once
#include "hal/touch_sensor_ll.h"
#include "hal/touch_sensor_types.h"
#include "hal/touch_sensor_legacy_types.h"
#include_next "hal/touch_sensor_hal.h"

2
components/hal/esp32/include/hal/touch_sensor_ll.h
View File

@ -21,7 +21,7 @@
#include "soc/sens_struct.h"
#include "soc/rtc_io_struct.h"
#include "soc/rtc_cntl_struct.h"
#include "hal/touch_sensor_types.h"
#include "hal/touch_sensor_legacy_types.h"
#ifdef __cplusplus

2
components/hal/esp32/touch_sensor_hal.c
View File

@ -7,7 +7,7 @@
// The HAL layer for Touch sensor (common part)
#include "hal/touch_sensor_hal.h"
#include "hal/touch_sensor_types.h"
#include "hal/touch_sensor_legacy_types.h"
void touch_hal_init(void)
{

31
components/hal/esp32p4/include/hal/touch_sensor_ll.h
View File

@ -24,7 +24,6 @@
#include "soc/touch_struct.h"
#include "soc/pmu_struct.h"
#include "soc/soc_caps.h"
#include "hal/touch_sensor_types.h"
#include "hal/touch_sens_types.h"
#ifdef __cplusplus
@ -174,17 +173,6 @@ static inline void touch_ll_enable_fsm_timer(bool enable)
LP_ANA_PERI.touch_mux0.touch_start_force = !enable;
}
/**
* Get touch sensor FSM mode.
* The measurement action can be triggered by the hardware timer, as well as by the software instruction.
*
* @param mode FSM mode.
*/
static inline void touch_ll_get_fsm_mode(touch_fsm_mode_t *mode)
{
*mode = (touch_fsm_mode_t)LP_ANA_PERI.touch_mux0.touch_fsm_en;
}
/**
* Is touch sensor FSM using hardware timer to trigger scanning.
* The measurement action can be triggered by the hardware timer, as well as by the software instruction.
@ -254,6 +242,7 @@ static inline void touch_ll_stop_fsm_repeated_timer(void)
* - true: enabled
* - true: disabled
*/
__attribute__((always_inline))
static inline bool touch_ll_is_fsm_repeated_timer_enabled(void)
{
return (bool)(PMU.touch_pwr_cntl.sleep_timer_en);
@ -304,7 +293,7 @@ __attribute__((always_inline))
static inline void touch_ll_enable_scan_mask(uint16_t chan_mask, bool enable)
{
// Channel shift workaround: the lowest bit takes no effect
uint16_t mask = (chan_mask << 1) & TOUCH_PAD_BIT_MASK_ALL;
uint16_t mask = (chan_mask << 1) & TOUCH_LL_FULL_CHANNEL_MASK;
uint16_t prev_mask = LP_ANA_PERI.touch_scan_ctrl1.touch_scan_pad_map;
if (enable) {
LP_ANA_PERI.touch_scan_ctrl1.touch_scan_pad_map = prev_mask | mask;
@ -328,7 +317,7 @@ static inline void touch_ll_enable_scan_mask(uint16_t chan_mask, bool enable)
static inline void touch_ll_enable_channel_mask(uint16_t enable_mask)
{
// Channel shift workaround: the lowest bit takes no effect
uint16_t mask = (enable_mask << 1) & TOUCH_PAD_BIT_MASK_ALL;
uint16_t mask = (enable_mask << 1) & TOUCH_LL_FULL_CHANNEL_MASK;
LP_ANA_PERI.touch_scan_ctrl1.touch_scan_pad_map = mask;
LP_ANA_PERI.touch_filter2.touch_outen = mask;
}
@ -478,7 +467,7 @@ static inline void touch_ll_set_clock_div(uint8_t sample_cfg_id, uint32_t div_nu
*
* @param type Select idle channel connect to high resistance state or ground. (No effect)
*/
static inline void touch_ll_set_idle_channel_connect(touch_pad_conn_type_t type)
static inline void touch_ll_set_idle_channel_connect(touch_idle_conn_t type)
{
(void)type;
}
@ -526,7 +515,7 @@ static inline void touch_ll_interrupt_disable(uint32_t int_mask)
* @param int_mask Pad mask to clear interrupts
*/
__attribute__((always_inline))
static inline void touch_ll_interrupt_clear(touch_pad_intr_mask_t int_mask)
static inline void touch_ll_interrupt_clear(uint32_t int_mask)
{
LP_TOUCH.int_clr.val = int_mask;
}
@ -659,9 +648,9 @@ static inline void touch_ll_reset_chan_benchmark(uint32_t chan_mask)
* Set filter mode. The input of the filter is the raw value of touch reading,
* and the output of the filter is involved in the judgment of the touch state.
*
* @param mode Filter mode type. Refer to ``touch_filter_mode_t``.
* @param mode Filter mode type. Refer to ``touch_benchmark_filter_mode_t``.
*/
static inline void touch_ll_filter_set_filter_mode(touch_filter_mode_t mode)
static inline void touch_ll_filter_set_filter_mode(touch_benchmark_filter_mode_t mode)
{
LP_ANA_PERI.touch_filter1.touch_filter_mode = mode;
}
@ -670,9 +659,9 @@ static inline void touch_ll_filter_set_filter_mode(touch_filter_mode_t mode)
* Set filter mode. The input to the filter is raw data and the output is the smooth data.
* The smooth data is used to determine the touch status.
*
* @param mode Filter mode type. Refer to ``touch_smooth_mode_t``.
* @param mode Filter mode type. Refer to ``touch_smooth_filter_mode_t``.
*/
static inline void touch_ll_filter_set_smooth_mode(touch_smooth_mode_t mode)
static inline void touch_ll_filter_set_smooth_mode(touch_smooth_filter_mode_t mode)
{
LP_ANA_PERI.touch_filter1.touch_smooth_lvl = mode;
}
@ -797,7 +786,7 @@ static inline void touch_ll_waterproof_set_shield_chan_mask(uint32_t mask)
*
* @param driver_level The driver level of the touch buff
*/
static inline void touch_ll_waterproof_set_shield_driver(touch_pad_shield_driver_t driver_level)
static inline void touch_ll_waterproof_set_shield_driver(touch_chan_shield_cap_t driver_level)
{
LP_ANA_PERI.touch_ana_para.touch_touch_buf_drv = driver_level;
}

2
components/hal/esp32s2/include/hal/touch_sensor_hal.h
View File

@ -15,7 +15,7 @@
#pragma once
#include "hal/touch_sensor_ll.h"
#include "hal/touch_sensor_types.h"
#include "hal/touch_sensor_legacy_types.h"
#include_next "hal/touch_sensor_hal.h"

65
components/hal/esp32s2/include/hal/touch_sensor_ll.h
View File

@ -16,6 +16,7 @@
#include <stdlib.h>
#include <stdbool.h>
#include "esp_bit_defs.h"
#include "hal/misc.h"
#include "hal/assert.h"
#include "soc/touch_sensor_periph.h"
@ -23,7 +24,6 @@
#include "soc/sens_struct.h"
#include "soc/rtc_cntl_struct.h"
#include "soc/rtc_io_struct.h"
#include "hal/touch_sensor_types.h"
#include "hal/touch_sens_types.h"
#ifdef __cplusplus
@ -137,7 +137,7 @@ static inline uint32_t touch_ll_get_intr_status_mask(void)
* - touch channel number
*/
__attribute__((always_inline))
static inline uint32_t IRAM_ATTR touch_ll_get_current_meas_channel(void)
static inline uint32_t touch_ll_get_current_meas_channel(void)
{
return SENS.sar_touch_status0.touch_scan_curr;
}
@ -176,7 +176,7 @@ static inline void touch_ll_get_active_channel_mask(uint32_t *active_mask)
__attribute__((always_inline))
static inline void touch_ll_enable_scan_mask(uint16_t chan_mask, bool enable)
{
uint16_t mask = chan_mask & TOUCH_PAD_BIT_MASK_ALL;
uint16_t mask = chan_mask & TOUCH_LL_FULL_CHANNEL_MASK;
uint16_t prev_mask = RTCCNTL.touch_scan_ctrl.touch_scan_pad_map;
if (enable) {
RTCCNTL.touch_scan_ctrl.touch_scan_pad_map = prev_mask | mask;
@ -211,7 +211,6 @@ static inline void touch_ll_set_power_on_wait_cycle(uint32_t wait_cycles)
HAL_FORCE_MODIFY_U32_REG_FIELD(RTCCNTL.touch_ctrl2, touch_xpd_wait, wait_cycles); //wait volt stable
}
// HAL_FORCE_MODIFY_U32_REG_FIELD(RTCCNTL.touch_ctrl1, touch_meas_num, meas_time);
/**
* Set touch sensor touch sensor charge and discharge times of every measurement on a pad.
*
@ -237,27 +236,56 @@ static inline void touch_ll_set_measure_interval_ticks(uint16_t interval_ticks)
HAL_FORCE_MODIFY_U32_REG_FIELD(RTCCNTL.touch_ctrl1, touch_sleep_cycles, interval_ticks);
}
/**
* Set the Touch pad charge speed.
*
* @param touch_num Touch channel number
* @param charge_speed Charge speed of this touch channel
*/
static inline void touch_ll_set_charge_speed(uint32_t touch_num, touch_charge_speed_t charge_speed)
{
RTCIO.touch_pad[touch_num].dac = charge_speed;
}
/**
* Set the upper limitation of the touch channel voltage while charging
*
* @param high_lim The high(upper) limitation of charge
*/
static inline void touch_ll_set_charge_voltage_high_limit(touch_volt_lim_h_t high_lim)
{
RTCCNTL.touch_ctrl2.touch_drefh = (uint32_t)high_lim & 0x3;
RTCCNTL.touch_ctrl2.touch_drange = (uint32_t)high_lim >> 2;
}
/**
* Set the lower limitation of the touch channel voltage while discharging
*
* @param low_lim The lower limitation of discharge
*/
static inline void touch_ll_set_charge_voltage_low_limit(touch_volt_lim_l_t low_lim)
{
RTCCNTL.touch_ctrl2.touch_drefl = low_lim;
}
/**
* Set the initial charge voltage of touch channel
* i.e., the touch pad measurement start from a low voltage or a high voltage
*
* @param touch_num Touch channel number
* @param init_charge_volt The initial charge voltage
*/
static inline void touch_ll_set_init_charge_voltage(uint32_t touch_num, touch_init_charge_volt_t init_charge_volt)
{
RTCIO.touch_pad[touch_num].tie_opt = init_charge_volt;
}
/**
* Set the connection of the idle channel
* The idle channel is the channel that is enabled and powered on but not under measurement.
*
* @param idle_conn
*/
static inline void touch_ll_set_idle_channel_connection(touch_idle_conn_t idle_conn)
{
RTCCNTL.touch_scan_ctrl.touch_inactive_connection = idle_conn;
@ -385,6 +413,7 @@ static inline void touch_ll_stop_fsm_repeated_timer(void)
* - true: enabled
* - false: disabled
*/
__attribute__((always_inline))
static inline bool touch_ll_is_fsm_repeated_timer_enabled(void)
{
return (bool)RTCCNTL.touch_ctrl2.touch_slp_timer_en;
@ -467,9 +496,9 @@ static inline void touch_ll_filter_enable(bool enable)
* Set filter mode. The input of the filter is the raw value of touch reading,
* and the output of the filter is involved in the judgment of the touch state.
*
* @param mode Filter mode type. Refer to ``touch_filter_mode_t``.
* @param mode Filter mode type. Refer to ``touch_benchmark_filter_mode_t``.
*/
static inline void touch_ll_filter_set_filter_mode(touch_filter_mode_t mode)
static inline void touch_ll_filter_set_filter_mode(touch_benchmark_filter_mode_t mode)
{
RTCCNTL.touch_filter_ctrl.touch_filter_mode = mode;
}
@ -490,12 +519,21 @@ static inline void touch_ll_filter_set_jitter_step(uint32_t step)
* Set the denoise coefficient regarding the denoise level.
*
* @param denoise_lvl Range [0 ~ 4]. 0 = no noise resistance, otherwise higher denoise_lvl means more noise resistance.
* 0 = no noise resistance
* 1 = noise resistance is 1/4 benchmark
* 2 = noise resistance is 3/8 benchmark
* 3 = noise resistance is 1/2 benchmark
* 4 = noise resistance is 1 benchmark
*/
static inline void touch_ll_filter_set_denoise_level(int denoise_lvl)
{
HAL_ASSERT(denoise_lvl >= 0 && denoise_lvl <= 4);
bool always_update = denoise_lvl == 0;
// Map denoise level to actual noise threshold coefficients
/* Map denoise level to actual noise threshold coefficients
denoise_lvl=1 -> noise_thresh=2, 1/4 benchmark
denoise_lvl=2 -> noise_thresh=1, 3/8 benchmark
denoise_lvl=3 -> noise_thresh=0, 1/2 benchmark
denoise_lvl=4 -> noise_thresh=3, 1 benchmark */
uint32_t noise_thresh = denoise_lvl == 4 ? 3 : 3 - denoise_lvl;
RTCCNTL.touch_filter_ctrl.touch_noise_thres = always_update ? 0 : noise_thresh;
@ -519,9 +557,9 @@ static inline void touch_ll_filter_set_active_hysteresis(uint32_t hysteresis)
* Set filter mode. The input to the filter is raw data and the output is the smooth data.
* The smooth data is used to determine the touch status.
*
* @param mode Filter mode type. Refer to ``touch_smooth_mode_t``.
* @param mode Filter mode type. Refer to ``touch_smooth_filter_mode_t``.
*/
static inline void touch_ll_filter_set_smooth_mode(touch_smooth_mode_t mode)
static inline void touch_ll_filter_set_smooth_mode(touch_smooth_filter_mode_t mode)
{
RTCCNTL.touch_filter_ctrl.touch_smooth_lvl = mode;
}
@ -599,9 +637,9 @@ static inline void touch_ll_waterproof_set_guard_chan(uint32_t pad_num)
* The equivalent capacitance of the shielded channel can be calculated
* from the reading of denoise channel.
*
* @param pad_num Touch sensor channel number.
* @param pad_num Touch sensor channel number. Refer to ``touch_chan_shield_cap_t``
*/
static inline void touch_ll_waterproof_set_shield_driver(touch_pad_shield_driver_t driver_level)
static inline void touch_ll_waterproof_set_shield_driver(touch_chan_shield_cap_t driver_level)
{
RTCCNTL.touch_scan_ctrl.touch_bufdrv = driver_level;
}
@ -707,7 +745,7 @@ static inline void touch_ll_denoise_set_reference_cap(touch_denoise_chan_cap_t c
*
* @param resolution Denoise resolution of denoise channel.
*/
static inline void touch_ll_denoise_set_resolution(touch_denoise_chan_res_t resolution)
static inline void touch_ll_denoise_set_resolution(touch_denoise_chan_resolution_t resolution)
{
RTCCNTL.touch_scan_ctrl.touch_denoise_res = resolution;
}
@ -723,8 +761,9 @@ static inline void touch_ll_denoise_read_data(uint32_t *data)
}
/******************************************************************************/
/* Legacy APIs */
/* Legacy APIs (to be removed in esp-idf v6.0) */
/******************************************************************************/
#include "hal/touch_sensor_legacy_types.h"
/**
* Set touch sensor touch sensor times of charge and discharge.
*

2
components/hal/esp32s2/touch_sensor_hal.c
View File

@ -9,7 +9,7 @@
#include "soc/soc_pins.h"
#include "soc/touch_sensor_pins.h"
#include "hal/touch_sensor_hal.h"
#include "hal/touch_sensor_types.h"
#include "hal/touch_sensor_legacy_types.h"
static int s_sleep_cycle = -1;
static int s_meas_times = -1;

2
components/hal/esp32s3/include/hal/touch_sensor_hal.h
View File

@ -15,7 +15,7 @@
#pragma once
#include "hal/touch_sensor_ll.h"
#include "hal/touch_sensor_types.h"
#include "hal/touch_sensor_legacy_types.h"
#include_next "hal/touch_sensor_hal.h"

65
components/hal/esp32s3/include/hal/touch_sensor_ll.h
View File

@ -16,6 +16,7 @@
#include <stdlib.h>
#include <stdbool.h>
#include "esp_bit_defs.h"
#include "hal/misc.h"
#include "hal/assert.h"
#include "soc/touch_sensor_periph.h"
@ -23,7 +24,6 @@
#include "soc/rtc_io_struct.h"
#include "soc/sens_struct.h"
#include "soc/soc_caps.h"
#include "hal/touch_sensor_types.h"
#include "hal/touch_sens_types.h"
#ifdef __cplusplus
@ -132,7 +132,7 @@ static inline uint32_t touch_ll_get_intr_status_mask(void)
* - touch channel number
*/
__attribute__((always_inline))
static inline uint32_t IRAM_ATTR touch_ll_get_current_meas_channel(void)
static inline uint32_t touch_ll_get_current_meas_channel(void)
{
return SENS.sar_touch_status0.touch_scan_curr;
}
@ -171,7 +171,7 @@ static inline void touch_ll_get_active_channel_mask(uint32_t *active_mask)
__attribute__((always_inline))
static inline void touch_ll_enable_scan_mask(uint16_t chan_mask, bool enable)
{
uint16_t mask = chan_mask & TOUCH_PAD_BIT_MASK_ALL;
uint16_t mask = chan_mask & TOUCH_LL_FULL_CHANNEL_MASK;
uint16_t prev_mask = RTCCNTL.touch_scan_ctrl.touch_scan_pad_map;
if (enable) {
RTCCNTL.touch_scan_ctrl.touch_scan_pad_map = prev_mask | mask;
@ -206,7 +206,6 @@ static inline void touch_ll_set_power_on_wait_cycle(uint32_t wait_cycles)
HAL_FORCE_MODIFY_U32_REG_FIELD(RTCCNTL.touch_ctrl2, touch_xpd_wait, wait_cycles); //wait volt stable
}
// HAL_FORCE_MODIFY_U32_REG_FIELD(RTCCNTL.touch_ctrl1, touch_meas_num, meas_time);
/**
* Set touch sensor touch sensor charge and discharge times of every measurement on a pad.
*
@ -232,6 +231,12 @@ static inline void touch_ll_set_measure_interval_ticks(uint16_t interval_ticks)
HAL_FORCE_MODIFY_U32_REG_FIELD(RTCCNTL.touch_ctrl1, touch_sleep_cycles, interval_ticks);
}
/**
* Set the Touch pad charge speed.
*
* @param touch_num Touch channel number
* @param charge_speed Charge speed of this touch channel
*/
static inline void touch_ll_set_charge_speed(uint32_t touch_num, touch_charge_speed_t charge_speed)
{
#define CHARGE_SPEED_MASK(val, num) ((val) << (29 - (num) * 3))
@ -248,22 +253,45 @@ static inline void touch_ll_set_charge_speed(uint32_t touch_num, touch_charge_sp
#undef CHARGE_SPEED_MASK
}
/**
* Set the upper limitation of the touch channel voltage while charging
*
* @param high_lim The high(upper) limitation of charge
*/
static inline void touch_ll_set_charge_voltage_high_limit(touch_volt_lim_h_t high_lim)
{
RTCCNTL.touch_ctrl2.touch_drefh = (uint32_t)high_lim & 0x3;
RTCCNTL.touch_ctrl2.touch_drange = (uint32_t)high_lim >> 2;
}
/**
* Set the lower limitation of the touch channel voltage while discharging
*
* @param low_lim The lower limitation of discharge
*/
static inline void touch_ll_set_charge_voltage_low_limit(touch_volt_lim_l_t low_lim)
{
RTCCNTL.touch_ctrl2.touch_drefl = low_lim;
}
/**
* Set the initial charge voltage of touch channel
* i.e., the touch pad measurement start from a low voltage or a high voltage
*
* @param touch_num Touch channel number
* @param init_charge_volt The initial charge voltage
*/
static inline void touch_ll_set_init_charge_voltage(uint32_t touch_num, touch_init_charge_volt_t init_charge_volt)
{
RTCIO.touch_pad[touch_num].tie_opt = init_charge_volt;
}
/**
* Set the connection of the idle channel
* The idle channel is the channel that is enabled and powered on but not under measurement.
*
* @param idle_conn
*/
static inline void touch_ll_set_idle_channel_connection(touch_idle_conn_t idle_conn)
{
RTCCNTL.touch_scan_ctrl.touch_inactive_connection = idle_conn;
@ -392,6 +420,7 @@ static inline void touch_ll_stop_fsm_repeated_timer(void)
* - true: enabled
* - false: disabled
*/
__attribute__((always_inline))
static inline bool touch_ll_is_fsm_repeated_timer_enabled(void)
{
return (bool)RTCCNTL.touch_ctrl2.touch_slp_timer_en;
@ -474,9 +503,9 @@ static inline void touch_ll_filter_enable(bool enable)
* Set filter mode. The input of the filter is the raw value of touch reading,
* and the output of the filter is involved in the judgment of the touch state.
*
* @param mode Filter mode type. Refer to ``touch_filter_mode_t``.
* @param mode Filter mode type. Refer to ``touch_benchmark_filter_mode_t``.
*/
static inline void touch_ll_filter_set_filter_mode(touch_filter_mode_t mode)
static inline void touch_ll_filter_set_filter_mode(touch_benchmark_filter_mode_t mode)
{
RTCCNTL.touch_filter_ctrl.touch_filter_mode = mode;
}
@ -497,12 +526,21 @@ static inline void touch_ll_filter_set_jitter_step(uint32_t step)
* Set the denoise coefficient regarding the denoise level.
*
* @param denoise_lvl Range [0 ~ 4]. 0 = no noise resistance, otherwise higher denoise_lvl means more noise resistance.
* 0 = no noise resistance
* 1 = noise resistance is 1/4 benchmark
* 2 = noise resistance is 3/8 benchmark
* 3 = noise resistance is 1/2 benchmark
* 4 = noise resistance is 1 benchmark
*/
static inline void touch_ll_filter_set_denoise_level(int denoise_lvl)
{
HAL_ASSERT(denoise_lvl >= 0 && denoise_lvl <= 4);
bool always_update = denoise_lvl == 0;
// Map denoise level to actual noise threshold coefficients
/* Map denoise level to actual noise threshold coefficients
denoise_lvl=1 -> noise_thresh=2, 1/4 benchmark
denoise_lvl=2 -> noise_thresh=1, 3/8 benchmark
denoise_lvl=3 -> noise_thresh=0, 1/2 benchmark
denoise_lvl=4 -> noise_thresh=3, 1 benchmark */
uint32_t noise_thresh = denoise_lvl == 4 ? 3 : 3 - denoise_lvl;
RTCCNTL.touch_filter_ctrl.touch_bypass_noise_thres = always_update;
@ -529,9 +567,9 @@ static inline void touch_ll_filter_set_active_hysteresis(uint32_t hysteresis)
* Set filter mode. The input to the filter is raw data and the output is the smooth data.
* The smooth data is used to determine the touch status.
*
* @param mode Filter mode type. Refer to ``touch_smooth_mode_t``.
* @param mode Filter mode type. Refer to ``touch_smooth_filter_mode_t``.
*/
static inline void touch_ll_filter_set_smooth_mode(touch_smooth_mode_t mode)
static inline void touch_ll_filter_set_smooth_mode(touch_smooth_filter_mode_t mode)
{
RTCCNTL.touch_filter_ctrl.touch_smooth_lvl = mode;
}
@ -609,9 +647,9 @@ static inline void touch_ll_waterproof_set_guard_chan(uint32_t pad_num)
* The equivalent capacitance of the shielded channel can be calculated
* from the reading of denoise channel.
*
* @param pad_num Touch sensor channel number.
* @param pad_num Touch sensor channel number. Refer to ``touch_chan_shield_cap_t``
*/
static inline void touch_ll_waterproof_set_shield_driver(touch_pad_shield_driver_t driver_level)
static inline void touch_ll_waterproof_set_shield_driver(touch_chan_shield_cap_t driver_level)
{
RTCCNTL.touch_scan_ctrl.touch_bufdrv = driver_level;
}
@ -717,7 +755,7 @@ static inline void touch_ll_denoise_set_reference_cap(touch_denoise_chan_cap_t c
*
* @param resolution Denoise resolution of denoise channel.
*/
static inline void touch_ll_denoise_set_resolution(touch_denoise_chan_res_t resolution)
static inline void touch_ll_denoise_set_resolution(touch_denoise_chan_resolution_t resolution)
{
RTCCNTL.touch_scan_ctrl.touch_denoise_res = resolution;
}
@ -733,8 +771,9 @@ static inline void touch_ll_denoise_read_data(uint32_t *data)
}
/******************************************************************************/
/* Legacy APIs */
/* Legacy APIs (to be removed in esp-idf v6.0) */
/******************************************************************************/
#include "hal/touch_sensor_legacy_types.h"
/**
* Set touch sensor touch sensor times of charge and discharge.
*

2
components/hal/esp32s3/touch_sensor_hal.c
View File

@ -9,7 +9,7 @@
#include "soc/soc_pins.h"
#include "hal/touch_sensor_hal.h"
#include "hal/touch_sensor_ll.h"
#include "hal/touch_sensor_types.h"
#include "hal/touch_sensor_legacy_types.h"
#include "soc/soc_caps.h"
static int s_sleep_cycle = -1;

44
components/hal/include/hal/touch_sens_hal.h
View File

@ -25,21 +25,33 @@ extern "C" {
#if SOC_TOUCH_SENSOR_VERSION > 1
#if SOC_TOUCH_SENSOR_VERSION == 2
/**
* @brief Sample configurations of the touch sensor
*
* @brief Sample configurations of the touch sensor V2
*/
typedef struct {
#if SOC_TOUCH_SENSOR_VERSION == 2 // S2/S3
uint32_t charge_times; /*!< The charge and discharge times of this sample configuration, the read data are positive correlation to the charge_times */
touch_volt_lim_h_t charge_volt_lim_h; /*!< The upper voltage limit while charging a touch pad */
touch_volt_lim_l_t charge_volt_lim_l; /*!< The lower voltage limit while charging a touch pad */
touch_idle_conn_t idle_conn; /*!< The connection of the idle touch channels.
* The idle touch channel is a channel which is enabled but not under measuring.
*/
touch_bias_type_t bias_type;
#elif SOC_TOUCH_SENSOR_VERSION == 3 // P4
uint32_t div_num; /*!< The division from the source clock to the sampling frequency */
uint32_t charge_times; /*!< The charge and discharge times of this sample configuration, the read data are positive correlation to the charge_times */
touch_volt_lim_h_t charge_volt_lim_h; /*!< The upper voltage limit while charging a touch pad. i.e., the touch controller won't charge the touch pad higher than this high voltage limitation. */
touch_volt_lim_l_t charge_volt_lim_l; /*!< The lower voltage limit while discharging a touch pad. i.e., the touch controller won't discharge the touch pad lower than this low voltage limitation. */
touch_idle_conn_t idle_conn; /*!< The connection of the idle touch channels.
* The idle touch channel is a channel which is enabled and power-on but not under measuring.
*/
touch_bias_type_t bias_type; /*!< The type of the touch sensor bias. Which affects the charge/discharge stability and power consumption */
} touch_hal_sample_config_v2_t;
/**
* @brief Alias of touch_hal_sample_config_v2_t for compatibility
*/
typedef touch_hal_sample_config_v2_t touch_hal_sample_config_t;
#elif SOC_TOUCH_SENSOR_VERSION == 3
/**
* @brief Sample configurations of the touch sensor V3
*/
typedef struct {
uint32_t div_num; /*!< The division of the touch output signal. It is proportional to the gain of the read data */
uint32_t charge_times; /*!< The charge and discharge times of the sample configuration, the read data are positive correlation to the charge_times */
uint8_t rc_filter_res; /*!< The resistance of the RC filter of the sample configuration, range [0, 3], while 0 = 0K, 1 = 1.5K, 2 = 3K, 3 = 4.5K */
uint8_t rc_filter_cap; /*!< The capacitance of the RC filter of the sample configuration, range [0, 127], while 0 = 0pF, 1 = 20fF, ..., 127 = 2.54pF */
@ -47,10 +59,16 @@ typedef struct {
uint8_t high_drv; /*!< High speed touch driver */
uint8_t bias_volt; /*!< The Internal LDO voltage, which decide the bias voltage of the sample wave, range [0,15] */
bool bypass_shield_output; /*!< Whether to bypass the shield output */
} touch_hal_sample_config_v3_t;
/**
* @brief Alias of touch_hal_sample_config_v3_t for compatibility
*/
typedef touch_hal_sample_config_v3_t touch_hal_sample_config_t;
#else
#error "Unsupported touch sensor version"
#endif
} touch_hal_sample_config_t;
/**
* @brief Configurations of the touch sensor controller

92
components/hal/include/hal/touch_sens_types.h
View File

@ -1,18 +1,60 @@
/*
* SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
#pragma once
#include "esp_bit_defs.h"
#include "soc/soc_caps.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Touch sensor shield channel drive capability level
*
*/
typedef enum {
TOUCH_SHIELD_CAP_40PF, /*!< The max equivalent capacitance in shield channel is 40pf */
TOUCH_SHIELD_CAP_80PF, /*!< The max equivalent capacitance in shield channel is 80pf */
TOUCH_SHIELD_CAP_120PF, /*!< The max equivalent capacitance in shield channel is 120pf */
TOUCH_SHIELD_CAP_160PF, /*!< The max equivalent capacitance in shield channel is 160pf */
TOUCH_SHIELD_CAP_200PF, /*!< The max equivalent capacitance in shield channel is 200pf */
TOUCH_SHIELD_CAP_240PF, /*!< The max equivalent capacitance in shield channel is 240pf */
TOUCH_SHIELD_CAP_280PF, /*!< The max equivalent capacitance in shield channel is 280pf */
TOUCH_SHIELD_CAP_320PF, /*!< The max equivalent capacitance in shield channel is 320pf */
} touch_chan_shield_cap_t;
/**
* @brief Touch channel Infinite Impulse Response (IIR) filter or Jitter filter for benchmark
* @note Recommended filter coefficient selection is `IIR_16`.
*/
typedef enum {
TOUCH_BM_IIR_FILTER_4, /*!< IIR Filter for benchmark, 1/4 raw_value + 3/4 benchmark */
TOUCH_BM_IIR_FILTER_8, /*!< IIR Filter for benchmark, 1/8 raw_value + 7/8 benchmark */
TOUCH_BM_IIR_FILTER_16, /*!< IIR Filter for benchmark, 1/16 raw_value + 15/16 benchmark (typical) */
TOUCH_BM_IIR_FILTER_32, /*!< IIR Filter for benchmark, 1/32 raw_value + 31/32 benchmark */
TOUCH_BM_IIR_FILTER_64, /*!< IIR Filter for benchmark, 1/64 raw_value + 63/64 benchmark */
TOUCH_BM_IIR_FILTER_128, /*!< IIR Filter for benchmark, 1/128 raw_value + 127/128 benchmark */
#if SOC_TOUCH_SENSOR_VERSION == 2
TOUCH_BM_IIR_FILTER_256, /*!< IIR Filter for benchmark, 1/256 raw_value + 255/256 benchmark */
#endif
TOUCH_BM_JITTER_FILTER, /*!< Jitter Filter for benchmark, raw value +/- jitter_step */
} touch_benchmark_filter_mode_t;
/**
* @brief Touch channel Infinite Impulse Response (IIR) filter for smooth data
*
*/
typedef enum {
TOUCH_SMOOTH_NO_FILTER, /*!< No filter adopted for smooth data, smooth data equals raw data */
TOUCH_SMOOTH_IIR_FILTER_2, /*!< IIR filter adopted for smooth data, smooth data equals 1/2 raw data + 1/2 last smooth data (typical) */
TOUCH_SMOOTH_IIR_FILTER_4, /*!< IIR filter adopted for smooth data, smooth data equals 1/4 raw data + 3/4 last smooth data */
TOUCH_SMOOTH_IIR_FILTER_8, /*!< IIR filter adopted for smooth data, smooth data equals 1/8 raw data + 7/8 last smooth data */
} touch_smooth_filter_mode_t;
/**
* @brief Touch sensor upper charging voltage limit
*/
@ -42,10 +84,10 @@ typedef enum {
* @brief Touch sensor lower discharging voltage limit
*/
typedef enum {
TOUCH_VOLT_LIM_L_0V5, /*!< Touch sensor lower voltage limit is 0.5V while charging a touch pad */
TOUCH_VOLT_LIM_L_0V6, /*!< Touch sensor lower voltage limit is 0.5V while charging a touch pad */
TOUCH_VOLT_LIM_L_0V7, /*!< Touch sensor lower voltage limit is 0.5V while charging a touch pad */
TOUCH_VOLT_LIM_L_0V8, /*!< Touch sensor lower voltage limit is 0.5V while charging a touch pad */
TOUCH_VOLT_LIM_L_0V5, /*!< Touch sensor lower voltage limit is 0.5V while discharging a touch pad */
TOUCH_VOLT_LIM_L_0V6, /*!< Touch sensor lower voltage limit is 0.6V while discharging a touch pad */
TOUCH_VOLT_LIM_L_0V7, /*!< Touch sensor lower voltage limit is 0.7V while discharging a touch pad */
TOUCH_VOLT_LIM_L_0V8, /*!< Touch sensor lower voltage limit is 0.8V while discharging a touch pad */
} touch_volt_lim_l_t;
/**
@ -70,41 +112,40 @@ typedef enum {
TOUCH_INIT_CHARGE_VOLT_HIGH = 1,/*!< Tie the initial charge voltage to high */
} touch_init_charge_volt_t;
/** Touch channel idle state configuration */
/**
* @brief Touch channel idle state configuration
*/
typedef enum {
TOUCH_IDLE_CONN_HIGHZ = 0, /*!< The idle (enabled but not measuring) touch channel is in high resistance state */
TOUCH_IDLE_CONN_HIGHZ = 0, /*!< The idle (enabled but not measuring) touch channel is at high resistance state */
TOUCH_IDLE_CONN_GND = 1, /*!< The idle (enabled but not measuring) touch channel is connected to the ground */
} touch_idle_conn_t;
/**
* @brief Touch sensor denoise channel internal reference capacitance
*
*/
typedef enum {
TOUCH_DENOISE_CHAN_CAP_L0 = 0, /*!< Denoise channel internal reference capacitance is 5pf */
TOUCH_DENOISE_CHAN_CAP_L1 = 1, /*!< Denoise channel internal reference capacitance is 6.4pf */
TOUCH_DENOISE_CHAN_CAP_L2 = 2, /*!< Denoise channel internal reference capacitance is 7.8pf */
TOUCH_DENOISE_CHAN_CAP_L3 = 3, /*!< Denoise channel internal reference capacitance is 9.2pf */
TOUCH_DENOISE_CHAN_CAP_L4 = 4, /*!< Denoise channel internal reference capacitance is 10.6pf */
TOUCH_DENOISE_CHAN_CAP_L5 = 5, /*!< Denoise channel internal reference capacitance is 12.0pf */
TOUCH_DENOISE_CHAN_CAP_L6 = 6, /*!< Denoise channel internal reference capacitance is 13.4pf */
TOUCH_DENOISE_CHAN_CAP_L7 = 7, /*!< Denoise channel internal reference capacitance is 14.8pf */
TOUCH_DENOISE_CHAN_CAP_5PF = 0, /*!< Denoise channel internal reference capacitance is 5.0pf */
TOUCH_DENOISE_CHAN_CAP_6PF = 1, /*!< Denoise channel internal reference capacitance is 6.4pf */
TOUCH_DENOISE_CHAN_CAP_7PF = 2, /*!< Denoise channel internal reference capacitance is 7.8pf */
TOUCH_DENOISE_CHAN_CAP_9PF = 3, /*!< Denoise channel internal reference capacitance is 9.2pf */
TOUCH_DENOISE_CHAN_CAP_10PF = 4, /*!< Denoise channel internal reference capacitance is 10.6pf */
TOUCH_DENOISE_CHAN_CAP_12PF = 5, /*!< Denoise channel internal reference capacitance is 12.0pf */
TOUCH_DENOISE_CHAN_CAP_13PF = 6, /*!< Denoise channel internal reference capacitance is 13.4pf */
TOUCH_DENOISE_CHAN_CAP_14PF = 7, /*!< Denoise channel internal reference capacitance is 14.8pf */
} touch_denoise_chan_cap_t;
/**
* @brief Touch sensor denoise channel noise suppression resolution
*
*/
typedef enum {
TOUCH_DENOISE_CHAN_RES_BIT12 = 0, /*!< Denoise channel noise suppression resolution is 12bit */
TOUCH_DENOISE_CHAN_RES_BIT10 = 1, /*!< Denoise channel noise suppression resolution is 10bit */
TOUCH_DENOISE_CHAN_RES_BIT8 = 2, /*!< Denoise channel noise suppression resolution is 8bit */
TOUCH_DENOISE_CHAN_RES_BIT4 = 3, /*!< Denoise channel noise suppression resolution is 4bit */
} touch_denoise_chan_res_t;
TOUCH_DENOISE_CHAN_RESOLUTION_BIT12 = 0, /*!< Denoise channel noise suppression resolution is 12bit */
TOUCH_DENOISE_CHAN_RESOLUTION_BIT10 = 1, /*!< Denoise channel noise suppression resolution is 10bit */
TOUCH_DENOISE_CHAN_RESOLUTION_BIT8 = 2, /*!< Denoise channel noise suppression resolution is 8bit */
TOUCH_DENOISE_CHAN_RESOLUTION_BIT4 = 3, /*!< Denoise channel noise suppression resolution is 4bit */
} touch_denoise_chan_resolution_t;
/**
* @brief Touch sensor bias type
*
*/
typedef enum {
TOUCH_BIAS_TYPE_BANDGAP, /*!< Use bandgap-bias to charge/discharge the touch channel, which is more stable but power-consuming */
@ -112,8 +153,7 @@ typedef enum {
} touch_bias_type_t;
/**
* @brief Touch channel counting mode of the binarized touch output
*
* @brief Touch channel binarized output counting mode
*/
typedef enum {
TOUCH_PAD_OUT_AS_DATA, /*!< Counting the output of touch channel as data.

4
components/hal/include/hal/touch_sensor_hal.h
View File

@ -10,14 +10,14 @@
* See readme.md in hal/include/hal/readme.md
******************************************************************************/
// The HAL layer for touch sensor (common part)
// The legacy HAL layer for touch sensor (common part)
#pragma once
#include "soc/soc_caps.h"
#if SOC_TOUCH_SENSOR_SUPPORTED
#include "hal/touch_sensor_ll.h"
#include "hal/touch_sensor_types.h"
#include "hal/touch_sensor_legacy_types.h"
#endif
#ifdef __cplusplus

0
components/hal/include/hal/touch_sensor_types.h → components/hal/include/hal/touch_sensor_legacy_types.h
View File

4
components/hal/touch_sens_hal.c
View File

@ -73,8 +73,8 @@ static void s_touch_hal_apply_sleep_config(void)
}
/* Whether to enable touch sensor wake-up the chip from deep sleep */
if (s_touch_slp_obj.deep_slp_chan >= 0) {
// touch_ll_sleep_set_channel_num(s_touch_slp_obj.deep_slp_chan);
// touch_ll_enable_channel_mask(BIT(s_touch_slp_obj.deep_slp_chan));
touch_ll_sleep_set_channel_num(s_touch_slp_obj.deep_slp_chan);
touch_ll_enable_channel_mask(BIT(s_touch_slp_obj.deep_slp_chan));
} else {
touch_ll_sleep_set_channel_num(TOUCH_LL_NULL_CHANNEL);
}

2
components/hal/touch_sensor_hal.c
View File

@ -7,7 +7,7 @@
// The HAL layer for Touch Sensor (common part)
#include "hal/touch_sensor_hal.h"
#include "hal/touch_sensor_types.h"
#include "hal/touch_sensor_legacy_types.h"
#include "soc/soc_caps.h"
void touch_hal_config(touch_pad_t touch_num)

10
components/soc/esp32s3/register/soc/rtc_cntl_reg.h
View File

@ -3061,12 +3061,12 @@ ork.*/
#define RTC_CNTL_TOUCH_BYPASS_NOISE_THRES_M (BIT(8))
#define RTC_CNTL_TOUCH_BYPASS_NOISE_THRES_V 0x1
#define RTC_CNTL_TOUCH_BYPASS_NOISE_THRES_S 8
/* RTC_CNTL_TOUCH_BYPASS_NEG_THRES : R/W ;bitpos:[7] ;default: 1'b0 ; */
/* RTC_CNTL_TOUCH_BYPASS_NN_THRES : R/W ;bitpos:[7] ;default: 1'b0 ; */
/*description: */
#define RTC_CNTL_TOUCH_BYPASS_NEG_THRES (BIT(7))
#define RTC_CNTL_TOUCH_BYPASS_NEG_THRES_M (BIT(7))
#define RTC_CNTL_TOUCH_BYPASS_NEG_THRES_V 0x1
#define RTC_CNTL_TOUCH_BYPASS_NEG_THRES_S 7
#define RTC_CNTL_TOUCH_BYPASS_NN_THRES (BIT(7))
#define RTC_CNTL_TOUCH_BYPASS_NN_THRES_M (BIT(7))
#define RTC_CNTL_TOUCH_BYPASS_NN_THRES_V 0x1
#define RTC_CNTL_TOUCH_BYPASS_NN_THRES_S 7
#define RTC_CNTL_USB_CONF_REG (DR_REG_RTCCNTL_BASE + 0x120)
/* RTC_CNTL_SW_HW_USB_PHY_SEL : R/W ;bitpos:[20] ;default: 1'b0 ; */

2
components/ulp/ulp_riscv/ulp_core/include/ulp_riscv_touch_ulp_core.h
View File

@ -8,7 +8,7 @@
#include "esp_err.h"
#include "ulp_riscv_register_ops.h"
#include "hal/touch_sensor_types.h"
#include "hal/touch_sensor_legacy_types.h"
#ifdef __cplusplus
extern "C" {

4
docs/conf_common.py
View File

@ -207,7 +207,7 @@ ESP32S2_DOCS = ['hw-reference/esp32s2/**',
'api-reference/peripherals/ds.rst',
'api-reference/peripherals/temp_sensor.rst',
'api-reference/system/async_memcpy.rst',
'api-reference/peripherals/touch_pad.rst',
'api-reference/peripherals/cap_touch_sens.rst',
'api-reference/peripherals/touch_element.rst',
'api-guides/RF_calibration.rst',
'api-guides/phy.rst'] + FTDI_JTAG_DOCS + USB_OTG_DFU_DOCS + USB_OTG_CONSOLE_DOCS
@ -215,7 +215,7 @@ ESP32S2_DOCS = ['hw-reference/esp32s2/**',
ESP32S3_DOCS = ['hw-reference/esp32s3/**',
'api-reference/system/ipc.rst',
'api-guides/flash_psram_config.rst',
'api-reference/peripherals/touch_pad.rst',
'api-reference/peripherals/cap_touch_sens.rst',
'api-reference/peripherals/sd_pullup_requirements.rst',
'api-guides/RF_calibration.rst',
'api-guides/phy.rst'] + USB_OTG_DFU_DOCS + USB_OTG_CONSOLE_DOCS + QEMU_DOCS

2
docs/docs_not_updated/esp32p4.txt
View File

@ -6,8 +6,6 @@ api-guides/usb-otg-console.rst
api-guides/esp-wifi-mesh.rst
api-guides/dfu.rst
api-guides/wifi-security.rst
api-reference/peripherals/touch_element.rst
api-reference/peripherals/touch_pad.rst
api-reference/peripherals/adc_calibration.rst
api-reference/peripherals/parlio.rst
api-reference/peripherals/sd_pullup_requirements.rst

1
docs/doxygen/Doxyfile
View File

@ -261,7 +261,6 @@ INPUT = \
$(PROJECT_PATH)/components/hal/include/hal/spi_types.h \
$(PROJECT_PATH)/components/hal/include/hal/temperature_sensor_types.h \
$(PROJECT_PATH)/components/hal/include/hal/timer_types.h \
$(PROJECT_PATH)/components/hal/include/hal/touch_sensor_types.h \
$(PROJECT_PATH)/components/hal/include/hal/twai_types.h \
$(PROJECT_PATH)/components/hal/include/hal/uart_types.h \
$(PROJECT_PATH)/components/hal/include/hal/efuse_hal.h \

1
docs/doxygen/Doxyfile_esp32
View File

@ -1,5 +1,6 @@
INPUT += \
$(PROJECT_PATH)/components/driver/touch_sensor/$(IDF_TARGET)/include/driver/touch_sensor.h \
$(PROJECT_PATH)/components/hal/include/hal/touch_sensor_legacy_types.h \
$(PROJECT_PATH)/components/esp_psram/include/esp32/himem.h \
$(PROJECT_PATH)/components/soc/$(IDF_TARGET)/include/soc/dac_channel.h \
$(PROJECT_PATH)/components/soc/$(IDF_TARGET)/include/soc/rtc_io_channel.h \

5
docs/doxygen/Doxyfile_esp32s2
View File

@ -1,8 +1,9 @@
INPUT += \
$(PROJECT_PATH)/components/driver/touch_sensor/$(IDF_TARGET)/include/driver/touch_sensor.h \
$(PROJECT_PATH)/components/esp_driver_touch_sens/include/driver/touch_sens.h \
$(PROJECT_PATH)/components/esp_driver_touch_sens/include/driver/touch_sens_types.h \
$(PROJECT_PATH)/components/esp_driver_touch_sens/hw_ver2/include/driver/touch_version_types.h \
$(PROJECT_PATH)/components/soc/$(IDF_TARGET)/include/soc/dac_channel.h \
$(PROJECT_PATH)/components/soc/$(IDF_TARGET)/include/soc/rtc_io_channel.h \
$(PROJECT_PATH)/components/soc/$(IDF_TARGET)/include/soc/touch_sensor_channel.h \
$(PROJECT_PATH)/components/ulp/ulp_fsm/include/$(IDF_TARGET)/ulp.h \
$(PROJECT_PATH)/components/touch_element/include/touch_element/touch_button.h \
$(PROJECT_PATH)/components/touch_element/include/touch_element/touch_element.h \

5
docs/doxygen/Doxyfile_esp32s3
View File

@ -1,7 +1,8 @@
INPUT += \
$(PROJECT_PATH)/components/driver/touch_sensor/$(IDF_TARGET)/include/driver/touch_sensor.h \
$(PROJECT_PATH)/components/esp_driver_touch_sens/include/driver/touch_sens.h \
$(PROJECT_PATH)/components/esp_driver_touch_sens/include/driver/touch_sens_types.h \
$(PROJECT_PATH)/components/esp_driver_touch_sens/hw_ver2/include/driver/touch_version_types.h \
$(PROJECT_PATH)/components/esp_lcd/rgb/include/esp_lcd_panel_rgb.h \
$(PROJECT_PATH)/components/soc/$(IDF_TARGET)/include/soc/touch_sensor_channel.h \
$(PROJECT_PATH)/components/ulp/ulp_fsm/include/$(IDF_TARGET)/ulp.h \
$(PROJECT_PATH)/components/touch_element/include/touch_element/touch_button.h \
$(PROJECT_PATH)/components/touch_element/include/touch_element/touch_element.h \

102
docs/en/api-reference/peripherals/cap_touch_sens.rst
View File

@ -3,7 +3,7 @@ Capacitive Touch Sensor
:link_to_translation:`zh_CN:[中文]`
{IDF_TARGET_TOUCH_SENSOR_VERSION:default="NOT_UPDATED", esp32p4="v3"}
{IDF_TARGET_TOUCH_SENSOR_VERSION:default="NOT_UPDATED", esp32s2="v2", esp32s3="v2", esp32p4="v3"}
Introduction
---------------
@ -35,59 +35,9 @@ Overview of Capacitive Touch Sensor Versions
Overview of Touch Sensor Channels
------------------------------------
.. only:: esp32p4
.. list-table::
:header-rows: 1
:widths: 20 20
* - Channel
- GPIO
* - CH0
- IO2
* - CH1
- IO3
* - CH2
- IO4
* - CH3
- IO5
* - CH4
- IO6
* - CH5
- IO7
* - CH6
- IO8
* - CH7
- IO9
* - CH8
- IO10
* - CH9
- IO11
* - CH10
- IO12
* - CH11
- IO13
* - CH12
- IO14
* - CH13
- IO15
* - CH14
- Internal
.. include:: cap_touch_sens/{IDF_TARGET_PATH_NAME}.inc
:start-after: touch-chan-mapping
:end-before: ---
Terminology in the Driver
----------------------------
@ -148,6 +98,7 @@ Categorized by functionality, the APIs of Capacitive Touch Sensor mainly include
:SOC_TOUCH_SUPPORT_WATERPROOF: - `Waterproof Configuration <#touch-waterproof>`__
:SOC_TOUCH_SUPPORT_PROX_SENSING: - `Proximity Sensing Configuration <#touch-prox-sensing>`__
:SOC_TOUCH_SUPPORT_SLEEP_WAKEUP: - `Sleep Wake-up Configuration <#touch-sleep-wakeup>`__
:SOC_TOUCH_SUPPORT_DENOISE_CHAN: - `Denoise Channel Configuration <#touch-denoise-chan>`__
.. _touch-ctrl:
@ -385,7 +336,13 @@ Call :cpp:func:`touch_channel_read_data` to read the data with different types.
The {IDF_TARGET_NAME} supports proximity sensing. Proximity sensing can be registered by calling :cpp:func:`touch_sensor_config_proximity_sensing` and specify the configurations :cpp:type:`touch_proximity_config_t`.
Since the capacitance change caused by proximity sensing is far less than that caused by physical touch, large area of copper foil is often used on PCB to increase the sensing area. In addition, multiple rounds of scans are needed and the result of each scan will be accumulated in the driver to improve the measurement sensitivity. The scan times (rounds) can be determined by :cpp:member:`touch_proximity_config_t::scan_times` and the charging times of the proximity channel in one scan can be determined by :cpp:member:`touch_proximity_config_t::charge_times`. Generally, the larger the scan times and charging times is, the higher the sensitivity will be, however, the read data will be unstable if the sensitivity is too high. Proper parameters should be determined regarding the application.
.. only:: esp32p4
Since the capacitance change caused by proximity sensing is far less than that caused by physical touch, large area of copper foil is often used on PCB to increase the sensing area. In addition, multiple rounds of scans are needed and the result of each scan will be accumulated in the driver to improve the measurement sensitivity. The scan times (rounds) can be determined by :cpp:member:`touch_proximity_config_t::scan_times` and the charging times of the proximity channel in one scan can be determined by :cpp:member:`touch_proximity_config_t::charge_times`. Generally, the larger the scan times and charging times is, the higher the sensitivity will be, however, the read data will be unstable if the sensitivity is too high. Proper parameters should be determined regarding the application.
.. only:: not esp32p4
Since the capacitance change caused by proximity sensing is far less than that caused by physical touch, large area of copper foil is often used on PCB to increase the sensing area. In addition, multiple rounds of scans are needed and the result of each scan will be accumulated in the driver to improve the measurement sensitivity. The scan times (rounds) can be determined by :cpp:member:`touch_proximity_config_t::scan_times`. Generally, the larger the scan times and charging times is, the higher the sensitivity will be, however, the read data will be unstable if the sensitivity is too high. Proper parameters should be determined regarding the application.
The accumulated proximity data can be read by :cpp:func:`touch_channel_read_data` with the data type :cpp:enumerator:`TOUCH_CHAN_DATA_TYPE_PROXIMITY`
@ -421,7 +378,7 @@ Call :cpp:func:`touch_channel_read_data` to read the data with different types.
If you want to read or configure the touch sensor during the sleep, you can turn to the driver ``components/ulp/ulp_riscv/ulp_core/include/ulp_riscv_touch_ulp_core.h`` which based on the :doc:`Ultra Low Power (ULP) Coprocessor <../system/ulp>`.
- Light sleep wake-up: you need to set :cpp:member:`slp_wakeup_lvl` to :cpp:enumerator:`TOUCH_LIGHT_SLEEP_WAKEUP` to enable the light sleep wake-up by touch sensor. Note that any registered touch channel can wake-up the chip from light sleep.
- Deep sleep wake-up: beside setting :cpp:member:`slp_wakeup_lvl` to :cpp:enumerator:`TOUCH_DEEP_SLEEP_WAKEUP`, you need to specify :cpp:member:`deep_slp_chan` additionally. Only the specified channel can wake-up the chip from the deep sleep, in order to reduce the power consumption. And also, the driver supports to store another set of configurations for the deep sleep via :cpp:member:`deep_slp_sens_cfg`, this set of configurations only takes effect during the deep sleep, you can customize the configurations to save more power. The configurations will be reset to the previous set after waking-up from the deep sleep. Please be aware that, not only deep sleep wake-up, but also light sleep wake-up will be enabled when the :cpp:member:`slp_wakeup_lvl` is :cpp:enumerator:`TOUCH_DEEP_SLEEP_WAKEUP`.
- Deep sleep wake-up: beside setting :cpp:member:`slp_wakeup_lvl` to :cpp:enumerator:`TOUCH_DEEP_SLEEP_WAKEUP`, you need to specify :cpp:member:`deep_slp_chan` additionally. In order to reduce the power consumption, only the specified channel can wake-up the chip from the deep sleep when RTC_PREI power domain off. And also, the driver supports to store another set of configurations for the deep sleep via :cpp:member:`deep_slp_sens_cfg`, this set of configurations only takes effect during the deep sleep, you can customize the configurations to save more power. The configurations will be reset to the previous set after waking-up from the deep sleep. Please be aware that, not only deep sleep wake-up, but also light sleep wake-up will be enabled when the :cpp:member:`slp_wakeup_lvl` is :cpp:enumerator:`TOUCH_DEEP_SLEEP_WAKEUP`.
To deregister the sleep wake-up function, you can call :cpp:func:`touch_sensor_config_sleep_wakeup` again, and set the second parameter (i.e. :cpp:type:`touch_sleep_config_t` pointer) to ``NULL``.
@ -444,15 +401,44 @@ Call :cpp:func:`touch_channel_read_data` to read the data with different types.
// Register the deep sleep wake-up
ESP_ERROR_CHECK(touch_sensor_config_sleep_wakeup(sens_handle, &deep_slp_cfg));
.. _touch-denoise-chan:
.. only:: SOC_TOUCH_SUPPORT_DENOISE_CHAN
Denoise Channel Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The {IDF_TARGET_NAME} supports the internal background noise suppression by the denoise channel. Denoise channel can be registered by calling :cpp:func:`touch_sensor_config_denoise_channel` and specify the configurations :cpp:type:`touch_denoise_chan_config_t`.
Denoise channel is an internal channel that not fanned out. After the denoise channel is enabled, the sampled data of the other touch channels will minus the data of the denoise channel automatically, so the final measurement result of the touch channels will be attenuated compare to the original data.
Aside of the common touch channel configuration, the reference capacitance that attached to the denoise channel can be set by :cpp:member:`touch_denoise_chan_config_t::ref_cap`. And the noise suppression resolution can be set by :cpp:member:`touch_denoise_chan_config_t::resolution`. The higher the resolution, the greater and more accuracy the denoise channel sample data will be, and the better suppression effect it takes. But at the same time, the attenuation of other touch channel sampling values also increases.
For example, the denoise channel resolution is :cpp:enumerator:`touch_denoise_chan_resolution_t::TOUCH_DENOISE_CHAN_RESOLUTION_BIT8`, i.e., maximum sample data is ``255``. Assuming the actual sample data of a normal touch channel is ``10000``, and the denoise channel sample data is ``100``, then the final measurement result of the touch channel will be ``10000 - 100 = 9900``; If we increase the resolution to :cpp:enumerator:`touch_denoise_chan_resolution_t::TOUCH_DENOISE_CHAN_RESOLUTION_BIT12`, i.e., maximum sample data is ``4095``, the resolution is ``16`` times greater. So the denoise channel sample data will be about ``100 * 16 = 1600``, then the final measurement result of this touch channel will be ``10000 - 1600 = 8400.``
To deregister the denoise channel, you can call :cpp:func:`touch_sensor_config_denoise_channel` again, and set the second parameter (i.e. :cpp:type:`touch_denoise_chan_config_t` pointer) to ``NULL``.
.. code-block:: c
touch_denoise_chan_config_t denoise_cfg = {
// Denoise channel configurations
// ...
}
// Register the denoise channel
ESP_ERROR_CHECK(touch_sensor_config_denoise_channel(sens_handle, &denoise_cfg));
// ...
// Deregister the denoise channel
ESP_ERROR_CHECK(touch_sensor_config_denoise_channel(sens_handle, NULL));
Application Examples
------------------------
- :example:`peripherals/touch_sensor/touch_sensor_v3` demonstrates how to register touch channels and read the data, including hardware requirements and project configuration instructions.
- :example:`peripherals/touch_sensor/touch_sens_basic` demonstrates how to register touch channels and read the data, including hardware requirements and project configuration instructions.
API Reference
-------------
.. only:: esp32p4
.. only:: esp32p4 or esp32s2 or esp32s3
.. include-build-file:: inc/touch_sens.inc
.. include-build-file:: inc/touch_sens_types.inc

64
docs/en/api-reference/peripherals/cap_touch_sens/esp32p4.inc Normal file
View File

@ -0,0 +1,64 @@
.. This file gets included from other .rst files in this folder.
.. It contains target-specific snippets.
.. Comments and '---' lines act as delimiters.
..
.. This is necessary mainly because RST doesn't support substitutions
.. (defined in RST, not in Python) inside code blocks. If that is ever implemented,
.. These code blocks can be moved back to the main .rst files, with target-specific
.. file names being replaced by substitutions.
.. touch-chan-mapping
.. list-table::
:header-rows: 1
:widths: 20 20
* - Channel
- GPIO
* - CH0
- IO2
* - CH1
- IO3
* - CH2
- IO4
* - CH3
- IO5
* - CH4
- IO6
* - CH5
- IO7
* - CH6
- IO8
* - CH7
- IO9
* - CH8
- IO10
* - CH9
- IO11
* - CH10
- IO12
* - CH11
- IO13
* - CH12
- IO14
* - CH13
- IO15
* - CH14
- Internal
---

64
docs/en/api-reference/peripherals/cap_touch_sens/esp32s2.inc Normal file
View File

@ -0,0 +1,64 @@
.. This file gets included from other .rst files in this folder.
.. It contains target-specific snippets.
.. Comments and '---' lines act as delimiters.
..
.. This is necessary mainly because RST doesn't support substitutions
.. (defined in RST, not in Python) inside code blocks. If that is ever implemented,
.. These code blocks can be moved back to the main .rst files, with target-specific
.. file names being replaced by substitutions.
.. touch-chan-mapping
.. list-table::
:header-rows: 1
:widths: 20 20
* - Channel
- GPIO
* - CH0
- Internal
* - CH1
- IO1
* - CH2
- IO2
* - CH3
- IO3
* - CH4
- IO4
* - CH5
- IO5
* - CH6
- IO6
* - CH7
- IO7
* - CH8
- IO8
* - CH9
- IO9
* - CH10
- IO10
* - CH11
- IO11
* - CH12
- IO12
* - CH13
- IO13
* - CH14
- IO14
---

64
docs/en/api-reference/peripherals/cap_touch_sens/esp32s3.inc Normal file
View File

@ -0,0 +1,64 @@
.. This file gets included from other .rst files in this folder.
.. It contains target-specific snippets.
.. Comments and '---' lines act as delimiters.
..
.. This is necessary mainly because RST doesn't support substitutions
.. (defined in RST, not in Python) inside code blocks. If that is ever implemented,
.. These code blocks can be moved back to the main .rst files, with target-specific
.. file names being replaced by substitutions.
.. touch-chan-mapping
.. list-table::
:header-rows: 1
:widths: 20 20
* - Channel
- GPIO
* - CH0
- Internal
* - CH1
- IO1
* - CH2
- IO2
* - CH3
- IO3
* - CH4
- IO4
* - CH5
- IO5
* - CH6
- IO6
* - CH7
- IO7
* - CH8
- IO8
* - CH9
- IO9
* - CH10
- IO10
* - CH11
- IO11
* - CH12
- IO12
* - CH13
- IO13
* - CH14
- IO14
---

4
docs/en/api-reference/peripherals/index.rst
View File

@ -42,8 +42,8 @@ Peripherals API
:SOC_GPSPI_SUPPORTED: spi_slave
:SOC_SPI_SUPPORT_SLAVE_HD_VER2: spi_slave_hd
:SOC_TEMP_SENSOR_SUPPORTED: temp_sensor
:SOC_TOUCH_SENSOR_SUPPORTED and not esp32p4: touch_pad
:esp32p4: cap_touch_sens
:esp32: touch_pad
:SOC_TOUCH_SENSOR_SUPPORTED and not esp32: cap_touch_sens
:esp32s2: touch_element
:SOC_TWAI_SUPPORTED: twai
uart

6
docs/en/api-reference/peripherals/touch_element.rst
View File

@ -6,7 +6,11 @@ Touch Element
Overview
--------
The Touch Element Library is a highly abstracted element library designed on the basis of the touch sensor driver. The library provides a unified and user-friendly software interface to quickly build capacitive touch sensor applications. For more information about the touch sensor driver API, see :doc:`../peripherals/touch_pad`.
The Touch Element Library is a highly abstracted element library designed on the basis of the touch sensor driver. The library provides a unified and user-friendly software interface to quickly build capacitive touch sensor applications.
.. warning::
The Touch Element Library currently is still based on the legacy touch driver. Please refer to the :doc:`new driver of Capacitive Touch Sensor </api-reference/peripherals/cap_touch_sens>` if you don't need the Touch Element Library.
Architecture
^^^^^^^^^^^^

16
docs/en/api-reference/peripherals/touch_pad.rst
View File

@ -5,6 +5,12 @@ Touch Sensor
{IDF_TARGET_TOUCH_SENSOR_VERSION:default="v2", esp32="v1"}
.. only:: esp32s2 or esp32s3
.. warning::
The touch driver in this document has been deprecated, please move to the new document for the latest touch driver: :doc:`Capacitive Touch Sensor </api-reference/peripherals/cap_touch_sens>`.
Introduction
------------
@ -146,8 +152,6 @@ Touch State Measurements
It can also be used, for example, to evaluate a particular touch pad design by checking the range of sensor readings when a pad is touched or released. This information can be then used to establish a touch threshold.
For the demonstration of how to read the touch pad data, check the application example :example:`peripherals/touch_sensor/touch_sensor_{IDF_TARGET_TOUCH_SENSOR_VERSION}/touch_pad_read`.
Method of Measurements
^^^^^^^^^^^^^^^^^^^^^^
@ -250,7 +254,7 @@ Touch detection is implemented in ESP32's hardware based on the user-configured
Hardware touch detection can also be wired to interrupts. This is described in the next section.
If measurements are noisy and capacity changes are small, hardware touch detection might be unreliable. To resolve this issue, instead of using hardware detection/provided interrupts, implement measurement filtering and perform touch detection in your own application. For sample implementation of both methods of touch detection, see :example:`peripherals/touch_sensor/touch_sensor_{IDF_TARGET_TOUCH_SENSOR_VERSION}/touch_pad_interrupt`.
If measurements are noisy and capacity changes are small, hardware touch detection might be unreliable. To resolve this issue, instead of using hardware detection/provided interrupts, implement measurement filtering and perform touch detection in your own application.
Touch Triggered Interrupts
^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -300,9 +304,9 @@ Application Examples
.. only:: esp32s2 or esp32s3
- :example:`peripherals/touch_sensor/touch_sensor_v2/touch_pad_read` demonstrates how to read and display raw values from capacitive touch pad sensors on {IDF_TARGET_NAME}, including how to calibrate the sensors and detect touch actions.
- :example:`peripherals/touch_sensor/touch_sensor_v2/touch_pad_interrupt` demonstrates how to set up {IDF_TARGET_NAME}'s capacitive touch pad peripheral to trigger an interrupt when a pad is touched, and how to detect the touch event by the software for sensor designs when greater touch detection sensitivity is required.
.. warning::
The example that uses legacy driver is removed, please see :example:`peripherals/touch_sensor/touch_sens_basic` for the usage of the new driver.
.. _touch_pad-api-reference:
@ -321,4 +325,4 @@ Some useful macros can be used to specified the GPIO number of a touch pad chann
2. ``TOUCH_PAD_GPIO4_CHANNEL`` is the channel number of GPIO 4 (channel 0).
.. include-build-file:: inc/touch_sensor_channel.inc
.. include-build-file:: inc/touch_sensor_types.inc
.. include-build-file:: inc/touch_sensor_legacy_types.inc

112
docs/zh_CN/api-reference/peripherals/cap_touch_sens.rst
View File

@ -3,7 +3,7 @@
:link_to_translation:`en:[English]`
{IDF_TARGET_TOUCH_SENSOR_VERSION:default="NOT_UPDATED", esp32p4="v3"}
{IDF_TARGET_TOUCH_SENSOR_VERSION:default="NOT_UPDATED", esp32s2="v2", esp32s3="v2", esp32p4="v3"}
概述
------
@ -35,59 +35,9 @@
触摸通道概览
----------------------
.. only:: esp32p4
.. list-table::
:header-rows: 1
:widths: 20 20
* - 通道
- GPIO
* - CH0
- IO2
* - CH1
- IO3
* - CH2
- IO4
* - CH3
- IO5
* - CH4
- IO6
* - CH5
- IO7
* - CH6
- IO8
* - CH7
- IO9
* - CH8
- IO10
* - CH9
- IO11
* - CH10
- IO12
* - CH11
- IO13
* - CH12
- IO14
* - CH13
- IO15
* - CH14
- 未引出
.. include:: cap_touch_sens/{IDF_TARGET_PATH_NAME}.inc
:start-after: touch-chan-mapping
:end-before: ---
驱动中的术语介绍
-------------------------
@ -148,6 +98,7 @@
:SOC_TOUCH_SUPPORT_WATERPROOF: - `防水防潮配置 <#touch-waterproof>`__
:SOC_TOUCH_SUPPORT_PROX_SENSING: - `接近感应配置 <#touch-prox-sensing>`__
:SOC_TOUCH_SUPPORT_SLEEP_WAKEUP: - `睡眠唤醒配置 <#touch-sleep-wakeup>`__
:SOC_TOUCH_SUPPORT_DENOISE_CHAN: - `去噪通道配置 <#touch-denoise-chan>`__
.. _touch-ctrl:
@ -385,7 +336,13 @@
{IDF_TARGET_NAME} 支持接近感应功能。可通过调用 :cpp:func:`touch_sensor_config_proximity_sensing` 并配置 :cpp:type:`touch_proximity_config_t` 来注册接近感应功能。
由于接近感应引起的电容变化远小于物理触摸，PCB 上常用较大面积的铺铜来增大触摸通道的感应面积，另外需要在硬件上对接近感应通道进行多轮扫描并在驱动中进行累加来提高测量灵敏度。接近感应的灵敏度由测量轮数 :cpp:member:`touch_proximity_config_t::scan_times` 以及单次测量的充放电次数 :cpp:member:`touch_proximity_config_t::charge_times` 决定。测量轮数以及充放电次数越高，灵敏度越高，但是过高的灵敏度容易导致误触发，请选择适当的灵敏度来保证触发的稳定性。
.. only:: esp32p4
由于接近感应引起的电容变化远小于物理触摸，PCB 上常用较大面积的铺铜来增大触摸通道的感应面积，另外需要在硬件上对接近感应通道进行多轮扫描并在驱动中进行累加来提高测量灵敏度。接近感应的灵敏度由测量轮数 :cpp:member:`touch_proximity_config_t::scan_times` 以及单次测量的充放电次数 :cpp:member:`touch_proximity_config_t::charge_times` 决定。测量轮数以及充放电次数越高，灵敏度越高，但是过高的灵敏度容易导致误触发，请选择适当的灵敏度来保证触发的稳定性。
.. only:: not esp32p4
由于接近感应引起的电容变化远小于物理触摸，PCB 上常用较大面积的铺铜来增大触摸通道的感应面积，另外需要在硬件上对接近感应通道进行多轮扫描并在驱动中进行累加来提高测量灵敏度。接近感应的灵敏度由测量轮数 :cpp:member:`touch_proximity_config_t::scan_times` 决定。测量轮数以及充放电次数越高，灵敏度越高，但是过高的灵敏度容易导致误触发，请选择适当的灵敏度来保证触发的稳定性。
接近感应通道多次测量的累加值也可通过 :cpp:func:`touch_channel_read_data` 获取，数据类型 :cpp:type:`touch_chan_data_type_t` 为 :cpp:enumerator:`TOUCH_CHAN_DATA_TYPE_PROXIMITY`。
@ -410,7 +367,7 @@
睡眠唤醒配置
^^^^^^^^^^^^^^
{IDF_TARGET_NAME} 支持触摸传感器将芯片从浅睡眠或深睡眠状态中唤醒。可通过调用 :cpp:func:`touch_sensor_config_sleep_wakeup` 并配置 :cpp:type:`touch_sleep_config_t` 来注册接近感应功能。
{IDF_TARGET_NAME} 支持触摸传感器将芯片从 Light-sleep 或 Deep-sleep 状态中唤醒。可通过调用 :cpp:func:`touch_sensor_config_sleep_wakeup` 并配置 :cpp:type:`touch_sleep_config_t` 来注册接近感应功能。
注册触摸传感器的睡眠唤醒功能后，处于睡眠状态下的芯片仍将继续保持对触摸传感器的采样，这将会导致芯片睡眠后的功耗增加，可通过减少充放电次数、增加采样间隔等方式来降低功耗。
@ -420,8 +377,8 @@
若需要在睡眠过程中进行读数、配置等操作，可通过运行在 :doc:`超低功耗协处理器 ULP <../system/ulp>` 上的触摸传感器驱动 ``components/ulp/ulp_riscv/ulp_core/include/ulp_riscv_touch_ulp_core.h`` 实现。
- 浅睡眠状态唤醒：通过指定 :cpp:member:`slp_wakeup_lvl` 为 :cpp:enumerator:`TOUCH_LIGHT_SLEEP_WAKEUP` 即可启用触摸传感器浅睡眠唤醒功能。注意任何已注册的触摸传感器通道都会在浅睡眠状态下保持采样并支持唤醒浅睡眠。
- 深睡眠状态唤醒：启用触摸传感器深睡眠唤醒功能除了指定 :cpp:member:`slp_wakeup_lvl` 为 :cpp:enumerator:`TOUCH_DEEP_SLEEP_WAKEUP` 外，还需要指定深睡眠唤醒通道 :cpp:member:`deep_slp_chan`，注意只有该指定的通道才会在深睡眠状态下保持采样以及唤醒，以此降低在深睡眠状态下的功耗。此外，若需要在深度睡眠下使用另一套低功耗的配置来进一步降低功耗，可以通过 :cpp:member:`deep_slp_sens_cfg` 额外指定一套低功耗配置，在进入深睡眠前，驱动会应用这套配置，从深睡眠状态唤醒后，则会重新配置到之前的配置。请注意当 :cpp:member:`slp_wakeup_lvl` 配置为 :cpp:enumerator:`TOUCH_DEEP_SLEEP_WAKEUP` 后，触摸传感器不仅能唤醒深睡眠状态，还能唤醒浅睡眠状态。
- Light-sleep 状态唤醒：通过指定 :cpp:member:`slp_wakeup_lvl` 为 :cpp:enumerator:`TOUCH_LIGHT_SLEEP_WAKEUP` 即可启用触摸传感器 Light-sleep 唤醒功能。注意任何已注册的触摸传感器通道都会在 Light-sleep 状态下保持采样并支持唤醒 Light-sleep。
- Deep-sleep 状态唤醒：启用触摸传感器 Deep-sleep 唤醒功能除了指定 :cpp:member:`slp_wakeup_lvl` 为 :cpp:enumerator:`TOUCH_DEEP_SLEEP_WAKEUP` 外，还需要指定 Deep-sleep 唤醒通道 :cpp:member:`deep_slp_chan`，注意只有该指定的通道才会在 Deep-sleep 状态下保持采样以及唤醒，以此降低在 Deep-sleep 状态下的功耗。此外，若需要在深度睡眠下使用另一套低功耗的配置来进一步降低功耗，可以通过 :cpp:member:`deep_slp_sens_cfg` 额外指定一套低功耗配置，在进入 Deep-sleep 前，驱动会应用这套配置，从 Deep-sleep 状态唤醒后，则会重新配置到之前的配置。请注意当 :cpp:member:`slp_wakeup_lvl` 配置为 :cpp:enumerator:`TOUCH_DEEP_SLEEP_WAKEUP` 后，触摸传感器不仅能唤醒 Deep-sleep 状态，还能唤醒 Light-sleep 状态。
若需要注销睡眠唤醒功能，可再次调用 :cpp:func:`touch_sensor_config_sleep_wakeup` 并将第二个参数（即 :cpp:type:`touch_sleep_config_t` 的配置结构体指针）设为 ``NULL`` 来注销睡眠唤醒功能。
@ -430,7 +387,7 @@
touch_sleep_config_t light_slp_cfg = {
.slp_wakeup_lvl = TOUCH_LIGHT_SLEEP_WAKEUP,
};
// 注册浅睡眠唤醒功能
// 注册 Light-sleep 唤醒功能
ESP_ERROR_CHECK(touch_sensor_config_sleep_wakeup(sens_handle, &light_slp_cfg));
// ...
// 注销睡眠唤醒功能
@ -438,21 +395,50 @@
touch_sleep_config_t deep_slp_cfg = {
.slp_wakeup_lvl = TOUCH_DEEP_SLEEP_WAKEUP,
.deep_slp_chan = dslp_chan_handle,
// 其他深睡眠唤醒配置
// 其他 Deep-sleep 唤醒配置
// ...
};
// 注册深睡眠唤醒功能
// 注册 Deep-sleep 唤醒功能
ESP_ERROR_CHECK(touch_sensor_config_sleep_wakeup(sens_handle, &deep_slp_cfg));
.. _touch-denoise-chan:
.. only:: SOC_TOUCH_SUPPORT_DENOISE_CHAN
去噪通道配置
^^^^^^^^^^^^
{IDF_TARGET_NAME} 支持通过去噪通道抑制内部背景噪声。可通过调用 :cpp:func:`touch_sensor_config_denoise_channel` 并配置 :cpp:type:`touch_denoise_chan_config_t` 来注册去噪通道。
去噪通道是一个没有引出的内部触摸通道。去噪通道使能之后，其他触摸通道的采样值会自动减去去噪通道的采样值，从而实现去噪。因此最终测量结果相比去噪前会有一定衰减。
除了常规的触摸通道配置，去噪通道还可以配置 :cpp:member:`touch_denoise_chan_config_t::ref_cap` 来指定连接到该通道上的参考电容大小，以及 :cpp:member:`touch_denoise_chan_config_t::resolution` 来指定噪声抑制的分辨率。分辨率越高，去噪通道采样值越大越精确，抑制效果越好，但同时其他触摸通道在自动扣除去噪通道采样值后的测量值衰减也越大。
例如，去噪通道分辨率为 :cpp:enumerator:`touch_denoise_chan_resolution_t::TOUCH_DENOISE_CHAN_RESOLUTION_BIT8`，即去噪通道采样值最大为 ``255``。假设此时一个常规通道实际采样值为 ``10000``，去噪通道采样值假设为 ``100``，则该常规通道扣除去噪通道采样值后的读数为 ``10000 - 100 = 9900``；若分辨率改为 :cpp:enumerator:`touch_denoise_chan_resolution_t::TOUCH_DENOISE_CHAN_RESOLUTION_BIT12`，即去噪通道采样值最大为 ``4095``，去噪通道分辨率提升 ``16`` 倍，去噪通道采样值大概为 ``100 * 16 = 1600``。此时该常规通道扣除去噪通道采样值后的读数为 ``10000 - 1600 = 8400``。
若需要注销去噪通道功能，可再次调用 :cpp:func:`touch_sensor_config_denoise_channel` 并将第二个参数（即 :cpp:type:`touch_denoise_chan_config_t` 的配置结构体指针）设为 ``NULL`` 来注销去噪通道功能。
.. code-block:: c
touch_denoise_chan_config_t denoise_cfg = {
// 去噪通道配置
// ...
}
// 注册去噪通道
ESP_ERROR_CHECK(touch_sensor_config_denoise_channel(sens_handle, &denoise_cfg));
// ...
// 注销去噪通道
ESP_ERROR_CHECK(touch_sensor_config_denoise_channel(sens_handle, NULL));
应用示例
--------
- :example:`peripherals/touch_sensor/touch_sensor_v3` 演示了如何注册触摸通道并读取数据，并说明了硬件要求及项目配置。
- :example:`peripherals/touch_sensor/touch_sens_basic` 演示了如何注册触摸通道并读取数据，并说明了硬件要求及项目配置。
API 参考
----------
.. only:: esp32p4
.. only:: esp32p4 or esp32s2 or esp32s3
.. include-build-file:: inc/touch_sens.inc
.. include-build-file:: inc/touch_sens_types.inc

64
docs/zh_CN/api-reference/peripherals/cap_touch_sens/esp32p4.inc Normal file
View File

@ -0,0 +1,64 @@
.. This file gets included from other .rst files in this folder.
.. It contains target-specific snippets.
.. Comments and '---' lines act as delimiters.
..
.. This is necessary mainly because RST doesn't support substitutions
.. (defined in RST, not in Python) inside code blocks. If that is ever implemented,
.. These code blocks can be moved back to the main .rst files, with target-specific
.. file names being replaced by substitutions.
.. touch-chan-mapping
.. list-table::
:header-rows: 1
:widths: 20 20
* - 通道
- GPIO
* - CH0
- IO2
* - CH1
- IO3
* - CH2
- IO4
* - CH3
- IO5
* - CH4
- IO6
* - CH5
- IO7
* - CH6
- IO8
* - CH7
- IO9
* - CH8
- IO10
* - CH9
- IO11
* - CH10
- IO12
* - CH11
- IO13
* - CH12
- IO14
* - CH13
- IO15
* - CH14
- 未引出
---

64
docs/zh_CN/api-reference/peripherals/cap_touch_sens/esp32s2.inc Normal file
View File

@ -0,0 +1,64 @@
.. This file gets included from other .rst files in this folder.
.. It contains target-specific snippets.
.. Comments and '---' lines act as delimiters.
..
.. This is necessary mainly because RST doesn't support substitutions
.. (defined in RST, not in Python) inside code blocks. If that is ever implemented,
.. These code blocks can be moved back to the main .rst files, with target-specific
.. file names being replaced by substitutions.
.. touch-chan-mapping
.. list-table::
:header-rows: 1
:widths: 20 20
* - 通道
- GPIO
* - CH0
- 未引出
* - CH1
- IO1
* - CH2
- IO2
* - CH3
- IO3
* - CH4
- IO4
* - CH5
- IO5
* - CH6
- IO6
* - CH7
- IO7
* - CH8
- IO8
* - CH9
- IO9
* - CH10
- IO10
* - CH11
- IO11
* - CH12
- IO12
* - CH13
- IO13
* - CH14
- IO14
---

64
docs/zh_CN/api-reference/peripherals/cap_touch_sens/esp32s3.inc Normal file
View File

@ -0,0 +1,64 @@
.. This file gets included from other .rst files in this folder.
.. It contains target-specific snippets.
.. Comments and '---' lines act as delimiters.
..
.. This is necessary mainly because RST doesn't support substitutions
.. (defined in RST, not in Python) inside code blocks. If that is ever implemented,
.. These code blocks can be moved back to the main .rst files, with target-specific
.. file names being replaced by substitutions.
.. touch-chan-mapping
.. list-table::
:header-rows: 1
:widths: 20 20
* - 通道
- GPIO
* - CH0
- 未引出
* - CH1
- IO1
* - CH2
- IO2
* - CH3
- IO3
* - CH4
- IO4
* - CH5
- IO5
* - CH6
- IO6
* - CH7
- IO7
* - CH8
- IO8
* - CH9
- IO9
* - CH10
- IO10
* - CH11
- IO11
* - CH12
- IO12
* - CH13
- IO13
* - CH14
- IO14
---

4
docs/zh_CN/api-reference/peripherals/index.rst
View File

@ -42,8 +42,8 @@
:SOC_SPI_SUPPORT_SLAVE_HD_VER2: spi_slave_hd
:SOC_JPEG_CODEC_SUPPORTED: jpeg
:SOC_TEMP_SENSOR_SUPPORTED: temp_sensor
:SOC_TOUCH_SENSOR_SUPPORTED and not esp32p4: touch_pad
:esp32p4: cap_touch_sens
:esp32: touch_pad
:SOC_TOUCH_SENSOR_SUPPORTED and not esp32: cap_touch_sens
:esp32s2: touch_element
:SOC_TWAI_SUPPORTED: twai
uart

6
docs/zh_CN/api-reference/peripherals/touch_element.rst
View File

@ -6,7 +6,11 @@
概述
--------
触摸元件库是基于触摸传感器驱动设计的高度抽象的元件库，该库提供了统一且友好的软件接口，可以快速构建电容式触摸传感器的应用。有关触摸传感器驱动 API 的更多信息，请参阅 :doc:`../peripherals/touch_pad`。
触摸元件库是基于触摸传感器驱动设计的高度抽象的元件库，该库提供了统一且友好的软件接口，可以快速构建电容式触摸传感器的应用。
.. warning::
目前的触摸元件库仍然基于旧的触摸传感器驱动。如您不需要使用触摸元件库，请参考新的 :doc:`电容式触摸传感器 </api-reference/peripherals/cap_touch_sens>` 驱动。
架构
^^^^^^^^^^^^

16
docs/zh_CN/api-reference/peripherals/touch_pad.rst
View File

@ -5,6 +5,12 @@
{IDF_TARGET_TOUCH_SENSOR_VERSION:default="v2", esp32="v1"}
.. only:: esp32s2 or esp32s3
.. warning::
该文档所演示的 Touch 驱动已弃用, 请移步新文档查看最新的 Touch 驱动: :doc:`Capacitive Touch Sensor </api-reference/peripherals/cap_touch_sens>`.
概述
------------
@ -146,8 +152,6 @@
该函数也可以用于检查触碰和释放触摸传感器时传感器读数变化范围，然后根据这些信息设定触摸传感器的触摸阈值。
请参考应用示例 :example:`peripherals/touch_sensor/touch_sensor_{IDF_TARGET_TOUCH_SENSOR_VERSION}/touch_pad_read`，查看如何使用读取触摸传感器数据。
测量方式
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -250,7 +254,7 @@
也可以将硬件触摸监测连接至中断，详细介绍见下一章节。
如果测量中存在噪声，且电容变化幅度较小，硬件触摸监测结果可能就不太理想。如需解决这一问题，不建议使用硬件监测或中断信号，建议在自己的应用程序中进行采样滤波，并执行触摸监测。请参考 :example:`peripherals/touch_sensor/touch_sensor_{IDF_TARGET_TOUCH_SENSOR_VERSION}/touch_pad_interrupt`，查看以上两种触摸监测的实现方式。
如果测量中存在噪声，且电容变化幅度较小，硬件触摸监测结果可能就不太理想。如需解决这一问题，不建议使用硬件监测或中断信号，建议在自己的应用程序中进行采样滤波，并执行触摸监测。
中断触发
^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -300,9 +304,9 @@
.. only:: esp32s2 or esp32s3
- :example:`peripherals/touch_sensor/touch_sensor_v2/touch_pad_read` 演示了如何在 {IDF_TARGET_NAME} 上读取并显示电容触摸传感器的原始值，包括如何校准传感器以及监测触摸动作。
- :example:`peripherals/touch_sensor/touch_sensor_v2/touch_pad_interrupt` 演示了如何设置 {IDF_TARGET_NAME} 的电容触摸板外设，使其在被触摸时触发中断，以及在需要更高触摸监测灵敏度的传感器设计中，如何通过软件来监测触摸事件。
.. warning::
使用老驱动的例程已移除，新驱动用法请参考 :example:`peripherals/touch_sensor/touch_sens_basic`。
.. _touch_pad-api-reference:
@ -321,4 +325,4 @@ GPIO 宏查找表
2. ``TOUCH_PAD_GPIO4_CHANNEL`` 定义了 GPIO 4 的通道（即通道 0）。
.. include-build-file:: inc/touch_sensor_channel.inc
.. include-build-file:: inc/touch_sensor_types.inc
.. include-build-file:: inc/touch_sensor_legacy_types.inc

23
examples/peripherals/.build-test-rules.yml
View File

@ -420,24 +420,19 @@ examples/peripherals/touch_sensor/touch_element:
- if: IDF_TARGET in ["esp32s2", "esp32s3"]
reason: only supports esp32s2 and esp32s3
examples/peripherals/touch_sensor/touch_sens_basic:
disable:
- if: SOC_TOUCH_SENSOR_SUPPORTED != 1
- if: SOC_TOUCH_SENSOR_VERSION == 1
temporary: true
reason: not supported yet
depends_components:
- esp_driver_touch_sens
examples/peripherals/touch_sensor/touch_sensor_v1:
disable:
- if: SOC_TOUCH_SENSOR_VERSION != 1
examples/peripherals/touch_sensor/touch_sensor_v2:
disable:
- if: SOC_TOUCH_SENSOR_VERSION != 2
examples/peripherals/touch_sensor/touch_sensor_v3:
disable:
- if: SOC_TOUCH_SENSOR_VERSION != 3
disable_test:
- if: IDF_TARGET == "esp32p4"
temporary: true
reason: the runners do not support the pins for touch sensor
depends_components:
- esp_driver_touch_sens
examples/peripherals/twai/twai_alert_and_recovery:
disable:
- if: SOC_TWAI_SUPPORTED != 1

0
examples/peripherals/touch_sensor/touch_sensor_v3/CMakeLists.txt → examples/peripherals/touch_sensor/touch_sens_basic/CMakeLists.txt
View File

4
examples/peripherals/touch_sensor/touch_sensor_v3/README.md → examples/peripherals/touch_sensor/touch_sens_basic/README.md
View File

@ -1,5 +1,5 @@
| Supported Targets | ESP32-P4 |
| ----------------- | -------- |
| Supported Targets | ESP32-P4 | ESP32-S2 | ESP32-S3 |
| ----------------- | -------- | -------- | -------- |
# Capacity Touch Sensor Example (for hardware version 3)

2
examples/peripherals/touch_sensor/touch_sensor_v3/main/CMakeLists.txt → examples/peripherals/touch_sensor/touch_sens_basic/main/CMakeLists.txt
View File

@ -1,3 +1,3 @@
idf_component_register(SRCS "touch_sens_v3_example_main.c"
idf_component_register(SRCS "touch_sens_basic_example_main.c"
REQUIRES esp_driver_touch_sens
INCLUDE_DIRS ".")

77
examples/peripherals/touch_sensor/touch_sensor_v3/main/touch_sens_v3_example_main.c → examples/peripherals/touch_sensor/touch_sens_basic/main/touch_sens_basic_example_main.c
View File

@ -10,11 +10,7 @@
#include "freertos/task.h"
#include "driver/touch_sens.h"
#include "esp_check.h"
// Touch version 3 supports multiple sample configurations
#define EXAMPLE_TOUCH_SAMPLE_CFG_NUM 1 // Up to 'TOUCH_SAMPLE_CFG_NUM'
#define EXAMPLE_TOUCH_CHANNEL_NUM 4
#define EXAMPLE_TOUCH_CHAN_INIT_SCAN_TIMES 3
#include "touch_sens_example_config.h"
static touch_sensor_handle_t s_sens_handle = NULL;
static touch_channel_handle_t s_chan_handle[EXAMPLE_TOUCH_CHANNEL_NUM] = {};
@ -22,6 +18,13 @@ static touch_channel_handle_t s_chan_handle[EXAMPLE_TOUCH_CHANNEL_NUM] = {};
static float s_thresh2bm_ratio[EXAMPLE_TOUCH_CHANNEL_NUM] = {
[0 ... EXAMPLE_TOUCH_CHANNEL_NUM - 1] = 0.015f, // 1.5%
};
// The touch channel IDs that used in this example
static int s_channel_id[EXAMPLE_TOUCH_CHANNEL_NUM] = {
TOUCH_MIN_CHAN_ID,
TOUCH_MIN_CHAN_ID + 1,
TOUCH_MIN_CHAN_ID + 2,
TOUCH_MIN_CHAN_ID + 3,
};
bool example_touch_on_active_callback(touch_sensor_handle_t sens_handle, const touch_active_event_data_t *event, void *user_ctx)
{
@ -56,7 +59,7 @@ static void example_touch_do_initial_scanning(void)
ESP_ERROR_CHECK(touch_channel_read_data(s_chan_handle[i], TOUCH_CHAN_DATA_TYPE_BENCHMARK, benchmark));
/* Calculate the proper active thresholds regarding the initial benchmark */
printf("[CH %d]", i);
touch_channel_config_t chan_cfg = {};
touch_channel_config_t chan_cfg = EXAMPLE_TOUCH_CHAN_CFG_DEFAULT();
for (int j = 0; j < EXAMPLE_TOUCH_SAMPLE_CFG_NUM; j++) {
chan_cfg.active_thresh[j] = (uint32_t)(benchmark[j] * s_thresh2bm_ratio[i]);
printf(" %d: %"PRIu32", %"PRIu32"\t", j, benchmark[j], chan_cfg.active_thresh[j]);
@ -70,15 +73,7 @@ static void example_touch_do_initial_scanning(void)
void app_main(void)
{
/* Use the default sample configurations */
touch_sensor_sample_config_t sample_cfg[EXAMPLE_TOUCH_SAMPLE_CFG_NUM] = {
TOUCH_SENSOR_V3_DEFAULT_SAMPLE_CONFIG(1, 1, 1),
#if EXAMPLE_TOUCH_SAMPLE_CFG_NUM > 1
TOUCH_SENSOR_V3_DEFAULT_SAMPLE_CONFIG(2, 1, 1),
#endif
#if EXAMPLE_TOUCH_SAMPLE_CFG_NUM > 2
TOUCH_SENSOR_V3_DEFAULT_SAMPLE_CONFIG(4, 1, 1),
#endif
};
touch_sensor_sample_config_t sample_cfg[EXAMPLE_TOUCH_SAMPLE_CFG_NUM] = EXAMPLE_TOUCH_SAMPLE_CFG_DEFAULT();
/* Allocate new touch controller handle */
touch_sensor_config_t sens_cfg = TOUCH_SENSOR_DEFAULT_BASIC_CONFIG(EXAMPLE_TOUCH_SAMPLE_CFG_NUM, sample_cfg);
ESP_ERROR_CHECK(touch_sensor_new_controller(&sens_cfg, &s_sens_handle));
@ -87,37 +82,27 @@ void app_main(void)
touch_sensor_filter_config_t filter_cfg = TOUCH_SENSOR_DEFAULT_FILTER_CONFIG();
ESP_ERROR_CHECK(touch_sensor_config_filter(s_sens_handle, &filter_cfg));
/** Following is about setting the touch channel active threshold of each sample configuration.
*
* @How to Determine:
* As the actual threshold is affected by various factors in real application,
* we need to run the touch app first to get the `benchmark` and the `smooth_data` that being touched.
*
* @Formula:
* threshold = benchmark * coeff, (coeff for example, 0.1%~20%)
* Please adjust the coeff to guarantee the threshold < smooth_data - benchmark
*
* @Typical Practice:
* Normally, we can't determine a fixed threshold at the beginning,
* but we can give them estimated values first and update them after an initial scanning (like this example),
* Step1: set an estimated value for each sample configuration first. (i.e., here)
* Step2: then reconfig the threshold after the initial scanning.(see `example_touch_do_initial_scanning`)
* Step3: adjust the `s_thresh2bm_ratio` to a proper value to trigger the active callback
*/
touch_channel_config_t chan_cfg = EXAMPLE_TOUCH_CHAN_CFG_DEFAULT();
/* Allocate new touch channel on the touch controller */
touch_channel_config_t chan_cfg = {
/** Set the touch channel active threshold of each sample configuration.
*
* @How to Determine:
* As the actual threshold is affected by various factors in real application,
* we need to run the touch app first to get the `benchmark` and the `smooth_data` that being touched.
*
* @Formula:
* threshold = benchmark * coeff, (coeff for example, 0.1%~20%)
* Please adjust the coeff to guarantee the threshold < smooth_data - benchmark
*
* @Typical Practice:
* Normally, we can't determine a fixed threshold at the beginning,
* but we can give them estimated values first and update them after an initial scanning (like this example),
* Step1: set an estimated value for each sample configuration first. (i.e., here)
* Step2: then reconfig the threshold after the initial scanning.(see `example_touch_do_initial_scanning`)
* Step3: adjust the `s_thresh2bm_ratio` to a proper value to trigger the active callback
*/
.active_thresh = {
1000, // estimated active threshold of sample configuration 0
#if EXAMPLE_TOUCH_SAMPLE_CFG_NUM > 1
2500, // estimated active threshold of sample configuration 1
#endif
#if EXAMPLE_TOUCH_SAMPLE_CFG_NUM > 2
5000, // estimated active threshold of sample configuration 2
#endif
},
};
for (int i = 0; i < EXAMPLE_TOUCH_CHANNEL_NUM; i++) {
ESP_ERROR_CHECK(touch_sensor_new_channel(s_sens_handle, i, &chan_cfg, &s_chan_handle[i]));
ESP_ERROR_CHECK(touch_sensor_new_channel(s_sens_handle, s_channel_id[i], &chan_cfg, &s_chan_handle[i]));
}
/* Do the initial scanning to initialize the touch channel data
@ -149,14 +134,14 @@ void app_main(void)
for (int i = 0; i < EXAMPLE_TOUCH_CHANNEL_NUM; i++) {
/* Read and print the benchmark of each sample configuration */
ESP_ERROR_CHECK(touch_channel_read_data(s_chan_handle[i], TOUCH_CHAN_DATA_TYPE_BENCHMARK, benchmark));
printf("benchmark [CH %d]:", i);
printf("benchmark [CH %d]:", s_channel_id[i]);
for (int j = 0; j < EXAMPLE_TOUCH_SAMPLE_CFG_NUM; j++) {
printf(" %"PRIu32, benchmark[j]);
}
printf("\n");
/* Read and print the channel data of each sample configuration */
ESP_ERROR_CHECK(touch_channel_read_data(s_chan_handle[i], TOUCH_CHAN_DATA_TYPE_SMOOTH, chan_data));
printf("chan_data [CH %d]:", i);
printf("chan_data [CH %d]:", s_channel_id[i]);
for (int j = 0; j < EXAMPLE_TOUCH_SAMPLE_CFG_NUM; j++) {
printf(" %"PRIu32, chan_data[j]);
}

54
examples/peripherals/touch_sensor/touch_sens_basic/main/touch_sens_example_config.h Normal file
View File

@ -0,0 +1,54 @@
/*
* SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: CC0-1.0
*/
#pragma once
#include "driver/touch_sens.h"
#include "esp_assert.h"
#ifdef __cplusplus
extern "C" {
#endif
// Touch version 3 supports multiple sample configurations
#define EXAMPLE_TOUCH_SAMPLE_CFG_NUM TOUCH_SAMPLE_CFG_NUM // Up to 'TOUCH_SAMPLE_CFG_NUM'
#define EXAMPLE_TOUCH_CHANNEL_NUM 4
#define EXAMPLE_TOUCH_CHAN_INIT_SCAN_TIMES 3
ESP_STATIC_ASSERT(EXAMPLE_TOUCH_SAMPLE_CFG_NUM <= TOUCH_SAMPLE_CFG_NUM, "sample configuration number exceed the supported number");
ESP_STATIC_ASSERT(EXAMPLE_TOUCH_CHANNEL_NUM <= (TOUCH_MAX_CHAN_ID - TOUCH_MIN_CHAN_ID + 1), "touch channel number exceed the max supported number ");
#if SOC_TOUCH_SENSOR_VERSION == 2
#define EXAMPLE_TOUCH_SAMPLE_CFG_DEFAULT() {TOUCH_SENSOR_V2_DEFAULT_SAMPLE_CONFIG(500, TOUCH_VOLT_LIM_L_0V5, TOUCH_VOLT_LIM_H_2V2)}
#define EXAMPLE_TOUCH_CHAN_CFG_DEFAULT() { \
.active_thresh = {2000}, \
.charge_speed = TOUCH_CHARGE_SPEED_7, \
.init_charge_volt = TOUCH_INIT_CHARGE_VOLT_LOW, \
}
#elif SOC_TOUCH_SENSOR_VERSION == 3
#define EXAMPLE_TOUCH_SAMPLE_CFG(res, cap, coarse_freq_tune, fine_freq_tune) { \
.div_num = 8, \
.charge_times = 500, \
.rc_filter_res = res, \
.rc_filter_cap = cap, \
.low_drv = fine_freq_tune, \
.high_drv = coarse_freq_tune, \
.bias_volt = 5, \
.bypass_shield_output = false, \
}
#define EXAMPLE_TOUCH_SAMPLE_CFG_DEFAULT() {EXAMPLE_TOUCH_SAMPLE_CFG(3, 29, 8, 3),\
EXAMPLE_TOUCH_SAMPLE_CFG(2, 88, 31, 7), \
EXAMPLE_TOUCH_SAMPLE_CFG(3, 10, 31, 7)}
#define EXAMPLE_TOUCH_CHAN_CFG_DEFAULT() { \
.active_thresh = {1000, 2500, 5000}, \
}
#else
#error "Target not supported"
#endif
#ifdef __cplusplus
}
#endif

3
examples/peripherals/touch_sensor/touch_sensor_v3/pytest_touch_sens_v3.py → examples/peripherals/touch_sensor/touch_sens_basic/pytest_touch_sens_basic.py
View File

@ -4,8 +4,9 @@ import pytest
from pytest_embedded import Dut
@pytest.mark.esp32s2
@pytest.mark.esp32s3
@pytest.mark.esp32p4
@pytest.mark.temp_skip_ci(targets=['esp32p4'], reason='esp32p4 runners do not support touch pins')
@pytest.mark.generic
def test_touch_sens_v3(dut: Dut) -> None:
dut.expect_exact('Initial benchmark and new threshold are:')

6
examples/peripherals/touch_sensor/touch_sensor_v2/touch_pad_interrupt/CMakeLists.txt
View File

@ -1,6 +0,0 @@
# The following lines of boilerplate have to be in your project's CMakeLists
# in this exact order for cmake to work correctly
cmake_minimum_required(VERSION 3.16)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(touch_pad_interrupt)

60
examples/peripherals/touch_sensor/touch_sensor_v2/touch_pad_interrupt/README.md
View File

@ -1,60 +0,0 @@
| Supported Targets | ESP32-S2 | ESP32-S3 |
| ----------------- | -------- | -------- |
# Touch Pad Interrupt Example
(See the README.md file in the upper level 'examples' directory for more information about examples.)
This example demonstrates how to set up ESP32-S2/S3's capacitive touch pad peripheral to trigger interrupt when a pad is touched. It also shows how to detect the touch event by the software for sensor designs when greater touch detection sensitivity is required.
- The hardware interrupt mode occupies less CPU resources, but we can only apply fixed threshold and software algorithms are also impossibile.
- The polling mode is flexible and supports various software algorithms. However, it comsumes more CPU.
ESP32-S2/S3 supports touch detection by configuring hardware registers. The hardware periodically detects the pulse counts. If the number of pulse counts exceeds the set threshold, a hardware interrupt will be generated to notify the application layer that a certain touch sensor channel may be triggered.
For a simpler example how to configure and read capacitive touch pads, please refer to [touch_pad_read](../touch_pad_read).
## How to use example
### Hardware Required
* A development board with ESP32-S2 or ESP32-S3 chip
* A touch extension board like [esp32-s2-touch-devkit-1](https://docs.espressif.com/projects/espressif-esp-dev-kits/en/latest/esp32s2/esp32-s2-touch-devkit-1/user_guide.html)
### Build and Flash
Build the project and flash it to the board, then run monitor tool to view serial output:
```
idf.py -p PORT flash monitor
```
(Replace PORT with the name of the serial port to use.)
(To exit the serial monitor, type ``Ctrl-]``.)
See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
## Example Output
The application cycles between the interrupt mode and the pooling mode with a filter, to compare performance of the touch sensor system between both scenarios:
```
I (304) Touch pad: Initializing touch pad
I (304) Touch pad: Denoise function init
I (304) Touch pad: touch pad waterproof init
I (304) Touch pad: touch pad filter init 2
I (414) Touch pad: test init: touch pad [7] base 7382, thresh 1476
I (414) Touch pad: test init: touch pad [9] base 7349, thresh 1469
I (414) Touch pad: test init: touch pad [11] base 8047, thresh 1609
I (414) Touch pad: test init: touch pad [13] base 8104, thresh 810
I (5954) Touch pad: TouchSensor [9] be actived, status mask 0x200
W (6034) Touch pad: TouchSensor [13] be actived, enter guard mode
W (6034) Touch pad: In guard mode. No response
W (6174) Touch pad: TouchSensor [13] be actived, exit guard mode
I (6194) Touch pad: TouchSensor [9] be inactived, status mask 0x0
```
## Troubleshooting
For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon.

2
examples/peripherals/touch_sensor/touch_sensor_v2/touch_pad_interrupt/main/CMakeLists.txt
View File

@ -1,2 +0,0 @@
idf_component_register(SRCS "tp_interrupt_main.c"
INCLUDE_DIRS ".")

211
examples/peripherals/touch_sensor/touch_sensor_v2/touch_pad_interrupt/main/tp_interrupt_main.c
View File

@ -1,211 +0,0 @@
/*
* SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: CC0-1.0
*/
#include <stdio.h>
#include <inttypes.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "freertos/queue.h"
#include "esp_log.h"
#include "driver/touch_pad.h"
static const char *TAG = "Touch pad";
static QueueHandle_t que_touch = NULL;
typedef struct touch_msg {
touch_pad_intr_mask_t intr_mask;
uint32_t pad_num;
uint32_t pad_status;
uint32_t pad_val;
} touch_event_t;
#define TOUCH_BUTTON_NUM 4
#define TOUCH_BUTTON_WATERPROOF_ENABLE 1
#define TOUCH_BUTTON_DENOISE_ENABLE 1
#define TOUCH_CHANGE_CONFIG 0
static const touch_pad_t button[TOUCH_BUTTON_NUM] = {
TOUCH_PAD_NUM7, // 'SELECT' button.
TOUCH_PAD_NUM9, // 'MENU' button.
TOUCH_PAD_NUM11, // 'BACK' button.
TOUCH_PAD_NUM13, // Guard ring for waterproof design.
// If this pad be touched, other pads no response.
};
/*
* Touch threshold. The threshold determines the sensitivity of the touch.
* This threshold is derived by testing changes in readings from different touch channels.
* If (raw_data - benchmark) > benchmark * threshold, the pad be activated.
* If (raw_data - benchmark) < benchmark * threshold, the pad be inactivated.
*/
static const float button_threshold[TOUCH_BUTTON_NUM] = {
0.2, // 20%.
0.2, // 20%.
0.2, // 20%.
0.1, // 10%.
};
/*
Handle an interrupt triggered when a pad is touched.
Recognize what pad has been touched and save it in a table.
*/
static void touchsensor_interrupt_cb(void *arg)
{
int task_awoken = pdFALSE;
touch_event_t evt;
evt.intr_mask = touch_pad_read_intr_status_mask();
evt.pad_status = touch_pad_get_status();
evt.pad_num = touch_pad_get_current_meas_channel();
xQueueSendFromISR(que_touch, &evt, &task_awoken);
if (task_awoken == pdTRUE) {
portYIELD_FROM_ISR();
}
}
static void tp_example_set_thresholds(void)
{
uint32_t touch_value;
for (int i = 0; i < TOUCH_BUTTON_NUM; i++) {
//read benchmark value
touch_pad_read_benchmark(button[i], &touch_value);
//set interrupt threshold.
touch_pad_set_thresh(button[i], touch_value * button_threshold[i]);
ESP_LOGI(TAG, "touch pad [%d] base %"PRIu32", thresh %"PRIu32, \
button[i], touch_value, (uint32_t)(touch_value * button_threshold[i]));
}
}
static void touchsensor_filter_set(touch_filter_mode_t mode)
{
/* Filter function */
touch_filter_config_t filter_info = {
.mode = mode, // Test jitter and filter 1/4.
.debounce_cnt = 1, // 1 time count.
.noise_thr = 0, // 50%
.jitter_step = 4, // use for jitter mode.
.smh_lvl = TOUCH_PAD_SMOOTH_IIR_2,
};
touch_pad_filter_set_config(&filter_info);
touch_pad_filter_enable();
ESP_LOGI(TAG, "touch pad filter init");
}
static void tp_example_read_task(void *pvParameter)
{
touch_event_t evt = {0};
static uint8_t guard_mode_flag = 0;
/* Wait touch sensor init done */
vTaskDelay(50 / portTICK_PERIOD_MS);
tp_example_set_thresholds();
while (1) {
int ret = xQueueReceive(que_touch, &evt, (TickType_t)portMAX_DELAY);
if (ret != pdTRUE) {
continue;
}
if (evt.intr_mask & TOUCH_PAD_INTR_MASK_ACTIVE) {
/* if guard pad be touched, other pads no response. */
if (evt.pad_num == button[3]) {
guard_mode_flag = 1;
ESP_LOGW(TAG, "TouchSensor [%"PRIu32"] be activated, enter guard mode", evt.pad_num);
} else {
if (guard_mode_flag == 0) {
ESP_LOGI(TAG, "TouchSensor [%"PRIu32"] be activated, status mask 0x%"PRIu32"", evt.pad_num, evt.pad_status);
} else {
ESP_LOGW(TAG, "In guard mode. No response");
}
}
}
if (evt.intr_mask & TOUCH_PAD_INTR_MASK_INACTIVE) {
/* if guard pad be touched, other pads no response. */
if (evt.pad_num == button[3]) {
guard_mode_flag = 0;
ESP_LOGW(TAG, "TouchSensor [%"PRIu32"] be inactivated, exit guard mode", evt.pad_num);
} else {
if (guard_mode_flag == 0) {
ESP_LOGI(TAG, "TouchSensor [%"PRIu32"] be inactivated, status mask 0x%"PRIu32, evt.pad_num, evt.pad_status);
}
}
}
if (evt.intr_mask & TOUCH_PAD_INTR_MASK_SCAN_DONE) {
ESP_LOGI(TAG, "The touch sensor group measurement is done [%"PRIu32"].", evt.pad_num);
}
if (evt.intr_mask & TOUCH_PAD_INTR_MASK_TIMEOUT) {
/* Add your exception handling in here. */
ESP_LOGI(TAG, "Touch sensor channel %"PRIu32" measure timeout. Skip this exception channel!!", evt.pad_num);
touch_pad_timeout_resume(); // Point on the next channel to measure.
}
}
}
void app_main(void)
{
if (que_touch == NULL) {
que_touch = xQueueCreate(TOUCH_BUTTON_NUM, sizeof(touch_event_t));
}
// Initialize touch pad peripheral, it will start a timer to run a filter
ESP_LOGI(TAG, "Initializing touch pad");
/* Initialize touch pad peripheral. */
touch_pad_init();
for (int i = 0; i < TOUCH_BUTTON_NUM; i++) {
touch_pad_config(button[i]);
}
#if TOUCH_CHANGE_CONFIG
/* If you want change the touch sensor default setting, please write here(after initialize). There are examples: */
touch_pad_set_measurement_interval(TOUCH_PAD_SLEEP_CYCLE_DEFAULT);
touch_pad_set_charge_discharge_times(TOUCH_PAD_MEASURE_CYCLE_DEFAULT);
touch_pad_set_voltage(TOUCH_PAD_HIGH_VOLTAGE_THRESHOLD, TOUCH_PAD_LOW_VOLTAGE_THRESHOLD, TOUCH_PAD_ATTEN_VOLTAGE_THRESHOLD);
touch_pad_set_idle_channel_connect(TOUCH_PAD_IDLE_CH_CONNECT_DEFAULT);
for (int i = 0; i < TOUCH_BUTTON_NUM; i++) {
touch_pad_set_cnt_mode(button[i], TOUCH_PAD_SLOPE_DEFAULT, TOUCH_PAD_TIE_OPT_DEFAULT);
}
#endif
#if TOUCH_BUTTON_DENOISE_ENABLE
/* Denoise setting at TouchSensor 0. */
touch_pad_denoise_t denoise = {
/* The bits to be cancelled are determined according to the noise level. */
.grade = TOUCH_PAD_DENOISE_BIT4,
/* By adjusting the parameters, the reading of T0 should be approximated to the reading of the measured channel. */
.cap_level = TOUCH_PAD_DENOISE_CAP_L4,
};
touch_pad_denoise_set_config(&denoise);
touch_pad_denoise_enable();
ESP_LOGI(TAG, "Denoise function init");
#endif
#if TOUCH_BUTTON_WATERPROOF_ENABLE
/* Waterproof function */
touch_pad_waterproof_t waterproof = {
.guard_ring_pad = button[3], // If no ring pad, set 0;
/* It depends on the number of the parasitic capacitance of the shield pad.
Based on the touch readings of T14 and T0, estimate the size of the parasitic capacitance on T14
and set the parameters of the appropriate hardware. */
.shield_driver = TOUCH_PAD_SHIELD_DRV_L2,
};
touch_pad_waterproof_set_config(&waterproof);
touch_pad_waterproof_enable();
ESP_LOGI(TAG, "touch pad waterproof init");
#endif
/* Filter setting */
touchsensor_filter_set(TOUCH_PAD_FILTER_IIR_16);
touch_pad_timeout_set(true, TOUCH_PAD_THRESHOLD_MAX);
/* Register touch interrupt ISR, enable intr type. */
touch_pad_isr_register(touchsensor_interrupt_cb, NULL, TOUCH_PAD_INTR_MASK_ALL);
/* If you have other touch algorithm, you can get the measured value after the `TOUCH_PAD_INTR_MASK_SCAN_DONE` interrupt is generated. */
touch_pad_intr_enable(TOUCH_PAD_INTR_MASK_ACTIVE | TOUCH_PAD_INTR_MASK_INACTIVE | TOUCH_PAD_INTR_MASK_TIMEOUT);
/* Enable touch sensor clock. Work mode is "timer trigger". */
touch_pad_set_fsm_mode(TOUCH_FSM_MODE_TIMER);
touch_pad_fsm_start();
// Start a task to show what pads have been touched
xTaskCreate(&tp_example_read_task, "touch_pad_read_task", 4096, NULL, 5, NULL);
}

15
examples/peripherals/touch_sensor/touch_sensor_v2/touch_pad_interrupt/pytest_touch_pad_interrupt_v2.py
View File

@ -1,15 +0,0 @@
# SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
# SPDX-License-Identifier: Unlicense OR CC0-1.0
import pytest
from pytest_embedded import Dut
@pytest.mark.esp32s2
@pytest.mark.esp32s3
@pytest.mark.generic
def test_touch_pad_interrupt_v2(dut: Dut) -> None:
dut.expect_exact('Touch pad: Initializing touch pad')
dut.expect_exact('Touch pad: Denoise function init')
dut.expect_exact('Touch pad: touch pad waterproof init')
dut.expect_exact('Touch pad: touch pad filter init')
dut.expect(r'touch pad \[\d+\] base \d+, thresh \d+')

6
examples/peripherals/touch_sensor/touch_sensor_v2/touch_pad_read/CMakeLists.txt
View File

@ -1,6 +0,0 @@
# The following lines of boilerplate have to be in your project's CMakeLists
# in this exact order for cmake to work correctly
cmake_minimum_required(VERSION 3.16)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(touch_pad_read)

50
examples/peripherals/touch_sensor/touch_sensor_v2/touch_pad_read/README.md
View File

@ -1,50 +0,0 @@
| Supported Targets | ESP32-S2 | ESP32-S3 |
| ----------------- | -------- | -------- |
# Touch Pad Read Example
(See the README.md file in the upper level 'examples' directory for more information about examples.)
Read and display raw values from capacitive touch pad sensors.
Once configured, ESP32S2/S3 will continuously measure capacitance of touch pad sensors. Measurement is reflected as numeric value inversely related to sensor's capacitance. With a finger touched on a pad, its capacitance will get larger meanwhile the measured value gets smaller, and vice versa.
To detect if a sensor is touched or not, each particular design should be calibrated by obtaining both measurements for each individual sensor. Then a threshold between both values can be established. With specific threshold, API is then able to distinguish whether specific sensor is touched or released. For ESP32-S2/S3, the hardware integrates the edge detection algorithm, which can achieve the purpose of detecting touch actions by configuring appropriate parameters. There is another similar example that demonstrates how to perform simple calibration and trigger an interrupt when a pad is touched - see [touch_pad_interrupt](../touch_pad_interrupt).
## How to use example
### Hardware Required
* A development board with ESP32-S2 or ESP32-S3 chip
* A touch extension board like [esp32-s2-touch-devkit-1](https://docs.espressif.com/projects/espressif-esp-dev-kits/en/latest/esp32s2/esp32-s2-touch-devkit-1/user_guide.html)
### Build and Flash
Build the project and flash it to the board, then run monitor tool to view serial output:
```
idf.py -p PORT flash monitor
```
(Replace PORT with the name of the serial port to use.)
(To exit the serial monitor, type ``Ctrl-]``.)
See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
## Example Output
ESP32-S2/S3 supports up to 14 capacitive touch pads, T1 - T14, which are connected to the specific GPIO pins. For the information of available pins please refer to ESP32-S2/S3 Technical Reference Manual. Note that T0 is an internal channel with no corresponding GPIO, it is mainly used for de-noise. This example will initialize all the 14 touch pads. The raw values of each pad can be monitored in the terminal:
```
Touch Sensor read, the output format is:
Touchpad num:[raw data]
T1: [6473] T2: [6507] T3: [6638] T4: [8917] T5: [9053] T6: [7190] T7: [7176] T8: [7416] T9: [7145] T10: [7387] T11: [7973] T12: [7776] T13: [8151] T14: [8190]
T1: [6463] T2: [6512] T3: [6643] T4: [8920] T5: [9050] T6: [7191] T7: [7176] T8: [7416] T9: [7143] T10: [7387] T11: [7974] T12: [7778] T13: [8152] T14: [8192]
T1: [6476] T2: [6508] T3: [6641] T4: [8919] T5: [9053] T6: [7190] T7: [7177] T8: [7416] T9: [7143] T10: [7386] T11: [7974] T12: [7776] T13: [8153] T14: [8193]
```
## Troubleshooting
For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon.

2
examples/peripherals/touch_sensor/touch_sensor_v2/touch_pad_read/main/CMakeLists.txt
View File

@ -1,2 +0,0 @@
idf_component_register(SRCS "tp_read_main.c"
INCLUDE_DIRS ".")

90
examples/peripherals/touch_sensor/touch_sensor_v2/touch_pad_read/main/tp_read_main.c
View File

@ -1,90 +0,0 @@
/*
* SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: CC0-1.0
*/
#include <stdio.h>
#include <inttypes.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/touch_pad.h"
#include "esp_log.h"
#define TOUCH_BUTTON_NUM 14
#define TOUCH_CHANGE_CONFIG 0
static const char *TAG = "touch read";
static const touch_pad_t button[TOUCH_BUTTON_NUM] = {
TOUCH_PAD_NUM1,
TOUCH_PAD_NUM2,
TOUCH_PAD_NUM3,
TOUCH_PAD_NUM4,
TOUCH_PAD_NUM5,
TOUCH_PAD_NUM6,
TOUCH_PAD_NUM7,
TOUCH_PAD_NUM8,
TOUCH_PAD_NUM9,
TOUCH_PAD_NUM10,
TOUCH_PAD_NUM11,
TOUCH_PAD_NUM12,
TOUCH_PAD_NUM13,
TOUCH_PAD_NUM14
};
/*
Read values sensed at all available touch pads.
Print out values in a loop on a serial monitor.
*/
static void tp_example_read_task(void *pvParameter)
{
uint32_t touch_value;
/* Wait touch sensor init done */
vTaskDelay(100 / portTICK_PERIOD_MS);
printf("Touch Sensor read, the output format is: \nTouchpad num:[raw data]\n\n");
while (1) {
for (int i = 0; i < TOUCH_BUTTON_NUM; i++) {
touch_pad_read_raw_data(button[i], &touch_value); // read raw data.
printf("T%d: [%4"PRIu32"] ", button[i], touch_value);
}
printf("\n");
vTaskDelay(200 / portTICK_PERIOD_MS);
}
}
void app_main(void)
{
/* Initialize touch pad peripheral. */
touch_pad_init();
for (int i = 0; i < TOUCH_BUTTON_NUM; i++) {
touch_pad_config(button[i]);
}
#if TOUCH_CHANGE_CONFIG
/* If you want change the touch sensor default setting, please write here(after initialize). There are examples: */
touch_pad_set_measurement_interval(TOUCH_PAD_SLEEP_CYCLE_DEFAULT);
touch_pad_set_charge_discharge_times(TOUCH_PAD_MEASURE_CYCLE_DEFAULT);
touch_pad_set_voltage(TOUCH_PAD_HIGH_VOLTAGE_THRESHOLD, TOUCH_PAD_LOW_VOLTAGE_THRESHOLD, TOUCH_PAD_ATTEN_VOLTAGE_THRESHOLD);
touch_pad_set_idle_channel_connect(TOUCH_PAD_IDLE_CH_CONNECT_DEFAULT);
for (int i = 0; i < TOUCH_BUTTON_NUM; i++) {
touch_pad_set_cnt_mode(button[i], TOUCH_PAD_SLOPE_DEFAULT, TOUCH_PAD_TIE_OPT_DEFAULT);
}
#endif
/* Denoise setting at TouchSensor 0. */
touch_pad_denoise_t denoise = {
/* The bits to be cancelled are determined according to the noise level. */
.grade = TOUCH_PAD_DENOISE_BIT4,
.cap_level = TOUCH_PAD_DENOISE_CAP_L4,
};
touch_pad_denoise_set_config(&denoise);
touch_pad_denoise_enable();
ESP_LOGI(TAG, "Denoise function init");
/* Enable touch sensor clock. Work mode is "timer trigger". */
touch_pad_set_fsm_mode(TOUCH_FSM_MODE_TIMER);
touch_pad_fsm_start();
/* Start task to read values by pads. */
xTaskCreate(&tp_example_read_task, "touch_pad_read_task", 4096, NULL, 5, NULL);
}

13
examples/peripherals/touch_sensor/touch_sensor_v2/touch_pad_read/pytest_touch_pad_read_v2.py
View File

@ -1,13 +0,0 @@
# SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
# SPDX-License-Identifier: Unlicense OR CC0-1.0
import pytest
from pytest_embedded import Dut
@pytest.mark.esp32s2
@pytest.mark.esp32s3
@pytest.mark.generic
def test_touch_pad_read_v2(dut: Dut) -> None:
dut.expect_exact('touch read: Denoise function init')
dut.expect(r'T1: \[\d+\] T2: \[\d+\] T3: \[\d+\] T4: \[\d+\] T5: \[\d+\] T6: \[\d+\] T7: \[\d+\] T8: \[\d+\] T9: \[\d+\]'
r' T10: \[\d+\] T11: \[\d+\] T12: \[\d+\] T13: \[\d+\] T14: \[\d+\]')

2
examples/system/deep_sleep/main/Kconfig.projbuild
View File

@ -3,7 +3,7 @@ menu "Example Configuration"
config EXAMPLE_TOUCH_WAKEUP
bool "Enable touch wake up"
default y
depends on SOC_PM_SUPPORT_TOUCH_SENSOR_WAKEUP
depends on SOC_PM_SUPPORT_TOUCH_SENSOR_WAKEUP && !IDF_TARGET_ESP32P4
help
This option enables wake up from deep sleep using touch pads.
ESP32 - TOUCH8 and TOUCH9, which correspond to GPIO33 and GPIO32.

2
examples/system/deep_sleep/main/touch_wakeup.c
View File

@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Unlicense OR CC0-1.0
*/

1
examples/system/deep_sleep/sdkconfig.defaults
View File

@ -6,3 +6,4 @@ CONFIG_NEWLIB_TIME_SYSCALL_USE_RTC_HRT=y
CONFIG_RTC_CLK_SRC_INT_RC=y
CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP=y
CONFIG_PARTITION_TABLE_CUSTOM=y
CONFIG_TOUCH_SUPPRESS_DEPRECATE_WARN=y

2
examples/system/ulp/ulp_riscv/touch/main/ulp_riscv_touch_example_main.c
View File

@ -10,7 +10,7 @@
#include "esp_sleep.h"
#include "ulp_riscv.h"
#include "ulp_main.h"
#include "driver/touch_pad.h"
#include "driver/touch_sensor.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"

1
examples/system/ulp/ulp_riscv/touch/sdkconfig.defaults
View File

@ -7,3 +7,4 @@ CONFIG_BOOTLOADER_LOG_LEVEL_WARN=y
CONFIG_BOOTLOADER_LOG_LEVEL=2
CONFIG_LOG_DEFAULT_LEVEL_WARN=y
CONFIG_LOG_DEFAULT_LEVEL=2
CONFIG_TOUCH_SUPPRESS_DEPRECATE_WARN=y