触摸传感器

[English]

概述

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

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

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

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

如果想评估触摸传感器的多种应用场景，请查看 ESP32 触摸功能开发套件。

功能介绍

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

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

• 配置触摸传感器 GPIO 管脚

• 触摸状态测量

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

• 滤波采样

• 触摸监测方式

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

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

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

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

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

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

配置触摸传感器 GPIO 管脚

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

触摸传感器通道	GPIO 管脚
T0	GPIO4
T1	GPIO0
T2	GPIO2
T3	MTDO
T4	MTCK
T5	MTDI
T6	MTMS
T7	GPIO27
T8	32K_XN
T9	32K_XP

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

触摸状态测量

借助以下两个函数从传感器读取原始数据和滤波后的数据：

• touch_pad_read_raw_data()

• touch_pad_read_filtered()

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

备注

使用 touch_pad_read_filtered() 之前，需要先调用 滤波采样 中特定的滤波器函数来初始化并配置该滤波器。

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

测量方式

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

备注

若设置的计数时间太短（即测量持续的时钟周期数太小），则可能导致结果不准确，但是过大的计数时间也会造成功耗上升。另外，若睡眠时间加测量时间的总时间过长，则会造成触摸传感器响应变慢。

优化测量

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

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

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

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

  • 电压门限：touch_pad_set_voltage()

  • 速率（斜率）：touch_pad_set_cnt_mode()

• 单次测量所用的时钟周期：touch_pad_set_measurement_clock_cycles()

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

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

上图中的 Output 代表触摸传感器读值，即一个测量周期内测得的脉冲计数值。

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

滤波采样

如果测量中存在噪声，可以使用提供的 API 函数对采样进行滤波。使用滤波器之前，请先调用 touch_pad_filter_start() 启动该滤波器。

滤波器类型为 IIR（无限脉冲响应滤波器），可以调用 touch_pad_set_filter_period() 配置此类滤波器的采样周期。

如需停止滤波器，请调用 touch_pad_filter_stop() 函数。如果不再使用该滤波器，请调用 touch_pad_filter_delete() 删除此滤波器。

触摸监测

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

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

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

中断触发

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

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

下一步就是设置如何触发中断。可以设置在阈值以下或以上触发中断，具体触发模式由函数 touch_pad_set_trigger_mode() 设置。

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

• touch_pad_isr_register() / touch_pad_isr_deregister()

• touch_pad_intr_enable() / touch_pad_intr_disable()

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

备注

触摸监测中的中断信号基于原始/未经滤波的采样（对比设置的阈值），并在硬件中实现。启用软件滤波 API（请参考 滤波采样）并不会影响这一过程。

从睡眠模式唤醒

如果使用触摸传感器中断将芯片从睡眠模式唤醒，可以选择配置一些触摸传感器，例如 SET1 或 SET1 和 SET2，触摸这些触摸传感器将触发中断并唤醒芯片。请调用 touch_pad_set_trigger_source() 实现上述操作。

可以使用以下函数管理 'SET' 中触摸传感器所需的位模式配置：

• touch_pad_set_group_mask() / touch_pad_get_group_mask()

• touch_pad_clear_group_mask()

应用示例

• peripherals/touch_sensor/touch_sensor_v1/touch_pad_read 演示了如何在 ESP32 上读取并打印电容触摸传感器的原始值或 IIR 滤波后的值，以及如何校准传感器。

• peripherals/touch_sensor/touch_sensor_v1/touch_pad_interrupt 演示了如何设置 ESP32 的电容触摸板，使其在被触摸时触发中断，以及如何使用软件监测来提高灵敏度，并比较硬件中断模式和软件轮询模式的性能。

API 参考

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.

备注

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.

参数

• touch_num -- touch pad index

• threshold -- interrupt threshold,

返回

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

备注

This API requests hardware measurement once. If IIR filter mode is enabled, please use 'touch_pad_read_raw_data' interface instead.

参数

• touch_num -- touch pad index

• touch_value -- pointer to accept touch sensor value

返回

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

备注

touch_pad_filter_start has to be called before calling touch_pad_read_filtered. This function can be called from ISR

参数

• touch_num -- touch pad index

• touch_value -- pointer to accept touch sensor value

返回

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

备注

touch_pad_filter_start has to be called before calling touch_pad_read_raw_data. This function can be called from ISR

参数

• touch_num -- touch pad index

• touch_value -- pointer to accept touch sensor value

返回

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

备注

The 'read_cb' callback is called in timer task in each filtering cycle.

参数

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

返回

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

参数

• fn -- Pointer to ISR handler

• arg -- Parameter for ISR

返回

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

备注

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)

备注

If clock cycles is too small, it may lead to inaccurate results.

参数

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

返回

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

参数

clock_cycle -- The clock cycles of each measurement

返回

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

备注

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

备注

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.

备注

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

返回

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

参数

• sleep_cycle -- Pointer to accept sleep cycle number

• meas_cycle -- Pointer to accept measurement cycle count.

返回

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

返回

• ESP_OK on success

esp_err_t touch_pad_set_thresh(touch_pad_t touch_num, uint16_t threshold)

Set touch sensor interrupt threshold.

参数

• touch_num -- touch pad index

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

返回

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

参数

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

参数

mode -- touch sensor interrupt trigger mode

返回

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

参数

mode -- pointer to accept touch sensor interrupt trigger mode

返回

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

参数

src -- touch sensor interrupt trigger source

返回

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

参数

src -- pointer to accept touch sensor interrupt trigger source

返回

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

参数

• 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

返回

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

参数

• 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

返回

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

参数

• 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

返回

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

返回

• ESP_OK on success

esp_err_t touch_pad_intr_disable(void)

To disable touch pad interrupt.

返回

• ESP_OK on success

esp_err_t touch_pad_intr_clear(void)

To clear touch pad interrupt.

返回

• 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

参数

new_period_ms -- filter period, in ms

返回

• 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

参数

p_period_ms -- pointer to accept period

返回

• 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

备注

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.

参数

filter_period_ms -- filter calibration period, in ms

返回

• 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

返回

• 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

返回

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

备注

This callback is called in timer task in each filtering cycle.

备注

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.

备注

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

---

此文档对您有帮助吗？

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

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