Touch Proximity Sensor

[中文]

The touch_proximity_sensor component is developed based on the built-in touch sensors of ESP32-S3. Using this component makes it easy to implement touch proximity sensing functionality.

Note

ESP32/ESP32-S2/ESP32-S3 touch-related components are intended for testing or demo purposes only. Due to the poor anti-interference capability of the touch functionality, it may not pass EMS testing, and therefore, it is not recommended for mass production products.
This component is currently only applicable to the ESP32-S3 and requires an IDF version greater than or equal to v5.0.

Principle of Operation

The touch proximity sensor is implemented based on the proximity sensing feature of the ESP32-S3 touch sensor. The hardware schematic of the sensor principle is as follows:

The hardware principle schematic diagram of the touch proximity sensor

When a target object approaches the sensor, its equivalent capacitance changes. The target object can be a human finger, hand, or any conductive object. When the touch sensor is configured in proximity sensing mode, the sensor output is an accumulated value. As the target object approaches the sensor panel, the cumulative value output by the sensor increases. Based on this characteristic, this solution defines the raw data output by the touch sensor (accumulated value) as raw_value , and derives two data variables, baseline and smooth_value, from it. Combined with a reasonable threshold detection algorithm, proximity sensing functionality is achieved.

The specific software implementation involves the following three steps:

Determine the validity of new data.
Update smooth_value and baseline based on the update logic of smooth_value and baseline using raw_value as the source data.
Determine whether smooth_value - baseline is greater than 0. If it is greater than 0, then determine whether it is greater than the trigger threshold . If it is greater, it is deemed as a valid sensing trigger action; if smooth_value - baseline is less than 0, first determine whether it is in a triggered state. If it is in a triggered state, then determine whether its absolute value is greater than the release trigger threshold . If it is greater, it is deemed as a valid trigger release action.

Hardware Reference for Testing

Development board
- Validation testing can be performed using the ESP-S2S3-Touch-DevKit-1 development kit. The mainboard is MainBoard v1.1, and the proximity sensing subboard is Proximity Board V1.0.

Configuration Reference

Create Proximity Sensing Sensor

Using the touch_proximity_sensor component, the proximity sensing sensor can be configured via the touch_proxi_config_t structure.

typedef struct {
    uint32_t channel_num;                           /*!< Number of touch proximity sensor channels */
    uint32_t *channel_list;                         /*!< Touch channel list */
    float *channel_threshold;                       /*!< Threshold for touch detection for each channel */
    uint32_t debounce_times;                        /*!< Number of consecutive readings needed to confirm state change */
    uint32_t *channel_gold_value;                   /*!< Reference values for touch channels */
    bool skip_lowlevel_init;                        /*!< Skip low level initialization when working with existing touch driver */
} touch_proxi_config_t;

The main parameters are:

Parameter	Description
channel_num	Number of touch proximity sensor channels, up to 3
channel_list	Array of touch channel numbers to be used
channel_threshold	Array of threshold values for each channel
debounce_times	Number of consecutive readings needed to confirm state change
channel_gold_value	Optional reference values for touch channels
skip_lowlevel_init	Skip low level init when working with existing touch driver

After configuring the parameters, create the proximity sensor using touch_proximity_sensor_create():

touch_proxi_config_t config = {
    .channel_num = 1,
    .channel_list = channel_list,
    .channel_threshold = channel_threshold,
    .debounce_times = 2,
};

esp_err_t ret = touch_proximity_sensor_create(&config, &sensor_handle, callback_func, NULL);

Event Handling

The proximity sensor requires periodic event handling to update states and trigger callbacks. This can be done in a task:

void proximity_task(void *arg)
{
    while (1) {
        touch_proximity_sensor_handle_events(sensor_handle);
        vTaskDelay(pdMS_TO_TICKS(20));
    }
}

// Create task
xTaskCreate(proximity_task, "proximity_task", 2048, NULL, 5, NULL);

Delete the Proximity Sensing Sensor

Use touch_proximity_sensor_delete() to delete the proximity sensing sensor object and release resources:

// Delete the touch proximity sensor
touch_proximity_sensor_delete(sensor_handle);

Parameter Adjustment Reference

The maximum value for channel_num is 3.
The channel_list array must be assigned values from the touch_pad_t enumeration variable.
meas_count has a default value of 20. Increasing meas_count slows down the update rate of new data from the touch sensor.
smooth_coef has a default value of 0.7. It is the coefficient used for data smoothing. The smoothed value smooth equals smooth * (1.0 - smooth_coef) + raw * smooth_coef . A larger smooth_coef gives more weight to raw , resulting in poorer smoothing of the waveform, faster response to raw , and weaker resistance to interference. Conversely, a smaller smooth_coef gives less weight to raw, resulting in better smoothing of the waveform, slower response to raw, and stronger resistance to interference.
baseline_coef has a default value of 0.05. It is the coefficient for baseline updating. The new baseline value equals baseline * (1.0 - baseline_coef) + smooth * baseline_coef . A larger value for baseline_coef causes the baseline to follow smooth more quickly, resulting in slower response time and stronger resistance to interference.
max_p has a default value of 0.5. When the difference between raw and baseline exceeds baseline * max_p , the raw value is considered an outlier and ignored.
min_n has a default value of 0.05. When the difference between baseline and raw exceeds baseline * min_n , the raw value is considered an outlier and ignored.
Increasing threshold_p and threshold_n values reduces the sensing distance for proximity sensing, but improves resistance to interference.
noise_p has a default value of 0.1, and noise_n has a default value of 0.2. Larger values for noise_p and noise_n make it easier for the baseline to follow smooth , resulting in a smaller sensing distance for proximity sensing and better resistance to interference.
debounce_p and debounce_n values need to be adjusted based on the value of meas_count . Smaller meas_count values require larger debounce_p and debounce_n values to increase resistance to interference.
reset_p has a default value of 0, used for baseline reset positive debounce. Setting to 0 disables this feature.
reset_n has a default value of 50, used for baseline reset negative debounce.

Parameter Adjustment Comparison

The default configuration parameters for the touch proximity sensor are as follows:

Parameter	Default Value
channel_num	1
channel_list	TOUCH_PAD_NUM8
meas_count	20
smooth_coef	0.7
baseline_coef	0.05
max_p	0.5
min_n	0.05
noise_p	0.1
noise_n	0.2
debounce_p	2
debounce_n	50
reset_p	0
reset_n	50

The following parameter adjustment comparisons will be made based on modifying only one parameter from the above parameters:

Modifying the value of meas_count changes the update rate of sensor data, with smaller values resulting in a wider waveform during sensing. The waveform comparison under different meas_count is shown below:
Modifying the value of smooth_coef changes the smoothing effect of the smooth waveform. The smaller the smooth_coef, the better the smoothing effect, stronger resistance to interference, slower response to raw , and vice versa. The waveform comparison under different smooth_coef is shown below:
Modifying the value of baseline_coef changes the updating effect of the baseline . Smaller values of baseline_coef result in slower response time and longer trigger duration. The waveform comparison under different baseline_coef is shown below:
Modifying the values of max_p and min_n will change the update logic of smooth and baseline . A too small value of max_p can cause the smooth to be “locked” when the hand approaches the sensing panel, potentially leading to failure to trigger; a too small value of min_n can cause both smooth and baseline to be “locked” when the hand leaves the sensing panel, resulting in failure to release the trigger. The waveform diagram for too small max_p and min_n values is as follows:
Modifying the value of threshold_p will change the proximity sensing distance. A smaller value allows for a longer sensing distance but decreases resistance to interference, making false triggers more likely. The waveform comparison under different threshold_p values is shown below:
Modifying the value of hysteresis_p will change the timing of triggering and releasing the trigger, i.e., the hysteresis. A smaller hysteresis_p value leads to faster trigger response, and vice versa. The waveform comparison under different hysteresis_p values is shown below:
Modifying the values of noise_p and noise_n will change the updating effect of baseline . A smaller value of noise_p causes baseline to follow smooth more slowly, resulting in slower trigger response and longer trigger duration, and vice versa. The waveform comparison under different noise_p and noise_n values is shown below:
Modifying the values of debounce_p and debounce_n will change the timing of triggering and releasing the trigger and the resistance to interference. A larger debounce_p value leads to slower trigger response and stronger resistance to interference, and vice versa; a larger debounce_n value leads to slower release of the trigger response and stronger resistance to interference, and vice versa. The values of debounce_p and debounce_n need to be adjusted in conjunction with meas_count ; as meas_count decreases, debounce_p and debounce_n should be appropriately increased. The waveform comparison under different debounce_p and debounce_n values is shown below:

Note

Achieving the ideal proximity sensing effect requires comprehensive adjustment of multiple parameters, rather than just tweaking one or two parameters.

Examples

touch/touch_proximity

API Reference

Header File

components/touch/touch_proximity_sensor/include/touch_proximity_sensor.h

Functions

esp_err_t touch_proximity_sensor_create(touch_proxi_config_t *config, touch_proximity_handle_t *sensor_handle, proxi_cb_t cb, void *cb_arg)

Create a touch proximity sensor instance.

Parameters

config – The touch pad channel configuration.
sensor_handle – The handle of the successfully created touch proximity sensor.
cb – Callback function to handle proximity events.
cb_arg – The callback function argument.

Returns

ESP_OK: Create the touch proximity sensor successfully.
ESP_ERR_NO_MEM: Failed to create the touch proximity sensor (memory allocation failed).

esp_err_t touch_proximity_sensor_delete(touch_proximity_handle_t proxi_sensor)

Delete the touch proximity sensor instance.

This function deletes the touch proximity sensor instance associated with the provided sensor handle.

Parameters

proxi_sensor – Pointer to the handle of the touch proximity sensor instance to be deleted.

Returns

ESP_OK: Delete the touch proximity sensor instance successfully

esp_err_t touch_proximity_sensor_get_data(touch_proximity_handle_t handle, uint32_t channel, uint32_t *data)

Get touch proximity sensor data.

Retrieves the smoothed touch sensor reading from the specified channel.

Parameters

handle – [in] Touch proximity sensor handle
channel – [in] Touch channel number
data – [out] Pointer to store the smoothed touch sensor data

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if handle or data is NULL
ESP_ERR_INVALID_STATE if sensor not initialized
ESP_ERR_NOT_FOUND if channel not found

esp_err_t touch_proximity_sensor_get_state(touch_proximity_handle_t handle, uint32_t channel, proxi_state_t *state)

Get current state of a proximity channel.

Returns whether the proximity channel is currently considered active (object detected) based on the current sensor readings and configured thresholds.

Parameters

handle – [in] Touch proximity sensor handle
channel – [in] Touch channel number
state – [out] Pointer to store the channel state

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if handle or state is NULL
ESP_ERR_INVALID_STATE if sensor not initialized
ESP_ERR_NOT_FOUND if channel not found

esp_err_t touch_proximity_sensor_handle_events(touch_proximity_handle_t handle)

Handle pending proximity sensor events.

Processes events from the FSM. This function should be called periodically to update proximity states and trigger callbacks.

Parameters

handle – [in] Touch proximity sensor handle

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if handle is NULL
ESP_ERR_INVALID_STATE if sensor not initialized

Structures

struct touch_proxi_config_t

Configuration structure for touch proximity sensor.

Public Members

uint32_t channel_num: Number of touch proximity sensor channels

uint32_t *channel_list: Touch channel list

float *channel_threshold: Threshold for touch detection for each channel

uint32_t debounce_times: Number of consecutive readings needed to confirm state change

uint32_t *channel_gold_value: Reference values for touch channels

bool skip_lowlevel_init: Skip low level initialization when working with existing touch driver

Type Definitions

typedef struct touch_proximity_sensor_t *touch_proximity_handle_t

typedef void (*proxi_cb_t)(uint32_t channel, proxi_state_t event, void *cb_arg): proximity sensor user callback type

Enumerations

enum proxi_state_t

Touch Proximity Sensor State.

Values:

enumerator PROXI_STATE_INACTIVE

enumerator PROXI_STATE_ACTIVE

Provide feedback about this document