esp-idf/docs/zh_CN/api-reference/peripherals/touch_element.rst

触摸元件
=============

:link_to_translation:`en:[English]`

概述
--------

触摸元件库是基于触摸传感器驱动设计的高度抽象的元件库，该库提供了统一且友好的软件接口，可以快速构建电容式触摸传感器的应用。有关触摸传感器驱动 API 的更多信息，请参阅 :doc:`../peripherals/touch_pad`。

架构
^^^^^^^^^^^^

触摸元件库通过触摸传感器驱动程序配置触摸传感器外设。使用时，部分必要的硬件参数需要传递给函数 :cpp:func:`touch_element_install`，但只有在调用 :cpp:func:`touch_element_start` 函数后，才会自动配置这些参数。这些参数配置会对实时系统产生很大的影响，因此步骤顺序很重要，必须在调用启动函数之后进行配置，确保系统正常运行。

上述参数包括触摸通道阈值、防水屏蔽传感器驱动级别等。触摸元件库会设置触摸传感器中断和 esp_timer 例程，并在触摸传感器中断服务例程中获取触摸传感器的硬件信息（通道状态、通道编号）。当特定通道事件发生时，硬件信息将传递给 esp_timer 回调例程，esp_timer 回调例程将触摸传感器通道信息分配给触摸元件（例如按键、滑条等）。随后，触摸元件库运行特定算法，更新触摸元件状态或计算其位置，并将结果分派给相应的处理程序。

因此，在使用触摸元件库时，你无需关注触摸传感器外设的工作细节，该库会处理大部分硬件信息，并将更有意义的信息传递给事件处理程序。

下图展示了触摸元件库的工作流程。

.. figure:: /../_static/touch_element/te_architecture.svg
    :scale: 100 %
    :align: center

    触摸元件库架构


下表展示了 {IDF_TARGET_NAME} 中与触摸元件库有关的功能。

.. list-table::
    :header-rows: 1
    :widths: 70 30
    :align: center

    * - 功能
      - ESP32S2
    * - 防水
      - ✔
    * - 按键
      - ✔
    * - 触摸滑条
      - ✔
    * - 矩阵按键
      - ✔


外设
^^^^^^^^^^

{IDF_TARGET_NAME} 集成了一个触摸传感器外设，具有多个物理通道。

.. only:: esp32s2 or esp32s3

    - 14 个物理电容触摸通道
    - 定时器或软件 FSM 触发模式
    - 高达 5 种中断（高阈值和低阈值中断、测量单通道完成和测量所有通道完成中断、测量超时中断）
    - 睡眠模式唤醒源
    - 硬件内置降噪
    - 硬件滤波器
    - 硬件防水传感器
    - 硬件近场感应传感器

这些通道的具体位置如下：

.. list-table::
    :header-rows: 1
    :widths: 50 50
    :align: center

    * - 通道
      - {IDF_TARGET_NAME}
    * - **通道 0**
      - **GPIO 0（保留）**
    * - **通道 1**
      - **GPIO 1**
    * - **通道 2**
      - **GPIO 2**
    * - **通道 3**
      - **GPIO 3**
    * - **通道 4**
      - **GPIO 4**
    * - **通道 5**
      - **GPIO 5**
    * - **通道 6**
      - **GPIO 6**
    * - **通道 7**
      - **GPIO 7**
    * - **通道 8**
      - **GPIO 8**
    * - **通道 9**
      - **GPIO 9**
    * - **通道 10**
      - **GPIO 10**
    * - **通道 11**
      - **GPIO 11**
    * - **通道 12**
      - **GPIO 12**
    * - **通道 13**
      - **GPIO 13**
    * - **通道 14**
      - **GPIO 14**


.. only:: esp32

    - 10 个物理电容触摸通道
    - 定时器或软件 FSM 触发模式
    - 2 种中断（超过阈值和低于阈值中断）
    - 睡眠模式唤醒源

这些通道的具体位置如下：

.. list-table::
    :header-rows: 1
    :widths: 50 50
    :align: center

    * - 通道
      - {IDF_TARGET_NAME}
    * - **通道 0**
      - **GPIO 0（有效）**
    * - **通道 1**
      - **GPIO 1**
    * - **通道 2**
      - **GPIO 2**
    * - **通道 3**
      - **GPIO 3**
    * - **通道 4**
      - **GPIO 4**
    * - **通道 5**
      - **GPIO 5**
    * - **通道 6**
      - **GPIO 6**
    * - **通道 7**
      - **GPIO 7**
    * - **通道 8**
      - **GPIO 8**
    * - **通道 9**
      - **GPIO 9**


术语
-----------

触摸元件库的有关术语如下：

.. list-table::
    :header-rows: 1
    :widths: 50 50
    :align: center

    * - 术语
      - 定义
    * - **触摸传感器 (touch sensor)**
      - 芯片内部的触摸传感器外设
    * - **触摸通道 (touch channel)**
      - 触摸传感器外设内的触摸通道
    * - **触摸焊盘 (touch pad)**
      - 外部物理触摸焊盘，通常位于 PCB 内部
    * - **降噪通道 (de-noise channel)**
      - 内部降噪通道，始终为通道 0 且已预留
    * - **屏蔽传感器 (shield sensor)**
      - 防水传感器之一，用于小面积的水滴检测，并补偿水滴对读数的影响
    * - **防护传感器 (guard sensor)**
      - 防水传感器之一，用于大面积的涉水检测，并临时禁用触摸传感器
    * - **屏蔽通道 (shield channel)**
      - 防水屏蔽传感器连接的通道，始终为通道 14
    * - **防护通道 (guard channel)**
      - 防水防护传感器连接的通道
    * - **屏蔽焊盘 (shield pad)**
      - 外部物理屏蔽焊盘，通常是网格状，与防水传感器相连
    * - **防护焊盘 (guard pad)**
      - 外部物理防护焊盘，通常是环状，与防护传感器相连

.. figure:: /../_static/touch_element/te_component.svg
    :scale: 100 %
    :align: center

    触摸传感器应用程序系统组件


触摸传感器信号
^^^^^^^^^^^^^^^^^^^

触摸传感器可提供以下信号：

- 原始信号：从触摸传感器获取、未经滤波的信号。
- 平滑信号：原始信号通过内部硬件滤波器滤波后的信号。
- 基准信号：经过滤波的信号，已过滤极低频噪声。

以上信号均可通过触摸传感器驱动程序 API 获取。

.. figure:: /../_static/touch_element/te_signal.png
    :scale: 40 %
    :align: center

    触摸传感器信号


触摸传感器信号阈值
^^^^^^^^^^^^^^^^^^^^^^

触摸传感器阈值支持重新配置，可用于确定触摸传感器状态。当平滑信号和基准信号间的差值大于阈值，即 ``（平滑信号 - 基准信号）> 信号阈值`` 时，触摸通道状态改变，并触发触摸中断。

.. figure:: /../_static/touch_element/te_threshold.svg
    :scale: 40 %
    :align: center

    触摸传感器信号阈值


灵敏度
^^^^^^^^^^^^^^^^

触摸传感器的一个重要性能参数，该值越大，表明触摸传感器越灵敏。可以通过以下公式计算：

.. math::

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


防水性能
^^^^^^^^^^^^^^^^^^

防水性能是触摸传感器的硬件功能，包括防护传感器和屏蔽传感器（始终连接到通道 14），可以抵御一定程度的水滴影响，并检测水流。


触摸按键
^^^^^^^^^^^^^^^^^^

触摸按键占用触摸传感器的一个通道，外观如下图所示：


.. figure:: /../_static/touch_element/te_button.svg
    :scale: 100 %
    :align: center

    触摸按键


触摸滑条
^^^^^^^^^^^^^^^^^^

触摸滑条占用触摸传感器的多个通道（至少三个），占用的通道越多，滑条的采样分辨率和准确度越高。触摸滑条外观如下图所示：

.. figure:: /../_static/touch_element/te_slider.svg
    :scale: 100 %
    :align: center

    触摸滑条


触摸矩阵
^^^^^^^^^^^^^^^^^^

触摸矩阵按键占用触摸传感器的多个通道（至少 2 + 2 = 4 个通道），它支持通过较少通道获取更多按键。{IDF_TARGET_NAME} 最多支持 49 个按键。触摸矩阵按键外观如下图所示：

.. figure:: /../_static/touch_element/te_matrix.svg
    :scale: 100 %
    :align: center

    触摸矩阵


使用触摸元件库
--------------

使用触摸元件库时，请遵循以下初始化流程：

1. 调用 :cpp:func:`touch_element_install`，初始化触摸元件库。
2. 调用 :cpp:func:`touch_xxxx_install`，初始化触摸元件（按键、滑条等）。
3. 调用 :cpp:func:`touch_xxxx_create`，创建新元件实例。
4. 调用 :cpp:func:`touch_xxxx_subscribe_event`，订阅事件通知。
5. 调用 :cpp:func:`touch_xxxx_set_dispatch_method`，选择事件通知的传递方式。
6. 选择使用回调函数传递事件通知时，调用 :cpp:func:`touch_xxxx_set_callback`，设置事件处理函数。
7. 调用 :cpp:func:`touch_element_start`，启用触摸元件库。
8. 选择使用回调函数传递事件通知时，若事件发生，驱动核心会调用回调函数，你无需做任何处理；选择使用事件任务传递事件通知时，你需要创建一个事件任务，并调用 :cpp:func:`touch_element_message_receive`，循环获取信息。
9. （可选）如果要暂停触摸元件的实时系统，或因某种原因无法获取触摸元件信息，应调用 :cpp:func:`touch_element_stop`，暂停触摸元件系统，然后再次调用 :cpp:func:`touch_element_start` 恢复系统。

上述流程代码如下所示：

.. code-block:: c

    static touch_xxx_handle_t element_handle; //声明一个触摸元件句柄

    //定义订阅的事件处理函数
    void event_handler(touch_xxx_handle_t out_handle, touch_xxx_message_t out_message, void *arg)
    {
        //事件处理逻辑
    }

    void app_main()
    {
        //使用默认初始化器配置触摸元件库
        touch_elem_global_config_t global_config = TOUCH_ELEM_GLOBAL_DEFAULT_CONFIG();
        touch_element_install(&global_config);

        //使用默认初始化器配置触摸元件
        touch_xxx_global_config_t elem_global_config = TOUCH_XXXX_GLOBAL_DEFAULT_CONFIG();
        touch_xxx_install(&elem_global_config);

        //创建新的实例
        touch_xxx_config_t element_config = {
            ...
            ...
        };
        touch_xxx_create(&element_config, &element_handle);

        //通过事件掩码订阅特定事件
        touch_xxx_subscribe_event(element_handle, TOUCH_ELEM_EVENT_ON_PRESS | TOUCH_ELEM_EVENT_ON_RELEASE, NULL);

        //选择使用回调函数传递事件通知
        touch_xxx_set_dispatch_method(element_handle, TOUCH_ELEM_DISP_CALLBACK);

        //注册回调函数
        touch_xxx_set_callback(element_handle, event_handler);

        //启用触摸元件库处理
        touch_element_start();
    }


初始化
^^^^^^^^^^^^^^

1. 要初始化触摸元件库，请调用 :cpp:func:`touch_element_install` 函数，并传递一个 :cpp:type:`touch_elem_global_config_t` 类型的实例作为参数，以配置触摸传感器外设和触摸元件库。默认初始化器位于 :cpp:func:`TOUCH_ELEM_GLOBAL_DEFAULT_CONFIG` 中，此默认配置适用于多数常见应用场景。建议在充分了解触摸传感器外设前，不要更改默认配置，以免影响系统。

2. 要初始化特定的触摸元件，需要调用其构造函数 :cpp:func:`touch_xxxx_install`。在调用此构造函数前，所有触摸元件都不会工作，以节省内存。因此，若要设置所需元件，需要为每个要使用的触摸元件分别调用构造函数。


启动触摸元件实例
^^^^^^^^^^^^^^^^

1. 要创建新的触摸元件实例，请调用 :cpp:func:`touch_xxxx_create`，选择一个通道，并将其 `灵敏度`_ 传递给新的元件实例。

2. 要订阅事件通知，请调用 :cpp:func:`touch_xxxx_subscribe_event`。触摸元件库提供了多个事件，事件掩码存放在 :idf_file:`components/touch_element/include/touch_element/touch_element.h` 中。通过使用这些事件掩码，可以订阅单个特定事件，或将单个事件组合在一起，订阅多个事件。

3. 要配置传递事件通知的方式，请调用 :cpp:func:`touch_xxxx_subscribe_event`。触摸元件库提供了两种方式: :cpp:enumerator:`TOUCH_ELEM_DISP_EVENT` 和 :cpp:enumerator:`TOUCH_ELEM_DISP_CALLBACK`，支持以不同方式获取并处理触摸元件信息。

事件处理
^^^^^^^^^^^^^^^^^

如果配置的是 :cpp:enumerator:`TOUCH_ELEM_DISP_EVENT`，需要启用一个事件处理任务获取触摸元件信息。调用 :cpp:func:`touch_element_message_receive` 可以获取所有元件的原始信息，随后通过调用相应的信息解码器 :cpp:func:`touch_xxxx_get_message`，提取特定类型元件的信息，获取有关触摸操作的详细数据。如果配置的是 :cpp:enumerator:`TOUCH_ELEM_DISP_CALLBACK`，在触摸元件开始工作之前，需要调用 :cpp:func:`touch_xxxx_set_callback`，传递一个事件处理函数，有关触摸操作的详细数据都会传递到该事件处理函数。

.. warning::

    由于事件处理函数在元件库的核心运行，即在 esp-timer 回调中运行，请避免执行可能导致阻塞或延迟的操作，如调用 :cpp:func:`vTaskDelay`。


事件处理过程代码如下所示：

.. code-block:: c

    /* ---------------------------------------------- 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); //信息解码
                ... //事件处理逻辑
            }
        }
    }
    void app_main()
    {
        ...

        touch_xxxx_set_dispatch_method(element_handle, TOUCH_ELEM_DISP_EVENT);  //设置以 TOUCH_ELEM_DISP_EVENT 传递事件通知
        xTaskCreate(&element_handler_task, "element_handler_task", 2048, NULL, 5, NULL);  //创建一个事件处理任务

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

    ...
    /* ---------------------------------------------- TOUCH_ELEM_DISP_CALLBACK ----------------------------------------------- */
    void element_handler(touch_xxxx_handle_t out_handle, touch_xxxx_message_t out_message, void *arg)
    {
        //事件处理逻辑
    }

    void app_main()
    {
        ...

        touch_xxxx_set_dispatch_method(element_handle, TOUCH_ELEM_DISP_CALLBACK);  //设置以 ``TOUCH_ELEM_DISP_CALLBACK`` 传递事件通知
        touch_xxxx_set_callback(element_handle, element_handler);  //注册事件处理函数

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


使用防水功能
^^^^^^^^^^^^^^^^

1. 一旦初始化触摸元件的防水功能，防水屏蔽传感器会始终处于开启状态。防水屏蔽传感器为可选项，如果不需要，可以通过配置结构体，将 ``TOUCH_WATERPROOF_GUARD_NOUSE`` 传递给 :cpp:func:`touch_element_waterproof_install`。

2. 要关联触摸元件与防护传感器，请调用 :cpp:func:`touch_element_waterproof_add`，将触摸元件句柄添加到触摸元件防水功能的掩码列表中。触摸元件与防护传感器关联后，水流触发防护传感器时会关闭触摸元件，为其提供保护。

查看使用触摸元件防水功能的示例代码，请前往 ESP-IDF 示例的 :example:`peripherals/touch_sensor/touch_element/touch_element_waterproof` 目录。

配置防水功能的代码如下所示：

.. code-block:: c

    void app_main()
    {
        ...

        touch_xxxx_install();                 //初始化实例（按键、滑条等）
        touch_xxxx_create(&element_handle);  //创建新的触摸元件

        ...

        touch_element_waterproof_install();              //初始化触摸元件防水功能
        touch_element_waterproof_add(element_handle);   //关联触摸元件与防护传感器

        ...
    }

从 Light/Deep-sleep 模式唤醒
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

仅触摸按键可配置为唤醒源。

使用触摸传感器，可以唤醒从 Light-sleep 或 Deep-sleep 模式中唤醒芯片。在 Light-sleep 模式下，任何已安装的触摸按键都可以唤醒芯片。但在 Deep-sleep 模式下，只有睡眠按键可以唤醒芯片，触摸传感器还会立即进行校准。如果手指没有及时离开，可能导致校准参考值出错。尽管在手指离开后，校准参考值会自行恢复，不会影响驱动逻辑，但如果你不想在从 Deep-sleep 模式唤醒时看到错误的校准参考值，可以调用 :cpp:func:`touch_element_sleep_enable_wakeup_calibration`，禁用唤醒校准功能。

查看使用触摸元件唤醒芯片的示例代码，请前往 ESP-IDF 示例的 :example:`system/light_sleep` 目录。

.. code-block:: c

    void app_main()
    {
        ...
        touch_element_install();
        touch_button_install();                 //初始化触摸按键
        touch_button_create(&element_handle);  //创建新的触摸元件

        ...

        // 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)); //（可选）禁用唤醒校准，防止基准值更新为错误值

        touch_element_start();

        ...
    }

应用示例
-------------------

查看使用触摸元件库的示例代码，请前往 ESP-IDF 示例的 :example:`peripherals/touch_sensor/touch_element` 目录。


API 参考 - 触摸元件核心
----------------------------------

.. include-build-file:: inc/touch_element.inc


API 参考 - 触摸按键
----------------------------------

.. include-build-file:: inc/touch_button.inc


API 参考 - 触摸滑条
----------------------------------

.. include-build-file:: inc/touch_slider.inc


API 参考 - 触摸矩阵
----------------------------------

.. include-build-file:: inc/touch_matrix.inc