触摸滑动传感器

[English]

概述

touch_slider_sensor 组件使用一个触摸 FSM 处理所有配置的频点,基于各通道的正向融合滤波幅度计算滑块位置,并报告位置、滑动和释放事件。组件用于测试和评估,支持的芯片及 ESP-IDF 版本以组件清单为准(需要 ESP-IDF 5.5 或更新版本)。

配置

使用 touch_slider_config_t 配置:

typedef struct {
    uint32_t channel_num;
    uint32_t *channel_list;
    uint32_t *thresholds;
    uint32_t sample_period_ms;
    uint32_t sample_cfg_num;
    uint32_t debounce_active;
    uint32_t debounce_inactive;
    uint32_t filter_reset_times;
    uint32_t position_range;
    uint8_t calculate_window;
    float swipe_threshold;
    float swipe_hysterisis;
    float swipe_alpha;
    bool skip_lowlevel_init;
} touch_slider_config_t;

thresholds 是绝对的归一化 FSM 判定计数,属于融合判定域,不是物理 raw 计数,也不是相对于假定 5000 基准的比例。calculate_window = 0 使用默认值(2 通道为 2,其余为 3);显式设置时可使用 1 到 channel_num。position_range 必须能放入事件使用的有符号数值范围。

示例

static uint32_t channels[] = {2, 4, 6, 12, 10, 8};
static uint32_t thresholds[] = {25, 25, 25, 25, 25, 25};
touch_slider_config_t config = {
    .channel_num = 6,
    .channel_list = channels,
    .thresholds = thresholds,
    .sample_period_ms = 0,
    .sample_cfg_num = 0,
    .debounce_active = 0,
    .debounce_inactive = 0,
    .filter_reset_times = 5,
    .position_range = 10000,
    .calculate_window = 0,
    .swipe_threshold = 50,
    .swipe_hysterisis = 40,
    .swipe_alpha = 0.9f,
    .skip_lowlevel_init = false,
};
touch_slider_handle_t handle = NULL;
ESP_ERROR_CHECK(touch_slider_sensor_create(&config, &handle,
                                           touch_slider_event_callback, NULL));

while (true) {
    ESP_ERROR_CHECK(touch_slider_sensor_handle_events(handle));
    vTaskDelay(pdMS_TO_TICKS(20));
}

回调收到的 TOUCH_SLIDER_EVENT_POSITION 数据位于 [0, position_range];释放事件携带有符号位移。可选的 touch_slider_sensor_get_data 查询返回指定通道的正向融合滤波幅度,不再接收频点参数。

应用示例

API 参考

Header File

Functions

esp_err_t touch_slider_sensor_create(const 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.

The low-level driver is started before callbacks are registered, so startup calibration samples cannot enter the FSM. One FSM receives complete frames and performs all configured frequency fusion.

参数
  • config – [in] Slider configuration.

  • handle – [out] Receives the created sensor handle.

  • cb – [in] Event callback, or NULL.

  • cb_arg – [in] User data passed to the callback.

返回

ESP_OK on success, or an error from allocation, low-level, or FSM setup.

esp_err_t touch_slider_sensor_delete(touch_slider_handle_t handle)

Delete a touch slider sensor instance.

参数

handle – [in] Handle returned by touch_slider_sensor_create(), or NULL.

返回

ESP_OK on success, or the first stop/delete error.

esp_err_t touch_slider_sensor_get_data(touch_slider_handle_t handle, uint32_t channel, uint32_t *data)

Get the normalized fused filtered amplitude for one channel.

The returned value is the positive part of fused_filtered; frequency fusion and smoothing are performed by the FSM.

参数
  • handle – [in] Slider sensor handle.

  • channel – [in] Configured channel number.

  • data – [out] Receives the nonnegative normalized amplitude.

返回

ESP_OK, ESP_ERR_INVALID_ARG, ESP_ERR_INVALID_STATE, or ESP_ERR_NOT_FOUND.

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

Get the current slider state.

参数
  • handle – [in] Slider sensor handle.

  • pressed – [out] True when any channel is active.

  • pos – [out] Current filtered position.

  • speed – [out] Current filtered position speed.

esp_err_t touch_slider_sensor_handle_events(touch_slider_handle_t handle)

Process pending touch slider frames and emit events.

参数

handle – [in] Slider sensor handle.

返回

ESP_OK on success, or an FSM processing error.

Structures

struct touch_slider_config_t

Configuration for a touch slider sensor.

thresholds are absolute normalized fused-count values in the FSM decision domain. They are not physical raw counts and are not ratios relative to a presumed baseline of 5000. The array values are copied by create().

Public Members

uint32_t channel_num

Number of slider channels; must be at least two.

uint32_t *channel_list

Channel IDs, with channel_num entries.

uint32_t *thresholds

Per-channel normalized press thresholds.

uint32_t sample_period_ms

Low-level sampling period; zero selects its default.

uint32_t sample_cfg_num

Frequency samples per frame; zero selects its default.

uint32_t debounce_active

Consecutive active frames; zero selects the FSM default.

uint32_t debounce_inactive

Consecutive inactive frames; zero selects the FSM default.

uint32_t filter_reset_times

Inactive event cycles before resetting the position filter.

uint32_t position_range

Maximum position; output is in [0, position_range].

uint8_t calculate_window

Adjacent channels used for position; zero selects a default.

float swipe_threshold

Speed threshold for identifying a swipe.

float swipe_hysterisis

Hysteresis around the swipe speed threshold.

float swipe_alpha

IIR coefficient for speed estimation, in [0, 1].

bool skip_lowlevel_init

Reuse an existing low-level instance when true.

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 event callback.

Param handle

[in] Touch slider sensor handle.

Param event

[in] Event type.

Param data

[in] Position for POSITION, or signed displacement for RELEASE.

Param cb_arg

[in] User data supplied at create().

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

Slider was swiped toward position_range.

enumerator TOUCH_SLIDER_EVENT_LEFT_SWIPE

Slider was swiped toward position zero.

enumerator TOUCH_SLIDER_EVENT_RELEASE

All slider channels were released.

enumerator TOUCH_SLIDER_EVENT_POSITION

A new slider position was calculated.