触摸接近感应传感器

[English]

概述

touch_proximity_sensor 使用 ESP32-S3 的触摸接近感应数据通路。接近感应保持独立的底层数据类型：累计测量值不会按普通触摸 raw 计数处理，不使用普通触摸的 5000 启动目标，也不使用普通触摸频率估计接口。组件需要 ESP-IDF 5.5 或更新版本，并运行在 ESP32-S3 上。

封装层把完整的接近感应帧交给一个 FSM 处理。FSM 的有效周期等于底层扫描周期乘以底层实际报告的 proximity_count。应在独立的接近基准稳定后，根据目标板空闲数据调整阈值。

配置

使用 touch_proxi_config_t 配置：

typedef struct {
    uint32_t channel_num;
    uint32_t *channel_list;
    uint32_t *thresholds;
    uint32_t sample_period_ms;
    uint32_t sample_cfg_num;
    uint32_t proximity_count;
    uint32_t debounce_active;
    uint32_t debounce_inactive;
    bool skip_lowlevel_init;
} touch_proxi_config_t;

thresholds 是接近感应数据域中的绝对归一化 FSM 判定计数，不是百分比，也不是普通触摸 raw 计数。采样字段为零时使用底层默认值；proximity_count 为零时使用 Kconfig 默认值（范围 1 到 255）。设置 skip_lowlevel_init = true 时，现有底层实例必须是接近感应类型；如果显式指定计数，还必须与底层实际计数一致。

示例

static uint32_t channels[] = {8};
static uint32_t thresholds[] = {25};
touch_proxi_config_t config = {
    .channel_num = 1,
    .channel_list = channels,
    .thresholds = thresholds,
    .sample_period_ms = 0,
    .sample_cfg_num = 0,
    .proximity_count = 0,
    .debounce_active = 2,
    .debounce_inactive = 2,
    .skip_lowlevel_init = false,
};
touch_proximity_handle_t handle = NULL;
ESP_ERROR_CHECK(touch_proximity_sensor_create(&config, &handle,
                                              proximity_callback, NULL));

while (true) {
    ESP_ERROR_CHECK(touch_proximity_sensor_handle_events(handle));
    vTaskDelay(pdMS_TO_TICKS(20));
}

使用 touch_proximity_sensor_get_data() 查询正向融合滤波幅度，使用 touch_proximity_sensor_get_state() 查询稳定状态；回调会报告按下和释放状态变化。

应用示例

API 参考

Header File

Functions

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

Create a touch proximity sensor instance.

A pure proximity low-level configuration is created when requested. Its startup path does not use ordinary touch 5000-count alignment. One FSM consumes complete proximity frames and performs any configured frequency fusion without using the ordinary touch frequency estimator.

参数

  • config – [in] Proximity sensor configuration.

  • sensor_handle – [out] Receives the created sensor handle.

  • cb – [in] State-change callback, or NULL.

  • cb_arg – [in] User data passed to the callback.

返回

ESP_OK on success, or an allocation, low-level, or FSM error.

esp_err_t touch_proximity_sensor_delete(touch_proximity_handle_t proxi_sensor)

Delete a touch proximity sensor instance.

参数

proxi_sensor – [in] Handle returned by create(), or NULL.

返回

ESP_OK on success, or the first stop/delete error.

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

Get the normalized positive fused proximity amplitude.

参数

  • handle – [in] Proximity sensor handle.

  • channel – [in] Configured channel ID.

  • data – [out] Nonnegative normalized fused filtered amplitude.

返回

ESP_OK, ESP_ERR_INVALID_ARG, ESP_ERR_INVALID_STATE, or ESP_ERR_NOT_FOUND.

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

Get the current state of one proximity channel.

参数

  • handle – [in] Proximity sensor handle.

  • channel – [in] Configured channel ID.

  • state – [out] Receives the stable state.

返回

ESP_OK, ESP_ERR_INVALID_ARG, ESP_ERR_INVALID_STATE, or ESP_ERR_NOT_FOUND.

esp_err_t touch_proximity_sensor_handle_events(touch_proximity_handle_t handle)

Process pending proximity frames and invoke callbacks.

参数

handle – [in] Proximity sensor handle.

返回

ESP_OK on success, or an FSM processing error.

Structures

struct touch_proxi_config_t

Configuration for a touch proximity sensor.

Proximity channels use the low-level proximity data path and retain its accumulated-count unit. They are not ordinary touch raw counts and are not aligned to a 5000-count touch baseline. thresholds are normalized fused decision counts produced by the FSM after the independent proximity baseline is established; tune them from the target’s measured idle signal. All arrays are copied by create().

Public Members

uint32_t channel_num

Number of proximity channels.

uint32_t *channel_list

Channel IDs, with channel_num entries.

uint32_t *thresholds

Per-channel normalized proximity thresholds.

uint32_t sample_period_ms

Requested scan period; zero selects the low-level default.

uint32_t sample_cfg_num

Samples per frame; zero selects the low-level default.

uint32_t proximity_count

Measurements accumulated per frame; zero selects the Kconfig default.

uint32_t debounce_active

Consecutive active frames; zero selects the FSM default.

uint32_t debounce_inactive

Consecutive inactive frames; zero selects the FSM default.

bool skip_lowlevel_init

Reuse an existing proximity low-level instance when true.

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 state-change callback.

Param channel

[in] Channel that changed state.

Param event

[in] New stable proximity state.

Param cb_arg

[in] User data supplied at create().

Enumerations

enum proxi_state_t

Touch proximity sensor state.

Values:

enumerator PROXI_STATE_INACTIVE

No proximity event is active.

enumerator PROXI_STATE_ACTIVE

The configured proximity threshold is active.

提供有关此文档的反馈