Touch Button Sensor

[中文]

Overview

The touch_button_sensor component provides enhanced touch button detection functionality for ESP32 series chips. It uses multiple frequency sampling (for ESP32-P4) and FSM-based processing to provide reliable touch detection even in noisy environments.

Note

• ESP32/ESP32-S2/ESP32-S3 touch-related components are intended for testing or demo purposes only. Due to the poor anti-interference capability of the touch functionality, it may not pass EMS testing, and therefore, it is not recommended for mass production products.

• This component is currently applicable to ESP32, ESP32-S2, and ESP32-S3, and requires an IDF version greater than or equal to v5.3.

Key Features

• Multi-frequency touch sampling for improved noise immunity

• FSM-based touch detection with configurable thresholds

• Debounce support for reliable state changes

• Support for multiple touch channels

• Callback-based event notification

Dependencies

• touch_sensor_fsm

• touch_sensor_lowlevel

Configuration Parameters

Touch Button Configuration Structure

The touch button can be configured via the touch_button_config_t structure:

typedef struct {
    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 */
} touch_button_config_t;

Parameter Descriptions

Parameter	Description	Default Value
channel_num	Number of touch button sensor channels
channel_list	Array of touch channel numbers to use
channel_threshold	Array of threshold values for each channel
channel_gold_value	Reference values for touch channels (optional)	NULL
debounce_times	Consecutive readings for state change	3
skip_lowlevel_init	Skip touch driver initialization if exists	false

API Usage Examples

Create and Initialize

touch_button_config_t config = {
    .channel_num = 1,
    .channel_list = (uint32_t[]){8},            // Using touch channel 8
    .channel_threshold = (float[]){0.02},       // 2% change threshold
    .channel_gold_value = NULL,                  // No reference values
    .debounce_times = 3,                        // 3 readings to confirm
    .skip_lowlevel_init = false                 // Initialize touch hardware
};
touch_button_handle_t btn_handle = NULL;
esp_err_t ret = touch_button_sensor_create(&config, &btn_handle, button_state_callback, NULL);

State Change Callback

The callback function is called when a touch button state changes:

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("Button channel %d pressed\n", channel);
            break;
        case TOUCH_STATE_INACTIVE:
            printf("Button channel %d released\n", channel);
            break;
    }
}

Event Handling

The touch button sensor component provides an event handling mechanism to process touch events in a non-blocking way. Events should be handled periodically in your application’s main loop or in a dedicated task.

// In your main loop or task
while (1) {
    // Process any pending touch events
    touch_button_sensor_handle_events(btn_handle);

    // Add delay to prevent tight loop
    vTaskDelay(pdMS_TO_TICKS(20));  // 20ms interval is typically sufficient
}

Examples

• touch/touch_button

API Reference

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.

Parameters

• 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

Returns

• 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.

Parameters

handle – Touch button sensor handle to delete

Returns

• 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.

Parameters

• 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

Returns

• 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.

Parameters

• handle – Touch button sensor handle

• channel – Touch channel number

• state – Pointer to store the channel state

Returns

• 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.

Parameters

• handle – Touch button sensor handle

• channel – Touch channel number

• bitmap – Pointer to store the frequency activation bitmap

Returns

• 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.

Parameters

handle – Touch button sensor handle

Returns

• 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

Provide feedback about this document