触摸按键传感器

[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;       /*!< 滑块位置的最大值，位置范围为 [0, position_range]。数值越大位置精度越高 */
    uint8_t calculate_window;    /*!< 位置计算的窗口大小（应该 <= channel_num）。设置为 0 则自动默认：2通道用2，3+通道用3 */
    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	滑块位置最大值（数值越大精度越高）
calculate_window	位置计算的窗口大小	自动(0)
swipe_threshold	滑动检测的速度阈值
swipe_hysterisis	滑动检测的速度迟滞
swipe_alpha	速度滤波参数
skip_lowlevel_init	如果存在触摸驱动则跳过初始化	false

计算窗口配置

calculate_window 参数决定了用于位置计算的相邻触摸通道数量。这会影响滑块的精度和抗噪性能。

默认值（当设置为 0 时）：

• 2 通道: calculate_window = 2 （使用所有可用通道）

• 3+ 通道: calculate_window = 3 （精度和抗噪性能之间的最佳平衡）

手动配置：

• 您可以显式设置从 2 到 channel_num 的任何值

• 较小值 (2)：更高的灵敏度但更容易受噪声影响

• 较大值 (3+)：更好的抗噪性能但可能降低分辨率

• 对于高精度应用：推荐值为 min(3, channel_num)

• 注意：最小值为 2，因为滑动条位置计算至少需要 2 个相邻通道

向后兼容性：

• 设置 calculate_window = 0 启用自动默认选择

• 未初始化此字段的现有代码将使用最优默认值

• 显式设置的值继续按原来的方式工作

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,
    .calculate_window = 0,  // 使用默认值（6通道时自动选择为3）
    .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 间隔通常足够
}

示例

• touch/touch_slider_sensor

API 参考

Header File

• components/touch/touch_slider_sensor/include/touch_slider_sensor.h

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.

备注

The calculate_window parameter determines how many adjacent channels are used for position calculation. For backward compatibility, if set to 0, default values will be used:

• 2 channels: window_size = 2 (use all channels)

• 3+ channels: window_size = 3 (optimal balance between precision and noise immunity)

• For high-precision applications: window_size = min(3, channel_num)

参数

• 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, or if calculate_window is less than 2 or greater than channel_num (0 is acceptable for auto-default)

• 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

Maximum position value of touch slider, range [0, position_range]. Higher values provide better position resolution

uint8_t calculate_window

Window size for position calculation (should be <= channel_num). Set to 0 for auto-default: 2 for 2-channel, 3 for 3+ channels

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

提供有关此文档的反馈