Touch Slider Sensor

Overview

The touch_slider_sensor component uses one touch FSM for all configured frequencies. It calculates the slider position from each channel’s positive fused filtered amplitude and reports position, swipe, and release events. It is intended for testing and evaluation and requires ESP-IDF 5.5 or newer on the targets listed by its component manifest.

Configuration

Use 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 contains absolute normalized FSM decision counts. These values are in the fused decision domain, rather than physical raw counts or a ratio relative to a presumed 5000 baseline. calculate_window = 0 selects the default (2 for two channels, otherwise 3); explicit values from 1 through channel_num are valid. position_range must fit the signed event data range.

Example

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));
}

The callback receives TOUCH_SLIDER_EVENT_POSITION with a position in [0, position_range]. Release events carry a signed displacement. The optional touch_slider_sensor_get_data query returns the positive fused filtered amplitude for a configured channel; it no longer takes a frequency argument.

Examples

touch/touch_slider_sensor

API Reference

Header File

components/touch/touch_slider_sensor/include/touch_slider_sensor.h

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.

Parameters

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.

Returns

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.

Parameters: handle – [in] Handle returned by touch_slider_sensor_create(), or NULL.
Returns: 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.

Parameters

handle – [in] Slider sensor handle.
channel – [in] Configured channel number.
data – [out] Receives the nonnegative normalized amplitude.

Returns

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.

Parameters

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.

Parameters: handle – [in] Slider sensor handle.
Returns: 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.

Provide feedback about this document