eaw/esp-idf
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'feature/touch_sensor_driver_support_for_esp32s3' into 'master'

Browse Source 
driver(touch): support touch sensor for esp32s3 platform

Closes IDF-1784 and IDF-3302

See merge request espressif/esp-idf!14102
This commit is contained in:
Kevin (Lao Kaiyao)
2021-10-12 05:50:58 +00:00
parent 917d6e17b4 f4705f8eb4
commit a9faafee3c
82 changed files with 1237 additions and 577 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
docs/en/api-reference/peripherals/touch_pad.rst
View File

@@ -2,26 +2,28 @@ Touch Sensor
============
:link_to_translation:`zh_CN:[中文]`
{IDF_TARGET_TOUCH_SENSOR_VERSION:default="v2", esp32="v1"}
Introduction
------------
A touch sensor system is built on a substrate which carries electrodes and relevant connections under a protective flat surface. When a user touches the surface, the capacitance variation is used to evaluate if the touch was valid.
.. only:: esp32
.. only:: SOC_TOUCH_VERSION_1
ESP32 can handle up to 10 capacitive touch pads / GPIOs.
Touch sensor on {IDF_TARGET_NAME} can support up to 10 capacitive touch pads / GPIOs.
.. only:: esp32s2
.. only:: SOC_TOUCH_VERSION_2
{IDF_TARGET_NAME} can handle up to 14 capacitive touch pads / GPIOs.
Touch sensor on {IDF_TARGET_NAME} can support up to 14 capacitive touch pads / GPIOs.
The sensing pads can be arranged in different combinations (e.g., matrix, slider), so that a larger area or more points can be detected. The touch pad sensing process is under the control of a hardware-implemented finite-state machine (FSM) which is initiated by software or a dedicated hardware timer.
The sensing pads can be arranged in different combinations (e.g., matrix, slider), so that a larger area or more points can be detected. The touch pad sensing process is under the control of a hardware-implemented finite-state machine (FSM) which is initiated by software or a dedicated hardware timer.
For design, operation, and control registers of a touch sensor, see *{IDF_TARGET_NAME} Technical Reference Manual* > *On-Chip Sensors and Analog Signal Processing* [`PDF <{IDF_TARGET_TRM_EN_URL}#sensor>`__].
In-depth design details of touch sensors and firmware development guidelines for {IDF_TARGET_NAME} are available in `Touch Sensor Application Note <https://github.com/espressif/esp-iot-solution/blob/release/v1.0/documents/touch_pad_solution/touch_sensor_design_en.md>`_.
.. only:: esp32
.. only:: SOC_TOUCH_VERSION_1
For more information about testing touch sensors in various configurations, please check the `Guide for ESP32-Sense-Kit <https://github.com/espressif/esp-dev-kits/blob/master/esp32-sense-kit/docs/esp32_sense_kit_guide_en.md>`_.
@@ -59,7 +61,7 @@ Use the function :cpp:func:`touch_pad_set_fsm_mode` to select if touch pad measu
Touch State Measurements
^^^^^^^^^^^^^^^^^^^^^^^^
.. only:: esp32
.. only:: SOC_TOUCH_VERSION_1
The following two functions come in handy to read raw or filtered measurements from the sensor:
@@ -72,7 +74,7 @@ Touch State Measurements
Before using :cpp:func:`touch_pad_read_filtered`, you need to initialize and configure the filter by calling specific filter functions described in Section `Filtering of Measurements`_.
.. only:: esp32s2
.. only:: SOC_TOUCH_VERSION_2
The following function come in handy to read raw measurements from the sensor:
@@ -80,7 +82,7 @@ Touch State Measurements
It can also be used, for example, to evaluate a particular touch pad design by checking the range of sensor readings when a pad is touched or released. This information can be then used to establish a touch threshold.
For the demonstration of how to read the touch pad data, check the application example :example:`peripherals/touch_pad_read`.
For the demonstration of how to read the touch pad data, check the application example :example:`peripherals/touch_sensor/touch_sensor_{IDF_TARGET_TOUCH_SENSOR_VERSION}/touch_pad_read`.
Optimization of Measurements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -115,7 +117,7 @@ All functions are provided in pairs to *set* a specific parameter and to *get* t
Filtering of Measurements
^^^^^^^^^^^^^^^^^^^^^^^^^
.. only:: esp32
.. only:: SOC_TOUCH_VERSION_1
If measurements are noisy, you can filter them with provided API functions. Before using the filter, please start it by calling :cpp:func:`touch_pad_filter_start`.
@@ -123,7 +125,7 @@ Filtering of Measurements
You can stop the filter with :cpp:func:`touch_pad_filter_stop`. If not required anymore, the filter can be deleted by invoking :cpp:func:`touch_pad_filter_delete`.
.. only:: esp32s2
.. only:: SOC_TOUCH_VERSION_2
If measurements are noisy, you can filter them with provided API functions. The {IDF_TARGET_NAME}'s touch functionality provide two sets of APIs for doing this.
@@ -139,7 +141,7 @@ Touch detection is implemented in ESP32's hardware based on the user-configured
Hardware touch detection can also be wired to interrupts. This is described in the next section.
If measurements are noisy and capacity changes are small, hardware touch detection might be unreliable. To resolve this issue, instead of using hardware detection / provided interrupts, implement measurement filtering and perform touch detection in your own application. For sample implementation of both methods of touch detection, see :example:`peripherals/touch_pad_interrupt`.
If measurements are noisy and capacity changes are small, hardware touch detection might be unreliable. To resolve this issue, instead of using hardware detection / provided interrupts, implement measurement filtering and perform touch detection in your own application. For sample implementation of both methods of touch detection, see :example:`peripherals/touch_sensor/touch_sensor_{IDF_TARGET_TOUCH_SENSOR_VERSION}/touch_pad_interrupt`.
Touch Triggered Interrupts
^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -148,7 +150,7 @@ Before enabling an interrupt on a touch detection, you should establish a touch
Once a detection threshold is established, it can be set during initialization with :cpp:func:`touch_pad_config` or at the runtime with :cpp:func:`touch_pad_set_thresh`.
.. only:: esp32
.. only:: SOC_TOUCH_VERSION_1
In the next step, configure how interrupts are triggered. They can be triggered below or above the threshold, which is set with the function :cpp:func:`touch_pad_set_trigger_mode`.
@@ -159,13 +161,13 @@ Finally, configure and manage interrupt calls using the following functions:
When interrupts are operational, you can obtain the information from which particular pad an interrupt came by invoking :cpp:func:`touch_pad_get_status` and clear the pad status with :cpp:func:`touch_pad_clear_status`.
.. only:: esp32
.. only:: SOC_TOUCH_VERSION_1
.. note::
Interrupts on touch detection operate on raw / unfiltered measurements checked against user established threshold and are implemented in hardware. Enabling the software filtering API (see :ref:`touch_pad-api-filtering-of-measurements`) does not affect this process.
.. only:: esp32
.. only:: SOC_TOUCH_VERSION_1
Wakeup from Sleep Mode
^^^^^^^^^^^^^^^^^^^^^^
@@ -182,8 +184,8 @@ When interrupts are operational, you can obtain the information from which parti
Application Examples
--------------------
- Touch sensor read example: :example:`peripherals/touch_pad_read`.
- Touch sensor interrupt example: :example:`peripherals/touch_pad_interrupt`.
- Touch sensor read example: :example:`peripherals/touch_sensor/touch_sensor_{IDF_TARGET_TOUCH_SENSOR_VERSION}/touch_pad_read`.
- Touch sensor interrupt example: :example:`peripherals/touch_sensor/touch_sensor_{IDF_TARGET_TOUCH_SENSOR_VERSION}/touch_pad_interrupt`.
.. _touch_pad-api-reference:

2
docs/en/api-reference/system/sleep_modes.rst
View File

@@ -58,7 +58,7 @@ This wakeup mode doesn't require RTC peripherals or RTC memories to be powered o
:cpp:func:`esp_sleep_enable_timer_wakeup` function can be used to enable deep sleep wakeup using a timer.
.. only:: SOC_TOUCH_PAD_WAKE_SUPPORTED
.. only:: SOC_PM_SUPPORT_TOUCH_SENSOR_WAKEUP
Touch pad
^^^^^^^^^