# 触摸传感器

[English]

## 概述

触摸传感器系统由保护覆盖层、触摸电极、绝缘基板和走线组成，保护覆盖层位于最上层，绝缘基板上设有电极及走线。触摸覆盖层将引起电容变化，根据电容变化，可以判断此次触摸是否为有效触摸行为。

触摸传感器可以以矩阵或滑条等方式组合使用，从而覆盖更大触感区域及更多触感点。触摸传感由软件或专用硬件计时器发起，由有限状态机 (FSM) 硬件控制。

如需了解触摸传感器设计、操作及其控制寄存器等相关信息，请参考《ESP32-S3 技术参考手册》(PDF) 中“片上传感器与模拟信号处理”章节。

请参考 触摸传感器应用方案简介，查看触摸传感器设计详情和固件开发指南。

## 功能介绍

下面将 API 分解成几个函数组进行介绍：

- 初始化触摸传感器驱动程序

- 配置触摸传感器 GPIO 管脚

- 触摸状态测量

- 调整测量参数（优化测量）

- 滤波采样

- 触摸监测方式

- 设置中断信号监测触碰动作

- 中断触发，唤醒睡眠模式

请前往 API 参考 章节，查看某一函数的具体描述。应用示例 章节则介绍了此 API 的具体实现。

### 初始化触摸传感器驱动程序

使用触摸传感器之前，需要先调用 `touch_pad_init()` 函数初始化触摸传感器驱动程序。此函数设置了 API 参考 项下的 Macros 中列出的几项 `.._DEFAULT` 驱动程序参数，同时删除之前设置过的触摸传感器信息（如有），并禁用中断。

如果不再需要该驱动程序，可以调用 `touch_pad_deinit()` 释放已初始化的驱动程序。

### 配置触摸传感器 GPIO 管脚

可调用 `touch_pad_config()` 使能某一 GPIO 的触感功能。ESP32-S3 最多可支持 14 个电容式触摸传感器通道。

触摸传感器通道 | 管脚
--- | ---
T0 | 内部通道，无对应管脚
T1 | GPIO1
T2 | GPIO2
T3 | GPIO3
T4 | GPIO4
T5 | GPIO5
T6 | GPIO6
T7 | GPIO7
T8 | GPIO8
T9 | GPIO9
T10 | GPIO10
T11 | GPIO11
T12 | GPIO12
T13 | GPIO13
T14 | GPIO14

使用 `touch_pad_set_fsm_mode()` 选择触摸传感器测量（由 FSM 操作）是由硬件定时器自动启动，还是由软件自动启动。如果选择软件模式，请使用 `touch_pad_sw_start()` 启动 FSM。

### 触摸状态测量

借助以下函数从传感器读取原始数据：

- `touch_pad_read_raw_data()`

该函数也可以用于检查触碰和释放触摸传感器时传感器读数变化范围，然后根据这些信息设定触摸传感器的触摸阈值。

请参考应用示例 peripherals/touch_sensor/touch_sensor_v2/touch_pad_read，查看如何使用读取触摸传感器数据。

### 测量方式

触摸传感器会统计固定充放电次数所需的时间（即所需时钟周期数），其结果即为原始数据，可由 `touch_pad_read_raw_data()` 读出。上述固定的充放电次数可通过 `touch_pad_set_charge_discharge_times()` 设置。完成一次测量后，触摸传感器会在下次测量开始前保持睡眠状态。两次测量之前的间隔时间可由 `touch_pad_set_measurement_interval()` 进行设置。

备注

若设置的充放电次数太少，则可能导致结果不准确，但是充放电次数过多也会造成功耗上升。另外，若睡眠时间加测量时间的总时间过长，则会造成触摸传感器响应变慢。

### 优化测量

触摸传感器设有数个可配置参数，以适应触摸传感器设计特点。例如，如果需要感知较细微的电容变化，则可以缩小触摸传感器充放电的参考电压范围。使用 `touch_pad_set_voltage()` 函数，可以设置电压参考低值和参考高值。

优化测量除了可以识别细微的电容变化之外，还可以降低应用程序功耗，但可能会增加测量噪声干扰。如果得到的动态读数范围结果比较理想，则可以调用 `touch_pad_set_charge_discharge_times()` 函数来减少测量时间，从而进一步降低功耗。

可用的测量参数及相应的 'set' 函数总结如下：

- 触摸传感器充放电参数：

  > - 电压门限：`touch_pad_set_voltage()`

  > - 速率（斜率）：`touch_pad_set_cnt_mode()`

- 单次测量所需充放电次数：`touch_pad_set_charge_discharge_times()`

电压门限（参考低值/参考高值）、速率（斜率）与测量时间的关系如下图所示：

触摸传感器 - 测量参数之间的关系

上图中的 Output 代表触摸传感器读值，即固定充放电次数所需的时间。

所有函数均成对出现，用于设定某一特定参数，并获取当前参数值。例如：`touch_pad_set_voltage()` 和 `touch_pad_get_voltage()`。

### 滤波采样

如果测量中存在噪声，可以使用提供的 API 函数对采样进行滤波。ESP32-S3 的触摸功能提供了两套 API 可实现此功能。

一个是内部触摸通道，它没有连接到任何外部 GPIO。该降噪板的测量值可用于过滤所有通道上的干扰，如来自电源和外部 EMI 的噪声。

降噪参数由 `touch_pad_denoise_set_config()` 设置并由 `touch_pad_denoise_enable()` 启动。

另一是可配置的硬件实现 IIR-滤波器（无限脉冲响应滤波器），该滤波器可通过调用 `touch_pad_filter_set_config()` 函数进行配置，调用 `touch_pad_filter_enable()` 函数启用。

### 触摸监测

触摸监测基于配置的阈值和 FSM 执行的原始测量，并由 ESP32 硬件实现。可以调用 `touch_pad_get_status()` 查看被触碰的触摸传感器，或调用 `touch_pad_clear_status()` 清除触摸状态信息。

也可以将硬件触摸监测连接至中断，详细介绍见下一章节。

如果测量中存在噪声，且电容变化幅度较小，硬件触摸监测结果可能就不太理想。如需解决这一问题，不建议使用硬件监测或中断信号，建议在自己的应用程序中进行采样滤波，并执行触摸监测。请参考 peripherals/touch_sensor/touch_sensor_v2/touch_pad_interrupt，查看以上两种触摸监测的实现方式。

### 中断触发

在对触摸监测启用中断之前，请先设置一个触摸监测阈值。然后使用 触摸状态测量 中所述的函数读取并显示触摸和释放触摸传感器时测得的结果。如果测量中存在噪声且相对电容变化较小，请使用滤波器。也可以根据应用程序和环境条件，测试温度和电源电压变化对测量值的影响。

确定监测阈值后就可以在初始化时调用 `touch_pad_config()` 设置此阈值，或在运行时调用 `touch_pad_set_thresh()` 设置此阈值。

最后可以使用以下函数配置和管理中断调用：

- `touch_pad_isr_register()` / `touch_pad_isr_deregister()`

- `touch_pad_intr_enable()` / `touch_pad_intr_disable()`

中断配置完成后，可以调用 `touch_pad_get_status()` 查看中断信号来自哪个触摸传感器，也可以调用 `touch_pad_clear_status()` 清除触摸传感器状态信息。

## 应用示例

- peripherals/touch_sensor/touch_sensor_v2/touch_pad_read 演示了如何在 ESP32-S3 上读取并显示电容触摸传感器的原始值，包括如何校准传感器以及监测触摸动作。

- peripherals/touch_sensor/touch_sensor_v2/touch_pad_interrupt 演示了如何设置 ESP32-S3 的电容触摸板外设，使其在被触摸时触发中断，以及在需要更高触摸监测灵敏度的传感器设计中，如何通过软件来监测触摸事件。

## API 参考

### Header File

- components/driver/touch_sensor/esp32s3/include/driver/touch_sensor.h

- This header file can be included with:

  >     #include "driver/touch_sensor.h"

- This header file is a part of the API provided by the `driver` component. To declare that your component depends on `driver`, add the following to your CMakeLists.txt:

  >     REQUIRES driver

  > or

  >     PRIV_REQUIRES driver

### Functions

esp_err_t touch_pad_fsm_start(void)

  Set touch sensor FSM start.

  备注

  Start FSM after the touch sensor FSM mode is set.

  备注

  Call this function will reset benchmark of all touch channels.

  返回:

    - ESP_OK on success

esp_err_t touch_pad_fsm_stop(void)

  Stop touch sensor FSM.

  返回:

    - ESP_OK on success

esp_err_t touch_pad_sw_start(void)

  Trigger a touch sensor measurement, only support in SW mode of FSM.

  返回:

    - ESP_OK on success

esp_err_t touch_pad_set_charge_discharge_times(uint16_t charge_discharge_times)

  Set charge and discharge times of each measurement.

  备注

  This function will specify the charge and discharge times in each measurement period The clock is sourced from SOC_MOD_CLK_RTC_FAST, and its default frequency is SOC_CLK_RC_FAST_FREQ_APPROX The touch sensor will record the total clock cycles of all the charge and discharge cycles as the final result (raw value)

  备注

  If the charge and discharge times is too small, it may lead to inaccurate results.

  参数:

    charge_discharge_times -- Charge and discharge times, range: 0 ~ 0xffff. No exact typical value can be recommended because the capacity is influenced by the hardware design and how finger touches, but suggest adjusting this value to make the measurement time around 1 ms.

  返回:

    - ESP_OK Set charge and discharge times success

esp_err_t touch_pad_get_charge_discharge_times(uint16_t *charge_discharge_times)

  Get charge and discharge times of each measurement.

  参数:

    charge_discharge_times -- Charge and discharge times

  返回:

    - ESP_OK Get charge_discharge_times success

    - ESP_ERR_INVALID_ARG The input parameter is NULL

esp_err_t touch_pad_set_measurement_interval(uint16_t interval_cycle)

  Set the interval between two measurements.

  备注

  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

  参数:

    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.

  返回:

    - ESP_OK Set interval cycle success

esp_err_t touch_pad_get_measurement_interval(uint16_t *interval_cycle)

  Get the interval between two measurements.

  参数:

    interval_cycle -- The interval between two measurements

  返回:

    - ESP_OK Get interval cycle success

    - ESP_ERR_INVALID_ARG The input parameter is NULL

esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_times)

  Set touch sensor times of charge and discharge and sleep time. Excessive total time will slow down the touch response. Too small measurement time will not be sampled enough, resulting in inaccurate measurements.

  备注

  The touch sensor will measure time of a fixed number of charge/discharge cycles (specified as the second parameter). That means the time (raw value) will increase as the capacity of the touch pad is increasing. The time (raw value) here is the number of clock cycles which is sourced from SOC_MOD_CLK_RTC_FAST and at (SOC_CLK_RC_FAST_FREQ_APPROX) Hz as default

  备注

  The greater the duty cycle of the measurement time, the more system power is consumed.

  参数:

    - 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.

    - meas_times -- The times of charge and discharge in each measurement of touch channels. Range: 0 ~ 0xffff. Recommended typical value: Modify this value to make the measurement time around 1 ms.

  返回:

    - ESP_OK on success

esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_times)

  Get touch sensor times of charge and discharge and sleep time.

  参数:

    - sleep_cycle -- Pointer to accept sleep cycle number

    - meas_times -- Pointer to accept measurement times count.

  返回:

    - ESP_OK on success

esp_err_t touch_pad_set_idle_channel_connect(touch_pad_conn_type_t type)

  Set the connection type of touch channels in idle status. When a channel is in measurement mode, other initialized channels are in idle mode. The touch channel is generally adjacent to the trace, so the connection state of the idle channel affects the stability and sensitivity of the test channel. The `CONN_HIGHZ`(high resistance) setting increases the sensitivity of touch channels. The `CONN_GND`(grounding) setting increases the stability of touch channels.

  参数:

    type -- Select idle channel connect to high resistance state or ground.

  返回:

    - ESP_OK on success

esp_err_t touch_pad_get_idle_channel_connect(touch_pad_conn_type_t *type)

  Get the connection type of touch channels in idle status. When a channel is in measurement mode, other initialized channels are in idle mode. The touch channel is generally adjacent to the trace, so the connection state of the idle channel affects the stability and sensitivity of the test channel. The `CONN_HIGHZ`(high resistance) setting increases the sensitivity of touch channels. The `CONN_GND`(grounding) setting increases the stability of touch channels.

  参数:

    type -- Pointer to connection type.

  返回:

    - ESP_OK on success

esp_err_t touch_pad_set_thresh(touch_pad_t touch_num, uint32_t threshold)

  Set the trigger threshold of touch sensor. The threshold determines the sensitivity of the touch sensor. The threshold is the original value of the trigger state minus the benchmark value.

  备注

  If set "TOUCH_PAD_THRESHOLD_MAX", the touch is never be triggered.

  参数:

    - touch_num -- touch pad index

    - threshold -- threshold of touch sensor. Should be less than the max change value of touch.

  返回:

    - ESP_OK on success

esp_err_t touch_pad_get_thresh(touch_pad_t touch_num, uint32_t *threshold)

  Get touch sensor trigger threshold.

  参数:

    - touch_num -- touch pad index

    - threshold -- pointer to accept threshold

  返回:

    - ESP_OK on success

    - ESP_ERR_INVALID_ARG if argument is wrong

esp_err_t touch_pad_set_channel_mask(uint16_t enable_mask)

  Register touch channel into touch sensor scan group. The working mode of the touch sensor is cyclically scanned. This function will set the scan bits according to the given bitmask.

  备注

  If set this mask, the FSM timer should be stop firsty.

  备注

  The touch sensor that in scan map, should be deinit GPIO function firstly by `touch_pad_io_init`.

  参数:

    enable_mask -- bitmask of touch sensor scan group. e.g. TOUCH_PAD_NUM14 -> BIT(14)

  返回:

    - ESP_OK on success

esp_err_t touch_pad_get_channel_mask(uint16_t *enable_mask)

  Get the touch sensor scan group bit mask.

  参数:

    enable_mask -- Pointer to bitmask of touch sensor scan group. e.g. TOUCH_PAD_NUM14 -> BIT(14)

  返回:

    - ESP_OK on success

esp_err_t touch_pad_clear_channel_mask(uint16_t enable_mask)

  Clear touch channel from touch sensor scan group. The working mode of the touch sensor is cyclically scanned. This function will clear the scan bits according to the given bitmask.

  备注

  If clear all mask, the FSM timer should be stop firsty.

  参数:

    enable_mask -- bitmask of touch sensor scan group. e.g. TOUCH_PAD_NUM14 -> BIT(14)

  返回:

    - ESP_OK on success

esp_err_t touch_pad_config(touch_pad_t touch_num)

  Configure parameter for each touch channel.

  备注

  Touch num 0 is denoise channel, please use `touch_pad_denoise_enable` to set denoise function

  参数:

    touch_num -- touch pad index

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG if argument wrong

    - ESP_FAIL if touch pad not initialized

esp_err_t touch_pad_reset(void)

  Reset the FSM of touch module.

  备注

  Call this function after `touch_pad_fsm_stop`.

  返回:

    - ESP_OK Success

touch_pad_t touch_pad_get_current_meas_channel(void)

  Get the current measure channel.

  备注

  Should be called when touch sensor measurement is in cyclic scan mode.

  返回:

    - touch channel number

uint32_t touch_pad_read_intr_status_mask(void)

  Get the touch sensor interrupt status mask.

  返回:

    - touch interrupt bit

esp_err_t touch_pad_intr_enable(touch_pad_intr_mask_t int_mask)

  Enable touch sensor interrupt by bitmask.

  备注

  This API can be called in ISR handler.

  参数:

    int_mask -- Pad mask to enable interrupts

  返回:

    - ESP_OK on success

esp_err_t touch_pad_intr_disable(touch_pad_intr_mask_t int_mask)

  Disable touch sensor interrupt by bitmask.

  备注

  This API can be called in ISR handler.

  参数:

    int_mask -- Pad mask to disable interrupts

  返回:

    - ESP_OK on success

esp_err_t touch_pad_intr_clear(touch_pad_intr_mask_t int_mask)

  Clear touch sensor interrupt by bitmask.

  参数:

    int_mask -- Pad mask to clear interrupts

  返回:

    - ESP_OK on success

esp_err_t touch_pad_isr_register(intr_handler_t fn, void *arg, touch_pad_intr_mask_t intr_mask)

  Register touch-pad ISR. The handler will be attached to the same CPU core that this function is running on.

  参数:

    - fn -- Pointer to ISR handler

    - arg -- Parameter for ISR

    - intr_mask -- Enable touch sensor interrupt handler by bitmask.

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG Arguments error

    - ESP_ERR_NO_MEM No memory

esp_err_t touch_pad_timeout_set(bool enable, uint32_t threshold)

  Enable/disable the timeout check and set timeout threshold for all touch sensor channels measurements. If enable: When the touch reading of a touch channel exceeds the measurement threshold, a timeout interrupt will be generated. If disable: the FSM does not check if the channel under measurement times out.

  备注

  The threshold compared with touch readings.

  备注

  In order to avoid abnormal short circuit of some touch channels. This function should be turned on. Ensure the normal operation of other touch channels.

  参数:

    - enable -- true(default): Enable the timeout check; false: Disable the timeout check.

    - threshold -- For all channels, the maximum value that will not be exceeded during normal operation.

  返回:

    - ESP_OK Success

esp_err_t touch_pad_timeout_resume(void)

  Call this interface after timeout to make the touch channel resume normal work. Point on the next channel to measure. If this API is not called, the touch FSM will stop the measurement after timeout interrupt.

  备注

  Call this API after finishes the exception handling by user.

  返回:

    - ESP_OK Success

esp_err_t touch_pad_read_raw_data(touch_pad_t touch_num, uint32_t *raw_data)

  get raw data of touch sensor.

  备注

  After the initialization is complete, the "raw_data" is max value. You need to wait for a measurement cycle before you can read the correct touch value.

  参数:

    - touch_num -- touch pad index

    - raw_data -- pointer to accept touch sensor value

  返回:

    - ESP_OK Success

    - ESP_FAIL Touch channel 0 haven't this parameter.

esp_err_t touch_pad_read_benchmark(touch_pad_t touch_num, uint32_t *benchmark)

  get benchmark of touch sensor.

  备注

  After initialization, the benchmark value is the maximum during the first measurement period.

  参数:

    - touch_num -- touch pad index

    - benchmark -- pointer to accept touch sensor benchmark value

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG Touch channel 0 haven't this parameter.

esp_err_t touch_pad_filter_read_smooth(touch_pad_t touch_num, uint32_t *smooth)

  Get smoothed data that obtained by filtering the raw data.

  参数:

    - touch_num -- touch pad index

    - smooth -- pointer to smoothed data

esp_err_t touch_pad_reset_benchmark(touch_pad_t touch_num)

  Force reset benchmark to raw data of touch sensor.

  参数:

    touch_num -- touch pad index

    - TOUCH_PAD_MAX Reset basaline of all channels

  返回:

    - ESP_OK Success

esp_err_t touch_pad_filter_set_config(const touch_filter_config_t *filter_info)

  set parameter of touch sensor filter and detection algorithm. For more details on the detection algorithm, please refer to the application documentation.

  参数:

    filter_info -- select filter type and threshold of detection algorithm

  返回:

    - ESP_OK Success

esp_err_t touch_pad_filter_get_config(touch_filter_config_t *filter_info)

  get parameter of touch sensor filter and detection algorithm. For more details on the detection algorithm, please refer to the application documentation.

  参数:

    filter_info -- select filter type and threshold of detection algorithm

  返回:

    - ESP_OK Success

esp_err_t touch_pad_filter_enable(void)

  enable touch sensor filter for detection algorithm. For more details on the detection algorithm, please refer to the application documentation.

  返回:

    - ESP_OK Success

esp_err_t touch_pad_filter_disable(void)

  disable touch sensor filter for detection algorithm. For more details on the detection algorithm, please refer to the application documentation.

  返回:

    - ESP_OK Success

esp_err_t touch_pad_denoise_set_config(const touch_pad_denoise_t *denoise)

  set parameter of denoise pad (TOUCH_PAD_NUM0). T0 is an internal channel that does not have a corresponding external GPIO. T0 will work simultaneously with the measured channel Tn. Finally, the actual measured value of Tn is the value after subtracting lower bits of T0. The noise reduction function filters out interference introduced simultaneously on all channels, such as noise introduced by power supplies and external EMI.

  参数:

    denoise -- parameter of denoise

  返回:

    - ESP_OK Success

esp_err_t touch_pad_denoise_get_config(touch_pad_denoise_t *denoise)

  get parameter of denoise pad (TOUCH_PAD_NUM0).

  参数:

    denoise -- Pointer to parameter of denoise

  返回:

    - ESP_OK Success

esp_err_t touch_pad_denoise_enable(void)

  enable denoise function. T0 is an internal channel that does not have a corresponding external GPIO. T0 will work simultaneously with the measured channel Tn. Finally, the actual measured value of Tn is the value after subtracting lower bits of T0. The noise reduction function filters out interference introduced simultaneously on all channels, such as noise introduced by power supplies and external EMI.

  返回:

    - ESP_OK Success

esp_err_t touch_pad_denoise_disable(void)

  disable denoise function.

  返回:

    - ESP_OK Success

esp_err_t touch_pad_denoise_read_data(uint32_t *data)

  Get denoise measure value (TOUCH_PAD_NUM0).

  参数:

    data -- Pointer to receive denoise value

  返回:

    - ESP_OK Success

esp_err_t touch_pad_waterproof_set_config(const touch_pad_waterproof_t *waterproof)

  set parameter of waterproof function.

         The waterproof function includes a shielded channel (TOUCH_PAD_NUM14) and a guard channel.
         Guard pad is used to detect the large area of water covering the touch panel.
         Shield pad is used to shield the influence of water droplets covering the touch panel.
         It is generally designed as a grid and is placed around the touch buttons.

  参数:

    waterproof -- parameter of waterproof

  返回:

    - ESP_OK Success

esp_err_t touch_pad_waterproof_get_config(touch_pad_waterproof_t *waterproof)

  get parameter of waterproof function.

  参数:

    waterproof -- parameter of waterproof

  返回:

    - ESP_OK Success

esp_err_t touch_pad_waterproof_enable(void)

  Enable parameter of waterproof function. Should be called after function `touch_pad_waterproof_set_config`.

  返回:

    - ESP_OK Success

esp_err_t touch_pad_waterproof_disable(void)

  Disable parameter of waterproof function.

  返回:

    - ESP_OK Success

esp_err_t touch_pad_proximity_enable(touch_pad_t touch_num, bool enabled)

  Enable/disable proximity function of touch channels. The proximity sensor measurement is the accumulation of touch channel measurements.

  备注

  Supports up to three touch channels configured as proximity sensors.

  参数:

    - touch_num -- touch pad index

    - enabled -- true: enable the proximity function; false: disable the proximity function

  返回:

    - ESP_OK: Configured correctly.

    - ESP_ERR_INVALID_ARG: Touch channel number error.

    - ESP_ERR_NOT_SUPPORTED: Don't support configured.

esp_err_t touch_pad_proximity_set_count(touch_pad_t touch_num, uint32_t count)

  Set measure count of proximity channel. The proximity sensor measurement is the accumulation of touch channel measurements.

  备注

  All proximity channels use the same `count` value. So please pass the parameter `TOUCH_PAD_MAX`.

  参数:

    - touch_num -- Touch pad index. In this version, pass the parameter `TOUCH_PAD_MAX`.

    - count -- The cumulative times of measurements for proximity pad. Range: 0 ~ 255.

  返回:

    - ESP_OK: Configured correctly.

    - ESP_ERR_INVALID_ARG: Touch channel number error.

esp_err_t touch_pad_proximity_get_count(touch_pad_t touch_num, uint32_t *count)

  Get measure count of proximity channel. The proximity sensor measurement is the accumulation of touch channel measurements.

  备注

  All proximity channels use the same `count` value. So please pass the parameter `TOUCH_PAD_MAX`.

  参数:

    - touch_num -- Touch pad index. In this version, pass the parameter `TOUCH_PAD_MAX`.

    - count -- The cumulative times of measurements for proximity pad. Range: 0 ~ 255.

  返回:

    - ESP_OK: Configured correctly.

    - ESP_ERR_INVALID_ARG: Touch channel number error.

esp_err_t touch_pad_proximity_get_data(touch_pad_t touch_num, uint32_t *measure_out)

  Get the accumulated measurement of the proximity sensor. The proximity sensor measurement is the accumulation of touch channel measurements.

  参数:

    - touch_num -- touch pad index

    - measure_out -- If the accumulation process does not end, the `measure_out` is the process value.

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG Touch num is not proximity

esp_err_t touch_pad_sleep_channel_get_info(touch_pad_sleep_channel_t *slp_config)

  Get parameter of touch sensor sleep channel. The touch sensor can works in sleep mode to wake up sleep.

  备注

  After the sleep channel is configured, Please use special functions for sleep channel. e.g. The user should uses `touch_pad_sleep_channel_read_data` instead of `touch_pad_read_raw_data` to obtain the sleep channel reading.

  参数:

    slp_config -- touch sleep pad config.

  返回:

    - ESP_OK Success

esp_err_t touch_pad_sleep_channel_enable(touch_pad_t pad_num, bool enable)

  Enable/Disable sleep channel function for touch sensor. The touch sensor can works in sleep mode to wake up sleep.

  备注

  ESP32S2 only support one sleep channel.

  备注

  After the sleep channel is configured, Please use special functions for sleep channel. e.g. The user should uses `touch_pad_sleep_channel_read_data` instead of `touch_pad_read_raw_data` to obtain the sleep channel reading.

  参数:

    - pad_num -- Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode.

    - enable -- true: enable sleep pad for touch sensor; false: disable sleep pad for touch sensor;

  返回:

    - ESP_OK Success

esp_err_t touch_pad_sleep_channel_enable_proximity(touch_pad_t pad_num, bool enable)

  Enable/Disable proximity function for sleep channel. The touch sensor can works in sleep mode to wake up sleep.

  备注

  ESP32S2 only support one sleep channel.

  参数:

    - pad_num -- Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode.

    - enable -- true: enable proximity for sleep channel; false: disable proximity for sleep channel;

  返回:

    - ESP_OK Success

esp_err_t touch_pad_sleep_set_threshold(touch_pad_t pad_num, uint32_t touch_thres)

  Set the trigger threshold of touch sensor in deep sleep. The threshold determines the sensitivity of the touch sensor.

  备注

  In general, the touch threshold during sleep can use the threshold parameter parameters before sleep.

  参数:

    - pad_num -- Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode.

    - touch_thres -- touch sleep pad threshold

  返回:

    - ESP_OK Success

esp_err_t touch_pad_sleep_get_threshold(touch_pad_t pad_num, uint32_t *touch_thres)

  Get the trigger threshold of touch sensor in deep sleep. The threshold determines the sensitivity of the touch sensor.

  备注

  In general, the touch threshold during sleep can use the threshold parameter parameters before sleep.

  参数:

    - pad_num -- Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode.

    - touch_thres -- touch sleep pad threshold

  返回:

    - ESP_OK Success

esp_err_t touch_pad_sleep_channel_read_benchmark(touch_pad_t pad_num, uint32_t *benchmark)

  Read benchmark of touch sensor sleep channel.

  参数:

    - pad_num -- Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode.

    - benchmark -- pointer to accept touch sensor benchmark value

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG parameter is NULL

esp_err_t touch_pad_sleep_channel_read_smooth(touch_pad_t pad_num, uint32_t *smooth_data)

  Read smoothed data of touch sensor sleep channel. Smoothed data is filtered from the raw data.

  参数:

    - pad_num -- Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode.

    - smooth_data -- pointer to accept touch sensor smoothed data

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG parameter is NULL

esp_err_t touch_pad_sleep_channel_read_data(touch_pad_t pad_num, uint32_t *raw_data)

  Read raw data of touch sensor sleep channel.

  参数:

    - pad_num -- Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode.

    - raw_data -- pointer to accept touch sensor raw data

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG parameter is NULL

esp_err_t touch_pad_sleep_channel_reset_benchmark(void)

  Reset benchmark of touch sensor sleep channel.

  返回:

    - ESP_OK Success

esp_err_t touch_pad_sleep_channel_read_proximity_cnt(touch_pad_t pad_num, uint32_t *proximity_cnt)

  Read proximity count of touch sensor sleep channel.

  参数:

    - pad_num -- Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode.

    - proximity_cnt -- pointer to accept touch sensor proximity count value

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG parameter is NULL

esp_err_t touch_pad_sleep_channel_set_work_time(uint16_t sleep_cycle, uint16_t meas_times)

  Change the operating frequency of touch pad in deep sleep state. Reducing the operating frequency can effectively reduce power consumption. If this function is not called, the working frequency of touch in the deep sleep state is the same as that in the wake-up state.

  参数:

    - sleep_cycle -- The touch sensor will sleep after each measurement. sleep_cycle decide the interval between each measurement. t_sleep = sleep_cycle / (RTC_SLOW_CLK frequency). The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function.

    - meas_times -- The times of charge and discharge in each measure process of touch channels. The timer frequency is 8Mhz. Range: 0 ~ 0xffff. Recommended typical value: Modify this value to make the measurement time around 1ms.

  返回:

    - ESP_OK Success

### Header File

- components/driver/touch_sensor/include/driver/touch_sensor_common.h

- This header file can be included with:

  >     #include "driver/touch_sensor_common.h"

- This header file is a part of the API provided by the `driver` component. To declare that your component depends on `driver`, add the following to your CMakeLists.txt:

  >     REQUIRES driver

  > or

  >     PRIV_REQUIRES driver

### Functions

esp_err_t touch_pad_init(void)

  Initialize touch module.

  备注

  If default parameter don't match the usage scenario, it can be changed after this function.

  返回:

    - ESP_OK Success

    - ESP_ERR_NO_MEM Touch pad init error

    - ESP_ERR_NOT_SUPPORTED Touch pad is providing current to external XTAL

esp_err_t touch_pad_deinit(void)

  Un-install touch pad driver.

  备注

  After this function is called, other touch functions are prohibited from being called.

  返回:

    - ESP_OK Success

    - ESP_FAIL Touch pad driver not initialized

esp_err_t touch_pad_io_init(touch_pad_t touch_num)

  Initialize touch pad GPIO.

  参数:

    touch_num -- touch pad index

  返回:

    - ESP_OK on success

    - ESP_ERR_INVALID_ARG if argument is wrong

esp_err_t touch_pad_set_voltage(touch_high_volt_t refh, touch_low_volt_t refl, touch_volt_atten_t atten)

  Set touch sensor high voltage threshold of chanrge. The touch sensor measures the channel capacitance value by charging and discharging the channel. So the high threshold should be less than the supply voltage.

  参数:

    - refh -- the value of DREFH

    - refl -- the value of DREFL

    - atten -- the attenuation on DREFH

  返回:

    - ESP_OK on success

    - ESP_ERR_INVALID_ARG if argument is wrong

esp_err_t touch_pad_get_voltage(touch_high_volt_t *refh, touch_low_volt_t *refl, touch_volt_atten_t *atten)

  Get touch sensor reference voltage,.

  参数:

    - refh -- pointer to accept DREFH value

    - refl -- pointer to accept DREFL value

    - atten -- pointer to accept the attenuation on DREFH

  返回:

    - ESP_OK on success

esp_err_t touch_pad_set_cnt_mode(touch_pad_t touch_num, touch_cnt_slope_t slope, touch_tie_opt_t opt)

  Set touch sensor charge/discharge speed for each pad. If the slope is 0, the counter would always be zero. If the slope is 1, the charging and discharging would be slow, accordingly. If the slope is set 7, which is the maximum value, the charging and discharging would be fast.

  备注

  The higher the charge and discharge current, the greater the immunity of the touch channel, but it will increase the system power consumption.

  参数:

    - touch_num -- touch pad index

    - slope -- touch pad charge/discharge speed

    - opt -- the initial voltage

  返回:

    - ESP_OK on success

    - ESP_ERR_INVALID_ARG if argument is wrong

esp_err_t touch_pad_get_cnt_mode(touch_pad_t touch_num, touch_cnt_slope_t *slope, touch_tie_opt_t *opt)

  Get touch sensor charge/discharge speed for each pad.

  参数:

    - touch_num -- touch pad index

    - slope -- pointer to accept touch pad charge/discharge slope

    - opt -- pointer to accept the initial voltage

  返回:

    - ESP_OK on success

    - ESP_ERR_INVALID_ARG if argument is wrong

esp_err_t touch_pad_isr_deregister(void (*fn)(void*), void *arg)

  Deregister the handler previously registered using touch_pad_isr_handler_register.

  参数:

    - fn -- handler function to call (as passed to touch_pad_isr_handler_register)

    - arg -- argument of the handler (as passed to touch_pad_isr_handler_register)

  返回:

    - ESP_OK on success

    - ESP_ERR_INVALID_STATE if a handler matching both fn and arg isn't registered

esp_err_t touch_pad_get_wakeup_status(touch_pad_t *pad_num)

  Get the touch pad which caused wakeup from deep sleep.

  参数:

    pad_num -- pointer to touch pad which caused wakeup

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG parameter is NULL

esp_err_t touch_pad_set_fsm_mode(touch_fsm_mode_t mode)

  Set touch sensor FSM mode, the test action can be triggered by the timer, as well as by the software.

  参数:

    mode -- FSM mode

  返回:

    - ESP_OK on success

    - ESP_ERR_INVALID_ARG if argument is wrong

esp_err_t touch_pad_get_fsm_mode(touch_fsm_mode_t *mode)

  Get touch sensor FSM mode.

  参数:

    mode -- pointer to accept FSM mode

  返回:

    - ESP_OK on success

esp_err_t touch_pad_clear_status(void)

  To clear the touch sensor channel active status.

  备注

  The FSM automatically updates the touch sensor status. It is generally not necessary to call this API to clear the status.

  返回:

    - ESP_OK on success

uint32_t touch_pad_get_status(void)

  Get the touch sensor channel active status mask. The bit position represents the channel number. The 0/1 status of the bit represents the trigger status.

  返回:

    - The touch sensor status. e.g. Touch1 trigger status is `status_mask & (BIT1)`.

bool touch_pad_meas_is_done(void)

  Check touch sensor measurement status.

  返回:

    - True measurement is under way

    - False measurement done

### GPIO 宏查找表

可以使用宏定义某一触摸传感器通道的 GPIO，或定义某一 GPIO 的通道。例如：

1. `TOUCH_PAD_NUM5_GPIO_NUM` 定义了通道 5 的 GPIO（即 GPIO 12）；

2. `TOUCH_PAD_GPIO4_CHANNEL` 定义了 GPIO 4 的通道（即通道 0）。

### Header File

- components/soc/esp32s3/include/soc/touch_sensor_channel.h

- This header file can be included with:

  >     #include "soc/touch_sensor_channel.h"

### Macros

TOUCH_PAD_GPIO1_CHANNEL

TOUCH_PAD_NUM1_GPIO_NUM

TOUCH_PAD_GPIO2_CHANNEL

TOUCH_PAD_NUM2_GPIO_NUM

TOUCH_PAD_GPIO3_CHANNEL

TOUCH_PAD_NUM3_GPIO_NUM

TOUCH_PAD_GPIO4_CHANNEL

TOUCH_PAD_NUM4_GPIO_NUM

TOUCH_PAD_GPIO5_CHANNEL

TOUCH_PAD_NUM5_GPIO_NUM

TOUCH_PAD_GPIO6_CHANNEL

TOUCH_PAD_NUM6_GPIO_NUM

TOUCH_PAD_GPIO7_CHANNEL

TOUCH_PAD_NUM7_GPIO_NUM

TOUCH_PAD_GPIO8_CHANNEL

TOUCH_PAD_NUM8_GPIO_NUM

TOUCH_PAD_GPIO9_CHANNEL

TOUCH_PAD_NUM9_GPIO_NUM

TOUCH_PAD_GPIO10_CHANNEL

TOUCH_PAD_NUM10_GPIO_NUM

TOUCH_PAD_GPIO11_CHANNEL

TOUCH_PAD_NUM11_GPIO_NUM

TOUCH_PAD_GPIO12_CHANNEL

TOUCH_PAD_NUM12_GPIO_NUM

TOUCH_PAD_GPIO13_CHANNEL

TOUCH_PAD_NUM13_GPIO_NUM

TOUCH_PAD_GPIO14_CHANNEL

TOUCH_PAD_NUM14_GPIO_NUM

### Header File

- components/hal/include/hal/touch_sensor_types.h

- This header file can be included with:

  >     #include "hal/touch_sensor_types.h"

### Structures

struct touch_pad_denoise

  Touch sensor denoise configuration

  Public Members

  touch_pad_denoise_grade_t grade

    Select denoise range of denoise channel. Determined by measuring the noise amplitude of the denoise channel.

  touch_pad_denoise_cap_t cap_level

    Select internal reference capacitance of denoise channel. Ensure that the denoise readings are closest to the readings of the channel being measured. Use `touch_pad_denoise_read_data` to get the reading of denoise channel. The equivalent capacitance of the shielded channel can be calculated from the reading of denoise channel.

struct touch_pad_waterproof

  Touch sensor waterproof configuration

  Public Members

  touch_pad_t guard_ring_pad

    Waterproof. Select touch channel use for guard pad. Guard pad is used to detect the large area of water covering the touch panel.

  touch_pad_shield_driver_t shield_driver

    Waterproof. Shield channel drive capability configuration. Shield pad is used to shield the influence of water droplets covering the touch panel. When the waterproof function is enabled, Touch14 is set as shield channel by default. The larger the parasitic capacitance on the shielding channel, the higher the drive capability needs to be set. The equivalent capacitance of the shield channel can be estimated through the reading value of the denoise channel(Touch0).

struct touch_filter_config

  Touch sensor filter configuration

  Public Members

  touch_filter_mode_t mode

    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.

  uint32_t debounce_cnt

    Set debounce count, such as `n`. If the measured values continue to exceed the threshold for `n+1` times, the touch sensor state changes. Range: 0 ~ 7

  uint32_t noise_thr

    Noise threshold coefficient. Higher = More noise resistance. The actual noise should be less than (noise coefficient * touch threshold). Range: 0 ~ 3. The coefficient is 0: 4/8; 1: 3/8; 2: 2/8; 3: 1;

  uint32_t jitter_step

    Set jitter filter step size. Range: 0 ~ 15

  touch_smooth_mode_t smh_lvl

    Level of filter applied on the original data against large noise interference.

struct touch_pad_sleep_channel_t

  Touch sensor channel sleep configuration

  Public Members

  touch_pad_t touch_num

    Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode. If clear the sleep channel, point this pad to `TOUCH_PAD_NUM0`

  bool en_proximity

    enable proximity function for sleep pad

### Macros

TOUCH_PAD_BIT_MASK_ALL

TOUCH_PAD_SLOPE_DEFAULT

TOUCH_PAD_TIE_OPT_DEFAULT

TOUCH_PAD_BIT_MASK_MAX

TOUCH_PAD_HIGH_VOLTAGE_THRESHOLD

TOUCH_PAD_LOW_VOLTAGE_THRESHOLD

TOUCH_PAD_ATTEN_VOLTAGE_THRESHOLD

TOUCH_PAD_IDLE_CH_CONNECT_DEFAULT

TOUCH_PAD_THRESHOLD_MAX

  If set touch threshold max value, The touch sensor can't be in touched status

TOUCH_PAD_SLEEP_CYCLE_DEFAULT

  Excessive total time will slow down the touch response. Too small measurement time will not be sampled enough, resulting in inaccurate measurements.

  备注

  The greater the duty cycle of the measurement time, the more system power is consumed. The number of sleep cycle in each measure process of touch channels. The timer frequency is RTC_SLOW_CLK (can be 150k or 32k depending on the options). Range: 0 ~ 0xffff

TOUCH_PAD_MEASURE_CYCLE_DEFAULT

  The times of charge and discharge in each measure process of touch channels. The timer frequency is 8Mhz. Recommended typical value: Modify this value to make the measurement time around 1ms. Range: 0 ~ 0xffff

TOUCH_PAD_INTR_MASK_ALL

  All touch interrupt type enable.

TOUCH_PROXIMITY_MEAS_NUM_MAX

  Touch sensor proximity detection configuration

TOUCH_DEBOUNCE_CNT_MAX

TOUCH_NOISE_THR_MAX

TOUCH_JITTER_STEP_MAX

### Type Definitions

typedef struct touch_pad_denoise touch_pad_denoise_t

  Touch sensor denoise configuration

typedef struct touch_pad_waterproof touch_pad_waterproof_t

  Touch sensor waterproof configuration

typedef struct touch_filter_config touch_filter_config_t

  Touch sensor filter configuration

### Enumerations

enum touch_pad_t

  Touch pad channel

  Values:

  enumerator TOUCH_PAD_NUM0

    Touch pad channel 0 is GPIO4(ESP32)

  enumerator TOUCH_PAD_NUM1

    Touch pad channel 1 is GPIO0(ESP32) / GPIO1(ESP32-S2)

  enumerator TOUCH_PAD_NUM2

    Touch pad channel 2 is GPIO2(ESP32) / GPIO2(ESP32-S2)

  enumerator TOUCH_PAD_NUM3

    Touch pad channel 3 is GPIO15(ESP32) / GPIO3(ESP32-S2)

  enumerator TOUCH_PAD_NUM4

    Touch pad channel 4 is GPIO13(ESP32) / GPIO4(ESP32-S2)

  enumerator TOUCH_PAD_NUM5

    Touch pad channel 5 is GPIO12(ESP32) / GPIO5(ESP32-S2)

  enumerator TOUCH_PAD_NUM6

    Touch pad channel 6 is GPIO14(ESP32) / GPIO6(ESP32-S2)

  enumerator TOUCH_PAD_NUM7

    Touch pad channel 7 is GPIO27(ESP32) / GPIO7(ESP32-S2)

  enumerator TOUCH_PAD_NUM8

    Touch pad channel 8 is GPIO33(ESP32) / GPIO8(ESP32-S2)

  enumerator TOUCH_PAD_NUM9

    Touch pad channel 9 is GPIO32(ESP32) / GPIO9(ESP32-S2)

  enumerator TOUCH_PAD_NUM10

    Touch channel 10 is GPIO10(ESP32-S2)

  enumerator TOUCH_PAD_NUM11

    Touch channel 11 is GPIO11(ESP32-S2)

  enumerator TOUCH_PAD_NUM12

    Touch channel 12 is GPIO12(ESP32-S2)

  enumerator TOUCH_PAD_NUM13

    Touch channel 13 is GPIO13(ESP32-S2)

  enumerator TOUCH_PAD_NUM14

    Touch channel 14 is GPIO14(ESP32-S2)

  enumerator TOUCH_PAD_MAX

enum touch_high_volt_t

  Touch sensor high reference voltage

  Values:

  enumerator TOUCH_HVOLT_KEEP

    Touch sensor high reference voltage, no change

  enumerator TOUCH_HVOLT_2V4

    Touch sensor high reference voltage, 2.4V

  enumerator TOUCH_HVOLT_2V5

    Touch sensor high reference voltage, 2.5V

  enumerator TOUCH_HVOLT_2V6

    Touch sensor high reference voltage, 2.6V

  enumerator TOUCH_HVOLT_2V7

    Touch sensor high reference voltage, 2.7V

  enumerator TOUCH_HVOLT_MAX

enum touch_low_volt_t

  Touch sensor low reference voltage

  Values:

  enumerator TOUCH_LVOLT_KEEP

    Touch sensor low reference voltage, no change

  enumerator TOUCH_LVOLT_0V5

    Touch sensor low reference voltage, 0.5V

  enumerator TOUCH_LVOLT_0V6

    Touch sensor low reference voltage, 0.6V

  enumerator TOUCH_LVOLT_0V7

    Touch sensor low reference voltage, 0.7V

  enumerator TOUCH_LVOLT_0V8

    Touch sensor low reference voltage, 0.8V

  enumerator TOUCH_LVOLT_MAX

enum touch_volt_atten_t

  Touch sensor high reference voltage attenuation

  Values:

  enumerator TOUCH_HVOLT_ATTEN_KEEP

    Touch sensor high reference voltage attenuation, no change

  enumerator TOUCH_HVOLT_ATTEN_1V5

    Touch sensor high reference voltage attenuation, 1.5V attenuation

  enumerator TOUCH_HVOLT_ATTEN_1V

    Touch sensor high reference voltage attenuation, 1.0V attenuation

  enumerator TOUCH_HVOLT_ATTEN_0V5

    Touch sensor high reference voltage attenuation, 0.5V attenuation

  enumerator TOUCH_HVOLT_ATTEN_0V

    Touch sensor high reference voltage attenuation, 0V attenuation

  enumerator TOUCH_HVOLT_ATTEN_MAX

enum touch_cnt_slope_t

  Touch sensor charge/discharge speed

  Values:

  enumerator TOUCH_PAD_SLOPE_0

    Touch sensor charge / discharge speed, always zero

  enumerator TOUCH_PAD_SLOPE_1

    Touch sensor charge / discharge speed, slowest

  enumerator TOUCH_PAD_SLOPE_2

    Touch sensor charge / discharge speed

  enumerator TOUCH_PAD_SLOPE_3

    Touch sensor charge / discharge speed

  enumerator TOUCH_PAD_SLOPE_4

    Touch sensor charge / discharge speed

  enumerator TOUCH_PAD_SLOPE_5

    Touch sensor charge / discharge speed

  enumerator TOUCH_PAD_SLOPE_6

    Touch sensor charge / discharge speed

  enumerator TOUCH_PAD_SLOPE_7

    Touch sensor charge / discharge speed, fast

  enumerator TOUCH_PAD_SLOPE_MAX

enum touch_tie_opt_t

  Touch sensor initial charge level

  Values:

  enumerator TOUCH_PAD_TIE_OPT_LOW

    Initial level of charging voltage, low level

  enumerator TOUCH_PAD_TIE_OPT_HIGH

    Initial level of charging voltage, high level

  enumerator TOUCH_PAD_TIE_OPT_FLOAT

    Initial level of charging voltage, float

  enumerator TOUCH_PAD_TIE_OPT_MAX

    The max tie options

enum touch_fsm_mode_t

  Touch sensor FSM mode

  Values:

  enumerator TOUCH_FSM_MODE_TIMER

    To start touch FSM by timer

  enumerator TOUCH_FSM_MODE_SW

    To start touch FSM by software trigger

  enumerator TOUCH_FSM_MODE_MAX

enum touch_trigger_mode_t

  Values:

  enumerator TOUCH_TRIGGER_BELOW

    Touch interrupt will happen if counter value is less than threshold.

  enumerator TOUCH_TRIGGER_ABOVE

    Touch interrupt will happen if counter value is larger than threshold.

  enumerator TOUCH_TRIGGER_MAX

enum touch_trigger_src_t

  Values:

  enumerator TOUCH_TRIGGER_SOURCE_BOTH

    wakeup interrupt is generated if both SET1 and SET2 are "touched"

  enumerator TOUCH_TRIGGER_SOURCE_SET1

    wakeup interrupt is generated if SET1 is "touched"

  enumerator TOUCH_TRIGGER_SOURCE_MAX

enum touch_pad_intr_mask_t

  Values:

  enumerator TOUCH_PAD_INTR_MASK_DONE

    Measurement done for one of the enabled channels.

  enumerator TOUCH_PAD_INTR_MASK_ACTIVE

    Active for one of the enabled channels.

  enumerator TOUCH_PAD_INTR_MASK_INACTIVE

    Inactive for one of the enabled channels.

  enumerator TOUCH_PAD_INTR_MASK_SCAN_DONE

    Measurement done for all the enabled channels.

  enumerator TOUCH_PAD_INTR_MASK_TIMEOUT

    Timeout for one of the enabled channels.

  enumerator TOUCH_PAD_INTR_MASK_PROXI_MEAS_DONE

    For proximity sensor, when the number of measurements reaches the set count of measurements, an interrupt will be generated.

enum touch_pad_denoise_grade_t

  Values:

  enumerator TOUCH_PAD_DENOISE_BIT12

    Denoise range is 12bit

  enumerator TOUCH_PAD_DENOISE_BIT10

    Denoise range is 10bit

  enumerator TOUCH_PAD_DENOISE_BIT8

    Denoise range is 8bit

  enumerator TOUCH_PAD_DENOISE_BIT4

    Denoise range is 4bit

  enumerator TOUCH_PAD_DENOISE_MAX

enum touch_pad_denoise_cap_t

  Values:

  enumerator TOUCH_PAD_DENOISE_CAP_L0

    Denoise channel internal reference capacitance is 5pf

  enumerator TOUCH_PAD_DENOISE_CAP_L1

    Denoise channel internal reference capacitance is 6.4pf

  enumerator TOUCH_PAD_DENOISE_CAP_L2

    Denoise channel internal reference capacitance is 7.8pf

  enumerator TOUCH_PAD_DENOISE_CAP_L3

    Denoise channel internal reference capacitance is 9.2pf

  enumerator TOUCH_PAD_DENOISE_CAP_L4

    Denoise channel internal reference capacitance is 10.6pf

  enumerator TOUCH_PAD_DENOISE_CAP_L5

    Denoise channel internal reference capacitance is 12.0pf

  enumerator TOUCH_PAD_DENOISE_CAP_L6

    Denoise channel internal reference capacitance is 13.4pf

  enumerator TOUCH_PAD_DENOISE_CAP_L7

    Denoise channel internal reference capacitance is 14.8pf

  enumerator TOUCH_PAD_DENOISE_CAP_MAX

enum touch_pad_shield_driver_t

  Touch sensor shield channel drive capability level

  Values:

  enumerator TOUCH_PAD_SHIELD_DRV_L0

    The max equivalent capacitance in shield channel is 40pf

  enumerator TOUCH_PAD_SHIELD_DRV_L1

    The max equivalent capacitance in shield channel is 80pf

  enumerator TOUCH_PAD_SHIELD_DRV_L2

    The max equivalent capacitance in shield channel is 120pf

  enumerator TOUCH_PAD_SHIELD_DRV_L3

    The max equivalent capacitance in shield channel is 160pf

  enumerator TOUCH_PAD_SHIELD_DRV_L4

    The max equivalent capacitance in shield channel is 200pf

  enumerator TOUCH_PAD_SHIELD_DRV_L5

    The max equivalent capacitance in shield channel is 240pf

  enumerator TOUCH_PAD_SHIELD_DRV_L6

    The max equivalent capacitance in shield channel is 280pf

  enumerator TOUCH_PAD_SHIELD_DRV_L7

    The max equivalent capacitance in shield channel is 320pf

  enumerator TOUCH_PAD_SHIELD_DRV_MAX

enum touch_pad_conn_type_t

  Touch channel idle state configuration

  Values:

  enumerator TOUCH_PAD_CONN_HIGHZ

    Idle status of touch channel is high resistance state

  enumerator TOUCH_PAD_CONN_GND

    Idle status of touch channel is ground connection

  enumerator TOUCH_PAD_CONN_MAX

enum touch_filter_mode_t

  Touch channel IIR filter coefficient configuration.

  备注

  On ESP32S2. There is an error in the IIR calculation. The magnitude of the error is twice the filter coefficient. So please select a smaller filter coefficient on the basis of meeting the filtering requirements. Recommended filter coefficient selection `IIR_16`.

  Values:

  enumerator TOUCH_PAD_FILTER_IIR_4

    The filter mode is first-order IIR filter. The coefficient is 4.

  enumerator TOUCH_PAD_FILTER_IIR_8

    The filter mode is first-order IIR filter. The coefficient is 8.

  enumerator TOUCH_PAD_FILTER_IIR_16

    The filter mode is first-order IIR filter. The coefficient is 16 (Typical value).

  enumerator TOUCH_PAD_FILTER_IIR_32

    The filter mode is first-order IIR filter. The coefficient is 32.

  enumerator TOUCH_PAD_FILTER_IIR_64

    The filter mode is first-order IIR filter. The coefficient is 64.

  enumerator TOUCH_PAD_FILTER_IIR_128

    The filter mode is first-order IIR filter. The coefficient is 128.

  enumerator TOUCH_PAD_FILTER_IIR_256

    The filter mode is first-order IIR filter. The coefficient is 256.

  enumerator TOUCH_PAD_FILTER_JITTER

    The filter mode is jitter filter

  enumerator TOUCH_PAD_FILTER_MAX

enum touch_smooth_mode_t

  Level of filter applied on the original data against large noise interference.

  备注

  On ESP32S2. There is an error in the IIR calculation. The magnitude of the error is twice the filter coefficient. So please select a smaller filter coefficient on the basis of meeting the filtering requirements. Recommended filter coefficient selection `IIR_2`.

  Values:

  enumerator TOUCH_PAD_SMOOTH_OFF

    No filtering of raw data.

  enumerator TOUCH_PAD_SMOOTH_IIR_2

    Filter the raw data. The coefficient is 2 (Typical value).

  enumerator TOUCH_PAD_SMOOTH_IIR_4

    Filter the raw data. The coefficient is 4.

  enumerator TOUCH_PAD_SMOOTH_IIR_8

    Filter the raw data. The coefficient is 8.

  enumerator TOUCH_PAD_SMOOTH_MAX

此文档对您有帮助吗？

- 反馈已收到，谢谢！
- 如果您有其他意见，欢迎填写乐鑫文档反馈表。

- 我们重视您的反馈。
- 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。