Touch Element¶

Overview¶

Touch Element library provides a high level abstraction for building capacitive touch applications. The library’s implementation gives a unified and friendly software interface thus allows for smooth and easy capacitive touch application development. The library is implemented atop the touch sensor driver (please see Touch sensor driver API Reference for more information regarding low level API usage).

Architecture¶

Touch Element library configures touch sensor peripherals via touch sensor driver. While some necessary hardware parameters should be passed to touch_element_install() and will be configured automatically only after calling touch_element_start(), because it will make great influence on the run-time system.

These parameters include touch channel threshold, waterproof shield sensor driver-level and etc. Touch Element library sets touch sensor interrupt and esp-timer routine up and the hardware information of touch sensor (channel state, channel number) will be obtained in touch sensor interrupt service routine. When the specified channel event occurs, and those hardware information will be passed to the esp-timer callback routine, esp-timer callback routine will dispatch the touch sensor channel information to the touch elements(such as button, slider etc). Then runs the specified algorithm to update touch element’s state or calculate its position, dispatch the result to user.

So using Touch Element library, user doesn’t need to care about the implementation of touch sensor peripheral, Touch Element library will handle most of the hardware information and pass the more meaningful messages to user event handler routine.

Workflow of Touch Element library is illustrated in the picture below.

Touch Element architecture¶

The features in relation to the Touch Element library in ESP32-S2 are given in the table below.

Features	ESP32S2
Touch Element waterproof	✔
Touch Element button	✔
Touch Element slider	✔
Touch Element matrix button	✔

Peripheral¶

ESP32-S2 integrates one touch sensor peripheral with several physical channels.

14 physical capacitive touch channels
Timer or software FSM trigger mode
Up to 5 kinds of interrupt(Upper threshold and lower threshold interrupt, measure one channel finish and measure all channels finish interrupt, measurement timeout interrupt)
Sleep mode wakeup source
Hardware internal de-noise
Hardware filter
Hardware waterproof sensor
Hardware proximity sensor

The channels are located as follows:

Channel	ESP32-S2
Channel 0	GPIO 0 (reserved)
Channel 1	GPIO 1
Channel 2	GPIO 2
Channel 3	GPIO 3
Channel 4	GPIO 4
Channel 5	GPIO 5
Channel 6	GPIO 6
Channel 7	GPIO 7
Channel 8	GPIO 8
Channel 9	GPIO 9
Channel 10	GPIO 10
Channel 11	GPIO 11
Channel 12	GPIO 12
Channel 13	GPIO 13
Channel 14	GPIO 14

Terminology¶

The terms used in relation to the Touch Element library are given in the below.

Term	Definition
Touch sensor	Touch sensor peripheral inside the chip
Touch channel	Touch sensor channels inside the touch sensor peripheral
Touch pad	Off-chip physical solder pad (Generally inside the PCB)
De-noise channel	Internal de-noise channel (Is always Channel 0 and it is reserved)
Shield sensor	One of the waterproof sensor, use for compensating the influence of water drop
Guard sensor	One of the waterproof sensor, use for detecting the water stream
Shield channel	The channel that waterproof shield sensor connected to (Is always Channel 14)
Guard channel	The channel that waterproof guard sensor connected to
Shield pad	Off-chip physical solder pad (Generally is grids) and is connected to shield sensor
Guard pad	Off-chip physical solder pad (Is usually a ring) and is connected to guard sensor

Touch sensor application system components¶

Touch Sensor Signal¶

Each touch senor is able to provide the following types of signals:

Raw: The Raw signal is the unfiltered signal from the touch sensor
Smooth: The Smooth signal is a filtered version of the Raw signal via an internal hardware filter
Benchmark: The Benchmark signal is also a filtered signal that filters out extremely low-frequency noise.

All of these signals can be obtained using touch sensor driver API.

Touch sensor signals¶

Touch Sensor Threshold¶

The Touch Sensor Threshold value is a configurable threshold value used to determine when a touch sensor is touched or not. When difference between the Smooth signal and the Benchmark signal becomes greater than the threshold value (i.e., (smooth - benchmark) > threshold), the touch channel’s state will be changed and a touch interrupt will be triggered simultaneously.

Touch sensor signal threshold¶

Sensitivity¶

Important performance parameter of touch sensor, the larger it is, the better touch sensor will perform. It could be calculated by the format in below:

\[Sensitivity = \frac{Signal_{press} - Signal_{release}}{Signal_{release}} = \frac{Signal_{delta}}{Signal_{benchmark}}\]

Waterproof¶

Waterproof is a hardware feature of touch sensor which has guard sensor and shield sensor (Always connect to Channel 14) that has the ability to resist a degree influence of water drop and detect the water stream.

Touch Button¶

Touch button consumes one channel of touch sensor, and it looks like as the picture below:

Touch button¶

Touch Slider¶

Touch slider consumes several channels(at least three channels) of touch sensor, the more channels consumed, the higher resolution and accuracy position it will perform. Touch slider looks like as the picture below:

Touch slider¶

Touch Matrix¶

Touch matrix button consumes several channels(at least 2 + 2 = 4 channels), it gives a solution to use fewer channels and get more buttons. ESP32-S2 supports up to 49 buttons. Touch matrix button looks like as the picture below:

Touch matrix¶

Touch Element Library Usage¶

Using this library should follow the initialization flow below:

To initialize Touch Element library by calling touch_element_install()
To initialize touch elements(button/slider etc) by calling touch_xxxx_install()
To create a new element instance by calling touch_xxxx_create()
To subscribe events by calling touch_xxxx_subscribe_event()
To choose a dispatch method by calling touch_xxxx_set_dispatch_method() that tells the library how to notify you while the subscribed event occur
(If dispatch by callback) Call touch_xxxx_set_callback() to set the event handler function.
To start Touch Element library by calling touch_element_start()
(If dispatch by callback) The callback will be called by the driver core when event happen, no need to do anything; (If dispatch by event task) create an event task and call touch_element_message_receive() to obtain messages in a loop.
[Optional] If user wants to suspend the Touch Element run-time system or for some reason that could not obtain the touch element message, touch_element_stop() should be called to suspend the Touch Element system and then resume it by calling touch_element_start() again.

In code, the flow above may look like as follows:

static touch_xxx_handle_t element_handle; //Declare a touch element handle

//Define the subscribed event handler
void event_handler(touch_xxx_handle_t out_handle, touch_xxx_message_t out_message, void *arg)
{
    //Event handler logic
}

void app_main()
{
    //Using the default initializer to config Touch Element library
    touch_elem_global_config_t global_config = TOUCH_ELEM_GLOBAL_DEFAULT_CONFIG();
    touch_element_install(&global_config);

    //Using the default initializer to config Touch elements
    touch_xxx_global_config_t elem_global_config = TOUCH_XXXX_GLOBAL_DEFAULT_CONFIG();
    touch_xxx_install(&elem_global_config);

    //Create a new instance
    touch_xxx_config_t element_config = {
        ...
        ...
    };
    touch_xxx_create(&element_config, &element_handle);

    //Subscribe the specified events by using the event mask
    touch_xxx_subscribe_event(element_handle, TOUCH_ELEM_EVENT_ON_PRESS | TOUCH_ELEM_EVENT_ON_RELEASE, NULL);

    //Choose CALLBACK as the dispatch method
    touch_xxx_set_dispatch_method(element_handle, TOUCH_ELEM_DISP_CALLBACK);

    //Register the callback routine
    touch_xxx_set_callback(element_handle, event_handler);

    //Start Touch Element library processing
    touch_element_start();
}

Initialization¶

To initialize Touch Element library, user has to configure touch sensor peripheral and Touch Element library by calling touch_element_install() with touch_elem_global_config_t, the default initializer is available in TOUCH_ELEM_GLOBAL_DEFAULT_CONFIG() and this default configuration is suitable for the most general application scene, and users are suggested not to change the default configuration before fully understanding Touch Sensor peripheral, because some changes might bring several impacts to the system.
To initialize the specified element, all the elements will not work before its constructor (touch_xxxx_install()) is called so as to save memory, so user has to call the constructor of each used touch element respectively, to set up the specified element.

Touch Element Instance Startup¶

To create a new touch element instance by calling touch_xxxx_create(), selects channel and passes its Sensitivity for the new element instance.
To subscribe events by calling touch_xxxx_subscribe_event(), there several events in Touch Element library and the event mask is available on components/touch_element/include/touch_element/touch_element.h, user could use those events mask to subscribe specified event or combine them to subscribe multiple events.
To configure dispatch method by calling touch_xxxx_subscribe_event(), there are two dispatch methods in Touch Element library, one is TOUCH_ELEM_DISP_EVENT, the other one is TOUCH_ELEM_DISP_CALLBACK, it means that user could use two methods to obtain the touch element message and handle it.

Events Processing¶

If TOUCH_ELEM_DISP_EVENT dispatch method is configured, user need to startup an event handler task to obtain the touch element message, all the elements raw message could be obtained by calling touch_element_message_receive(), then extract the element-class-specific message by calling the corresponding message decoder (touch_xxxx_get_message()) to get the touch element’s extracted message; If TOUCH_ELEM_DISP_CALLBACK dispatch method is configured, user need to pass an event handler by calling touch_xxxx_set_callback() before the touch elem starts working, all the element’s extracted message will be passed to the event handler function.

Warning

Since the event handler function runs on the library driver core(The context located in esp-timer callback routine), user should not do something that attempts to block or delay, such as call vTaskDelay().

In code, the events handle procedure may look like as follows:

/* ---------------------------------------------- TOUCH_ELEM_DISP_EVENT ----------------------------------------------- */
void element_handler_task(void *arg)
{
    touch_elem_message_t element_message;
    while(1) {
        if (touch_element_message_receive(&element_message, Timeout) == ESP_OK) {
            const touch_xxxx_message_t *extracted_message = touch_xxxx_get_message(&element_message); //Decode message
            ... //Event handler logic
        }
    }
}
void app_main()
{
    ...

    touch_xxxx_set_dispatch_method(element_handle, TOUCH_ELEM_DISP_EVENT);  //Set TOUCH_ELEM_DISP_EVENT as the dispatch method
    xTaskCreate(&element_handler_task, "element_handler_task", 2048, NULL, 5, NULL);  //Create a handler task

    ...
}
/* -------------------------------------------------------------------------------------------------------------- */

...
/* ---------------------------------------------- TOUCH_ELEM_DISP_CALLBACK ----------------------------------------------- */
void element_handler(touch_xxxx_handle_t out_handle, touch_xxxx_message_t out_message, void *arg)
{
    //Event handler logic
}

void app_main()
{
    ...

    touch_xxxx_set_dispatch_method(element_handle, TOUCH_ELEM_DISP_CALLBACK);  //Set TOUCH_ELEM_DISP_CALLBACK as the dispatch method
    touch_xxxx_set_callback(element_handle, element_handler);  //Register an event handler function

    ...
}
/* -------------------------------------------------------------------------------------------------------------- */

Waterproof Usage¶

To initialize Touch Element waterproof, the waterproof shield sensor is always-on after Touch Element waterproof is initialized, however the waterproof guard sensor is optional, hence if user doesn’t need the guard sensor, TOUCH_WATERPROOF_GUARD_NOUSE has to be passed to touch_element_waterproof_install() by the configuration struct.
To associate the touch element with the guard sensor, pass the touch element’s handle to the Touch Element waterproof’s masked list by calling touch_element_waterproof_add(). By associating a touch element with the Guard sensor, the touch element will be disabled when the guard sensor is triggered by a stream of water so as to protect the touch element.

The Touch Element Waterproof example is available in peripherals/touch_element/touch_element_waterproof directory.

In code, the waterproof configuration may look like as follows:

void app_main()
{
    ...

    touch_xxxx_install();                 //Initialize instance (button, slider, etc)
    touch_xxxx_create(&element_handle);  //Create a new Touch element

    ...

    touch_element_waterproof_install();              //Initialize Touch Element waterproof
    touch_element_waterproof_add(element_handle);   //Let a element associates with guard sensor

    ...
}

Application Example¶

All the Touch Element library examples could be found in the peripherals/touch_element directory of ESP-IDF examples.

API Reference - Touch Element core¶

Header File¶

components/touch_element/include/touch_element/touch_element.h

Functions¶

esp_err_t touch_element_install(const touch_elem_global_config_t *global_config)¶

Touch element processing initialization.

Note

To reinitialize the touch element object, call touch_element_uninstall() first

Return

ESP_OK: Successfully initialized
ESP_ERR_INVALID_ARG: Invalid argument
ESP_ERR_NO_MEM: Insufficient memory
ESP_ERR_INVALID_STATE: Touch element is already initialized
Others: Unknown touch driver layer or lower layer error

Parameters

[in] global_config: Global initialization configuration structure

esp_err_t touch_element_start(void)¶

Touch element processing start.

This function starts the touch element processing system

Note

This function must only be called after all the touch element instances finished creating

Return

ESP_OK: Successfully started to process
Others: Unknown touch driver layer or lower layer error

esp_err_t touch_element_stop(void)¶

Touch element processing stop.

This function stops the touch element processing system

Note

This function must be called before changing the system (hardware, software) parameters

Return

ESP_OK: Successfully stopped to process
Others: Unknown touch driver layer or lower layer error

void touch_element_uninstall(void)¶

Release resources allocated using touch_element_install.

Return

ESP_OK: Successfully released touch element object
ESP_ERR_INVALID_STATE: Touch element object is not initialized
Others: Unknown touch driver layer or lower layer error

esp_err_t touch_element_message_receive(touch_elem_message_t *element_message, uint32_t ticks_to_wait)¶

Get current event message of touch element instance.

This function will receive the touch element message (handle, event type, etc…) from te_event_give(). It will block until a touch element event or a timeout occurs.

Return

ESP_OK: Successfully received touch element event
ESP_ERR_INVALID_STATE: Touch element library is not initialized
ESP_ERR_INVALID_ARG: element_message is null
ESP_ERR_TIMEOUT: Timed out waiting for event

Parameters

[out] element_message: Touch element event message structure
[in] ticks_to_wait: Number of FreeRTOS ticks to block for waiting event

esp_err_t touch_element_waterproof_install(const touch_elem_waterproof_config_t *waterproof_config)¶

Touch element waterproof initialization.

This function enables the hardware waterproof, then touch element system uses Shield-Sensor and Guard-Sensor to mitigate the influence of water-drop and water-stream.

Note

If the waterproof function is used, Shield-Sensor can not be disabled and it will use channel 14 as it’s internal channel. Hence, the user can not use channel 14 for another propose. And the Guard-Sensor is not necessary since it is optional.

Note

Shield-Sensor: It always uses channel 14 as the shield channel, so user must connect the channel 14 and Shield-Layer in PCB since it will generate a synchronous signal automatically

Note

Guard-Sensor: This function is optional. If used, the user must connect the guard channel and Guard-Ring in PCB. Any channels user wants to protect should be added into Guard-Ring in PCB.

Return

ESP_OK: Successfully initialized
ESP_ERR_INVALID_STATE: Touch element library is not initialized
ESP_ERR_INVALID_ARG: waterproof_config is null or invalid Guard-Sensor channel
ESP_ERR_NO_MEM: Insufficient memory

Parameters

[in] waterproof_config: Waterproof configuration

void touch_element_waterproof_uninstall(void)¶: Release resources allocated using touch_element_waterproof_install()

esp_err_t touch_element_waterproof_add(touch_elem_handle_t element_handle)¶

Add a masked handle to protect while Guard-Sensor has been triggered.

This function will add an application handle (button, slider, etc…) as a masked handle. While Guard-Sensor has been triggered, waterproof function will start working and lock the application internal state. While the influence of water is reduced, the application will be unlock and reset into IDLE state.

Note

The waterproof protection logic must follow the real circuit in PCB, it means that all of the channels inside the input handle must be inside the Guard-Ring in real circuit.

Return

ESP_OK: Successfully added a masked handle
ESP_ERR_INVALID_STATE: Waterproof is not initialized
ESP_ERR_INVALID_ARG: element_handle is null

Parameters

[in] element_handle: Touch element instance handle

esp_err_t touch_element_waterproof_remove(touch_elem_handle_t element_handle)¶

Remove a masked handle to protect.

This function will remove an application handle from masked handle table.

Return

ESP_OK: Successfully removed a masked handle
ESP_ERR_INVALID_STATE: Waterproof is not initialized
ESP_ERR_INVALID_ARG: element_handle is null
ESP_ERR_NOT_FOUND: Failed to search element_handle from waterproof mask_handle list

Parameters

[in] element_handle: Touch element instance handle

Structures¶

struct touch_elem_sw_config_t¶

Touch element software configuration.

Public Members

float waterproof_threshold_divider¶: Waterproof guard channel threshold divider.

uint8_t processing_period¶: Processing period(ms)

uint8_t intr_message_size¶: Interrupt message queue size.

uint8_t event_message_size¶: Event message queue size.

struct touch_elem_hw_config_t¶

Touch element hardware configuration.

Public Members

touch_high_volt_t upper_voltage¶: Touch sensor channel upper charge voltage.

touch_volt_atten_t voltage_attenuation¶: Touch sensor channel upper charge voltage attenuation (Diff voltage is upper - attenuation - lower)

touch_low_volt_t lower_voltage¶: Touch sensor channel lower charge voltage.

touch_pad_conn_type_t suspend_channel_polarity¶: Suspend channel polarity (High Impedance State or GND)

touch_pad_denoise_grade_t denoise_level¶: Internal de-noise level.

touch_pad_denoise_cap_t denoise_equivalent_cap¶: Internal de-noise channel (Touch channel 0) equivalent capacitance.

touch_smooth_mode_t smooth_filter_mode¶: Smooth value filter mode (This only apply to touch_pad_filter_read_smooth())

touch_filter_mode_t benchmark_filter_mode¶: Benchmark filter mode.

uint16_t sample_count¶: The count of sample in each measurement of touch sensor.

uint16_t sleep_cycle¶: The cycle (RTC slow clock) of sleep.

uint8_t benchmark_debounce_count¶: Benchmark debounce count.

uint8_t benchmark_calibration_threshold¶: Benchmark calibration threshold.

uint8_t benchmark_jitter_step¶: Benchmark jitter filter step (This only works at while benchmark filter mode is jitter filter)

struct touch_elem_global_config_t¶

Touch element global configuration passed to touch_element_install.

Public Members

touch_elem_hw_config_t hardware¶: Hardware configuration.

touch_elem_sw_config_t software¶: Software configuration.

struct touch_elem_waterproof_config_t¶

Touch element waterproof configuration passed to touch_element_waterproof_install.

Public Members

touch_pad_t guard_channel¶: Waterproof Guard-Sensor channel number (index)

float guard_sensitivity¶: Waterproof Guard-Sensor sensitivity.

struct touch_elem_message_t¶

Touch element event message type from touch_element_message_receive()

Public Members

touch_elem_handle_t handle¶: Touch element handle.

touch_elem_type_t element_type¶: Touch element type.

void *arg¶: User input argument.

uint8_t child_msg[8]¶: Encoded message.

Macros¶

TOUCH_ELEM_GLOBAL_DEFAULT_CONFIG()¶

TOUCH_ELEM_EVENT_NONE¶: None event.

TOUCH_ELEM_EVENT_ON_PRESS¶: On Press event.

TOUCH_ELEM_EVENT_ON_RELEASE¶: On Release event.

TOUCH_ELEM_EVENT_ON_LONGPRESS¶: On LongPress event.

TOUCH_ELEM_EVENT_ON_CALCULATION¶: On Calculation event.

TOUCH_WATERPROOF_GUARD_NOUSE¶: Waterproof no use guard sensor.

Type Definitions¶

typedef void *touch_elem_handle_t¶: Touch element handle type.

typedef uint32_t touch_elem_event_t¶: Touch element event type.

Enumerations¶

enum touch_elem_type_t¶

Touch element handle type.

Values:

TOUCH_ELEM_TYPE_BUTTON¶: Touch element button.

TOUCH_ELEM_TYPE_SLIDER¶: Touch element slider.

TOUCH_ELEM_TYPE_MATRIX¶: Touch element matrix button.

enum touch_elem_dispatch_t¶

Touch element event dispatch methods (event queue/callback)

Values:

TOUCH_ELEM_DISP_EVENT¶: Event queue dispatch.

TOUCH_ELEM_DISP_CALLBACK¶: Callback dispatch.

TOUCH_ELEM_DISP_MAX¶

API Reference - Touch Button¶

Header File¶

components/touch_element/include/touch_element/touch_button.h

Functions¶

esp_err_t touch_button_install(const touch_button_global_config_t *global_config)¶

Touch Button initialize.

This function initializes touch button global and acts on all touch button instances.

Return

ESP_OK: Successfully initialized touch button
ESP_ERR_INVALID_STATE: Touch element library was not initialized
ESP_ERR_INVALID_ARG: button_init is NULL
ESP_ERR_NO_MEM: Insufficient memory

Parameters

[in] global_config: Button object initialization configuration

void touch_button_uninstall(void)¶: Release resources allocated using touch_button_install()

esp_err_t touch_button_create(const touch_button_config_t *button_config, touch_button_handle_t *button_handle)¶

Create a new touch button instance.

Note

The sensitivity has to be explored in experiments, Sensitivity = (Raw(touch) - Raw(release)) / Raw(release) * 100%

Return

ESP_OK: Successfully create touch button
ESP_ERR_INVALID_STATE: Touch button driver was not initialized
ESP_ERR_NO_MEM: Insufficient memory
ESP_ERR_INVALID_ARG: Invalid configuration struct or arguments is NULL

Parameters

[in] button_config: Button configuration
[out] button_handle: Button handle

esp_err_t touch_button_delete(touch_button_handle_t button_handle)¶

Release resources allocated using touch_button_create()

Return

ESP_OK: Successfully released resources
ESP_ERR_INVALID_STATE: Touch button driver was not initialized
ESP_ERR_INVALID_ARG: button_handle is null
ESP_ERR_NOT_FOUND: Input handle is not a button handle

Parameters

[in] button_handle: Button handle

esp_err_t touch_button_subscribe_event(touch_button_handle_t button_handle, uint32_t event_mask, void *arg)¶

Touch button subscribes event.

This function uses event mask to subscribe to touch button events, once one of the subscribed events occurs, the event message could be retrieved by calling touch_element_message_receive() or input callback routine.

Note

Touch button only support three kind of event masks, they are TOUCH_ELEM_EVENT_ON_PRESS, TOUCH_ELEM_EVENT_ON_RELEASE, TOUCH_ELEM_EVENT_ON_LONGPRESS. You can use those event masks in any combination to achieve the desired effect.

Return

ESP_OK: Successfully subscribed touch button event
ESP_ERR_INVALID_STATE: Touch button driver was not initialized
ESP_ERR_INVALID_ARG: button_handle is null or event is not supported

Parameters

[in] button_handle: Button handle
[in] event_mask: Button subscription event mask
[in] arg: User input argument

esp_err_t touch_button_set_dispatch_method(touch_button_handle_t button_handle, touch_elem_dispatch_t dispatch_method)¶

Touch button set dispatch method.

This function sets a dispatch method that the driver core will use this method as the event notification method.

Return

ESP_OK: Successfully set dispatch method
ESP_ERR_INVALID_STATE: Touch button driver was not initialized
ESP_ERR_INVALID_ARG: button_handle is null or dispatch_method is invalid

Parameters

[in] button_handle: Button handle
[in] dispatch_method: Dispatch method (By callback/event)

esp_err_t touch_button_set_callback(touch_button_handle_t button_handle, touch_button_callback_t button_callback)¶

Touch button set callback.

This function sets a callback routine into touch element driver core, when the subscribed events occur, the callback routine will be called.

Note

Button message will be passed from the callback function and it will be destroyed when the callback function return.

Warning

Since this input callback routine runs on driver core (esp-timer callback routine), it should not do something that attempts to Block, such as calling vTaskDelay().

Return

ESP_OK: Successfully set callback
ESP_ERR_INVALID_STATE: Touch button driver was not initialized
ESP_ERR_INVALID_ARG: button_handle or button_callback is null

Parameters

[in] button_handle: Button handle
[in] button_callback: User input callback

esp_err_t touch_button_set_longpress(touch_button_handle_t button_handle, uint32_t threshold_time)¶

Touch button set long press trigger time.

This function sets the threshold time (ms) for a long press event. If a button is pressed and held for a period of time that exceeds the threshold time, a long press event is triggered.

Return

ESP_OK: Successfully set the threshold time of long press event
ESP_ERR_INVALID_STATE: Touch button driver was not initialized
ESP_ERR_INVALID_ARG: button_handle is null or time (ms) is not lager than 0

Parameters

[in] button_handle: Button handle
[in] threshold_time: Threshold time (ms) of long press event occur

const touch_button_message_t *touch_button_get_message(const touch_elem_message_t *element_message)¶

Touch button get message.

This function decodes the element message from touch_element_message_receive() and return a button message pointer.

Return

Touch button message pointer

Parameters

[in] element_message: element message

Structures¶

struct touch_button_global_config_t¶

Button initialization configuration passed to touch_button_install.

Public Members

float threshold_divider¶: Button channel threshold divider.

uint32_t default_lp_time¶: Button default LongPress event time (ms)

struct touch_button_config_t¶

Button configuration (for new instance) passed to touch_button_create()

Public Members

touch_pad_t channel_num¶: Button channel number (index)

float channel_sens¶: Button channel sensitivity.

struct touch_button_message_t¶

Button message type.

Public Members

touch_button_event_t event¶: Button event.

Macros¶

TOUCH_BUTTON_GLOBAL_DEFAULT_CONFIG()¶

Type Definitions¶

typedef touch_elem_handle_t touch_button_handle_t¶: Button handle.

typedef void (*touch_button_callback_t)(touch_button_handle_t, touch_button_message_t *, void *)¶: Button callback type.

Enumerations¶

enum touch_button_event_t¶

Button event type.

Values:

TOUCH_BUTTON_EVT_ON_PRESS¶: Button Press event.

TOUCH_BUTTON_EVT_ON_RELEASE¶: Button Release event.

TOUCH_BUTTON_EVT_ON_LONGPRESS¶: Button LongPress event.

TOUCH_BUTTON_EVT_MAX¶

API Reference - Touch Slider¶

Header File¶

components/touch_element/include/touch_element/touch_slider.h

Functions¶

esp_err_t touch_slider_install(const touch_slider_global_config_t *global_config)¶

Touch slider initialize.

This function initializes touch slider object and acts on all touch slider instances.

Return

ESP_OK: Successfully initialized touch slider
ESP_ERR_INVALID_STATE: Touch element library was not initialized
ESP_ERR_INVALID_ARG: slider_init is NULL
ESP_ERR_NO_MEM: Insufficient memory

Parameters

[in] global_config: Touch slider global initialization configuration

void touch_slider_uninstall(void)¶

Release resources allocated using touch_slider_install()

Return

ESP_OK: Successfully released resources

esp_err_t touch_slider_create(const touch_slider_config_t *slider_config, touch_slider_handle_t *slider_handle)¶

Create a new touch slider instance.

Note

The index of Channel array and sensitivity array must be one-one correspondence

Return

ESP_OK: Successfully create touch slider
ESP_ERR_INVALID_STATE: Touch slider driver was not initialized
ESP_ERR_INVALID_ARG: Invalid configuration struct or arguments is NULL
ESP_ERR_NO_MEM: Insufficient memory

Parameters

[in] slider_config: Slider configuration
[out] slider_handle: Slider handle

esp_err_t touch_slider_delete(touch_slider_handle_t slider_handle)¶

Release resources allocated using touch_slider_create.

Return

ESP_OK: Successfully released resources
ESP_ERR_INVALID_STATE: Touch slider driver was not initialized
ESP_ERR_INVALID_ARG: slider_handle is null
ESP_ERR_NOT_FOUND: Input handle is not a slider handle

Parameters

[in] slider_handle: Slider handle

esp_err_t touch_slider_subscribe_event(touch_slider_handle_t slider_handle, uint32_t event_mask, void *arg)¶

Touch slider subscribes event.

This function uses event mask to subscribe to touch slider events, once one of the subscribed events occurs, the event message could be retrieved by calling touch_element_message_receive() or input callback routine.

Note

Touch slider only support three kind of event masks, they are TOUCH_ELEM_EVENT_ON_PRESS, TOUCH_ELEM_EVENT_ON_RELEASE. You can use those event masks in any combination to achieve the desired effect.

Return

ESP_OK: Successfully subscribed touch slider event
ESP_ERR_INVALID_STATE: Touch slider driver was not initialized
ESP_ERR_INVALID_ARG: slider_handle is null or event is not supported

Parameters

[in] slider_handle: Slider handle
[in] event_mask: Slider subscription event mask
[in] arg: User input argument

esp_err_t touch_slider_set_dispatch_method(touch_slider_handle_t slider_handle, touch_elem_dispatch_t dispatch_method)¶

Touch slider set dispatch method.

This function sets a dispatch method that the driver core will use this method as the event notification method.

Return

ESP_OK: Successfully set dispatch method
ESP_ERR_INVALID_STATE: Touch slider driver was not initialized
ESP_ERR_INVALID_ARG: slider_handle is null or dispatch_method is invalid

Parameters

[in] slider_handle: Slider handle
[in] dispatch_method: Dispatch method (By callback/event)

esp_err_t touch_slider_set_callback(touch_slider_handle_t slider_handle, touch_slider_callback_t slider_callback)¶

Touch slider set callback.

This function sets a callback routine into touch element driver core, when the subscribed events occur, the callback routine will be called.

Note

Slider message will be passed from the callback function and it will be destroyed when the callback function return.

Warning

Since this input callback routine runs on driver core (esp-timer callback routine), it should not do something that attempts to Block, such as calling vTaskDelay().

Return

ESP_OK: Successfully set callback
ESP_ERR_INVALID_STATE: Touch slider driver was not initialized
ESP_ERR_INVALID_ARG: slider_handle or slider_callback is null

Parameters

[in] slider_handle: Slider handle
[in] slider_callback: User input callback

const touch_slider_message_t *touch_slider_get_message(const touch_elem_message_t *element_message)¶

Touch slider get message.

This function decodes the element message from touch_element_message_receive() and return a slider message pointer.

Return

Touch slider message pointer

Parameters

[in] element_message: element message

Structures¶

struct touch_slider_global_config_t¶

Slider initialization configuration passed to touch_slider_install.

Public Members

float quantify_lower_threshold¶: Slider signal quantification threshold.

float threshold_divider¶: Slider channel threshold divider.

uint16_t filter_reset_time¶: Slider position filter reset time (Unit is esp_timer callback tick)

uint16_t benchmark_update_time¶: Slider benchmark update time (Unit is esp_timer callback tick)

uint8_t position_filter_size¶: Moving window filter buffer size.

uint8_t position_filter_factor¶: One-order IIR filter factor.

uint8_t calculate_channel_count¶: The number of channels which will take part in calculation.

struct touch_slider_config_t¶

Slider configuration (for new instance) passed to touch_slider_create()

Public Members

const touch_pad_t *channel_array¶: Slider channel array.

const float *sensitivity_array¶: Slider channel sensitivity array.

uint8_t channel_num¶: The number of slider channels.

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

struct touch_slider_message_t¶

Slider message type.

Public Members

touch_slider_event_t event¶: Slider event.

touch_slider_position_t position¶: Slider position.

Macros¶

TOUCH_SLIDER_GLOBAL_DEFAULT_CONFIG()¶

Type Definitions¶

typedef uint32_t touch_slider_position_t¶: Slider position data type.

typedef touch_elem_handle_t touch_slider_handle_t¶: Slider instance handle.

typedef void (*touch_slider_callback_t)(touch_slider_handle_t, touch_slider_message_t *, void *)¶: Slider callback type.

Enumerations¶

enum touch_slider_event_t¶

Slider event type.

Values:

TOUCH_SLIDER_EVT_ON_PRESS¶: Slider on Press event.

TOUCH_SLIDER_EVT_ON_RELEASE¶: Slider on Release event.

TOUCH_SLIDER_EVT_ON_CALCULATION¶: Slider on Calculation event.

TOUCH_SLIDER_EVT_MAX¶

API Reference - Touch Slider¶

Header File¶

components/touch_element/include/touch_element/touch_matrix.h

Functions¶

esp_err_t touch_matrix_install(const touch_matrix_global_config_t *global_config)¶

Touch matrix button initialize.

This function initializes touch matrix button object and acts on all touch matrix button instances.

Return

ESP_OK: Successfully initialized touch matrix button
ESP_ERR_INVALID_STATE: Touch element library was not initialized
ESP_ERR_INVALID_ARG: matrix_init is NULL
ESP_ERR_NO_MEM: Insufficient memory

Parameters

[in] global_config: Touch matrix global initialization configuration

void touch_matrix_uninstall(void)¶

Release resources allocated using touch_matrix_install()

Return

ESP_OK: Successfully released resources

esp_err_t touch_matrix_create(const touch_matrix_config_t *matrix_config, touch_matrix_handle_t *matrix_handle)¶

Create a new touch matrix button instance.

Note

Channel array and sensitivity array must be one-one correspondence in those array

Note

Touch matrix button does not support Multi-Touch now

Return

ESP_OK: Successfully create touch matrix button
ESP_ERR_INVALID_STATE: Touch matrix driver was not initialized
ESP_ERR_INVALID_ARG: Invalid configuration struct or arguments is NULL
ESP_ERR_NO_MEM: Insufficient memory

Parameters

[in] matrix_config: Matrix button configuration
[out] matrix_handle: Matrix button handle

esp_err_t touch_matrix_delete(touch_matrix_handle_t matrix_handle)¶

Release resources allocated using touch_matrix_create()

Return

ESP_OK: Successfully released resources
ESP_ERR_INVALID_STATE: Touch matrix driver was not initialized
ESP_ERR_INVALID_ARG: matrix_handle is null
ESP_ERR_NOT_FOUND: Input handle is not a matrix handle

Parameters

[in] matrix_handle: Matrix handle

esp_err_t touch_matrix_subscribe_event(touch_matrix_handle_t matrix_handle, uint32_t event_mask, void *arg)¶

Touch matrix button subscribes event.

This function uses event mask to subscribe to touch matrix events, once one of the subscribed events occurs, the event message could be retrieved by calling touch_element_message_receive() or input callback routine.

Note

Touch matrix button only support three kind of event masks, they are TOUCH_ELEM_EVENT_ON_PRESS, TOUCH_ELEM_EVENT_ON_RELEASE, TOUCH_ELEM_EVENT_ON_LONGPRESS. You can use those event masks in any combination to achieve the desired effect.

Return

ESP_OK: Successfully subscribed touch matrix event
ESP_ERR_INVALID_STATE: Touch matrix driver was not initialized
ESP_ERR_INVALID_ARG: matrix_handle is null or event is not supported

Parameters

[in] matrix_handle: Matrix handle
[in] event_mask: Matrix subscription event mask
[in] arg: User input argument

esp_err_t touch_matrix_set_dispatch_method(touch_matrix_handle_t matrix_handle, touch_elem_dispatch_t dispatch_method)¶

Touch matrix button set dispatch method.

This function sets a dispatch method that the driver core will use this method as the event notification method.

Return

ESP_OK: Successfully set dispatch method
ESP_ERR_INVALID_STATE: Touch matrix driver was not initialized
ESP_ERR_INVALID_ARG: matrix_handle is null or dispatch_method is invalid

Parameters

[in] matrix_handle: Matrix button handle
[in] dispatch_method: Dispatch method (By callback/event)

esp_err_t touch_matrix_set_callback(touch_matrix_handle_t matrix_handle, touch_matrix_callback_t matrix_callback)¶

Touch matrix button set callback.

This function sets a callback routine into touch element driver core, when the subscribed events occur, the callback routine will be called.

Note

Matrix message will be passed from the callback function and it will be destroyed when the callback function return.

Warning

Since this input callback routine runs on driver core (esp-timer callback routine), it should not do something that attempts to Block, such as calling vTaskDelay().

Return

ESP_OK: Successfully set callback
ESP_ERR_INVALID_STATE: Touch matrix driver was not initialized
ESP_ERR_INVALID_ARG: matrix_handle or matrix_callback is null

Parameters

[in] matrix_handle: Matrix button handle
[in] matrix_callback: User input callback

esp_err_t touch_matrix_set_longpress(touch_matrix_handle_t matrix_handle, uint32_t threshold_time)¶

Touch matrix button set long press trigger time.

This function sets the threshold time (ms) for a long press event. If a matrix button is pressed and held for a period of time that exceeds the threshold time, a long press event is triggered.

Return

ESP_OK: Successfully set the time of long press event
ESP_ERR_INVALID_STATE: Touch matrix driver was not initialized
ESP_ERR_INVALID_ARG: matrix_handle is null or time (ms) is 0

Parameters

[in] matrix_handle: Matrix button handle
[in] threshold_time: Threshold time (ms) of long press event occur

const touch_matrix_message_t *touch_matrix_get_message(const touch_elem_message_t *element_message)¶

Touch matrix get message.

This function decodes the element message from touch_element_message_receive() and return a matrix message pointer.

Return

Touch matrix message pointer

Parameters

[in] element_message: element message

Structures¶

struct touch_matrix_global_config_t¶

Matrix button initialization configuration passed to touch_matrix_install.

Public Members

float threshold_divider¶: Matrix button channel threshold divider.

uint32_t default_lp_time¶: Matrix button default LongPress event time (ms)

struct touch_matrix_config_t¶

Matrix button configuration (for new instance) passed to touch_matrix_create()

Public Members

const touch_pad_t *x_channel_array¶: Matrix button x-axis channels array.

const touch_pad_t *y_channel_array¶: Matrix button y-axis channels array.

const float *x_sensitivity_array¶: Matrix button x-axis channels sensitivity array.

const float *y_sensitivity_array¶: Matrix button y-axis channels sensitivity array.

uint8_t x_channel_num¶: The number of channels in x-axis.

uint8_t y_channel_num¶: The number of channels in y-axis.

struct touch_matrix_position_t¶

Matrix button position data type.

Public Members

uint8_t x_axis¶: Matrix button x axis position.

uint8_t y_axis¶: Matrix button y axis position.

uint8_t index¶: Matrix button position index.

struct touch_matrix_message_t¶

Matrix message type.

Public Members

touch_matrix_event_t event¶: Matrix event.

touch_matrix_position_t position¶: Matrix position.

Macros¶

TOUCH_MATRIX_GLOBAL_DEFAULT_CONFIG()¶

Type Definitions¶

typedef touch_elem_handle_t touch_matrix_handle_t¶: Matrix button instance handle.

typedef void (*touch_matrix_callback_t)(touch_matrix_handle_t, touch_matrix_message_t *, void *)¶: Matrix button callback type.

Enumerations¶

enum touch_matrix_event_t¶

Matrix button event type.

Values:

TOUCH_MATRIX_EVT_ON_PRESS¶: Matrix button Press event.

TOUCH_MATRIX_EVT_ON_RELEASE¶: Matrix button Press event.

TOUCH_MATRIX_EVT_ON_LONGPRESS¶: Matrix button LongPress event.

TOUCH_MATRIX_EVT_MAX¶

Provide feedback about this document