mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
docs: provide CN translation for api-reference/peripherals/touch_element.rst (backport v5.1)
This commit is contained in:
Cai Xin Ying
Krzysztof Budzynski
parent
1b87f35f0f
commit
b93ffc1cb4
@ -1,21 +1,23 @@
|
||||
Touch Element
|
||||
=============
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
Touch Element library provides a high level abstraction for building capacitive touch applications. The library's implementation gives a unified and friendly software interface thus allows for smooth and easy capacitive touch application development. The library is implemented atop the touch sensor driver (please see :doc:`Touch sensor driver API Reference <../peripherals/touch_pad>` for more information regarding low level API usage).
|
||||
The Touch Element Library is a highly abstracted element library designed on the basis of the touch sensor driver. The library provides a unified and user-friendly software interface to quickly build capacitive touch sensor applications. For more information about the touch sensor driver API, see :doc:`../peripherals/touch_pad`.
|
||||
|
||||
Architecture
|
||||
^^^^^^^^^^^^
|
||||
|
||||
Touch Element library configures touch sensor peripherals via touch sensor driver. While some necessary hardware parameters should be passed to :cpp:func:`touch_element_install` and will be configured automatically only after calling :cpp:func:`touch_element_start`, because it will make great influence on the run-time system.
|
||||
The Touch Element library configures touch sensor peripherals via the touch sensor driver. However, some necessary hardware parameters should be passed to :cpp:func:`touch_element_install` and will be configured automatically only after calling :cpp:func:`touch_element_start`. This sequential order is essential because configuring these parameters has a significant impact on the run-time system. Therefore, they must be configured after calling the start function to ensure the system functions properly.
|
||||
|
||||
These parameters include touch channel threshold, waterproof shield sensor driver-level and etc. Touch Element library sets touch sensor interrupt and esp-timer routine up and the hardware information of touch sensor (channel state, channel number) will be obtained in touch sensor interrupt service routine. When the specified channel event occurs, and those hardware information will be passed to the esp-timer callback routine, esp-timer callback routine will dispatch the touch sensor channel information to the touch elements(such as button, slider etc). Then runs the specified algorithm to update touch element's state or calculate its position, dispatch the result to user.
|
||||
These parameters include touch channel threshold, driver-level of waterproof shield sensor, etc. The Touch Element library sets the touch sensor interrupt and the esp_timer routine up, and the hardware information of the touch sensor (channel state, channel number) will be obtained in the touch sensor interrupt service routine. When the specified channel event occurs, the hardware information is passed to the esp_timer callback routine, which then dispatches the touch sensor channel information to the touch elements (such as button, slider, etc.). The library then runs a specified algorithm to update the touch element's state or calculate its position and dispatches the result accordingly.
|
||||
|
||||
So using Touch Element library, user doesn't need to care about the implementation of touch sensor peripheral, Touch Element library will handle most of the hardware information and pass the more meaningful messages to user event handler routine.
|
||||
So when using the Touch Element library, you are relieved from the implementation details of the touch sensor peripheral. The library handles most of the hardware information and passes the more meaningful messages to the event handler routine.
|
||||
|
||||
Workflow of Touch Element library is illustrated in the picture below.
|
||||
The workflow of the Touch Element library is illustrated in the picture below.
|
||||
|
||||
.. figure:: /../_static/touch_element/te_architecture.svg
|
||||
:scale: 100 %
|
||||
@ -26,17 +28,21 @@ Workflow of Touch Element library is illustrated in the picture below.
|
||||
|
||||
The features in relation to the Touch Element library in {IDF_TARGET_NAME} are given in the table below.
|
||||
|
||||
+--------------------------------------------------------------+---------------------+
|
||||
| Features | ESP32S2 |
|
||||
+==============================================================+=====================+
|
||||
| Touch Element waterproof | ✔ |
|
||||
+--------------------------------------------------------------+---------------------+
|
||||
| Touch Element button | ✔ |
|
||||
+--------------------------------------------------------------+---------------------+
|
||||
| Touch Element slider | ✔ |
|
||||
+--------------------------------------------------------------+---------------------+
|
||||
| Touch Element matrix button | ✔ |
|
||||
+--------------------------------------------------------------+---------------------+
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 70 30
|
||||
:align: center
|
||||
|
||||
* - Features
|
||||
- ESP32S2
|
||||
* - Touch Element waterproof
|
||||
- ✔
|
||||
* - Touch Element button
|
||||
- ✔
|
||||
* - Touch Element slider
|
||||
- ✔
|
||||
* - Touch Element matrix button
|
||||
- ✔
|
||||
|
||||
|
||||
Peripheral
|
||||
@ -44,68 +50,128 @@ Peripheral
|
||||
|
||||
{IDF_TARGET_NAME} integrates one touch sensor peripheral with several physical channels.
|
||||
|
||||
.. only:: esp32s2
|
||||
.. only:: esp32s2 or esp32s3
|
||||
|
||||
- 14 physical capacitive touch channels
|
||||
- Timer or software FSM trigger mode
|
||||
- Up to 5 kinds of interrupt(Upper threshold and lower threshold interrupt, measure one channel finish and measure all channels finish interrupt, measurement timeout interrupt)
|
||||
- Up to 5 kinds of interrupt (Upper threshold and lower threshold interrupt, measure one channel finish and measure all channels finish interrupt, measurement timeout interrupt)
|
||||
- Sleep mode wakeup source
|
||||
- Hardware internal de-noise
|
||||
- Hardware filter
|
||||
- Hardware waterproof sensor
|
||||
- Hardware proximity sensor
|
||||
|
||||
The channels are located as follows:
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 50 50
|
||||
:align: center
|
||||
|
||||
* - Channel
|
||||
- {IDF_TARGET_NAME}
|
||||
* - **Channel 0**
|
||||
- **GPIO 0 (reserved)**
|
||||
* - **Channel 1**
|
||||
- **GPIO 1**
|
||||
* - **Channel 2**
|
||||
- **GPIO 2**
|
||||
* - **Channel 3**
|
||||
- **GPIO 3**
|
||||
* - **Channel 4**
|
||||
- **GPIO 4**
|
||||
* - **Channel 5**
|
||||
- **GPIO 5**
|
||||
* - **Channel 6**
|
||||
- **GPIO 6**
|
||||
* - **Channel 7**
|
||||
- **GPIO 7**
|
||||
* - **Channel 8**
|
||||
- **GPIO 8**
|
||||
* - **Channel 9**
|
||||
- **GPIO 9**
|
||||
* - **Channel 10**
|
||||
- **GPIO 10**
|
||||
* - **Channel 11**
|
||||
- **GPIO 11**
|
||||
* - **Channel 12**
|
||||
- **GPIO 12**
|
||||
* - **Channel 13**
|
||||
- **GPIO 13**
|
||||
* - **Channel 14**
|
||||
- **GPIO 14**
|
||||
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
- 10 physical capacitive touch channels
|
||||
- Timer or software FSM trigger mode
|
||||
- 2 kinds of interrupt(Greater than threshold and less than threshold)
|
||||
- 2 kinds of interrupt (Greater than the threshold and less than the threshold)
|
||||
- Sleep mode wakeup source
|
||||
|
||||
|
||||
The channels are located as follows:
|
||||
|
||||
======================= =======================
|
||||
Channel {IDF_TARGET_NAME}
|
||||
======================= =======================
|
||||
**Channel 0** **GPIO 0 (reserved)**
|
||||
**Channel 1** **GPIO 1**
|
||||
**Channel 2** **GPIO 2**
|
||||
**Channel 3** **GPIO 3**
|
||||
**Channel 4** **GPIO 4**
|
||||
**Channel 5** **GPIO 5**
|
||||
**Channel 6** **GPIO 6**
|
||||
**Channel 7** **GPIO 7**
|
||||
**Channel 8** **GPIO 8**
|
||||
**Channel 9** **GPIO 9**
|
||||
**Channel 10** **GPIO 10**
|
||||
**Channel 11** **GPIO 11**
|
||||
**Channel 12** **GPIO 12**
|
||||
**Channel 13** **GPIO 13**
|
||||
**Channel 14** **GPIO 14**
|
||||
======================= =======================
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 50 50
|
||||
:align: center
|
||||
|
||||
* - Channel
|
||||
- {IDF_TARGET_NAME}
|
||||
* - **Channel 0**
|
||||
- **GPIO 0 (effective)**
|
||||
* - **Channel 1**
|
||||
- **GPIO 1**
|
||||
* - **Channel 2**
|
||||
- **GPIO 2**
|
||||
* - **Channel 3**
|
||||
- **GPIO 3**
|
||||
* - **Channel 4**
|
||||
- **GPIO 4**
|
||||
* - **Channel 5**
|
||||
- **GPIO 5**
|
||||
* - **Channel 6**
|
||||
- **GPIO 6**
|
||||
* - **Channel 7**
|
||||
- **GPIO 7**
|
||||
* - **Channel 8**
|
||||
- **GPIO 8**
|
||||
* - **Channel 9**
|
||||
- **GPIO 9**
|
||||
|
||||
|
||||
Terminology
|
||||
-----------
|
||||
|
||||
The terms used in relation to the Touch Element library are given in the below.
|
||||
The terms used in relation to the Touch Element library are given below.
|
||||
|
||||
======================= =========================================================================================
|
||||
Term Definition
|
||||
======================= =========================================================================================
|
||||
**Touch sensor** Touch sensor peripheral inside the chip
|
||||
**Touch channel** Touch sensor channels inside the touch sensor peripheral
|
||||
**Touch pad** Off-chip physical solder pad (Generally inside the PCB)
|
||||
**De-noise channel** Internal de-noise channel (Is always Channel 0 and it is reserved)
|
||||
**Shield sensor** One of the waterproof sensor, use for compensating the influence of water drop
|
||||
**Guard sensor** One of the waterproof sensor, use for detecting the water stream
|
||||
**Shield channel** The channel that waterproof shield sensor connected to (Is always Channel 14)
|
||||
**Guard channel** The channel that waterproof guard sensor connected to
|
||||
**Shield pad** Off-chip physical solder pad (Generally is grids) and is connected to shield sensor
|
||||
**Guard pad** Off-chip physical solder pad (Is usually a ring) and is connected to guard sensor
|
||||
======================= =========================================================================================
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 50 50
|
||||
:align: center
|
||||
|
||||
* - Term
|
||||
- Definition
|
||||
* - **Touch sensor**
|
||||
- Touch sensor peripheral inside the chip
|
||||
* - **Touch channel**
|
||||
- Touch sensor channels inside the touch sensor peripheral
|
||||
* - **Touch pad**
|
||||
- Off-chip physical solder pad, generally inside the PCB
|
||||
* - **De-noise channel**
|
||||
- Internal de-noise channel, which is always Channel 0 and is reserved
|
||||
* - **Shield sensor**
|
||||
- One of the waterproof sensors for detecting droplets in small areas and compensating for the influence of water drops on measurements
|
||||
* - **Guard sensor**
|
||||
- One of the waterproof sensors for detecting extensive wading and to temporarily disable the touch sensor
|
||||
* - **Shield channel**
|
||||
- The channel that waterproof shield sensor connected to, which is always Channel 14
|
||||
* - **Guard channel**
|
||||
- The channel that waterproof guard sensor connected to
|
||||
* - **Shield pad**
|
||||
- Off-chip physical solder pad, generally is grids, and is connected to shield the sensor
|
||||
* - **Guard pad**
|
||||
- Off-chip physical solder pad, usually a ring, and is connected to the guard sensor
|
||||
|
||||
.. figure:: /../_static/touch_element/te_component.svg
|
||||
:scale: 100 %
|
||||
@ -117,10 +183,10 @@ The terms used in relation to the Touch Element library are given in the below.
|
||||
Touch Sensor Signal
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Each touch senor is able to provide the following types of signals:
|
||||
Each touch sensor is able to provide the following types of signals:
|
||||
|
||||
- Raw: The Raw signal is the unfiltered signal from the touch sensor
|
||||
- Smooth: The Smooth signal is a filtered version of the Raw signal via an internal hardware filter
|
||||
- Raw: The Raw signal is the unfiltered signal from the touch sensor.
|
||||
- Smooth: The Smooth signal is a filtered version of the Raw signal via an internal hardware filter.
|
||||
- Benchmark: The Benchmark signal is also a filtered signal that filters out extremely low-frequency noise.
|
||||
|
||||
All of these signals can be obtained using touch sensor driver API.
|
||||
@ -132,10 +198,10 @@ All of these signals can be obtained using touch sensor driver API.
|
||||
Touch sensor signals
|
||||
|
||||
|
||||
Touch Sensor Threshold
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
Touch Sensor Signal Threshold
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The Touch Sensor Threshold value is a configurable threshold value used to determine when a touch sensor is touched or not. When difference between the Smooth signal and the Benchmark signal becomes greater than the threshold value (i.e., ``(smooth - benchmark) > threshold``), the touch channel's state will be changed and a touch interrupt will be triggered simultaneously.
|
||||
The Touch Sensor Threshold value is a configurable threshold value used to determine when a touch sensor is touched or not. When the difference between the Smooth signal and the Benchmark signal becomes greater than the threshold value (i.e., ``(smooth - benchmark) > threshold``), the touch channel's state will be changed and a touch interrupt will be triggered simultaneously.
|
||||
|
||||
.. figure:: /../_static/touch_element/te_threshold.svg
|
||||
:scale: 40 %
|
||||
@ -147,7 +213,7 @@ The Touch Sensor Threshold value is a configurable threshold value used to deter
|
||||
Sensitivity
|
||||
^^^^^^^^^^^
|
||||
|
||||
Important performance parameter of touch sensor, the larger it is, the better touch sensor will perform. It could be calculated by the format in below:
|
||||
Important performance parameter of the touch sensor, the larger it is, the better touch the sensor performs. It could be calculated by the format below:
|
||||
|
||||
.. math::
|
||||
|
||||
@ -157,13 +223,13 @@ Important performance parameter of touch sensor, the larger it is, the better to
|
||||
Waterproof
|
||||
^^^^^^^^^^
|
||||
|
||||
Waterproof is a hardware feature of touch sensor which has guard sensor and shield sensor (Always connect to Channel 14) that has the ability to resist a degree influence of water drop and detect the water stream.
|
||||
Waterproof is the hardware feature of a touch sensor which has a guard sensor and shield sensor (always connect to Channel 14) that has the ability to resist a degree of influence of water drop and detect the water stream.
|
||||
|
||||
|
||||
Touch Button
|
||||
^^^^^^^^^^^^
|
||||
|
||||
Touch button consumes one channel of touch sensor, and it looks like as the picture below:
|
||||
The touch button consumes one channel of the touch sensor, and it looks like as the picture below:
|
||||
|
||||
|
||||
.. figure:: /../_static/touch_element/te_button.svg
|
||||
@ -176,7 +242,7 @@ Touch button consumes one channel of touch sensor, and it looks like as the pict
|
||||
Touch Slider
|
||||
^^^^^^^^^^^^
|
||||
|
||||
Touch slider consumes several channels(at least three channels) of touch sensor, the more channels consumed, the higher resolution and accuracy position it will perform. Touch slider looks like as the picture below:
|
||||
The touch slider consumes several channels (at least three channels) of the touch sensor, the more channels consumed, the higher resolution and accuracy position it performs. The touch slider looks like as the picture below:
|
||||
|
||||
.. figure:: /../_static/touch_element/te_slider.svg
|
||||
:scale: 100 %
|
||||
@ -188,7 +254,7 @@ Touch slider consumes several channels(at least three channels) of touch sensor,
|
||||
Touch Matrix
|
||||
^^^^^^^^^^^^
|
||||
|
||||
Touch matrix button consumes several channels(at least 2 + 2 = 4 channels), it gives a solution to use fewer channels and get more buttons. {IDF_TARGET_NAME} supports up to 49 buttons. Touch matrix button looks like as the picture below:
|
||||
The touch matrix button consumes several channels (at least 2 + 2 = 4 channels), and it gives a solution to use fewer channels and get more buttons. {IDF_TARGET_NAME} supports up to 49 buttons. The touch matrix button looks like as the picture below:
|
||||
|
||||
.. figure:: /../_static/touch_element/te_matrix.svg
|
||||
:scale: 100 %
|
||||
@ -202,15 +268,15 @@ Touch Element Library Usage
|
||||
|
||||
Using this library should follow the initialization flow below:
|
||||
|
||||
1. To initialize Touch Element library by calling :cpp:func:`touch_element_install`
|
||||
2. To initialize touch elements(button/slider etc) by calling :cpp:func:`touch_xxxx_install`
|
||||
3. To create a new element instance by calling :cpp:func:`touch_xxxx_create`
|
||||
4. To subscribe events by calling :cpp:func:`touch_xxxx_subscribe_event`
|
||||
5. To choose a dispatch method by calling :cpp:func:`touch_xxxx_set_dispatch_method` that tells the library how to notify you while the subscribed event occur
|
||||
6. (If dispatch by callback) Call :cpp:func:`touch_xxxx_set_callback` to set the event handler function.
|
||||
7. To start Touch Element library by calling :cpp:func:`touch_element_start`
|
||||
8. (If dispatch by callback) The callback will be called by the driver core when event happen, no need to do anything; (If dispatch by event task) create an event task and call :cpp:func:`touch_element_message_receive` to obtain messages in a loop.
|
||||
9. [Optional] If user wants to suspend the Touch Element run-time system or for some reason that could not obtain the touch element message, :cpp:func:`touch_element_stop` should be called to suspend the Touch Element system and then resume it by calling :cpp:func:`touch_element_start` again.
|
||||
1. To initialize the Touch Element library by calling :cpp:func:`touch_element_install`.
|
||||
2. To initialize touch elements (button/slider etc) by calling :cpp:func:`touch_xxxx_install`.
|
||||
3. To create a new element instance by calling :cpp:func:`touch_xxxx_create`.
|
||||
4. To subscribe events by calling :cpp:func:`touch_xxxx_subscribe_event`.
|
||||
5. To choose a dispatch method by calling :cpp:func:`touch_xxxx_set_dispatch_method` that tells the library how to notify you while the subscribed event occurs.
|
||||
6. If dispatch by callback, call :cpp:func:`touch_xxxx_set_callback` to set the event handler function.
|
||||
7. To start the Touch Element library by calling :cpp:func:`touch_element_start`.
|
||||
8. If dispatch by callback, the callback will be called by the driver core when an event happens, no need to do anything; If dispatch by event task, create an event task and call :cpp:func:`touch_element_message_receive` to obtain messages in a loop.
|
||||
9. (Optional) If you want to suspend the Touch Element run-time system or for some reason that could not obtain the touch element message, :cpp:func:`touch_element_stop` should be called to suspend the Touch Element system and then resume it by calling :cpp:func:`touch_element_start` again.
|
||||
|
||||
In code, the flow above may look like as follows:
|
||||
|
||||
@ -258,28 +324,28 @@ In code, the flow above may look like as follows:
|
||||
Initialization
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
1. To initialize Touch Element library, user has to configure touch sensor peripheral and Touch Element library by calling :cpp:func:`touch_element_install` with :cpp:type:`touch_elem_global_config_t`, the default initializer is available in :cpp:func:`TOUCH_ELEM_GLOBAL_DEFAULT_CONFIG` and this default configuration is suitable for the most general application scene, and users are suggested not to change the default configuration before fully understanding Touch Sensor peripheral, because some changes might bring several impacts to the system.
|
||||
1. To initialize the Touch Element library, you have to configure the touch sensor peripheral and Touch Element library by calling :cpp:func:`touch_element_install` with :cpp:type:`touch_elem_global_config_t`, the default initializer is available in :cpp:func:`TOUCH_ELEM_GLOBAL_DEFAULT_CONFIG` and this default configuration is suitable for the most general application scene, and it is suggested not to change the default configuration before fully understanding Touch Sensor peripheral because some changes might bring several impacts to the system.
|
||||
|
||||
2. To initialize the specified element, all the elements will not work before its constructor (:cpp:func:`touch_xxxx_install`) is called so as to save memory, so user has to call the constructor of each used touch element respectively, to set up the specified element.
|
||||
2. To initialize the specified element, all the elements will not work before its constructor :cpp:func:`touch_xxxx_install` is called so as to save memory, so you have to call the constructor of each used touch element respectively, to set up the specified element.
|
||||
|
||||
|
||||
Touch Element Instance Startup
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
1. To create a new touch element instance by calling :cpp:func:`touch_xxxx_create`, selects channel and passes its `Sensitivity`_ for the new element instance.
|
||||
1. To create a new touch element instance, call :cpp:func:`touch_xxxx_create`, select a channel, and provide its `Sensitivity`_ value for the new element instance.
|
||||
|
||||
2. To subscribe events by calling :cpp:func:`touch_xxxx_subscribe_event`, there several events in Touch Element library and the event mask is available on :idf_file:`components/touch_element/include/touch_element/touch_element.h`, user could use those events mask to subscribe specified event or combine them to subscribe multiple events.
|
||||
2. To subscribe to events, call :cpp:func:`touch_xxxx_subscribe_event`. The Touch Element library offers several events, and the event mask is available in :idf_file:`components/touch_element/include/touch_element/touch_element.h`. You can use these event masks to subscribe to specific events individually or combine them to subscribe to multiple events.
|
||||
|
||||
3. To configure dispatch method by calling :cpp:func:`touch_xxxx_subscribe_event`, there are two dispatch methods in Touch Element library, one is :cpp:enumerator:`TOUCH_ELEM_DISP_EVENT`, the other one is :cpp:enumerator:`TOUCH_ELEM_DISP_CALLBACK`, it means that user could use two methods to obtain the touch element message and handle it.
|
||||
3. To configure the dispatch method, use :cpp:func:`touch_xxxx_set_dispatch_method`. The Touch Element library provides two dispatch methods: :cpp:enumerator:`TOUCH_ELEM_DISP_EVENT` and :cpp:enumerator:`TOUCH_ELEM_DISP_CALLBACK`. These methods allow you to obtain the touch element message and handle it using different approaches.
|
||||
|
||||
Events Processing
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
If :cpp:enumerator:`TOUCH_ELEM_DISP_EVENT` dispatch method is configured, user need to startup an event handler task to obtain the touch element message, all the elements raw message could be obtained by calling :cpp:func:`touch_element_message_receive`, then extract the element-class-specific message by calling the corresponding message decoder (:cpp:func:`touch_xxxx_get_message`) to get the touch element's extracted message; If :cpp:enumerator:`TOUCH_ELEM_DISP_CALLBACK` dispatch method is configured, user need to pass an event handler by calling :cpp:func:`touch_xxxx_set_callback` before the touch elem starts working, all the element's extracted message will be passed to the event handler function.
|
||||
If :cpp:enumerator:`TOUCH_ELEM_DISP_EVENT` dispatch method is configured, you need to start up an event handler task to obtain the touch element message, all the elements' raw message could be obtained by calling :cpp:func:`touch_element_message_receive`, then extract the element-class-specific message by calling the corresponding message decoder with :cpp:func:`touch_xxxx_get_message` to get the touch element's extracted message; If :cpp:enumerator:`TOUCH_ELEM_DISP_CALLBACK` dispatch method is configured, you need to pass an event handler by calling :cpp:func:`touch_xxxx_set_callback` before the touch element starts working, all the element's extracted message will be passed to the event handler function.
|
||||
|
||||
.. warning::
|
||||
Since the event handler function runs on the library driver core(The context located in esp-timer callback routine), user
|
||||
should not do something that attempts to block or delay, such as call :cpp:func:`vTaskDelay`.
|
||||
|
||||
Since the event handler function runs on the core of the element library, i.e., in the esp_timer callback routine, please avoid performing operations that may cause blocking or delays, such as calling :cpp:func:`vTaskDelay`.
|
||||
|
||||
|
||||
In code, the events handle procedure may look like as follows:
|
||||
@ -330,13 +396,13 @@ In code, the events handle procedure may look like as follows:
|
||||
Waterproof Usage
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
1. To initialize Touch Element waterproof, the waterproof shield sensor is always-on after Touch Element waterproof is initialized, however the waterproof guard sensor is optional, hence if user doesn't need the guard sensor, `TOUCH_WATERPROOF_GUARD_NOUSE` has to be passed to :cpp:func:`touch_element_waterproof_install` by the configuration struct.
|
||||
1. The waterproof shield sensor is always-on after Touch Element waterproof is initialized, however, the waterproof guard sensor is optional, hence if the you do not need the guard sensor, ``TOUCH_WATERPROOF_GUARD_NOUSE`` has to be passed to :cpp:func:`touch_element_waterproof_install` by the configuration struct.
|
||||
|
||||
2. To associate the touch element with the guard sensor, pass the touch element's handle to the Touch Element waterproof's masked list by calling :cpp:func:`touch_element_waterproof_add`. By associating a touch element with the Guard sensor, the touch element will be disabled when the guard sensor is triggered by a stream of water so as to protect the touch element.
|
||||
|
||||
The Touch Element Waterproof example is available in `peripherals/touch_element/touch_element_waterproof` directory.
|
||||
The Touch Element Waterproof example is available in :example:`peripherals/touch_sensor/touch_element/touch_element_waterproof` directory.
|
||||
|
||||
In code, the waterproof configuration may look like as follows:
|
||||
In code, the waterproof configuration may look as follows:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
@ -350,19 +416,19 @@ In code, the waterproof configuration may look like as follows:
|
||||
...
|
||||
|
||||
touch_element_waterproof_install(); //Initialize Touch Element waterproof
|
||||
touch_element_waterproof_add(element_handle); //Let a element associates with guard sensor
|
||||
touch_element_waterproof_add(element_handle); //Let an element associate with the guard sensor
|
||||
|
||||
...
|
||||
}
|
||||
|
||||
Wakeup from Light/Deep Sleep
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Wakeup from Light/Deep-sleep Mode
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Only Touch Button can be configured as wake up source.
|
||||
Only Touch Button can be configured as a wake-up source.
|
||||
|
||||
Light or deep sleep are both supported to be waken up by touch sensor. For the light sleep, any installed touch button can wake it up. But only the sleep button can wake up from deep sleep, and the touch sensor will do a calibration immediately, the reference value will be calibrated to a wrong value if our finger doesn't remove timely. Though the wrong reference value will recover after the finger remove away and have no affect to the driver logic, if you don't want to see a wrong reference value while waking up from deep sleep, you can call :cpp:func:`touch_element_sleep_enable_wakeup_calibration` to disable the wakeup calibration.
|
||||
Light- or Deep-sleep modes are both supported to be wakened up by a touch sensor. For the Light-sleep mode, any installed touch button can wake it up. But only the sleep button can wake up from Deep-sleep mode, and the touch sensor will do a calibration immediately, the reference value will be calibrated to a wrong value if our finger does not remove timely. Though the wrong reference value recovers after the finger removes away and has no effect on the driver logic, if you do not want to see a wrong reference value while waking up from Deep-sleep mode, you can call :cpp:func:`touch_element_sleep_enable_wakeup_calibration` to disable the wakeup calibration.
|
||||
|
||||
The Touch Element Wakeup example is available in `example/system/light_sleep` directory.
|
||||
The Touch Element Wakeup example is available in `system/light_sleep` directory.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
@ -377,7 +443,7 @@ The Touch Element Wakeup example is available in `example/system/light_sleep` di
|
||||
|
||||
// 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)); // (optional) Disable wakeup calibration to prevent updating the base line to a wrong value
|
||||
// ESP_ERROR_CHECK(touch_element_sleep_enable_wakeup_calibration(button_handle[0], false)); // (optional) Disable wakeup calibration to prevent updating the baseline to a wrong value
|
||||
|
||||
touch_element_start();
|
||||
|
||||
@ -386,10 +452,11 @@ The Touch Element Wakeup example is available in `example/system/light_sleep` di
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
All the Touch Element library examples could be found in the `peripherals/touch_element` directory of ESP-IDF examples.
|
||||
|
||||
All the Touch Element library examples could be found in the :example:`peripherals/touch_sensor/touch_element` directory of ESP-IDF examples.
|
||||
|
||||
|
||||
API Reference - Touch Element core
|
||||
API Reference - Touch Element Core
|
||||
----------------------------------
|
||||
|
||||
.. include-build-file:: inc/touch_element.inc
|
||||
|
||||
@ -1 +1,480 @@
|
||||
.. include:: ../../../en/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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user