触摸按键传感器

[English]

概述

touch_button_sensor 组件为 ESP32 系列芯片提供增强型触摸按键检测功能。

备注

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

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

主要特性

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

  • 支持滑动手势识别

  • 基于回调的事件通知

依赖项

  • touch_sensor_fsm

  • touch_sensor_lowlevel

配置参数

触摸滑动配置结构体

触摸滑动可以通过 touch_slider_config_t 结构体进行配置：

typedef struct {
    uint32_t channel_num;         /*!< 触摸按键传感器通道数量 */
    uint32_t *channel_list;       /*!< 触摸通道列表 */
    float *channel_threshold;     /*!< 每个通道的触摸检测阈值 */
    uint32_t *channel_gold_value; /*!< （可选）触摸通道的参考值 */
    uint32_t debounce_times;      /*!< 确认状态改变所需的连续读数次数 */
    uint32_t filter_reset_times;  /*!< 重置位置的读数次数 */
    uint32_t position_range;       /*!< 滑块最右端的范围 */
    float swipe_threshold;        /*!< 滑动检测的速度阈值 */
    float swipe_hysterisis;       /*!< 滑动检测的速度迟滞 */
    float swipe_alpha;            /*!< 速度滤波参数 */
    bool skip_lowlevel_init;      /*!< 当与现有触摸驱动程序一起工作时跳过底层初始化 */
} touch_slider_config_t;

参数说明

参数

描述

默认值

channel_num

触摸按键传感器通道数量

channel_list

要使用的触摸通道号数组

channel_threshold

每个通道的阈值数组

channel_gold_value

触摸通道的参考值（可选）

NULL

debounce_times

确认状态改变所需的连续读数次数

3

filter_reset_times

重置位置的读数次数

position_range

滑块最右端的范围

swipe_threshold

滑动检测的速度阈值

swipe_hysterisis

滑动检测的速度迟滞

swipe_alpha

速度滤波参数

skip_lowlevel_init

如果存在触摸驱动则跳过初始化

false

API 使用示例

创建和初始化

uint32_t channel_list[] = {2, 4, 6, 12, 10, 8};
float threshold[] = {0.005f, 0.005f, 0.005f, 0.005f, 0.005f, 0.005f};
touch_slider_config_t config = {
    .channel_num = 6,
    .channel_list = channel_list,
    .channel_threshold = threshold,
    .filter_reset_times = 5,
    .position_range = 10000,
    .swipe_alpha = 0.9,
    .swipe_threshold = 50,
    .swipe_hysterisis = 40,
    .channel_gold_value = NULL,
    .debounce_times = 0,
    .skip_lowlevel_init = false
};

// Test successful creation
TEST_ASSERT_EQUAL(ESP_OK, touch_slider_sensor_create(&config, &s_touch_slider,  touch_slider_event_callback, NULL));
TEST_ASSERT_NOT_NULL(s_touch_slider);

事件回调函数

当位置改变或者状态改变时会调用回调函数。结合滑动速度或者松开的位移可以判断手势。

static void touch_slider_event_callback(touch_slider_handle_t handle, touch_slider_event_t event, int32_t data, void *cb_arg)
{
    if (event == TOUCH_SLIDER_EVENT_RIGHT_SWIPE) {
        printf("右滑（速度）\n");
    } else if (event == TOUCH_SLIDER_EVENT_LEFT_SWIPE) {
        printf("左滑（速度）\n");
    } else if (event == TOUCH_SLIDER_EVENT_RELEASE) {
        printf("滑动 %ld\n", data);
        if (data > 1000)
        {
            printf("右滑（位移）\n");
        }
        else if (data < -1000)
        {
            printf("左滑（位移）\n");
        }
    } else if (event == TOUCH_SLIDER_EVENT_POSITION)
    {
        printf("位置,%" PRId64 ",%lu\n", get_time_in_ms(), data);
    }
}

事件处理

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

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

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

示例

API 参考

Header File

Functions

esp_err_t touch_slider_sensor_create(touch_slider_config_t *config, touch_slider_handle_t *handle, touch_slider_event_cb_t cb, void *cb_arg)

Create a touch slider 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 slider sensor configuration

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

  • cb – Callback function for touch slider events

  • 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_slider_sensor_delete(touch_slider_handle_t handle)

Delete a touch slider sensor instance.

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

参数

handle – Touch slider 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_slider_sensor_get_data(touch_slider_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 slider 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

void touch_slider_sensor_get_state(touch_slider_handle_t handle, bool *pressed, uint32_t *pos, float *speed)

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 slider sensor handle

  • pressed – Touch slider is pressed or not

  • pos – Touch slider speed

  • speed – Touch slider speed

esp_err_t touch_slider_sensor_handle_events(touch_slider_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 slider 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_slider_config_t

Configuration structure for touch slider sensor.

Public Members

uint32_t channel_num

Number of touch slider 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

uint32_t filter_reset_times

Number of consecutive readings to reset position filter

uint32_t position_range

The right region of touch slider position range, [0, position_range (less than or equal to 255)]

float swipe_threshold

The speed threshold for identifying swiping

float swipe_hysterisis

The speed hysterisis for identifying swiping

float swipe_alpha

Filter parameter for estimating speed

bool skip_lowlevel_init

Skip low level initialization when working with existing touch driver

Type Definitions

typedef struct touch_slider_sensor_t *touch_slider_handle_t
typedef void (*touch_slider_event_cb_t)(touch_slider_handle_t handle, touch_slider_event_t event, int32_t data, void *cb_arg)

Touch slider sensor event callback function type.

Param handle

Touch slider sensor handle

Param event

Touch slider event

Param data

Touch slider data. Position if event == TOUCH_SLIDER_EVENT_POSITION, displacement if event == TOUCH_SLIDER_EVENT_RELEASE

Param cb_arg

User data passed to the callback

Enumerations

enum touch_slider_event_t

Touch slider event.

Values:

enumerator TOUCH_SLIDER_EVENT_NONE

Touch slider is stationary

enumerator TOUCH_SLIDER_EVENT_RIGHT_SWIPE

Touch slider is swiped right (from 0 to position_range)

enumerator TOUCH_SLIDER_EVENT_LEFT_SWIPE

Touch slider is swiped left (from position_range to 0)

enumerator TOUCH_SLIDER_EVENT_RELEASE

Touch slider is released

enumerator TOUCH_SLIDER_EVENT_POSITION

Touch slider position is calculated

提供有关此文档的反馈