触摸按键传感器

[English]

概述

touch_button_sensor 组件为 ESP32 系列芯片提供增强型触摸按键检测功能。它使用多频采样（适用于 ESP32-P4）和基于软件 FSM 的处理来提供可靠的触摸检测，即使在嘈杂的环境中也能正常工作。

备注

• ESP32/ESP32-S2/ESP32-S3 触摸相关组件仅用于测试或演示目的。由于触摸功能的抗干扰能力差，可能无法通过 EMS 测试，因此不建议用于量产产品。

• 该组件目前适用于 ESP32、ESP32-S2 和 ESP32-S3，并且需要 IDF 版本大于等于 v5.3。

主要特性

• 多频触摸采样，提高抗噪声性能

• 基于 FSM 的触摸检测，具有可配置的阈值

• 支持去抖动以确保状态变化的可靠性

• 支持多个触摸通道

• 基于回调的事件通知

依赖项

• touch_sensor_fsm

• touch_sensor_lowlevel

配置参数

触摸按键配置结构体

触摸按键可以通过 touch_button_config_t 结构体进行配置：

typedef struct {
    uint32_t channel_num;          /*!< 触摸按键传感器通道数量 */
    uint32_t *channel_list;        /*!< 触摸通道列表 */
    float *channel_threshold;       /*!< 每个通道的触摸检测阈值 */
    uint32_t *channel_gold_value;   /*!< （可选）触摸通道的参考值 */
    uint32_t debounce_times;        /*!< 确认状态改变所需的连续读数次数 */
    bool skip_lowlevel_init;        /*!< 当与现有触摸驱动程序一起工作时跳过底层初始化 */
} touch_button_config_t;

参数说明

参数	描述	默认值
channel_num	触摸按键传感器通道数量
channel_list	要使用的触摸通道号数组
channel_threshold	每个通道的阈值数组
channel_gold_value	触摸通道的参考值（可选）	NULL
debounce_times	确认状态改变所需的连续读数次数	3
skip_lowlevel_init	如果存在触摸驱动则跳过初始化	false

API 使用示例

创建和初始化

touch_button_config_t config = {
    .channel_num = 1,
    .channel_list = (uint32_t[]){8},            // 使用触摸通道 8
    .channel_threshold = (float[]){0.02},       // 2% 变化阈值
    .channel_gold_value = NULL,                  // 无参考值
    .debounce_times = 3,                        // 3 次读数确认
    .skip_lowlevel_init = false                 // 初始化触摸硬件
};
touch_button_handle_t btn_handle = NULL;
esp_err_t ret = touch_button_sensor_create(&config, &btn_handle, button_state_callback, NULL);

状态改变回调函数

当触摸按键状态改变时会调用回调函数：

void button_state_callback(touch_button_handle_t handle, uint32_t channel, touch_state_t state, void *arg)
{
    switch (state) {
        case TOUCH_STATE_ACTIVE:
            printf("按键通道 %d 被按下\n", channel);
            break;
        case TOUCH_STATE_INACTIVE:
            printf("按键通道 %d 被释放\n", channel);
            break;
    }
}

事件处理

触摸按键传感器组件提供了一个事件处理机制，以非阻塞方式处理触摸事件。事件应该在应用程序的主循环或专用任务中定期处理。

// 在主循环或任务中
while (1) {
    // 处理所有待处理的触摸事件
    touch_button_sensor_handle_events(btn_handle);

    // 添加延时以防止紧密循环
    vTaskDelay(pdMS_TO_TICKS(20));  // 20ms 间隔通常足够
}

示例

• touch/touch_button

API 参考

Header File

• components/touch/touch_button_sensor/include/touch_button_sensor.h

Functions

esp_err_t touch_button_sensor_create(touch_button_config_t *config, touch_button_handle_t *handle, touch_cb_t cb, void *cb_arg)

Create a touch button sensor instance.

This function initializes the touch sensor hardware (unless skip_lowlevel_init is true), sets up FSM instances for touch detection, and registers callbacks for touch events.

参数

• config – Touch button sensor configuration

• handle – Pointer to receive the created touch button sensor handle

• cb – Callback function for touch state changes

• cb_arg – User data to pass to callback function

返回

• ESP_OK on success

• ESP_ERR_INVALID_ARG if config, handle, or required config fields are NULL

• ESP_ERR_NO_MEM if memory allocation fails

• ESP_FAIL if touch sensor or FSM initialization fails

esp_err_t touch_button_sensor_delete(touch_button_handle_t handle)

Delete a touch button sensor instance.

Stops all FSMs, unregisters callbacks, frees resources, and optionally deinitializes the touch sensor hardware.

参数

handle – Touch button sensor handle to delete

返回

• ESP_OK on success (or if handle is NULL)

• ESP_ERR_INVALID_STATE if sensor state is invalid

esp_err_t touch_button_sensor_get_data(touch_button_handle_t handle, uint32_t channel, uint32_t channel_alt, uint32_t *data)

Get touch sensor data for a specific channel and frequency.

Retrieves the smoothed touch sensor reading from the specified channel and frequency instance.

参数

• handle – Touch button sensor handle

• channel – Touch channel number

• channel_alt – Frequency instance index (0 to SOC_TOUCH_SAMPLE_CFG_NUM-1)

• data – Pointer to store the smoothed touch sensor data

返回

• ESP_OK on success

• ESP_ERR_INVALID_ARG if handle or data is NULL

• ESP_ERR_INVALID_STATE if sensor not initialized

• ESP_ERR_NOT_FOUND if channel not configured

esp_err_t touch_button_sensor_get_state(touch_button_handle_t handle, uint32_t channel, touch_state_t *state)

Get current state of a touch channel.

Returns whether the touch channel is currently considered active (touched) based on the combined state of all frequency instances.

参数

• handle – Touch button sensor handle

• channel – Touch channel number

• state – Pointer to store the channel state

返回

• ESP_OK on success

• ESP_ERR_INVALID_ARG if handle or state is NULL

• ESP_ERR_INVALID_STATE if sensor not initialized

• ESP_ERR_NOT_FOUND if channel not configured

esp_err_t touch_button_sensor_get_state_bitmap(touch_button_handle_t handle, uint32_t channel, uint32_t *bitmap)

Get active frequency bitmap for a touch channel.

Returns a bitmap indicating which frequency instances have detected a touch on the specified channel. Each bit corresponds to one frequency.

参数

• handle – Touch button sensor handle

• channel – Touch channel number

• bitmap – Pointer to store the frequency activation bitmap

返回

• ESP_OK on success

• ESP_ERR_INVALID_ARG if handle or bitmap is NULL

• ESP_ERR_INVALID_STATE if sensor not initialized

• ESP_ERR_NOT_FOUND if channel not configured

esp_err_t touch_button_sensor_handle_events(touch_button_handle_t handle)

Handle pending touch sensor events.

Processes events from all FSM instances. This function should be called periodically to update touch states and trigger callbacks.

参数

handle – Touch button sensor handle

返回

• ESP_OK on success

• ESP_ERR_INVALID_ARG if handle is NULL

• ESP_ERR_INVALID_STATE if sensor not initialized

Structures

struct touch_button_config_t

Configuration structure for touch button sensor.

Public Members

uint32_t channel_num

Number of touch button sensor channels

uint32_t *channel_list

Touch channel list

float *channel_threshold

Threshold for touch detection for each channel

uint32_t *channel_gold_value

(Optional) Reference values for touch channels

uint32_t debounce_times

Number of consecutive readings needed to confirm state change

bool skip_lowlevel_init

Skip low level initialization when working with existing touch driver

Type Definitions

typedef struct touch_button_sensor_t *touch_button_handle_t

typedef void (*touch_cb_t)(touch_button_handle_t handle, uint32_t channel, touch_state_t state, void *cb_arg)

Touch sensor callback function type.

Param handle

Touch button sensor handle

Param channel

Channel number that triggered the event

Param state

Current state of the touch sensor

Param cb_arg

User data passed to the callback

Enumerations

enum touch_state_t

Touch sensor state.

Values:

enumerator TOUCH_STATE_INACTIVE

Touch sensor is inactive

enumerator TOUCH_STATE_ACTIVE

Touch sensor is active

提供有关此文档的反馈