# Touch Sensor

[中文]

## Introduction

A touch sensor system is built on a substrate which carries electrodes and relevant connections under a protective flat surface. When the surface is touched, the capacitance variation is used to evaluate if the touch was valid.

The sensing pads can be arranged in different combinations (e.g., matrix, slider), so that a larger area or more points can be detected. The touch pad sensing process is under the control of a hardware-implemented finite-state machine (FSM) which is initiated by software or a dedicated hardware timer.

For design, operation, and control registers of a touch sensor, see ESP32 Technical Reference Manual > On-Chip Sensors and Analog Signal Processing [PDF].

In-depth design details of touch sensors and firmware development guidelines for ESP32 are available in Touch Sensor Application Note.

For more information about testing touch sensors in various configurations, please check the Guide for ESP32-Sense-Kit.

## Functionality Overview

Description of API is broken down into groups of functions to provide a quick overview of the following features:

- Initialization of touch pad driver

- Configuration of touch pad GPIO pins

- Taking measurements

- Adjusting parameters of measurements

- Filtering measurements

- Touch detection methods

- Setting up interrupts to report touch detection

- Waking up from Sleep mode on interrupt

For detailed description of a particular function, please go to Section API Reference. Practical implementation of this API is covered in Section Application Examples.

### Initialization

Before using a touch pad, you need to initialize the touch pad driver by calling the function `touch_pad_init()`. This function sets several `.._DEFAULT` driver parameters listed in API Reference under Macros. It also removes the information about which pads have been touched before, if any, and disables interrupts.

If the driver is not required anymore, deinitialize it by calling `touch_pad_deinit()`.

### Configuration

Enabling the touch sensor functionality for a particular GPIO is done with `touch_pad_config()`. The following 10 capacitive touch pads are supported for ESP32.

Touch Pad | GPIO Pin
--- | ---
T0 | GPIO4
T1 | GPIO0
T2 | GPIO2
T3 | MTDO
T4 | MTCK
T5 | MTDI
T6 | MTMS
T7 | GPIO27
T8 | 32K_XN
T9 | 32K_XP

Use the function `touch_pad_set_fsm_mode()` to select if touch pad measurement (operated by FSM) should be started automatically by a hardware timer, or by software. If software mode is selected, use `touch_pad_sw_start()` to start the FSM.

### Touch State Measurements

The following two functions come in handy to read raw or filtered measurements from the sensor:

- `touch_pad_read_raw_data()`

- `touch_pad_read_filtered()`

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

Note

Before using `touch_pad_read_filtered()`, you need to initialize and configure the filter by calling specific filter functions described in Section Filtering of Measurements.

For the demonstration of how to read the touch pad data, check the application example peripherals/touch_sensor/touch_sensor_v1/touch_pad_read.

### Method of Measurements

The touch sensor counts the number of charge/discharge cycles over a fixed period of time (specified by `touch_pad_set_measurement_clock_cycles()`). The count result is the raw data that read from `touch_pad_read_raw_data()`. After finishing one measurement, the touch sensor sleeps until the next measurement start, this interval between two measurements can be set by `touch_pad_set_measurement_interval()`.

Note

If the specified clock cycles for measurement is too small, the result may be inaccurate, but increasing clock cycles will increase the power consumption as well. Additionally, the response of the touch sensor will slow down if the total time of the interval and measurement is too long.

### Optimization of Measurements

A touch sensor has several configurable parameters to match the characteristics of a particular touch pad design. For instance, to sense smaller capacity changes, it is possible to narrow down the reference voltage range within which the touch pads are charged/discharged. The high and low reference voltages are set using the function `touch_pad_set_voltage()`.

Besides the ability to discern smaller capacity changes, a positive side effect is reduction of power consumption for low power applications. A likely negative effect is an increase in measurement noise. If the dynamic range of obtained readings is still satisfactory, then further reduction of power consumption might be done by reducing the measurement time with `touch_pad_set_measurement_clock_cycles()`.

The following list summarizes available measurement parameters and corresponding 'set' functions:

- Touch pad charge / discharge parameters:

  > - voltage range: `touch_pad_set_voltage()`

  > - speed (slope): `touch_pad_set_cnt_mode()`

- Clock cycles of one measurement: `touch_pad_set_measurement_clock_cycles()`

Relationship between the voltage range (high/low reference voltages), speed (slope), and measurement time is shown in the figure below.

Touch pad - relationship between measurement parameters

The last chart Output represents the touch sensor reading, i.e., the count of pulses collected within the measurement time.

All functions are provided in pairs to set a specific parameter and to get the current parameter's value, e.g., `touch_pad_set_voltage()` and `touch_pad_get_voltage()`.

### Filtering of Measurements

If measurements are noisy, you can filter them with provided API functions. Before using the filter, please start it by calling `touch_pad_filter_start()`.

The filter type is IIR (infinite impulse response), and it has a configurable period that can be set with the function `touch_pad_set_filter_period()`.

You can stop the filter with `touch_pad_filter_stop()`. If not required anymore, the filter can be deleted by invoking `touch_pad_filter_delete()`.

### Touch Detection

Touch detection is implemented in ESP32's hardware based on the user-configured threshold and raw measurements executed by FSM. Use the functions `touch_pad_get_status()` to check which pads have been touched and `touch_pad_clear_status()` to clear the touch status information.

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 peripherals/touch_sensor/touch_sensor_v1/touch_pad_interrupt.

### Touch Triggered Interrupts

Before enabling an interrupt on a touch detection, you should establish a touch detection threshold. Use the functions described in Touch State Measurements to read and display sensor measurements when a pad is touched and released. Apply a filter if measurements are noisy and relative capacity changes are small. Depending on your application and environment conditions, test the influence of temperature and power supply voltage changes on measured values.

Once a detection threshold is established, it can be set during initialization with `touch_pad_config()` or at the runtime with `touch_pad_set_thresh()`.

In the next step, configure how interrupts are triggered. They can be triggered below or above the threshold, which is set with the function `touch_pad_set_trigger_mode()`.

Finally, configure and manage interrupt calls using the following functions:

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

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

When interrupts are operational, you can obtain the information from which particular pad an interrupt came by invoking `touch_pad_get_status()` and clear the pad status with `touch_pad_clear_status()`.

Note

Interrupts on touch detection operate on raw/unfiltered measurements checked against user established threshold and are implemented in hardware. Enabling the software filtering API (see Filtering of Measurements) does not affect this process.

### Wakeup from Sleep Mode

If touch pad interrupts are used to wake up the chip from a sleep mode, you can select a certain configuration of pads (SET1 or both SET1 and SET2) that should be touched to trigger the interrupt and cause the subsequent wakeup. To do so, use the function `touch_pad_set_trigger_source()`.

Configuration of required bit patterns of pads may be managed for each 'SET' with:

- `touch_pad_set_group_mask()` / `touch_pad_get_group_mask()`

- `touch_pad_clear_group_mask()`

## Application Examples

- peripherals/touch_sensor/touch_sensor_v1/touch_pad_read demonstrates how to read and print raw or IIR filtered values from capacitive touch sensors on ESP32, and how to calibrate the sensors.

- peripherals/touch_sensor/touch_sensor_v1/touch_pad_interrupt demonstrates how to set up the ESP32's capacitive touch pad to trigger an interrupt when touched, and how to use software detection for greater sensitivity, comparing the performance of hardware interrupt mode and software polling mode.

## API Reference

### Header File

- components/driver/touch_sensor/esp32/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_config(touch_pad_t touch_num, uint16_t threshold)

  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.

  Parameters:

    - touch_num -- touch pad index

    - threshold -- interrupt threshold,

  Returns:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG if argument wrong

    - ESP_FAIL if touch pad not initialized

esp_err_t touch_pad_read(touch_pad_t touch_num, uint16_t *touch_value)

  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.

  Parameters:

    - touch_num -- touch pad index

    - touch_value -- pointer to accept touch sensor value

  Returns:

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

  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

  Parameters:

    - touch_num -- touch pad index

    - touch_value -- pointer to accept touch sensor value

  Returns:

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

  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

  Parameters:

    - touch_num -- touch pad index

    - touch_value -- pointer to accept touch sensor value

  Returns:

    - 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_set_filter_read_cb(filter_cb_t read_cb)

  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.

  Parameters:

    read_cb -- Pointer to filtered callback function. If the argument passed in is NULL, the callback will stop.

  Returns:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG set error

esp_err_t touch_pad_isr_register(intr_handler_t fn, void *arg)

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

  Parameters:

    - fn -- Pointer to ISR handler

    - arg -- Parameter for ISR

  Returns:

    - ESP_OK Success ;

    - ESP_ERR_INVALID_ARG GPIO error

    - ESP_ERR_NO_MEM No memory

esp_err_t touch_pad_set_measurement_clock_cycles(uint16_t clock_cycle)

  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.

  Parameters:

    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

  Returns:

    - ESP_OK Set the clock cycle success

esp_err_t touch_pad_get_measurement_clock_cycles(uint16_t *clock_cycle)

  Get the clock cycles of each measurement.

  Parameters:

    clock_cycle -- The clock cycles of each measurement

  Returns:

    - ESP_OK Get the clock cycle 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.

  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

  Parameters:

    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.

  Returns:

    - ESP_OK Set interval cycle success

esp_err_t touch_pad_get_measurement_interval(uint16_t *interval_cycle)

  Get the interval between two measurements.

  Parameters:

    interval_cycle -- The interval between two measurements

  Returns:

    - 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_cycle)

  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.

  Parameters:

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

  Returns:

    - ESP_OK on success

esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_cycle)

  Get touch sensor measurement and sleep time.

  Parameters:

    - sleep_cycle -- Pointer to accept sleep cycle number

    - meas_cycle -- Pointer to accept measurement cycle count.

  Returns:

    - ESP_OK on success

    - ESP_ERR_INVALID_ARG The input parameter is NULL

esp_err_t touch_pad_sw_start(void)

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

  Returns:

    - ESP_OK on success

esp_err_t touch_pad_set_thresh(touch_pad_t touch_num, uint16_t threshold)

  Set touch sensor interrupt threshold.

  Parameters:

    - touch_num -- touch pad index

    - threshold -- threshold of touchpad count, refer to touch_pad_set_trigger_mode to see how to set trigger mode.

  Returns:

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

  Get touch sensor interrupt threshold.

  Parameters:

    - touch_num -- touch pad index

    - threshold -- pointer to accept threshold

  Returns:

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

  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.

  Parameters:

    mode -- touch sensor interrupt trigger mode

  Returns:

    - ESP_OK on success

    - ESP_ERR_INVALID_ARG if argument is wrong

esp_err_t touch_pad_get_trigger_mode(touch_trigger_mode_t *mode)

  Get touch sensor interrupt trigger mode.

  Parameters:

    mode -- pointer to accept touch sensor interrupt trigger mode

  Returns:

    - ESP_OK on success

esp_err_t touch_pad_set_trigger_source(touch_trigger_src_t src)

  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.

  Parameters:

    src -- touch sensor interrupt trigger source

  Returns:

    - ESP_OK on success

    - ESP_ERR_INVALID_ARG if argument is wrong

esp_err_t touch_pad_get_trigger_source(touch_trigger_src_t *src)

  Get touch sensor interrupt trigger source.

  Parameters:

    src -- pointer to accept touch sensor interrupt trigger source

  Returns:

    - ESP_OK on success

esp_err_t touch_pad_set_group_mask(uint16_t set1_mask, uint16_t set2_mask, uint16_t en_mask)

  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.

  Parameters:

    - set1_mask -- bitmask of touch sensor signal group1, it's a 10-bit value

    - set2_mask -- bitmask of touch sensor signal group2, it's a 10-bit value

    - en_mask -- bitmask of touch sensor work enable, it's a 10-bit value

  Returns:

    - ESP_OK on success

    - ESP_ERR_INVALID_ARG if argument is wrong

esp_err_t touch_pad_get_group_mask(uint16_t *set1_mask, uint16_t *set2_mask, uint16_t *en_mask)

  Get touch sensor group mask.

  Parameters:

    - set1_mask -- pointer to accept bitmask of touch sensor signal group1, it's a 10-bit value

    - set2_mask -- pointer to accept bitmask of touch sensor signal group2, it's a 10-bit value

    - en_mask -- pointer to accept bitmask of touch sensor work enable, it's a 10-bit value

  Returns:

    - ESP_OK on success

esp_err_t touch_pad_clear_group_mask(uint16_t set1_mask, uint16_t set2_mask, uint16_t en_mask)

  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.

  Parameters:

    - set1_mask -- bitmask touch sensor signal group1, it's a 10-bit value

    - set2_mask -- bitmask touch sensor signal group2, it's a 10-bit value

    - en_mask -- bitmask of touch sensor work enable, it's a 10-bit value

  Returns:

    - ESP_OK on success

    - ESP_ERR_INVALID_ARG if argument is wrong

esp_err_t touch_pad_intr_enable(void)

  To enable touch pad interrupt.

  Returns:

    - ESP_OK on success

esp_err_t touch_pad_intr_disable(void)

  To disable touch pad interrupt.

  Returns:

    - ESP_OK on success

esp_err_t touch_pad_intr_clear(void)

  To clear touch pad interrupt.

  Returns:

    - ESP_OK on success

esp_err_t touch_pad_set_filter_period(uint32_t new_period_ms)

  set touch pad filter calibration period, in ms. Need to call touch_pad_filter_start before all touch filter APIs

  Parameters:

    new_period_ms -- filter period, in ms

  Returns:

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

  get touch pad filter calibration period, in ms Need to call touch_pad_filter_start before all touch filter APIs

  Parameters:

    p_period_ms -- pointer to accept period

  Returns:

    - ESP_OK Success

    - ESP_ERR_INVALID_STATE driver state error

    - ESP_ERR_INVALID_ARG parameter error

esp_err_t touch_pad_filter_start(uint32_t filter_period_ms)

  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.

  Parameters:

    filter_period_ms -- filter calibration period, in ms

  Returns:

    - 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_stop(void)

  stop touch pad filter function Need to call touch_pad_filter_start before all touch filter APIs

  Returns:

    - ESP_OK Success

    - ESP_ERR_INVALID_STATE driver state error

esp_err_t touch_pad_filter_delete(void)

  delete touch pad filter driver and release the memory Need to call touch_pad_filter_start before all touch filter APIs

  Returns:

    - ESP_OK Success

    - ESP_ERR_INVALID_STATE driver state error

### Type Definitions

typedef void (*filter_cb_t)(uint16_t *raw_value, uint16_t *filtered_value)

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

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

  Note

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

  Returns:

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

  Note

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

  Returns:

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

  Parameters:

    touch_num -- touch pad index

  Returns:

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

  Parameters:

    - refh -- the value of DREFH

    - refl -- the value of DREFL

    - atten -- the attenuation on DREFH

  Returns:

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

  Parameters:

    - refh -- pointer to accept DREFH value

    - refl -- pointer to accept DREFL value

    - atten -- pointer to accept the attenuation on DREFH

  Returns:

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

  Note

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

  Parameters:

    - touch_num -- touch pad index

    - slope -- touch pad charge/discharge speed

    - opt -- the initial voltage

  Returns:

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

  Parameters:

    - touch_num -- touch pad index

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

    - opt -- pointer to accept the initial voltage

  Returns:

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

  Parameters:

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

  Returns:

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

  Parameters:

    pad_num -- pointer to touch pad which caused wakeup

  Returns:

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

  Parameters:

    mode -- FSM mode

  Returns:

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

  Parameters:

    mode -- pointer to accept FSM mode

  Returns:

    - ESP_OK on success

esp_err_t touch_pad_clear_status(void)

  To clear the touch sensor channel active status.

  Note

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

  Returns:

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

  Returns:

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

  Returns:

    - True measurement is under way

    - False measurement done

### GPIO Lookup Macros

Some useful macros can be used to specified the GPIO number of a touch pad channel, or vice versa. e.g.,

1. `TOUCH_PAD_NUM5_GPIO_NUM` is the GPIO number of channel 5 (12);

2. `TOUCH_PAD_GPIO4_CHANNEL` is the channel number of GPIO 4 (channel 0).

### Header File

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

- This header file can be included with:

  >     #include "soc/touch_sensor_channel.h"

### Macros

TOUCH_PAD_GPIO4_CHANNEL

TOUCH_PAD_NUM0_GPIO_NUM

TOUCH_PAD_GPIO0_CHANNEL

TOUCH_PAD_NUM1_GPIO_NUM

TOUCH_PAD_GPIO2_CHANNEL

TOUCH_PAD_NUM2_GPIO_NUM

TOUCH_PAD_GPIO15_CHANNEL

TOUCH_PAD_NUM3_GPIO_NUM

TOUCH_PAD_GPIO13_CHANNEL

TOUCH_PAD_NUM4_GPIO_NUM

TOUCH_PAD_GPIO12_CHANNEL

TOUCH_PAD_NUM5_GPIO_NUM

TOUCH_PAD_GPIO14_CHANNEL

TOUCH_PAD_NUM6_GPIO_NUM

TOUCH_PAD_GPIO27_CHANNEL

TOUCH_PAD_NUM7_GPIO_NUM

TOUCH_PAD_GPIO33_CHANNEL

TOUCH_PAD_NUM8_GPIO_NUM

TOUCH_PAD_GPIO32_CHANNEL

TOUCH_PAD_NUM9_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"

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

  The timer frequency is RTC_SLOW_CLK (can be 150k or 32k depending on the options), max value is 0xffff

TOUCH_PAD_MEASURE_CYCLE_DEFAULT

  The timer frequency is 8Mhz, the max value is 0x7fff

TOUCH_FSM_MODE_DEFAULT

  The touch FSM my be started by the software or timer

TOUCH_TRIGGER_MODE_DEFAULT

  Interrupts can be triggered if sensor value gets below or above threshold

TOUCH_TRIGGER_SOURCE_DEFAULT

  The wakeup trigger source can be SET1 or both SET1 and SET2

### 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_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_MAX

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

Was this page helpful?

- Thank you! We received your feedback.
- If you have any comments, fill in Espressif Documentation Feedback Form.

- We value your feedback.
- Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.