Touch Element

Overview

The Touch Element Library is a highly abstracted element library designed on the basis of the touch sensor driver. The library provides a unified and user-friendly software interface to quickly build capacitive touch sensor applications.

WARNING: The Touch Element Library is only usable for the ESP32-S2 and ESP32-S3 chips.

WARNING: The Touch Element Library currently is still based on the legacy touch driver. Please refer to the new driver of Capacitive Touch Sensor if you don't need the Touch Element Library.

Architecture

The Touch Element library configures touch sensor peripherals via the touch sensor driver. However, some necessary hardware parameters should be passed to touch_element_install and will be configured automatically only after calling touch_element_start. This sequential order is essential because configuring these parameters has a significant impact on the run-time system. Therefore, they must be configured after calling the start function to ensure the system functions properly.

These parameters include touch channel threshold, driver-level of waterproof shield sensor, etc. The Touch Element library sets the touch sensor interrupt and the esp_timer routine up, and the hardware information of the touch sensor (channel state, channel number) will be obtained in the touch sensor interrupt service routine. When the specified channel event occurs, the hardware information is passed to the esp_timer callback routine, which then dispatches the touch sensor channel information to the touch elements (such as button, slider, etc.). The library then runs a specified algorithm to update the touch element's state or calculate its position and dispatches the result accordingly.

So when using the Touch Element library, you are relieved from the implementation details of the touch sensor peripheral. The library handles most of the hardware information and passes the more meaningful messages to the event handler routine.

The workflow of the Touch Element library is illustrated in the picture below.

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

Peripheral

ESP32-S2 / ESP32-S3 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:

Terminology

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

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, which is always Channel 0 and is reserved

Shield sensor

• One of the waterproof sensors for detecting droplets in small areas and compensating for the influence of water drops on measurements

Guard sensor

• One of the waterproof sensors for detecting extensive wading and to temporarily disable the touch sensor

Shield channel

• The channel that waterproof shield sensor connected to, which 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 the sensor

Guard pad

• Off-chip physical solder pad, usually a ring, and is connected to the guard sensor

Touch Sensor Signal

Each touch sensor 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 Signal Threshold

The Touch Sensor Threshold value is a configurable threshold value used to determine when a touch sensor is touched or not. When the 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.

Sensitivity

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

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

Waterproof

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

Touch Button

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

Touch Slider

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

Touch Matrix

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

Touch Element Library Usage

Using this library should follow the initialization flow below:

1. To initialize the Touch Element library by calling touch_element_install.
2. To initialize touch elements (button/slider etc) by calling touch_button_install, touch_slider_install or touch_matrix_install.
3. To create a new element instance by calling touch_button_create, touch_slider_create or touch_matrix_create.
4. To subscribe events by calling touch_button_subscribe_event, touch_slider_subscribe_event or touch_matrix_subscribe_event.
5. To choose a dispatch method by calling touch_button_set_dispatch_method, touch_slider_set_dispatch_method or touch_matrix_set_dispatch_method that tells the library how to notify you while the subscribed event occurs.
6. If dispatch by callback, call touch_button_set_callback, touch_slider_set_callback or touch_matrix_set_callback to set the event handler function.
7. To start the Touch Element library by calling touch_element_start.
8. If dispatch by callback, the callback will be called by the driver core when an event happens, 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.
9. (Optional) If you want 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_button_handle_t element_handle; //Declare a touch element handle

    //Define the subscribed event handler
    void event_handler(touch_button_handle_t out_handle, touch_button_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_slider_global_config_t elem_global_config = TOUCH_SLIDER_GLOBAL_DEFAULT_CONFIG();
        touch_slider_install(&elem_global_config);

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

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

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

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

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

Initialization

1. To initialize the Touch Element library, you have to configure the 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 it is suggested not to change the default configuration before fully understanding Touch Sensor peripheral because some changes might bring several impacts to the system.

2. To initialize the specified element, all the elements will not work before its constructor touch_button_install, touch_slider_install or touch_matrix_install is called so as to save memory, so you have to call the constructor of each used touch element respectively, to set up the specified element.

Touch Element Instance Startup

1. To create a new touch element instance, call touch_button_create, touch_slider_create or touch_matrix_create, select a channel, and provide its Sensitivity_ value for the new element instance.

2. To subscribe to events, call touch_button_subscribe_event, touch_slider_subscribe_event or touch_matrix_subscribe_event. The Touch Element library offers several events, and the event mask is available in touch_element.h. You can use these event masks to subscribe to specific events individually or combine them to subscribe to multiple events.

3. To configure the dispatch method, use touch_button_set_dispatch_method, touch_slider_set_dispatch_method or touch_matrix_set_dispatch_method. The Touch Element library provides two dispatch methods defined in touch_elem_dispatch_t: TOUCH_ELEM_DISP_EVENT and TOUCH_ELEM_DISP_CALLBACK. These methods allow you to obtain the touch element message and handle it using different approaches.

Events Processing

If TOUCH_ELEM_DISP_EVENT dispatch method is configured, you need to start up 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 with touch_button_get_message, touch_slider_get_message to get the touch element's extracted message; If TOUCH_ELEM_DISP_CALLBACK dispatch method is configured, you need to pass an event handler by calling touch_slider_set_callback or touch_matrix_get_message to get the touch element's extracted message; If TOUCH_ELEM_DISP_CALLBACK dispatch method is configured, you need to pass an event handler by calling touch_matrix_set_callback before the touch element 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 core of the element library, i.e., in the esp_timer callback routine, please avoid performing operations that may cause blocking or delays, such as calling 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_matrix_message_t *extracted_message = touch_matrix_get_message(&element_message); //Decode message
                ... //Event handler logic
            }
        }
    }
    void app_main()
    {
        ...

        touch_matrix_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_matrix_handle_t out_handle, touch_matrix_message_t out_message, void *arg)
    {
        //Event handler logic
    }

    void app_main()
    {
        ...

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

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

Waterproof Usage

1. The waterproof shield sensor is always-on after Touch Element waterproof is initialized, however, the waterproof guard sensor is optional, hence if the you do not need the guard sensor, TOUCH_WATERPROOF_GUARD_NOUSE has to be passed to touch_element_waterproof_install by the configuration struct.

2. 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 under the examples/touch_element_waterproof directory.

In code, the waterproof configuration may look as follows:

    void app_main()
    {
        ...

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

        ...

        touch_element_waterproof_install();              //Initialize Touch Element waterproof
        touch_element_waterproof_add(element_handle);   //Let an element associate with the guard sensor

        ...
    }

Wakeup from Light/Deep-sleep Mode

Only Touch Button can be configured as a wake-up source.

Light- or Deep-sleep modes are both supported to be wakened up by a touch sensor. For the Light-sleep mode, any installed touch button can wake it up. But only the sleep button can wake up from Deep-sleep mode, and the touch sensor will do a calibration immediately, the reference value will be calibrated to a wrong value if our finger does not remove timely. Though the wrong reference value recovers after the finger removes away and has no effect on the driver logic, if you do not want to see a wrong reference value while waking up from Deep-sleep mode, you can call touch_element_sleep_enable_wakeup_calibration to disable the wakeup calibration.

    void app_main()
    {
        ...
        touch_element_install();
        touch_button_install();                 //Initialize the touch button
        touch_button_create(&element_handle);  //Create a new Touch element

        ...

        // ESP_ERROR_CHECK(touch_element_enable_light_sleep(&sleep_config));
        ESP_ERROR_CHECK(touch_element_enable_deep_sleep(button_handle[0], &sleep_config));
        // ESP_ERROR_CHECK(touch_element_sleep_enable_wakeup_calibration(button_handle[0], false)); // (optional) Disable wakeup calibration to prevent updating the benchmark to a wrong value

        touch_element_start();

        ...
    }

API Reference

Header files

• include/touch_element/touch_button.h
• include/touch_element/touch_element.h
• include/touch_element/touch_matrix.h
• include/touch_element/touch_sensor_legacy_types.h
• include/touch_element/touch_slider.h

File include/touch_element/touch_button.h

Structures and Types

Functions

Macros

Structures and Types Documentation

typedef touch_button_callback_t

Button callback type.

typedef void(* touch_button_callback_t) (touch_button_handle_t, touch_button_message_t *, void *);

struct touch_button_config_t

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

Variables:

• touch_pad_t channel_num
  Button channel number (index)

• float channel_sens
  Button channel sensitivity.

enum touch_button_event_t

Button event type.

enum touch_button_event_t {
    TOUCH_BUTTON_EVT_ON_PRESS,
    TOUCH_BUTTON_EVT_ON_RELEASE,
    TOUCH_BUTTON_EVT_ON_LONGPRESS,
    TOUCH_BUTTON_EVT_MAX
};

struct touch_button_global_config_t

Button initialization configuration passed to touch_button_install.

Variables:

• uint32_t default_lp_time
  Button default LongPress event time (ms)

• float threshold_divider
  Button channel threshold divider.

typedef touch_button_handle_t

Button handle.

typedef touch_elem_handle_t touch_button_handle_t;

struct touch_button_message_t

Button message type.

Variables:

• touch_button_event_t event
  Button event.

Functions Documentation

function touch_button_create

Create a new touch button instance.

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

Parameters:

• button_config Button configuration
• button_handle Button handle

Note:

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

Returns:

• 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

function touch_button_delete

Release resources allocated using touch_button_create()

esp_err_t touch_button_delete (
    touch_button_handle_t button_handle
) 

Parameters:

• button_handle Button handle

Returns:

• 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

function touch_button_get_message

Touch button get message.

const touch_button_message_t * touch_button_get_message (
    const touch_elem_message_t *element_message
) 

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

Parameters:

• element_message element message

Returns:

Touch button message pointer

function touch_button_install

Touch Button initialize.

esp_err_t touch_button_install (
    const touch_button_global_config_t *global_config
) 

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

Parameters:

• global_config Button object initialization configuration

Returns:

• 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

function touch_button_set_callback

Touch button set callback.

esp_err_t touch_button_set_callback (
    touch_button_handle_t button_handle,
    touch_button_callback_t button_callback
) 

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

Parameters:

• button_handle Button handle
• button_callback User input callback

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().

Returns:

• 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

function touch_button_set_dispatch_method

Touch button set dispatch method.

esp_err_t touch_button_set_dispatch_method (
    touch_button_handle_t button_handle,
    touch_elem_dispatch_t dispatch_method
) 

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

Parameters:

• button_handle Button handle
• dispatch_method Dispatch method (By callback/event)

Returns:

• 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

function touch_button_set_longpress

Touch button set long press trigger time.

esp_err_t touch_button_set_longpress (
    touch_button_handle_t button_handle,
    uint32_t threshold_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.

Parameters:

• button_handle Button handle
• threshold_time Threshold time (ms) of long press event occur

Returns:

• 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

function touch_button_subscribe_event

Touch button subscribes event.

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

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.

Parameters:

• button_handle Button handle
• event_mask Button subscription event mask
• arg User input argument

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.

Returns:

• 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

function touch_button_uninstall

Release resources allocated using touch_button_install()

void touch_button_uninstall (
    void
) 

Macros Documentation

define TOUCH_BUTTON_GLOBAL_DEFAULT_CONFIG

#define TOUCH_BUTTON_GLOBAL_DEFAULT_CONFIG (
    
) {                                                                             \
    .threshold_divider = 0.8,                                                 \
    .default_lp_time = 1000                                                   \
}

File include/touch_element/touch_element.h

Structures and Types

Functions

Macros

Structures and Types Documentation

enum touch_elem_dispatch_t

Touch element event dispatch methods (event queue/callback)

enum touch_elem_dispatch_t {
    TOUCH_ELEM_DISP_EVENT,
    TOUCH_ELEM_DISP_CALLBACK,
    TOUCH_ELEM_DISP_MAX
};

typedef touch_elem_event_t

Touch element event type.

typedef uint32_t touch_elem_event_t;

struct touch_elem_global_config_t

Touch element global configuration passed to touch_element_install.

Variables:

• touch_elem_hw_config_t hardware
  Hardware configuration.

• touch_elem_sw_config_t software
  Software configuration.

typedef touch_elem_handle_t

Touch element handle type.

typedef void* touch_elem_handle_t;

struct touch_elem_hw_config_t

Touch element hardware configuration.

Variables:

• uint8_t benchmark_calibration_threshold
  Benchmark calibration threshold.

• uint8_t benchmark_debounce_count
  Benchmark debounce count.

• touch_filter_mode_t benchmark_filter_mode
  Benchmark filter mode.

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

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

• touch_pad_denoise_grade_t denoise_level
  Internal de-noise level.

• touch_low_volt_t lower_voltage
  Touch sensor channel lower charge voltage.

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

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

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

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

struct touch_elem_message_t

Touch element event message type from touch_element_message_receive()

Variables:

• void * arg
  User input argument.

• uint8_t child_msg
  Encoded message.

• touch_elem_type_t element_type
  Touch element type.

• touch_elem_handle_t handle
  Touch element handle.

struct touch_elem_sleep_config_t

Touch element sleep configuration passed to touch_element_enable_light_sleep or touch_element_enable_deep_sleep.

Variables:

• uint16_t sample_count
  scan times in every measurement, normally equal to the 'sample_count' field in ' touch_elem_hw_config_t'.

• uint16_t sleep_cycle
  sleep_cycle decide the interval between two measurements， t_sleep = sleep_cycle / (RTC_SLOW_CLK frequency), normally equal to the 'sleep_cycle' field in ' touch_elem_hw_config_t'.

struct touch_elem_sw_config_t

Touch element software configuration.

Variables:

• uint8_t event_message_size
  Event message queue size.

• uint8_t intr_message_size
  Interrupt message queue size.

• uint8_t processing_period
  Processing period(ms)

• float waterproof_threshold_divider
  Waterproof guard channel threshold divider.

enum touch_elem_type_t

Touch element handle type.

enum touch_elem_type_t {
    TOUCH_ELEM_TYPE_BUTTON,
    TOUCH_ELEM_TYPE_SLIDER,
    TOUCH_ELEM_TYPE_MATRIX
};

struct touch_elem_waterproof_config_t

Touch element waterproof configuration passed to touch_element_waterproof_install.

Variables:

• touch_pad_t guard_channel
  Waterproof Guard-Sensor channel number (index)

• float guard_sensitivity
  Waterproof Guard-Sensor sensitivity.

Functions Documentation

function touch_element_disable_deep_sleep

Release the resources that allocated by touch_element_enable_deep_sleep()

esp_err_t touch_element_disable_deep_sleep (
    void
) 

This function will also disable the touch sensor to wake up the device

Returns:

• ESP_OK: uninstall success
• ESP_ERR_INVALID_STATE: touch sleep has not been installed

function touch_element_disable_light_sleep

Release the resources that allocated by touch_element_enable_deep_sleep()

esp_err_t touch_element_disable_light_sleep (
    void
) 

This function will also disable the touch sensor to wake up the device

Returns:

• ESP_OK: uninstall success
• ESP_ERR_INVALID_STATE: touch sleep has not been installed

function touch_element_enable_deep_sleep

Touch element deep sleep initialization.

esp_err_t touch_element_enable_deep_sleep (
    touch_elem_handle_t wakeup_elem_handle,
    const touch_elem_sleep_config_t *sleep_config
) 

This function will enable the device wake-up from deep sleep or light sleep by touch sensor

Note:

It should be called after touch button element installed. Only one touch button can be registered as the deep sleep wake-up button

Parameters:

• wakeup_elem_handle Touch element instance handle for waking up the device, only support button element
• sleep_config Sleep configurations, set NULL to use default config

Returns:

• ESP_OK: Successfully initialized touch sleep
• ESP_ERR_INVALID_STATE: Touch element is not installed or touch sleep has been installed
• ESP_ERR_INVALID_ARG: inputted argument is NULL
• ESP_ERR_NO_MEM: no memory for touch sleep struct
• ESP_ERR_NOT_SUPPORTED: inputted wakeup_elem_handle is not touch_button_handle_t type, currently only touch_button_handle_t supported

function touch_element_enable_light_sleep

Touch element light sleep initialization.

esp_err_t touch_element_enable_light_sleep (
    const touch_elem_sleep_config_t *sleep_config
) 

Note:

It should be called after touch button element installed. Any of installed touch element can wake up from the light sleep

Parameters:

• sleep_config Sleep configurations, set NULL to use default config

Returns:

• ESP_OK: Successfully initialized touch sleep
• ESP_ERR_INVALID_STATE: Touch element is not installed or touch sleep has been installed
• ESP_ERR_INVALID_ARG: inputted argument is NULL
• ESP_ERR_NO_MEM: no memory for touch sleep struct
• ESP_ERR_NOT_SUPPORTED: inputted wakeup_elem_handle is not touch_button_handle_t type, currently only touch_button_handle_t supported

function touch_element_install

Touch element processing initialization.

esp_err_t touch_element_install (
    const touch_elem_global_config_t *global_config
) 

Parameters:

• global_config Global initialization configuration structure

Note:

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

Returns:

• 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

function touch_element_message_receive

Get current event message of touch element instance.

esp_err_t touch_element_message_receive (
    touch_elem_message_t *element_message,
    uint32_t ticks_to_wait
) 

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.

Parameters:

• element_message Touch element event message structure
• ticks_to_wait Number of FreeRTOS ticks to block for waiting event

Returns:

• 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

function touch_element_sleep_enable_wakeup_calibration

Touch element wake up calibrations.

esp_err_t touch_element_sleep_enable_wakeup_calibration (
    touch_elem_handle_t element_handle,
    bool en
) 

This function will also disable the touch sensor to wake up the device

Returns:

• ESP_OK: uninstall success
• ESP_ERR_INVALID_STATE: touch sleep has not been installed

function touch_element_start

Touch element processing start.

esp_err_t touch_element_start (
    void
) 

This function starts the touch element processing system

Note:

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

Returns:

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

function touch_element_stop

Touch element processing stop.

esp_err_t touch_element_stop (
    void
) 

This function stops the touch element processing system

Note:

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

Returns:

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

function touch_element_uninstall

Release resources allocated using touch_element_install.

void touch_element_uninstall (
    void
) 

function touch_element_waterproof_add

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

esp_err_t touch_element_waterproof_add (
    touch_elem_handle_t element_handle
) 

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.

Parameters:

• element_handle Touch element instance handle

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.

Returns:

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

function touch_element_waterproof_install

Touch element waterproof initialization.

esp_err_t touch_element_waterproof_install (
    const touch_elem_waterproof_config_t *waterproof_config
) 

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.

Parameters:

• waterproof_config Waterproof configuration

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.

Returns:

• 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

function touch_element_waterproof_remove

Remove a masked handle to protect.

esp_err_t touch_element_waterproof_remove (
    touch_elem_handle_t element_handle
) 

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

Parameters:

• element_handle Touch element instance handle

Returns:

• 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

function touch_element_waterproof_uninstall

Release resources allocated using touch_element_waterproof_install()

void touch_element_waterproof_uninstall (
    void
) 

Macros Documentation

define TOUCH_ELEM_EVENT_NONE

None event.

#define TOUCH_ELEM_EVENT_NONE BIT(0)

define TOUCH_ELEM_EVENT_ON_CALCULATION

On Calculation event.

#define TOUCH_ELEM_EVENT_ON_CALCULATION BIT(4)

define TOUCH_ELEM_EVENT_ON_LONGPRESS

On LongPress event.

#define TOUCH_ELEM_EVENT_ON_LONGPRESS BIT(3)

define TOUCH_ELEM_EVENT_ON_PRESS

On Press event.

#define TOUCH_ELEM_EVENT_ON_PRESS BIT(1)

define TOUCH_ELEM_EVENT_ON_RELEASE

On Release event.

#define TOUCH_ELEM_EVENT_ON_RELEASE BIT(2)

define TOUCH_ELEM_GLOBAL_DEFAULT_CONFIG

#define TOUCH_ELEM_GLOBAL_DEFAULT_CONFIG (
    
) {                                                                             \
    .hardware = {                                                             \
        .upper_voltage = TOUCH_HVOLT_2V7 ,                                     \
        .voltage_attenuation = TOUCH_HVOLT_ATTEN_0V5 ,                         \
        .lower_voltage = TOUCH_LVOLT_0V5 ,                                     \
        .suspend_channel_polarity = TOUCH_PAD_CONN_HIGHZ ,                     \
        .denoise_level = TOUCH_PAD_DENOISE_BIT4 ,                              \
        .denoise_equivalent_cap = TOUCH_PAD_DENOISE_CAP_L0 ,                   \
        .smooth_filter_mode = TOUCH_PAD_SMOOTH_IIR_2 ,                         \
        .benchmark_filter_mode = TOUCH_PAD_FILTER_IIR_16 ,                     \
        .sample_count = 500,                                                  \
        .sleep_cycle = 0xf,                                                   \
        .benchmark_debounce_count = 2,                                        \
        .benchmark_calibration_threshold = 2,                                 \
        .benchmark_jitter_step = 5                                            \
    },                                                                        \
    .software = {                                                             \
        .waterproof_threshold_divider = 0.8,                                  \
        .processing_period = 10,                                              \
        .intr_message_size = 14,                                              \
        .event_message_size = 20                                              \
    }                                                                         \
}

define TOUCH_WATERPROOF_GUARD_NOUSE

Waterproof no use guard sensor.

#define TOUCH_WATERPROOF_GUARD_NOUSE (0)

File include/touch_element/touch_matrix.h

Structures and Types

Functions

Macros

Structures and Types Documentation

typedef touch_matrix_callback_t

Matrix button callback type.

typedef void(* touch_matrix_callback_t) (touch_matrix_handle_t, touch_matrix_message_t *, void *);

struct touch_matrix_config_t

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

Variables:

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

• uint8_t x_channel_num
  The number of channels in x-axis.

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

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

• uint8_t y_channel_num
  The number of channels in y-axis.

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

enum touch_matrix_event_t

Matrix button event type.

enum touch_matrix_event_t {
    TOUCH_MATRIX_EVT_ON_PRESS,
    TOUCH_MATRIX_EVT_ON_RELEASE,
    TOUCH_MATRIX_EVT_ON_LONGPRESS,
    TOUCH_MATRIX_EVT_MAX
};

struct touch_matrix_global_config_t

Matrix button initialization configuration passed to touch_matrix_install.

Variables:

• uint32_t default_lp_time
  Matrix button default LongPress event time (ms)

• float threshold_divider
  Matrix button channel threshold divider.

typedef touch_matrix_handle_t

Matrix button instance handle.

typedef touch_elem_handle_t touch_matrix_handle_t;

struct touch_matrix_message_t

Matrix message type.

Variables:

• touch_matrix_event_t event
  Matrix event.

• touch_matrix_position_t position
  Matrix position.

struct touch_matrix_position_t

Matrix button position data type.

Variables:

• uint8_t index
  Matrix button position index.

• uint8_t x_axis
  Matrix button x axis position.

• uint8_t y_axis
  Matrix button y axis position.

Functions Documentation

function touch_matrix_create

Create a new touch matrix button instance.

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

Parameters:

• matrix_config Matrix button configuration
• matrix_handle Matrix button handle

Note:

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

Note:

Touch matrix button does not support Multi-Touch now

Returns:

• 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

function touch_matrix_delete

Release resources allocated using touch_matrix_create()

esp_err_t touch_matrix_delete (
    touch_matrix_handle_t matrix_handle
) 

Parameters:

• matrix_handle Matrix handle

Returns:

• 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

function touch_matrix_get_message

Touch matrix get message.

const touch_matrix_message_t * touch_matrix_get_message (
    const touch_elem_message_t *element_message
) 

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

Parameters:

• element_message element message

Returns:

Touch matrix message pointer

function touch_matrix_install

Touch matrix button initialize.

esp_err_t touch_matrix_install (
    const touch_matrix_global_config_t *global_config
) 

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

Parameters:

• global_config Touch matrix global initialization configuration

Returns:

• 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

function touch_matrix_set_callback

Touch matrix button set callback.

esp_err_t touch_matrix_set_callback (
    touch_matrix_handle_t matrix_handle,
    touch_matrix_callback_t matrix_callback
) 

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

Parameters:

• matrix_handle Matrix button handle
• matrix_callback User input callback

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().

Returns:

• 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

function touch_matrix_set_dispatch_method

Touch matrix button set dispatch method.

esp_err_t touch_matrix_set_dispatch_method (
    touch_matrix_handle_t matrix_handle,
    touch_elem_dispatch_t dispatch_method
) 

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

Parameters:

• matrix_handle Matrix button handle
• dispatch_method Dispatch method (By callback/event)

Returns:

• 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

function touch_matrix_set_longpress

Touch matrix button set long press trigger time.

esp_err_t touch_matrix_set_longpress (
    touch_matrix_handle_t matrix_handle,
    uint32_t threshold_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.

Parameters:

• matrix_handle Matrix button handle
• threshold_time Threshold time (ms) of long press event occur

Returns:

• 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

function touch_matrix_subscribe_event

Touch matrix button subscribes event.

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

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.

Parameters:

• matrix_handle Matrix handle
• event_mask Matrix subscription event mask
• arg User input argument

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.

Returns:

• 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

function touch_matrix_uninstall

Release resources allocated using touch_matrix_install()

void touch_matrix_uninstall (
    void
) 

Macros Documentation

define TOUCH_MATRIX_GLOBAL_DEFAULT_CONFIG

#define TOUCH_MATRIX_GLOBAL_DEFAULT_CONFIG (
    
) {                                                                             \
    .threshold_divider = 0.8,                                                 \
    .default_lp_time = 1000                                                   \
}

File include/touch_element/touch_sensor_legacy_types.h

Structures and Types

Macros

Structures and Types Documentation

enum touch_benchmark_filter_mode_t

Touch channel Infinite Impulse Response (IIR) filter or Jitter filter for benchmark.

enum touch_benchmark_filter_mode_t {
    TOUCH_BM_IIR_FILTER_4,
    TOUCH_BM_IIR_FILTER_8,
    TOUCH_BM_IIR_FILTER_16,
    TOUCH_BM_IIR_FILTER_32,
    TOUCH_BM_IIR_FILTER_64,
    TOUCH_BM_IIR_FILTER_128,
    TOUCH_BM_IIR_FILTER_256,
    TOUCH_BM_JITTER_FILTER
};

Note:

Recommended filter coefficient selection is IIR_16.

enum touch_chan_shield_cap_t

Touch sensor shield channel drive capability level.

enum touch_chan_shield_cap_t {
    TOUCH_SHIELD_CAP_40PF,
    TOUCH_SHIELD_CAP_80PF,
    TOUCH_SHIELD_CAP_120PF,
    TOUCH_SHIELD_CAP_160PF,
    TOUCH_SHIELD_CAP_200PF,
    TOUCH_SHIELD_CAP_240PF,
    TOUCH_SHIELD_CAP_280PF,
    TOUCH_SHIELD_CAP_320PF
};

enum touch_cnt_slope_t

enum touch_cnt_slope_t {
    TOUCH_PAD_SLOPE_0 = 0,
    TOUCH_PAD_SLOPE_1 = 1,
    TOUCH_PAD_SLOPE_2 = 2,
    TOUCH_PAD_SLOPE_3 = 3,
    TOUCH_PAD_SLOPE_4 = 4,
    TOUCH_PAD_SLOPE_5 = 5,
    TOUCH_PAD_SLOPE_6 = 6,
    TOUCH_PAD_SLOPE_7 = 7,
    TOUCH_PAD_SLOPE_MAX
};

Touch sensor charge/discharge speed

struct touch_filter_config

Touch sensor filter configuration

Variables:

• uint32_t debounce_cnt
  Set debounce count, such as n. If the measured values continue to exceed the threshold forn+1 times, the touch sensor state changes. Range: 0 ~ 7

• uint32_t jitter_step
  Set jitter filter step size. Range: 0 ~ 15

• touch_filter_mode_t mode
  Set filter mode. The input of the filter is the raw value of touch reading, and the output of the filter is involved in the judgment of the touch state.

• uint32_t noise_thr
  Noise threshold coefficient. Higher = More noise resistance. The actual noise should be less than (noise coefficient * touch threshold). Range: 0 ~ 3. The coefficient is 0: 4/8; 1: 3/8; 2: 2/8; 3: 1;

• touch_smooth_mode_t smh_lvl
  Level of filter applied on the original data against large noise interference.

typedef touch_filter_config_t

typedef struct touch_filter_config touch_filter_config_t;

Touch sensor filter configuration

enum touch_filter_mode_t

Touch channel IIR filter coefficient configuration.

enum touch_filter_mode_t {
    TOUCH_PAD_FILTER_IIR_4 = 0,
    TOUCH_PAD_FILTER_IIR_8,
    TOUCH_PAD_FILTER_IIR_16,
    TOUCH_PAD_FILTER_IIR_32,
    TOUCH_PAD_FILTER_IIR_64,
    TOUCH_PAD_FILTER_IIR_128,
    TOUCH_PAD_FILTER_IIR_256,
    TOUCH_PAD_FILTER_JITTER,
    TOUCH_PAD_FILTER_MAX
};

Note:

On ESP32S2. There is an error in the IIR calculation. The magnitude of the error is twice the filter coefficient. So please select a smaller filter coefficient on the basis of meeting the filtering requirements. Recommended filter coefficient selection IIR_16.

enum touch_fsm_mode_t

enum touch_fsm_mode_t {
    TOUCH_FSM_MODE_TIMER = 0,
    TOUCH_FSM_MODE_SW,
    TOUCH_FSM_MODE_MAX
};

Touch sensor FSM mode

enum touch_high_volt_t

enum touch_high_volt_t {
    TOUCH_HVOLT_KEEP = -1,
    TOUCH_HVOLT_2V4 = 0,
    TOUCH_HVOLT_2V5,
    TOUCH_HVOLT_2V6,
    TOUCH_HVOLT_2V7,
    TOUCH_HVOLT_MAX
};

Touch sensor high reference voltage

enum touch_low_volt_t

enum touch_low_volt_t {
    TOUCH_LVOLT_KEEP = -1,
    TOUCH_LVOLT_0V5 = 0,
    TOUCH_LVOLT_0V6,
    TOUCH_LVOLT_0V7,
    TOUCH_LVOLT_0V8,
    TOUCH_LVOLT_MAX
};

Touch sensor low reference voltage

enum touch_pad_conn_type_t

enum touch_pad_conn_type_t {
    TOUCH_PAD_CONN_HIGHZ = 0,
    TOUCH_PAD_CONN_GND = 1,
    TOUCH_PAD_CONN_MAX
};

Touch channel idle state configuration

struct touch_pad_denoise

Touch sensor denoise configuration

Variables:

• touch_pad_denoise_cap_t cap_level
  Select internal reference capacitance of denoise channel. Ensure that the denoise readings are closest to the readings of the channel being measured. Use touch_pad_denoise_read_data to get the reading of denoise channel. The equivalent capacitance of the shielded channel can be calculated from the reading of denoise channel.

• touch_pad_denoise_grade_t grade
  Select denoise range of denoise channel. Determined by measuring the noise amplitude of the denoise channel.

enum touch_pad_denoise_cap_t

enum touch_pad_denoise_cap_t {
    TOUCH_PAD_DENOISE_CAP_L0 = 0,
    TOUCH_PAD_DENOISE_CAP_L1 = 1,
    TOUCH_PAD_DENOISE_CAP_L2 = 2,
    TOUCH_PAD_DENOISE_CAP_L3 = 3,
    TOUCH_PAD_DENOISE_CAP_L4 = 4,
    TOUCH_PAD_DENOISE_CAP_L5 = 5,
    TOUCH_PAD_DENOISE_CAP_L6 = 6,
    TOUCH_PAD_DENOISE_CAP_L7 = 7,
    TOUCH_PAD_DENOISE_CAP_MAX = 8
};

enum touch_pad_denoise_grade_t

enum touch_pad_denoise_grade_t {
    TOUCH_PAD_DENOISE_BIT12 = 0,
    TOUCH_PAD_DENOISE_BIT10 = 1,
    TOUCH_PAD_DENOISE_BIT8 = 2,
    TOUCH_PAD_DENOISE_BIT4 = 3,
    TOUCH_PAD_DENOISE_MAX
};

typedef touch_pad_denoise_t

typedef struct touch_pad_denoise touch_pad_denoise_t;

Touch sensor denoise configuration

enum touch_pad_intr_mask_t

enum touch_pad_intr_mask_t {
    TOUCH_PAD_INTR_MASK_DONE = BIT(0),
    TOUCH_PAD_INTR_MASK_ACTIVE = BIT(1),
    TOUCH_PAD_INTR_MASK_INACTIVE = BIT(2),
    TOUCH_PAD_INTR_MASK_SCAN_DONE = BIT(3),
    TOUCH_PAD_INTR_MASK_TIMEOUT = BIT(4)
};

enum touch_pad_shield_driver_t

enum touch_pad_shield_driver_t {
    TOUCH_PAD_SHIELD_DRV_L0 = 0,
    TOUCH_PAD_SHIELD_DRV_L1,
    TOUCH_PAD_SHIELD_DRV_L2,
    TOUCH_PAD_SHIELD_DRV_L3,
    TOUCH_PAD_SHIELD_DRV_L4,
    TOUCH_PAD_SHIELD_DRV_L5,
    TOUCH_PAD_SHIELD_DRV_L6,
    TOUCH_PAD_SHIELD_DRV_L7,
    TOUCH_PAD_SHIELD_DRV_MAX
};

Touch sensor shield channel drive capability level

struct touch_pad_sleep_channel_t

Touch sensor channel sleep configuration

Variables:

• bool en_proximity
  enable proximity function for sleep pad

• touch_pad_t touch_num
  Set touch channel number for sleep pad. Only one touch sensor channel is supported in deep sleep mode. If clear the sleep channel, point this pad to TOUCH_PAD_NUM0

enum touch_pad_t

enum touch_pad_t {
    TOUCH_PAD_NUM0 = 0,
    TOUCH_PAD_NUM1,
    TOUCH_PAD_NUM2,
    TOUCH_PAD_NUM3,
    TOUCH_PAD_NUM4,
    TOUCH_PAD_NUM5,
    TOUCH_PAD_NUM6,
    TOUCH_PAD_NUM7,
    TOUCH_PAD_NUM8,
    TOUCH_PAD_NUM9,
    TOUCH_PAD_NUM10,
    TOUCH_PAD_NUM11,
    TOUCH_PAD_NUM12,
    TOUCH_PAD_NUM13,
    TOUCH_PAD_NUM14,
    TOUCH_PAD_MAX
};

Touch pad channel

struct touch_pad_waterproof

Touch sensor waterproof configuration

Variables:

• touch_pad_t guard_ring_pad
  Waterproof. Select touch channel use for guard pad. Guard pad is used to detect the large area of water covering the touch panel.

• touch_pad_shield_driver_t shield_driver
  Waterproof. Shield channel drive capability configuration. Shield pad is used to shield the influence of water droplets covering the touch panel. When the waterproof function is enabled, Touch14 is set as shield channel by default. The larger the parasitic capacitance on the shielding channel, the higher the drive capability needs to be set. The equivalent capacitance of the shield channel can be estimated through the reading value of the denoise channel(Touch0).

typedef touch_pad_waterproof_t

typedef struct touch_pad_waterproof touch_pad_waterproof_t;

Touch sensor waterproof configuration

enum touch_smooth_filter_mode_t

Touch channel Infinite Impulse Response (IIR) filter for smooth data.

enum touch_smooth_filter_mode_t {
    TOUCH_SMOOTH_NO_FILTER,
    TOUCH_SMOOTH_IIR_FILTER_2,
    TOUCH_SMOOTH_IIR_FILTER_4,
    TOUCH_SMOOTH_IIR_FILTER_8
};

enum touch_smooth_mode_t

Level of filter applied on the original data against large noise interference.

enum touch_smooth_mode_t {
    TOUCH_PAD_SMOOTH_OFF = 0,
    TOUCH_PAD_SMOOTH_IIR_2 = 1,
    TOUCH_PAD_SMOOTH_IIR_4 = 2,
    TOUCH_PAD_SMOOTH_IIR_8 = 3,
    TOUCH_PAD_SMOOTH_MAX
};

Note:

On ESP32S2. There is an error in the IIR calculation. The magnitude of the error is twice the filter coefficient. So please select a smaller filter coefficient on the basis of meeting the filtering requirements. Recommended filter coefficient selection IIR_2.

enum touch_tie_opt_t

enum touch_tie_opt_t {
    TOUCH_PAD_TIE_OPT_LOW = 0,
    TOUCH_PAD_TIE_OPT_HIGH = 1,
    TOUCH_PAD_TIE_OPT_FLOAT = 2,
    TOUCH_PAD_TIE_OPT_MAX
};

Touch sensor initial charge level

enum touch_trigger_mode_t

enum touch_trigger_mode_t {
    TOUCH_TRIGGER_BELOW = 0,
    TOUCH_TRIGGER_ABOVE = 1,
    TOUCH_TRIGGER_MAX
};

enum touch_trigger_src_t

enum touch_trigger_src_t {
    TOUCH_TRIGGER_SOURCE_BOTH = 0,
    TOUCH_TRIGGER_SOURCE_SET1 = 1,
    TOUCH_TRIGGER_SOURCE_MAX
};

enum touch_volt_atten_t

enum touch_volt_atten_t {
    TOUCH_HVOLT_ATTEN_KEEP = -1,
    TOUCH_HVOLT_ATTEN_1V5 = 0,
    TOUCH_HVOLT_ATTEN_1V,
    TOUCH_HVOLT_ATTEN_0V5,
    TOUCH_HVOLT_ATTEN_0V,
    TOUCH_HVOLT_ATTEN_MAX
};

Touch sensor high reference voltage attenuation

Macros Documentation

define TOUCH_DEBOUNCE_CNT_MAX

#define TOUCH_DEBOUNCE_CNT_MAX (7)

define TOUCH_JITTER_STEP_MAX

#define TOUCH_JITTER_STEP_MAX (15)

define TOUCH_NOISE_THR_MAX

#define TOUCH_NOISE_THR_MAX (3)

define TOUCH_PAD_ATTEN_VOLTAGE_THRESHOLD

#define TOUCH_PAD_ATTEN_VOLTAGE_THRESHOLD ( TOUCH_HVOLT_ATTEN_0V5 )

define TOUCH_PAD_BIT_MASK_ALL

#define TOUCH_PAD_BIT_MASK_ALL ((1<<SOC_TOUCH_SENSOR_NUM)-1)

define TOUCH_PAD_BIT_MASK_MAX

#define TOUCH_PAD_BIT_MASK_MAX ( TOUCH_PAD_BIT_MASK_ALL )

define TOUCH_PAD_HIGH_VOLTAGE_THRESHOLD

#define TOUCH_PAD_HIGH_VOLTAGE_THRESHOLD ( TOUCH_HVOLT_2V7 )

define TOUCH_PAD_IDLE_CH_CONNECT_DEFAULT

#define TOUCH_PAD_IDLE_CH_CONNECT_DEFAULT ( TOUCH_PAD_CONN_GND )

define TOUCH_PAD_INTR_MASK_ALL

#define TOUCH_PAD_INTR_MASK_ALL ( TOUCH_PAD_INTR_MASK_TIMEOUT \
                                | TOUCH_PAD_INTR_MASK_SCAN_DONE \
                                | TOUCH_PAD_INTR_MASK_INACTIVE \
                                | TOUCH_PAD_INTR_MASK_ACTIVE \
                                | TOUCH_PAD_INTR_MASK_DONE )

All touch interrupt type enable.

define TOUCH_PAD_LOW_VOLTAGE_THRESHOLD

#define TOUCH_PAD_LOW_VOLTAGE_THRESHOLD ( TOUCH_LVOLT_0V5 )

define TOUCH_PAD_MEASURE_CYCLE_DEFAULT

#define TOUCH_PAD_MEASURE_CYCLE_DEFAULT (500)

The times of charge and discharge in each measure process of touch channels. The timer frequency is 8Mhz. Recommended typical value: Modify this value to make the measurement time around 1ms. Range: 0 ~ 0xffff

define TOUCH_PAD_SLEEP_CYCLE_DEFAULT

#define TOUCH_PAD_SLEEP_CYCLE_DEFAULT (0xf)

Excessive total time will slow down the touch response. Too small measurement time will not be sampled enough, resulting in inaccurate measurements.

Note:

The greater the duty cycle of the measurement time, the more system power is consumed. The number of sleep cycle in each measure process of touch channels. The timer frequency is RTC_SLOW_CLK (can be 150k or 32k depending on the options). Range: 0 ~ 0xffff

define TOUCH_PAD_SLOPE_DEFAULT

#define TOUCH_PAD_SLOPE_DEFAULT ( TOUCH_PAD_SLOPE_7 )

define TOUCH_PAD_THRESHOLD_MAX

#define TOUCH_PAD_THRESHOLD_MAX (0x1FFFFF)

If set touch threshold max value, The touch sensor can't be in touched status

define TOUCH_PAD_TIE_OPT_DEFAULT

#define TOUCH_PAD_TIE_OPT_DEFAULT ( TOUCH_PAD_TIE_OPT_FLOAT )

define TOUCH_PROXIMITY_MEAS_NUM_MAX

#define TOUCH_PROXIMITY_MEAS_NUM_MAX (0xFF)

Touch sensor proximity detection configuration

File include/touch_element/touch_slider.h

Structures and Types

Functions

Macros

Structures and Types Documentation

typedef touch_slider_callback_t

Slider callback type.

typedef void(* touch_slider_callback_t) (touch_slider_handle_t, touch_slider_message_t *, void *);

struct touch_slider_config_t

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

Variables:

• const touch_pad_t * channel_array
  Slider channel 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)].

• const float * sensitivity_array
  Slider channel sensitivity array.

enum touch_slider_event_t

Slider event type.

enum touch_slider_event_t {
    TOUCH_SLIDER_EVT_ON_PRESS,
    TOUCH_SLIDER_EVT_ON_RELEASE,
    TOUCH_SLIDER_EVT_ON_CALCULATION,
    TOUCH_SLIDER_EVT_MAX
};

struct touch_slider_global_config_t

Slider initialization configuration passed to touch_slider_install.

Variables:

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

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

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

• uint8_t position_filter_factor
  One-order IIR filter factor.

• uint8_t position_filter_size
  Moving window filter buffer size.

• float quantify_lower_threshold
  Slider signal quantification threshold.

• float threshold_divider
  Slider channel threshold divider.

typedef touch_slider_handle_t

Slider instance handle.

typedef touch_elem_handle_t touch_slider_handle_t;

struct touch_slider_message_t

Slider message type.

Variables:

• touch_slider_event_t event
  Slider event.

• touch_slider_position_t position
  Slider position.

typedef touch_slider_position_t

Slider position data type.

typedef uint32_t touch_slider_position_t;

Functions Documentation

function touch_slider_create

Create a new touch slider instance.

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

Parameters:

• slider_config Slider configuration
• slider_handle Slider handle

Note:

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

Returns:

• 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

function touch_slider_delete

Release resources allocated using touch_slider_create.

esp_err_t touch_slider_delete (
    touch_slider_handle_t slider_handle
) 

Parameters:

• slider_handle Slider handle

Returns:

• 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

function touch_slider_get_message

Touch slider get message.

const touch_slider_message_t * touch_slider_get_message (
    const touch_elem_message_t *element_message
) 

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

Parameters:

• element_message element message

Returns:

Touch slider message pointer

function touch_slider_install

Touch slider initialize.

esp_err_t touch_slider_install (
    const touch_slider_global_config_t *global_config
) 

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

Parameters:

• global_config Touch slider global initialization configuration

Returns:

• 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

function touch_slider_set_callback

Touch slider set callback.

esp_err_t touch_slider_set_callback (
    touch_slider_handle_t slider_handle,
    touch_slider_callback_t slider_callback
) 

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

Parameters:

• slider_handle Slider handle
• slider_callback User input callback

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().

Returns:

• 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

function touch_slider_set_dispatch_method

Touch slider set dispatch method.

esp_err_t touch_slider_set_dispatch_method (
    touch_slider_handle_t slider_handle,
    touch_elem_dispatch_t dispatch_method
) 

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

Parameters:

• slider_handle Slider handle
• dispatch_method Dispatch method (By callback/event)

Returns:

• 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

function touch_slider_subscribe_event

Touch slider subscribes event.

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

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.

Parameters:

• slider_handle Slider handle
• event_mask Slider subscription event mask
• arg User input argument

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.

Returns:

• 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

function touch_slider_uninstall

Release resources allocated using touch_slider_install()

void touch_slider_uninstall (
    void
) 

Macros Documentation

define TOUCH_SLIDER_GLOBAL_DEFAULT_CONFIG

#define TOUCH_SLIDER_GLOBAL_DEFAULT_CONFIG (
    
) {                                                                             \
    .quantify_lower_threshold = 0.3,                                          \
    .threshold_divider = 0.8,                                                 \
    .filter_reset_time = 50,                                                  \
    .benchmark_update_time = 500,                                             \
    .position_filter_size = 10,                                               \
    .position_filter_factor = 2,                                              \
    .calculate_channel_count = 3                                              \
}