触摸传感器

[English]

概述

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

ESP32 可支持最多 10 个电容式触摸板/GPIO,触摸板可以以矩阵或滑条等方式组合使用,从而覆盖更大触感区域及更多触感点。触摸传感由有限状态机 (FSM) 硬件控制,由软件或专用硬件计时器发起。

如需了解触摸传感器设计、操作及其控制寄存器等相关信息,请参考《ESP32-S2 技术参考手册》(PDF),您也可以在《ESP32 技术参考手册》中查看这一子系统是如何运行的。

请参考 触摸传感器应用方案简介,查看触摸传感器设计详情和固件开发指南。更多关于在多种配置环境下测试触摸传感器的信息,请参考 ESP32 触摸功能开发套件

功能介绍

下面将 API 分解成几个函数组进行介绍,帮助您快速了解以下功能:

  • 初始化触摸板驱动程序

  • 配置触摸板 GPIO 管脚

  • 触摸状态测量

  • 调整测量参数(优化测量)

  • 过滤触摸测量

  • 触摸监测方式

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

  • 中断触发

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

初始化触摸板驱动程序

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

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

配置触摸板 GPIO 管脚

调用 touch_pad_config() 使能某一 GPIO 的触感功能。

使用 touch_pad_set_fsm_mode() 选择触摸板测量(由 FSM 操作)是由硬件计时器自动启动,还是由软件自动启动。如果选择软件模式,请使用 touch_pad_sw_start() 启动 FSM。

触摸状态测量

借助以下两个函数从传感器读取原始数据或过滤后的数据:

  • touch_pad_read()

  • touch_pad_read_filtered()

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

注解

使用 touch_pad_read_filtered() 之前,需要先调用 过滤触摸测量 中特定的滤波器函数初始化并配置该滤波器。

请参考应用示例 peripherals/touch_pad_read,查看如何使用这两个读值函数。

优化测量

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

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

可用的测量参数及相应的 ‘set’ 函数总结如下:

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

Touch Pad - relationship between measurement parameters

触摸板 - 测量参数之间的关系

上图中的 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_pad_interrupt,查看以上两种触摸监测的实现方式。

中断触发

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

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

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

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

中断配置完成后,您可以调用 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()

应用示例

API 参考

Functions

esp_err_t touch_pad_fsm_start(void)

Set touch sensor FSM start.

Note

Start FSM after the touch sensor FSM mode is set.

Note

Call this function will reset benchmark of all touch channels.

Return

  • ESP_OK on success

esp_err_t touch_pad_fsm_stop(void)

Stop touch sensor FSM.

Return

  • ESP_OK on success

esp_err_t touch_pad_sw_start(void)

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

Return

  • ESP_OK on success

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.

Note

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

Return

  • ESP_OK on success

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

Return

  • ESP_OK on success

Parameters
  • sleep_cycle: Pointer to accept sleep cycle number

  • meas_times: Pointer to accept measurement times count.

esp_err_t touch_pad_set_idle_channel_connect(touch_pad_conn_type_t type)

Set connection type of touch channel 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.

Return

  • ESP_OK on success

Parameters
  • type: Select idle channel connect to high resistance state or ground.

esp_err_t touch_pad_get_idle_channel_connect(touch_pad_conn_type_t *type)

Set connection type of touch channel 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.

Return

  • ESP_OK on success

Parameters
  • type: Pointer to connection type.

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.

Note

If set “TOUCH_PAD_THRESHOLD_MAX”, the touch is never be triggered.

Return

  • ESP_OK on success

Parameters
  • touch_num: touch pad index

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

esp_err_t touch_pad_get_thresh(touch_pad_t touch_num, uint32_t *threshold)

Get touch sensor trigger threshold.

Return

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG if argument is wrong

Parameters
  • touch_num: touch pad index

  • threshold: pointer to accept threshold

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.

Note

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

Note

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

Return

  • ESP_OK on success

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

esp_err_t touch_pad_get_channel_mask(uint16_t *enable_mask)

Get the touch sensor scan group bit mask.

Return

  • ESP_OK on success

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

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.

Note

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

Return

  • ESP_OK on success

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

esp_err_t touch_pad_config(touch_pad_t touch_num)

Configure parameter for each touch channel.

Note

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

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG if argument wrong

  • ESP_FAIL if touch pad not initialized

Parameters
  • touch_num: touch pad index

esp_err_t touch_pad_reset(void)

Reset the FSM of touch module.

Note

Call this function after touch_pad_fsm_stop.

Return

  • ESP_OK Success

touch_pad_t touch_pad_get_current_meas_channel(void)

Get the current measure channel.

Note

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

Return

  • touch channel number

uint32_t touch_pad_read_intr_status_mask(void)

Get the touch sensor interrupt status mask.

Return

  • touch interrupt bit

esp_err_t touch_pad_intr_enable(touch_pad_intr_mask_t int_mask)

Enable touch sensor interrupt by bitmask.

Note

This API can be called in ISR handler.

Return

  • ESP_OK on success

Parameters
  • int_mask: Pad mask to enable interrupts

esp_err_t touch_pad_intr_disable(touch_pad_intr_mask_t int_mask)

Disable touch sensor interrupt by bitmask.

Note

This API can be called in ISR handler.

Return

  • ESP_OK on success

Parameters
  • int_mask: Pad mask to disable interrupts

esp_err_t touch_pad_intr_clear(touch_pad_intr_mask_t int_mask)

Clear touch sensor interrupt by bitmask.

Return

  • ESP_OK on success

Parameters
  • int_mask: Pad mask to clear interrupts

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.

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Arguments error

  • ESP_ERR_NO_MEM No memory

Parameters
  • fn: Pointer to ISR handler

  • arg: Parameter for ISR

  • intr_mask: Enable touch sensor interrupt handler by bitmask.

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.

Note

The threshold compared with touch readings.

Note

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

Return

  • ESP_OK Success

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

Note

Call this API after finishes the exception handling by user.

Return

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

Note

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

Return

  • ESP_OK Success

  • ESP_FAIL Touch channel 0 haven’t this parameter.

Parameters
  • touch_num: touch pad index

  • raw_data: pointer to accept touch sensor value

esp_err_t touch_pad_read_benchmark(touch_pad_t touch_num, uint32_t *benchmark)

get benchmark of touch sensor.

Note

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

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Touch channel 0 haven’t this parameter.

Parameters
  • touch_num: touch pad index

  • benchmark: pointer to accept touch sensor benchmark value

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.

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

Return

  • ESP_OK Success

Parameters
  • touch_num: touch pad index

    • TOUCH_PAD_MAX Reset basaline of all channels

esp_err_t touch_pad_filter_set_config(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.

Return

  • ESP_OK Success

Parameters
  • filter_info: select filter type and threshold of detection algorithm

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.

Return

  • ESP_OK Success

Parameters
  • filter_info: select filter type and threshold of detection algorithm

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.

Return

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

Return

  • ESP_OK Success

esp_err_t touch_pad_denoise_set_config(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.

Return

  • ESP_OK Success

Parameters
  • denoise: parameter of denoise

esp_err_t touch_pad_denoise_get_config(touch_pad_denoise_t *denoise)

get parameter of denoise pad (TOUCH_PAD_NUM0).

Return

  • ESP_OK Success

Parameters
  • denoise: Pointer to parameter of denoise

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.

Return

  • ESP_OK Success

esp_err_t touch_pad_denoise_disable(void)

disable denoise function.

Return

  • ESP_OK Success

esp_err_t touch_pad_denoise_read_data(uint32_t *data)

Get denoise measure value (TOUCH_PAD_NUM0).

Return

  • ESP_OK Success

Parameters
  • data: Pointer to receive denoise value

esp_err_t touch_pad_waterproof_set_config(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.

Return

  • ESP_OK Success

Parameters
  • waterproof: parameter of waterproof

esp_err_t touch_pad_waterproof_get_config(touch_pad_waterproof_t *waterproof)

get parameter of waterproof function.

Return

  • ESP_OK Success

Parameters
  • waterproof: parameter of waterproof

esp_err_t touch_pad_waterproof_enable(void)

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

Return

  • ESP_OK Success

esp_err_t touch_pad_waterproof_disable(void)

Disable parameter of waterproof function.

Return

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

Note

Supports up to three touch channels configured as proximity sensors.

Return

  • ESP_OK: Configured correctly.

  • ESP_ERR_INVALID_ARG: Touch channel number error.

  • ESP_ERR_NOT_SUPPORTED: Don’t support configured.

Parameters
  • touch_num: touch pad index

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

esp_err_t touch_pad_