Merge branch 'feature/touch_driver_ng_on_32' into 'master'
feat(touch): support touch v1 in new touch driver Closes IDF-10183 and IDF-11423 See merge request espressif/esp-idf!34781
This commit is contained in:
Kevin (Lao Kaiyao)
@@ -3,7 +3,7 @@
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
{IDF_TARGET_TOUCH_SENSOR_VERSION:default="NOT_UPDATED", esp32s2="v2", esp32s3="v2", esp32p4="v3"}
|
||||
{IDF_TARGET_TOUCH_SENSOR_VERSION:default="NOT_UPDATED", esp32="v1", esp32s2="v2", esp32s3="v2", esp32p4="v3"}
|
||||
|
||||
概述
|
||||
------
|
||||
@@ -25,13 +25,40 @@
|
||||
| V1 | ESP32 | 第一代触摸传感器，触摸时读数变小 |
|
||||
+-----------+--------------+------------------------------------------------------------------------+
|
||||
| V2 | ESP32-S2 | 第二代触摸传感器，触摸时读数变大 |
|
||||
| | | 新增防水防潮、接近感应、睡眠唤醒功能 |
|
||||
| | | 新增硬件滤波器、基线、防水防潮、接近感应、睡眠唤醒功能 |
|
||||
| +--------------+------------------------------------------------------------------------+
|
||||
| | ESP32-S3 | 第二代触摸传感器，新增接近感应测量完成中断 |
|
||||
+-----------+--------------+------------------------------------------------------------------------+
|
||||
| V3 | ESP32-P4 | 第三代触摸传感器，新增跳频扫描 |
|
||||
+-----------+--------------+------------------------------------------------------------------------+
|
||||
|
||||
测量原理
|
||||
-----------
|
||||
|
||||
触摸传感器通过硬件内部的电流或电压偏置对触摸通道进行充电和放电操作，由于触摸通道存在内部电容和电路中的寄生电容，充放电时在通道引脚上表现为锯齿波。当手指贴近或者触摸该通道时，通道、人体和大地之间形成充放电回路，使得触摸通道耦合的电容增大，充放电速度变慢，即锯齿波周期增大。
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
触摸传感器会在固定时间内对触摸通道进行充放电，并统计充放电次数，其计数结果即为原始数据。其中单次测量的充放电持续时间可由 :cpp:member:`touch_sensor_sample_config_t::charge_times` 指定，两次测量中间的间隔时间可由 :cpp:member:`touch_sensor_config_t::meas_interval_us` 指定。
|
||||
|
||||
.. figure:: ../../../_static/touch_pad-measurement-parameters.jpg
|
||||
:align: center
|
||||
:alt: Touch Pad - relationship between measurement parameters
|
||||
:figclass: align-center
|
||||
|
||||
触摸传感器工作原理示意图
|
||||
|
||||
.. only:: not esp32
|
||||
|
||||
触摸传感器会统计固定充放电次数所需的时钟周期数，其计数结果即为原始数据。其中单次测量的充放电次数可由 :cpp:member:`touch_sensor_sample_config_t::charge_duration_ms` 指定，两次测量中间的间隔时间可由 :cpp:member:`touch_sensor_config_t::meas_interval_us` 指定。
|
||||
|
||||
.. figure:: ../../../_static/touch_pad-measurement-parameters-version2.png
|
||||
:align: center
|
||||
:alt: Touch Pad - relationship between measurement parameters
|
||||
:figclass: align-center
|
||||
|
||||
触摸传感器工作原理示意图
|
||||
|
||||
触摸通道概览
|
||||
----------------------
|
||||
|
||||
@@ -93,8 +120,8 @@
|
||||
- `启用和禁用 <#touch-enable>`__
|
||||
- `连续扫描 <#touch-conti-scan>`__
|
||||
- `单次扫描 <#touch-oneshot-scan>`__
|
||||
- `基线值配置 <#touch-benchmark>`__
|
||||
- `测量值读数 <#touch-read>`__
|
||||
:SOC_TOUCH_SUPPORT_BENCHMARK: - `基线值配置 <#touch-benchmark>`__
|
||||
:SOC_TOUCH_SUPPORT_WATERPROOF: - `防水防潮配置 <#touch-waterproof>`__
|
||||
:SOC_TOUCH_SUPPORT_PROX_SENSING: - `接近感应配置 <#touch-prox-sensing>`__
|
||||
:SOC_TOUCH_SUPPORT_SLEEP_WAKEUP: - `睡眠唤醒配置 <#touch-sleep-wakeup>`__
|
||||
@@ -182,6 +209,14 @@
|
||||
|
||||
若需要注销滤波器，可再次调用 :cpp:func:`touch_sensor_config_filter` 并将第二个参数（即 :cpp:type:`touch_sensor_filter_config_t` 的配置结构体指针）设为 ``NULL`` 来注销滤波器功能。
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
触摸传感器版本 {IDF_TARGET_TOUCH_SENSOR_VERSION} 本身不支持硬件滤波器，但是驱动中可以基于 ``esp_timer`` 设置周期性触发的软件滤波器。可以通过 :cpp:member:`touch_sensor_filter_config_t::interval_ms` 来制定软件滤波触发的间隔时间，另外 :cpp:member:`touch_sensor_filter_config_t::data_filter_fn` 接口支持指定自定义滤波函数，若无特殊滤波器要求，也可将该接口设为 ``NULL`` 来使用驱动中的默认滤波器。
|
||||
|
||||
.. only:: not esp32
|
||||
|
||||
触摸传感器版本 {IDF_TARGET_TOUCH_SENSOR_VERSION} 支持硬件滤波器。基线的滤波与更新策略可通过 :cpp:member:`touch_sensor_filter_config_t::benchmark` 进行配置，而读数值的滤波可通过 :cpp:member:`touch_sensor_filter_config_t::data` 进行配置。
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
// ...
|
||||
@@ -268,21 +303,6 @@
|
||||
// 触发单次扫描，并设置超时时间为 1000 ms
|
||||
ESP_ERROR_CHECK(touch_sensor_trigger_oneshot_scanning(sens_handle, 1000));
|
||||
|
||||
.. _touch-benchmark:
|
||||
|
||||
基线值配置
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
一般情况下，不需要额外设置触摸传感器的基线值，若有必要强制复位基线值到当前平滑值，可调用 :cpp:func:`touch_channel_config_benchmark`。
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
touch_chan_benchmark_config_t benchmark_cfg = {
|
||||
// 基线操作
|
||||
// ...
|
||||
};
|
||||
ESP_ERROR_CHECK(touch_channel_config_benchmark(chan_handle, &benchmark_cfg));
|
||||
|
||||
.. _touch-read:
|
||||
|
||||
测量值读数
|
||||
@@ -301,6 +321,23 @@
|
||||
// 读取滤波后的平滑数据
|
||||
ESP_ERROR_CHECK(touch_channel_read_data(chan_handle, TOUCH_CHAN_DATA_TYPE_SMOOTH, smooth_data));
|
||||
|
||||
.. _touch-benchmark:
|
||||
|
||||
.. only:: SOC_TOUCH_SUPPORT_BENCHMARK
|
||||
|
||||
基线值配置
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
一般情况下，不需要额外设置触摸传感器的基线值，若有必要强制复位基线值到当前平滑值，可调用 :cpp:func:`touch_channel_config_benchmark`。
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
touch_chan_benchmark_config_t benchmark_cfg = {
|
||||
// 基线操作
|
||||
// ...
|
||||
};
|
||||
ESP_ERROR_CHECK(touch_channel_config_benchmark(chan_handle, &benchmark_cfg));
|
||||
|
||||
.. _touch-waterproof:
|
||||
|
||||
.. only:: SOC_TOUCH_SUPPORT_WATERPROOF
|
||||
@@ -377,8 +414,11 @@
|
||||
|
||||
若需要在睡眠过程中进行读数、配置等操作，可通过运行在 :doc:`超低功耗协处理器 ULP <../system/ulp>` 上的触摸传感器驱动 ``components/ulp/ulp_riscv/ulp_core/include/ulp_riscv_touch_ulp_core.h`` 实现。
|
||||
|
||||
- Light-sleep 状态唤醒：通过指定 :cpp:member:`slp_wakeup_lvl` 为 :cpp:enumerator:`TOUCH_LIGHT_SLEEP_WAKEUP` 即可启用触摸传感器 Light-sleep 唤醒功能。注意任何已注册的触摸传感器通道都会在 Light-sleep 状态下保持采样并支持唤醒 Light-sleep。
|
||||
- Deep-sleep 状态唤醒：启用触摸传感器 Deep-sleep 唤醒功能除了指定 :cpp:member:`slp_wakeup_lvl` 为 :cpp:enumerator:`TOUCH_DEEP_SLEEP_WAKEUP` 外，还需要指定 Deep-sleep 唤醒通道 :cpp:member:`deep_slp_chan`，注意只有该指定的通道才会在 Deep-sleep 状态下保持采样以及唤醒，以此降低在 Deep-sleep 状态下的功耗。此外，若需要在深度睡眠下使用另一套低功耗的配置来进一步降低功耗，可以通过 :cpp:member:`deep_slp_sens_cfg` 额外指定一套低功耗配置，在进入 Deep-sleep 前，驱动会应用这套配置，从 Deep-sleep 状态唤醒后，则会重新配置到之前的配置。请注意当 :cpp:member:`slp_wakeup_lvl` 配置为 :cpp:enumerator:`TOUCH_DEEP_SLEEP_WAKEUP` 后，触摸传感器不仅能唤醒 Deep-sleep 状态，还能唤醒 Light-sleep 状态。
|
||||
.. list::
|
||||
|
||||
- Light-sleep 状态唤醒：通过指定 :cpp:member:`slp_wakeup_lvl` 为 :cpp:enumerator:`TOUCH_LIGHT_SLEEP_WAKEUP` 即可启用触摸传感器 Light-sleep 唤醒功能。注意任何已注册的触摸传感器通道都会在 Light-sleep 状态下保持采样并支持唤醒 Light-sleep。
|
||||
:esp32: - Deep-sleep 状态唤醒：通过指定 :cpp:member:`slp_wakeup_lvl` 为 :cpp:enumerator:`TOUCH_DEEP_SLEEP_WAKEUP` 即可启用触摸传感器 Deep-sleep 唤醒功能。注意版本 {IDF_TARGET_TOUCH_SENSOR_VERSION} 启用 Deep-sleep 唤醒后，会在 Deep-sleep 中保持 RTC 电源域开启，以维持触摸传感器工作，此时任何已注册的触摸传感器通道都可以在 Deep-sleep 状态下保持采样并支持唤醒 Deep-sleep。
|
||||
:not esp32: - Deep-sleep 状态唤醒：启用触摸传感器 Deep-sleep 唤醒功能除了指定 :cpp:member:`slp_wakeup_lvl` 为 :cpp:enumerator:`TOUCH_DEEP_SLEEP_WAKEUP` 外，还需要指定 Deep-sleep 唤醒通道 :cpp:member:`deep_slp_chan`，注意只有该指定的通道才会在 Deep-sleep 状态下保持采样以及唤醒，以此降低在 Deep-sleep 状态下的功耗。此外，若需要在深度睡眠下使用另一套低功耗的配置来进一步降低功耗，可以通过 :cpp:member:`deep_slp_sens_cfg` 额外指定一套低功耗配置，在进入 Deep-sleep 前，驱动会应用这套配置，从 Deep-sleep 状态唤醒后，则会重新配置到之前的配置。请注意当 :cpp:member:`slp_wakeup_lvl` 配置为 :cpp:enumerator:`TOUCH_DEEP_SLEEP_WAKEUP` 后，触摸传感器不仅能唤醒 Deep-sleep 状态，还能唤醒 Light-sleep 状态。
|
||||
|
||||
.. only:: not esp32
|
||||
|
||||
@@ -437,11 +477,28 @@
|
||||
|
||||
- :example:`peripherals/touch_sensor/touch_sens_basic` 演示了如何注册触摸通道并读取数据，并说明了硬件要求及项目配置。
|
||||
|
||||
应用注意事项
|
||||
------------
|
||||
|
||||
触摸传感器功耗问题
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
由于触摸传感器的测量需要对电容进行充放电，所以它是一个比较耗能的外设。在一些对功耗要求比较高的应用中，可采用以下几个方法来降低触摸传感器功耗。
|
||||
|
||||
.. list::
|
||||
|
||||
- 减少触摸通道数量：可在同一通道上复用多种功能（如单双击、长按等），从而减少触摸传感器的数量。
|
||||
- 增加测量间隔：通过增大 :cpp:member:`touch_sensor_config_t::meas_interval_us` 测量间隔，来降低测量频率，从而降低功耗。
|
||||
:esp32: - 降低单次测量时间：通过降低 :cpp:member:`touch_sensor_sample_config_t::charge_duration_ms` 单次测量时间，来减少充放电次数，从而降低功耗。
|
||||
:not esp32: - 减少单次测量充放电次数：通过减少 :cpp:member:`touch_sensor_sample_config_t::charge_times` 单次测量充放电次数，以降低功耗。
|
||||
:esp32s2 or esp32s3: - 电流偏置类型设为自偏置：通过设置 :cpp:member:`touch_sensor_sample_config_t::bias_type` 为 :cpp:enumerator:`touch_bias_type_t::TOUCH_BIAS_TYPE_SELF` 来使用功耗更低的自偏置。
|
||||
:esp32 or esp32s2 or esp32s3: - 降低充放电幅度：:cpp:member:`touch_sensor_sample_config_t::charge_volt_lim_l` 和 :cpp:member:`touch_sensor_sample_config_t::charge_volt_lim_h` 用于指定放电时的电压下限和充电时的电压上限，同时降低这两个电压值以及上下限之间的压差可降低功耗。
|
||||
:esp32 or esp32s2 or esp32s3: - 降低电流偏置强度：降低 :cpp:member:`touch_channel_config_t::charge_speed` 充放电速度（即电流偏置的电流大小）从而降低功耗。
|
||||
:esp32p4: - 降低 LDO 电压偏置强度：降低 :cpp:member:`touch_channel_config_t::bias_volt` 从而降低功耗。
|
||||
|
||||
API 参考
|
||||
----------
|
||||
|
||||
.. only:: esp32p4 or esp32s2 or esp32s3
|
||||
|
||||
.. include-build-file:: inc/touch_sens.inc
|
||||
.. include-build-file:: inc/touch_sens_types.inc
|
||||
.. include-build-file:: inc/touch_version_types.inc
|
||||
.. include-build-file:: inc/touch_sens.inc
|
||||
.. include-build-file:: inc/touch_sens_types.inc
|
||||
.. include-build-file:: inc/touch_version_types.inc
|
||||
|
||||
@@ -0,0 +1,49 @@
|
||||
.. This file gets included from other .rst files in this folder.
|
||||
.. It contains target-specific snippets.
|
||||
.. Comments and '---' lines act as delimiters.
|
||||
..
|
||||
.. This is necessary mainly because RST doesn't support substitutions
|
||||
.. (defined in RST, not in Python) inside code blocks. If that is ever implemented,
|
||||
.. These code blocks can be moved back to the main .rst files, with target-specific
|
||||
.. file names being replaced by substitutions.
|
||||
|
||||
.. touch-chan-mapping
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 20 20
|
||||
|
||||
* - 通道
|
||||
- GPIO
|
||||
|
||||
* - CH0
|
||||
- IO4
|
||||
|
||||
* - CH1
|
||||
- IO0
|
||||
|
||||
* - CH2
|
||||
- IO2
|
||||
|
||||
* - CH3
|
||||
- IO15
|
||||
|
||||
* - CH4
|
||||
- IO13
|
||||
|
||||
* - CH5
|
||||
- IO12
|
||||
|
||||
* - CH6
|
||||
- IO14
|
||||
|
||||
* - CH7
|
||||
- IO27
|
||||
|
||||
* - CH8
|
||||
- IO33
|
||||
|
||||
* - CH9
|
||||
- IO32
|
||||
|
||||
---
|
||||
@@ -45,8 +45,7 @@
|
||||
:SOC_LP_VAD_SUPPORTED: vad
|
||||
:SOC_JPEG_CODEC_SUPPORTED: jpeg
|
||||
:SOC_TEMP_SENSOR_SUPPORTED: temp_sensor
|
||||
:esp32: touch_pad
|
||||
:SOC_TOUCH_SENSOR_SUPPORTED and not esp32: cap_touch_sens
|
||||
:SOC_TOUCH_SENSOR_SUPPORTED: cap_touch_sens
|
||||
:esp32s2: touch_element
|
||||
:SOC_TWAI_SUPPORTED: twai
|
||||
uart
|
||||
|
||||
@@ -1,328 +0,0 @@
|
||||
触摸传感器
|
||||
============
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
{IDF_TARGET_TOUCH_SENSOR_VERSION:default="v2", esp32="v1"}
|
||||
|
||||
.. only:: esp32s2 or esp32s3
|
||||
|
||||
.. warning::
|
||||
|
||||
该文档所演示的 Touch 驱动已弃用, 请移步新文档查看最新的 Touch 驱动: :doc:`Capacitive Touch Sensor </api-reference/peripherals/cap_touch_sens>`.
|
||||
|
||||
概述
|
||||
------------
|
||||
|
||||
触摸传感器系统由保护覆盖层、触摸电极、绝缘基板和走线组成，保护覆盖层位于最上层，绝缘基板上设有电极及走线。触摸覆盖层将引起电容变化，根据电容变化，可以判断此次触摸是否为有效触摸行为。
|
||||
|
||||
触摸传感器可以以矩阵或滑条等方式组合使用，从而覆盖更大触感区域及更多触感点。触摸传感由软件或专用硬件计时器发起，由有限状态机 (FSM) 硬件控制。
|
||||
|
||||
如需了解触摸传感器设计、操作及其控制寄存器等相关信息，请参考《`{IDF_TARGET_NAME} 技术参考手册 <{IDF_TARGET_TRM_CN_URL}>`_》(PDF) 中“片上传感器与模拟信号处理”章节。
|
||||
|
||||
请参考 `触摸传感器应用方案简介 <https://github.com/espressif/esp-iot-solution/blob/release/v1.0/documents/touch_pad_solution/touch_sensor_design_en.md>`_，查看触摸传感器设计详情和固件开发指南。
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
如果想评估触摸传感器的多种应用场景，请查看 `ESP32 触摸功能开发套件 <https://docs.espressif.com/projects/espressif-esp-dev-kits/en/latest/esp32/esp32-sense-kit/user_guide.html>`_。
|
||||
|
||||
功能介绍
|
||||
----------------------
|
||||
|
||||
下面将 API 分解成几个函数组进行介绍：
|
||||
|
||||
- 初始化触摸传感器驱动程序
|
||||
- 配置触摸传感器 GPIO 管脚
|
||||
- 触摸状态测量
|
||||
- 调整测量参数（优化测量）
|
||||
- 滤波采样
|
||||
- 触摸监测方式
|
||||
- 设置中断信号监测触碰动作
|
||||
- 中断触发，唤醒睡眠模式
|
||||
|
||||
请前往 :ref:`touch_pad-api-reference` 章节，查看某一函数的具体描述。:ref:`应用示例 <touch_pad-api-examples>` 章节则介绍了此 API 的具体实现。
|
||||
|
||||
初始化触摸传感器驱动程序
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
使用触摸传感器之前，需要先调用 :cpp:func:`touch_pad_init` 函数初始化触摸传感器驱动程序。此函数设置了 :ref:`touch_pad-api-reference` 项下的 *Macros* 中列出的几项 ``.._DEFAULT`` 驱动程序参数，同时删除之前设置过的触摸传感器信息（如有），并禁用中断。
|
||||
|
||||
如果不再需要该驱动程序，可以调用 :cpp:func:`touch_pad_deinit` 释放已初始化的驱动程序。
|
||||
|
||||
配置触摸传感器 GPIO 管脚
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
可调用 :cpp:func:`touch_pad_config()` 使能某一 GPIO 的触感功能。{IDF_TARGET_NAME} 最多可支持 10 个电容式触摸传感器通道。
|
||||
|
||||
.. list-table::
|
||||
:align: center
|
||||
:widths: 50 50
|
||||
:header-rows: 1
|
||||
|
||||
* - 触摸传感器通道
|
||||
- GPIO 管脚
|
||||
* - T0
|
||||
- GPIO4
|
||||
* - T1
|
||||
- GPIO0
|
||||
* - T2
|
||||
- GPIO2
|
||||
* - T3
|
||||
- MTDO
|
||||
* - T4
|
||||
- MTCK
|
||||
* - T5
|
||||
- MTDI
|
||||
* - T6
|
||||
- MTMS
|
||||
* - T7
|
||||
- GPIO27
|
||||
* - T8
|
||||
- 32K_XN
|
||||
* - T9
|
||||
- 32K_XP
|
||||
|
||||
.. only:: esp32s2 or esp32s3
|
||||
|
||||
可调用 :cpp:func:`touch_pad_config()` 使能某一 GPIO 的触感功能。{IDF_TARGET_NAME} 最多可支持 14 个电容式触摸传感器通道。
|
||||
|
||||
.. list-table::
|
||||
:align: center
|
||||
:widths: 50 50
|
||||
:header-rows: 1
|
||||
|
||||
* - 触摸传感器通道
|
||||
- 管脚
|
||||
* - T0
|
||||
- 内部通道，无对应管脚
|
||||
* - T1
|
||||
- GPIO1
|
||||
* - T2
|
||||
- GPIO2
|
||||
* - T3
|
||||
- GPIO3
|
||||
* - T4
|
||||
- GPIO4
|
||||
* - T5
|
||||
- GPIO5
|
||||
* - T6
|
||||
- GPIO6
|
||||
* - T7
|
||||
- GPIO7
|
||||
* - T8
|
||||
- GPIO8
|
||||
* - T9
|
||||
- GPIO9
|
||||
* - T10
|
||||
- GPIO10
|
||||
* - T11
|
||||
- GPIO11
|
||||
* - T12
|
||||
- GPIO12
|
||||
* - T13
|
||||
- GPIO13
|
||||
* - T14
|
||||
- GPIO14
|
||||
|
||||
使用 :cpp:func:`touch_pad_set_fsm_mode` 选择触摸传感器测量（由 FSM 操作）是由硬件定时器自动启动，还是由软件自动启动。如果选择软件模式，请使用 :cpp:func:`touch_pad_sw_start` 启动 FSM。
|
||||
|
||||
触摸状态测量
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
借助以下两个函数从传感器读取原始数据和滤波后的数据：
|
||||
|
||||
* :cpp:func:`touch_pad_read_raw_data`
|
||||
* :cpp:func:`touch_pad_read_filtered`
|
||||
|
||||
这两个函数也可以用于检查触碰和释放触摸传感器时传感器读数变化范围，然后根据这些信息设定触摸传感器的触摸阈值。
|
||||
|
||||
.. note::
|
||||
|
||||
使用 :cpp:func:`touch_pad_read_filtered` 之前，需要先调用 `滤波采样`_ 中特定的滤波器函数来初始化并配置该滤波器。
|
||||
|
||||
.. only:: esp32s2 or esp32s3
|
||||
|
||||
借助以下函数从传感器读取原始数据：
|
||||
|
||||
* :cpp:func:`touch_pad_read_raw_data`
|
||||
|
||||
该函数也可以用于检查触碰和释放触摸传感器时传感器读数变化范围，然后根据这些信息设定触摸传感器的触摸阈值。
|
||||
|
||||
测量方式
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
触摸传感器会统计固定时间内的充放电次数，其计数结果即为原始数据，可由 :cpp:func:`touch_pad_read_raw_data` 读出。上述固定时间可通过 :cpp:func:`touch_pad_set_measurement_clock_cycles` 设置。完成一次测量后，触摸传感器会在下次测量开始前保持睡眠状态。两次测量之前的间隔时间可由 :cpp:func:`touch_pad_set_measurement_interval` 进行设置。
|
||||
|
||||
.. note::
|
||||
|
||||
若设置的计数时间太短（即测量持续的时钟周期数太小），则可能导致结果不准确，但是过大的计数时间也会造成功耗上升。另外，若睡眠时间加测量时间的总时间过长，则会造成触摸传感器响应变慢。
|
||||
|
||||
.. only:: esp32s2 or esp32s3
|
||||
|
||||
触摸传感器会统计固定充放电次数所需的时间（即所需时钟周期数），其结果即为原始数据，可由 :cpp:func:`touch_pad_read_raw_data` 读出。上述固定的充放电次数可通过 :cpp:func:`touch_pad_set_charge_discharge_times` 设置。完成一次测量后，触摸传感器会在下次测量开始前保持睡眠状态。两次测量之前的间隔时间可由 :cpp:func:`touch_pad_set_measurement_interval` 进行设置。
|
||||
|
||||
.. note::
|
||||
|
||||
若设置的充放电次数太少，则可能导致结果不准确，但是充放电次数过多也会造成功耗上升。另外，若睡眠时间加测量时间的总时间过长，则会造成触摸传感器响应变慢。
|
||||
|
||||
优化测量
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
触摸传感器设有数个可配置参数，以适应触摸传感器设计特点。例如，如果需要感知较细微的电容变化，则可以缩小触摸传感器充放电的参考电压范围。使用 :cpp:func:`touch_pad_set_voltage` 函数，可以设置电压参考低值和参考高值。
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
优化测量除了可以识别细微的电容变化之外，还可以降低应用程序功耗，但可能会增加测量噪声干扰。如果得到的动态读数范围结果比较理想，则可以调用 :cpp:func:`touch_pad_set_measurement_clock_cycles` 函数来减少测量时间，从而进一步降低功耗。
|
||||
|
||||
.. only:: esp32s2 or esp32s3
|
||||
|
||||
优化测量除了可以识别细微的电容变化之外，还可以降低应用程序功耗，但可能会增加测量噪声干扰。如果得到的动态读数范围结果比较理想，则可以调用 :cpp:func:`touch_pad_set_charge_discharge_times` 函数来减少测量时间，从而进一步降低功耗。
|
||||
|
||||
可用的测量参数及相应的 'set' 函数总结如下：
|
||||
|
||||
* 触摸传感器充放电参数：
|
||||
|
||||
* 电压门限：:cpp:func:`touch_pad_set_voltage`
|
||||
* 速率（斜率）：:cpp:func:`touch_pad_set_cnt_mode`
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
* 单次测量所用的时钟周期：:cpp:func:`touch_pad_set_measurement_clock_cycles`
|
||||
|
||||
.. only:: esp32s2 or esp32s3
|
||||
|
||||
* 单次测量所需充放电次数：:cpp:func:`touch_pad_set_charge_discharge_times`
|
||||
|
||||
电压门限（参考低值/参考高值）、速率（斜率）与测量时间的关系如下图所示：
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
.. figure:: ../../../_static/touch_pad-measurement-parameters.jpg
|
||||
:align: center
|
||||
:alt: Touch Pad - relationship between measurement parameters
|
||||
:figclass: align-center
|
||||
|
||||
触摸传感器 - 测量参数之间的关系
|
||||
|
||||
上图中的 **Output** 代表触摸传感器读值，即一个测量周期内测得的脉冲计数值。
|
||||
|
||||
.. only:: esp32s2 or esp32s3
|
||||
|
||||
.. figure:: ../../../_static/touch_pad-measurement-parameters-version2.png
|
||||
:align: center
|
||||
:alt: Touch Pad - relationship between measurement parameters
|
||||
:figclass: align-center
|
||||
|
||||
触摸传感器 - 测量参数之间的关系
|
||||
|
||||
上图中的 **Output** 代表触摸传感器读值，即固定充放电次数所需的时间。
|
||||
|
||||
所有函数均成对出现，用于设定某一特定参数，并获取当前参数值。例如：:cpp:func:`touch_pad_set_voltage` 和 :cpp:func:`touch_pad_get_voltage`。
|
||||
|
||||
.. _touch_pad-api-filtering-of-measurements:
|
||||
|
||||
滤波采样
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
.. only:: esp32
|
||||
|
||||
如果测量中存在噪声，可以使用提供的 API 函数对采样进行滤波。使用滤波器之前，请先调用 :cpp:func:`touch_pad_filter_start` 启动该滤波器。
|
||||
|
||||
滤波器类型为 IIR（无限脉冲响应滤波器），可以调用 :cpp:func:`touch_pad_set_filter_period` 配置此类滤波器的采样周期。
|
||||
|
||||
如需停止滤波器，请调用 :cpp:func:`touch_pad_filter_stop` 函数。如果不再使用该滤波器，请调用 :cpp:func:`touch_pad_filter_delete` 删除此滤波器。
|
||||
|
||||
.. only:: esp32s2 or esp32s3
|
||||
|
||||
如果测量中存在噪声，可以使用提供的 API 函数对采样进行滤波。{IDF_TARGET_NAME} 的触摸功能提供了两套 API 可实现此功能。
|
||||
|
||||
一个是内部触摸通道，它没有连接到任何外部 GPIO。该降噪板的测量值可用于过滤所有通道上的干扰，如来自电源和外部 EMI 的噪声。
|
||||
|
||||
降噪参数由 :cpp:func:`touch_pad_denoise_set_config` 设置并由 :cpp:func:`touch_pad_denoise_enable` 启动。
|
||||
|
||||
另一是可配置的硬件实现 IIR-滤波器（无限脉冲响应滤波器），该滤波器可通过调用 :cpp:func:`touch_pad_filter_set_config` 函数进行配置，调用 :cpp:func:`touch_pad_filter_enable` 函数启用。
|
||||
|
||||
触摸监测
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
触摸监测基于配置的阈值和 FSM 执行的原始测量，并由 ESP32 硬件实现。可以调用 :cpp:func:`touch_pad_get_status` 查看被触碰的触摸传感器，或调用 :cpp:func:`touch_pad_clear_status` 清除触摸状态信息。
|
||||
|
||||
也可以将硬件触摸监测连接至中断，详细介绍见下一章节。
|
||||
|
||||
如果测量中存在噪声，且电容变化幅度较小，硬件触摸监测结果可能就不太理想。如需解决这一问题，不建议使用硬件监测或中断信号，建议在自己的应用程序中进行采样滤波，并执行触摸监测。
|
||||
|
||||
中断触发
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
在对触摸监测启用中断之前，请先设置一个触摸监测阈值。然后使用 `触摸状态测量`_ 中所述的函数读取并显示触摸和释放触摸传感器时测得的结果。如果测量中存在噪声且相对电容变化较小，请使用滤波器。也可以根据应用程序和环境条件，测试温度和电源电压变化对测量值的影响。
|
||||
|
||||
确定监测阈值后就可以在初始化时调用 :cpp:func:`touch_pad_config` 设置此阈值，或在运行时调用 :cpp:func:`touch_pad_set_thresh` 设置此阈值。
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
下一步就是设置如何触发中断。可以设置在阈值以下或以上触发中断，具体触发模式由函数 :cpp:func:`touch_pad_set_trigger_mode` 设置。
|
||||
|
||||
最后可以使用以下函数配置和管理中断调用：
|
||||
|
||||
* :cpp:func:`touch_pad_isr_register` / :cpp:func:`touch_pad_isr_deregister`
|
||||
* :cpp:func:`touch_pad_intr_enable` / :cpp:func:`touch_pad_intr_disable`
|
||||
|
||||
中断配置完成后，可以调用 :cpp:func:`touch_pad_get_status` 查看中断信号来自哪个触摸传感器，也可以调用 :cpp:func:`touch_pad_clear_status` 清除触摸传感器状态信息。
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
.. note::
|
||||
|
||||
触摸监测中的中断信号基于原始/未经滤波的采样（对比设置的阈值），并在硬件中实现。启用软件滤波 API（请参考 :ref:`touch_pad-api-filtering-of-measurements`）并不会影响这一过程。
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
从睡眠模式唤醒
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
如果使用触摸传感器中断将芯片从睡眠模式唤醒，可以选择配置一些触摸传感器，例如 SET1 或 SET1 和 SET2，触摸这些触摸传感器将触发中断并唤醒芯片。请调用 :cpp:func:`touch_pad_set_trigger_source` 实现上述操作。
|
||||
|
||||
可以使用以下函数管理 'SET' 中触摸传感器所需的位模式配置：
|
||||
|
||||
* :cpp:func:`touch_pad_set_group_mask` / :cpp:func:`touch_pad_get_group_mask`
|
||||
* :cpp:func:`touch_pad_clear_group_mask`
|
||||
|
||||
.. _touch_pad-api-examples:
|
||||
|
||||
应用示例
|
||||
--------
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
- :example:`peripherals/touch_sensor/touch_sensor_v1/touch_pad_read` 演示了如何在 {IDF_TARGET_NAME} 上读取并打印电容触摸传感器的原始值或 IIR 滤波后的值，以及如何校准传感器。
|
||||
- :example:`peripherals/touch_sensor/touch_sensor_v1/touch_pad_interrupt` 演示了如何设置 {IDF_TARGET_NAME} 的电容触摸板，使其在被触摸时触发中断，以及如何使用软件监测来提高灵敏度，并比较硬件中断模式和软件轮询模式的性能。
|
||||
|
||||
.. only:: esp32s2 or esp32s3
|
||||
|
||||
.. warning::
|
||||
|
||||
使用老驱动的例程已移除，新驱动用法请参考 :example:`peripherals/touch_sensor/touch_sens_basic`。
|
||||
|
||||
.. _touch_pad-api-reference:
|
||||
|
||||
API 参考
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/touch_sensor.inc
|
||||
.. include-build-file:: inc/touch_sensor_common.inc
|
||||
|
||||
GPIO 宏查找表
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
可以使用宏定义某一触摸传感器通道的 GPIO，或定义某一 GPIO 的通道。例如：
|
||||
|
||||
1. ``TOUCH_PAD_NUM5_GPIO_NUM`` 定义了通道 5 的 GPIO（即 GPIO 12）；
|
||||
2. ``TOUCH_PAD_GPIO4_CHANNEL`` 定义了 GPIO 4 的通道（即通道 0）。
|
||||
|
||||
.. include-build-file:: inc/touch_sensor_channel.inc
|
||||
.. include-build-file:: inc/touch_sensor_legacy_types.inc
|
||||
Reference in New Issue
Block a user