mirror of
https://github.com/espressif/esp-idf
synced 2025-03-09 17:19:09 -04:00
docs(touch): update touch sensor docs for the new driver
This commit is contained in:
laokaiyao
parent
09b15b479a
commit
805d2ffb34
@ -108,7 +108,7 @@ typedef struct {
|
||||
*
|
||||
*/
|
||||
typedef struct {
|
||||
uint32_t abs_active_thresh[TOUCH_SAMPLE_CFG_NUM]; /*!< The ablolute active threshould. The ``on_active`` and ``on_hw_active`` callback will trigger when
|
||||
uint32_t abs_active_thresh[TOUCH_SAMPLE_CFG_NUM]; /*!< The absolute active threshould. The ``on_active`` and ``on_hw_active`` callback will trigger when
|
||||
* - If touch_sensor_config_t::intr_trig_mode = TOUCH_INTR_TRIG_ON_BELOW_THRESH, the callback will keep triggering when the touch channel value below the threshold.
|
||||
* - If touch_sensor_config_t::intr_trig_mode = TOUCH_INTR_TRIG_ON_ABOVE_THRESH, the callback will keep triggering when the touch channel value above the threshold.
|
||||
*/
|
||||
@ -148,9 +148,9 @@ typedef struct {
|
||||
touch_sw_filter_t data_filter_fn; /*!< The data filter function pointer.
|
||||
* You can specify your own filter algorithm, or set NULL to use default software filter
|
||||
*/
|
||||
void *user_filter_ctx; /*!< User costomized filter context pointer.
|
||||
void *user_filter_ctx; /*!< User customized filter context pointer.
|
||||
* This pointer will be passed to the second parameter of `touch_sw_filter_t` .
|
||||
* So that users can access their costomized filter context in the software filter function.
|
||||
* So that users can access their customized filter context in the software filter function.
|
||||
*/
|
||||
} touch_sensor_filter_config_t;
|
||||
|
||||
|
||||
@ -122,6 +122,8 @@ LDO_DOCS = ['api-reference/peripherals/ldo_regulator.rst']
|
||||
|
||||
TEMP_SENSOR_DOCS = ['api-reference/peripherals/temp_sensor.rst']
|
||||
|
||||
TOUCH_SENSOR_DOCS = ['api-reference/peripherals/cap_touch_sens.rst']
|
||||
|
||||
SPIRAM_DOCS = ['api-guides/external-ram.rst']
|
||||
|
||||
USB_DOCS = ['api-reference/peripherals/usb_device.rst',
|
||||
@ -212,7 +214,6 @@ ESP32_DOCS = ['api-reference/system/himem.rst',
|
||||
'security/secure-boot-v1.rst',
|
||||
'api-reference/peripherals/dac.rst',
|
||||
'api-reference/peripherals/sd_pullup_requirements.rst',
|
||||
'api-reference/peripherals/touch_pad.rst',
|
||||
'hw-reference/esp32/**',
|
||||
'api-guides/RF_calibration.rst',
|
||||
'api-guides/phy.rst'] + FTDI_JTAG_DOCS + QEMU_DOCS
|
||||
@ -222,7 +223,6 @@ ESP32S2_DOCS = ['hw-reference/esp32s2/**',
|
||||
'api-reference/peripherals/ds.rst',
|
||||
'api-reference/peripherals/temp_sensor.rst',
|
||||
'api-reference/system/async_memcpy.rst',
|
||||
'api-reference/peripherals/cap_touch_sens.rst',
|
||||
'api-reference/peripherals/touch_element.rst',
|
||||
'api-guides/RF_calibration.rst',
|
||||
'api-guides/phy.rst'] + FTDI_JTAG_DOCS + USB_OTG_DFU_DOCS + USB_OTG_CONSOLE_DOCS
|
||||
@ -230,7 +230,6 @@ ESP32S2_DOCS = ['hw-reference/esp32s2/**',
|
||||
ESP32S3_DOCS = ['hw-reference/esp32s3/**',
|
||||
'api-reference/system/ipc.rst',
|
||||
'api-guides/flash_psram_config.rst',
|
||||
'api-reference/peripherals/cap_touch_sens.rst',
|
||||
'api-reference/peripherals/sd_pullup_requirements.rst',
|
||||
'api-guides/RF_calibration.rst',
|
||||
'api-guides/phy.rst'] + USB_OTG_DFU_DOCS + USB_OTG_CONSOLE_DOCS + QEMU_DOCS
|
||||
@ -297,6 +296,7 @@ conditional_include_dict = {'SOC_BT_SUPPORTED':BT_DOCS,
|
||||
'CONFIG_IDF_TARGET_ARCH_XTENSA':XTENSA_DOCS,
|
||||
'CONFIG_IDF_TARGET_ARCH_RISCV':RISCV_DOCS,
|
||||
'SOC_TEMP_SENSOR_SUPPORTED':TEMP_SENSOR_DOCS,
|
||||
'SOC_TOUCH_SENSOR_SUPPORTED':TOUCH_SENSOR_DOCS,
|
||||
'SOC_TWAI_SUPPORTED':TWAI_DOCS,
|
||||
'SOC_I2C_SUPPORTED':I2C_DOCS,
|
||||
'SOC_GPSPI_SUPPORTED':SPI_DOCS,
|
||||
|
||||
@ -74,7 +74,6 @@ INPUT = \
|
||||
$(PROJECT_PATH)/components/bt/host/bluedroid/api/include/api/esp_spp_api.h \
|
||||
$(PROJECT_PATH)/components/bt/host/nimble/esp-hci/include/esp_nimble_hci.h \
|
||||
$(PROJECT_PATH)/components/console/esp_console.h \
|
||||
$(PROJECT_PATH)/components/driver/touch_sensor/include/driver/touch_sensor_common.h \
|
||||
$(PROJECT_PATH)/components/driver/twai/include/driver/twai.h \
|
||||
$(PROJECT_PATH)/components/driver/test_apps/components/esp_serial_slave_link/include/esp_serial_slave_link/essl_sdio.h \
|
||||
$(PROJECT_PATH)/components/driver/test_apps/components/esp_serial_slave_link/include/esp_serial_slave_link/essl_spi.h \
|
||||
|
||||
@ -1,10 +1,10 @@
|
||||
INPUT += \
|
||||
$(PROJECT_PATH)/components/driver/touch_sensor/$(IDF_TARGET)/include/driver/touch_sensor.h \
|
||||
$(PROJECT_PATH)/components/hal/include/hal/touch_sensor_legacy_types.h \
|
||||
$(PROJECT_PATH)/components/esp_driver_touch_sens/include/driver/touch_sens.h \
|
||||
$(PROJECT_PATH)/components/esp_driver_touch_sens/include/driver/touch_sens_types.h \
|
||||
$(PROJECT_PATH)/components/esp_driver_touch_sens/hw_ver1/include/driver/touch_version_types.h \
|
||||
$(PROJECT_PATH)/components/esp_psram/include/esp32/himem.h \
|
||||
$(PROJECT_PATH)/components/soc/$(IDF_TARGET)/include/soc/dac_channel.h \
|
||||
$(PROJECT_PATH)/components/soc/$(IDF_TARGET)/include/soc/rtc_io_channel.h \
|
||||
$(PROJECT_PATH)/components/soc/$(IDF_TARGET)/include/soc/touch_sensor_channel.h \
|
||||
$(PROJECT_PATH)/components/ulp/ulp_fsm/include/$(IDF_TARGET)/ulp.h \
|
||||
$(PROJECT_PATH)/components/bt/include/$(IDF_TARGET)/include/esp_bt.h \
|
||||
$(PROJECT_PATH)/components/perfmon/include/xtensa_perfmon_access.h \
|
||||
|
||||
@ -3,7 +3,7 @@ Capacitive Touch Sensor
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
{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"}
|
||||
|
||||
Introduction
|
||||
---------------
|
||||
@ -19,18 +19,45 @@ In-depth design details of touch sensors and firmware development guidelines for
|
||||
Overview of Capacitive Touch Sensor Versions
|
||||
-----------------------------------------------
|
||||
|
||||
+------------------+--------------+------------------------------------------------------------------------+
|
||||
| Hardware Version | Chip | Main Features |
|
||||
+==================+==============+========================================================================+
|
||||
| V1 | ESP32 | Version 1, the channel value decreases when it is touched |
|
||||
+------------------+--------------+------------------------------------------------------------------------+
|
||||
| V2 | ESP32-S2 | Version 2, the channel value increases when it is touched |
|
||||
| | | Supports waterproof, proximity sensing and sleep wake-up |
|
||||
| +--------------+------------------------------------------------------------------------+
|
||||
| | ESP32-S3 | Version 2, support proximity measurement done interrupt |
|
||||
+------------------+--------------+------------------------------------------------------------------------+
|
||||
| V3 | ESP32-P4 | Version 3, support frequency hopping |
|
||||
+------------------+--------------+------------------------------------------------------------------------+
|
||||
+------------------+-----------+---------------------------------------------------------------------------------------+
|
||||
| Hardware Version | Chip | Main Features |
|
||||
+==================+===========+=======================================================================================+
|
||||
| V1 | ESP32 | Version 1, the channel value decreases when it is touched |
|
||||
+------------------+-----------+---------------------------------------------------------------------------------------+
|
||||
| V2 | ESP32-S2 | Version 2, the channel value increases when it is touched |
|
||||
| | | Supports hardware filter, benchmark, waterproof, proximity sensing and sleep wake-up |
|
||||
| +-----------+---------------------------------------------------------------------------------------+
|
||||
| | ESP32-S3 | Version 2, support proximity measurement done interrupt |
|
||||
+------------------+-----------+---------------------------------------------------------------------------------------+
|
||||
| V3 | ESP32-P4 | Version 3, support frequency hopping |
|
||||
+------------------+-----------+---------------------------------------------------------------------------------------+
|
||||
|
||||
Measurement Principle
|
||||
---------------------
|
||||
|
||||
The touch sensor will charge and discharge the touch channel by the internal current or voltage bias. Due to the internal capacitance and the stray capacitance in the circuit, the signals on the touch pins will present as a sawtooth wave. When the finger is approaching or touched on the touch pad, the capacitance of the touch channel increases, which leads to a slower charge and discharge, and a longer sawtooth period.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
The touch sensor charges and discharges the touch channel within a fixed time and counts the number of charge-discharge cycles, and the count result serves as the raw data. The duration of a single charge-discharge measurement can be specified by :cpp:member:`touch_sensor_sample_config_t::charge_times`, and the interval between two measurements can be specified by :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
|
||||
|
||||
Touch Sensor Working Principle
|
||||
|
||||
.. only:: not esp32
|
||||
|
||||
The touch sensor counts the number of clock cycles spent for a fixed number of charge-discharge cycles, and the count result serves as the raw data. The number of charge-discharge cycles for a single measurement can be specified by :cpp:member:`touch_sensor_sample_config_t::charge_duration_ms`, and the interval between two measurements can be specified by :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
|
||||
|
||||
Touch Sensor Working Principle
|
||||
|
||||
Overview of Touch Sensor Channels
|
||||
------------------------------------
|
||||
@ -93,8 +120,8 @@ Categorized by functionality, the APIs of Capacitive Touch Sensor mainly include
|
||||
- `Enable and Disable <#touch-enable>`__
|
||||
- `Continuous Scan <#touch-conti-scan>`__
|
||||
- `Oneshot Scan <#touch-oneshot-scan>`__
|
||||
- `Benchmark Configuration <#touch-benchmark>`__
|
||||
- `Read Measurement Data <#touch-read>`__
|
||||
:SOC_TOUCH_SUPPORT_BENCHMARK: - `Benchmark Configuration <#touch-benchmark>`__
|
||||
:SOC_TOUCH_SUPPORT_WATERPROOF: - `Waterproof Configuration <#touch-waterproof>`__
|
||||
:SOC_TOUCH_SUPPORT_PROX_SENSING: - `Proximity Sensing Configuration <#touch-prox-sensing>`__
|
||||
:SOC_TOUCH_SUPPORT_SLEEP_WAKEUP: - `Sleep Wake-up Configuration <#touch-sleep-wakeup>`__
|
||||
@ -182,6 +209,14 @@ The filter can help to increase the stability in different use cases. The filter
|
||||
|
||||
To deregister the filter, you can call :cpp:func:`touch_sensor_config_filter` again, and set the second parameter (i.e. :cpp:type:`touch_sensor_filter_config_t` pointer) to ``NULL``.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
The touch sensor version {IDF_TARGET_TOUCH_SENSOR_VERSION} does not natively support the hardware filter, but the driver can set up a periodically triggered software filter based on ``esp_timer``. The interval for the software filter can be specified by :cpp:member:`touch_sensor_filter_config_t::interval_ms`. Additionally, the :cpp:member:`touch_sensor_filter_config_t::data_filter_fn` supports to specify a custom filtering function. If there are no special filter requirements, this interface can be set to ``NULL`` to use the default filter in the driver.
|
||||
|
||||
.. only:: not esp32
|
||||
|
||||
The touch sensor version {IDF_TARGET_TOUCH_SENSOR_VERSION} supports the hardware filter. The filtering and updating strategy for the benchmark can be configured by :cpp:member:`touch_sensor_filter_config_t::benchmark`, while the filtering of read values can be configured by :cpp:member:`touch_sensor_filter_config_t::data`.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
// ...
|
||||
@ -268,21 +303,6 @@ With the touch controller enabled, :cpp:func:`touch_sensor_trigger_oneshot_scann
|
||||
// Trigger an oneshot scan with timeout 1000 ms
|
||||
ESP_ERROR_CHECK(touch_sensor_trigger_oneshot_scanning(sens_handle, 1000));
|
||||
|
||||
.. _touch-benchmark:
|
||||
|
||||
Benchmark Configuration
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Normally, you don't have to set the benchmark manually, but you can force reset the benchmark to the current smooth value by calling :cpp:func:`touch_channel_config_benchmark` when necessary.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
touch_chan_benchmark_config_t benchmark_cfg = {
|
||||
// Benchmark operations
|
||||
// ...
|
||||
};
|
||||
ESP_ERROR_CHECK(touch_channel_config_benchmark(chan_handle, &benchmark_cfg));
|
||||
|
||||
.. _touch-read:
|
||||
|
||||
Read Measurement Data
|
||||
@ -301,6 +321,23 @@ Call :cpp:func:`touch_channel_read_data` to read the data with different types.
|
||||
// Read the smooth data
|
||||
ESP_ERROR_CHECK(touch_channel_read_data(chan_handle, TOUCH_CHAN_DATA_TYPE_SMOOTH, smooth_data));
|
||||
|
||||
.. _touch-benchmark:
|
||||
|
||||
.. only:: SOC_TOUCH_SUPPORT_BENCHMARK
|
||||
|
||||
Benchmark Configuration
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Normally, you don't have to set the benchmark manually, but you can force reset the benchmark to the current smooth value by calling :cpp:func:`touch_channel_config_benchmark` when necessary.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
touch_chan_benchmark_config_t benchmark_cfg = {
|
||||
// Benchmark operations
|
||||
// ...
|
||||
};
|
||||
ESP_ERROR_CHECK(touch_channel_config_benchmark(chan_handle, &benchmark_cfg));
|
||||
|
||||
.. _touch-waterproof:
|
||||
|
||||
.. only:: SOC_TOUCH_SUPPORT_WATERPROOF
|
||||
@ -377,8 +414,11 @@ Call :cpp:func:`touch_channel_read_data` to read the data with different types.
|
||||
|
||||
If you want to read or configure the touch sensor during the sleep, you can turn to the driver ``components/ulp/ulp_riscv/ulp_core/include/ulp_riscv_touch_ulp_core.h`` which based on the :doc:`Ultra Low Power (ULP) Coprocessor <../system/ulp>`.
|
||||
|
||||
- Light sleep wake-up: you need to set :cpp:member:`slp_wakeup_lvl` to :cpp:enumerator:`TOUCH_LIGHT_SLEEP_WAKEUP` to enable the light sleep wake-up by touch sensor. Note that any registered touch channel can wake-up the chip from light sleep.
|
||||
- Deep sleep wake-up: beside setting :cpp:member:`slp_wakeup_lvl` to :cpp:enumerator:`TOUCH_DEEP_SLEEP_WAKEUP`, you need to specify :cpp:member:`deep_slp_chan` additionally. In order to reduce the power consumption, only the specified channel can wake-up the chip from the deep sleep when RTC_PREI power domain off. And also, the driver supports to store another set of configurations for the deep sleep via :cpp:member:`deep_slp_sens_cfg`, this set of configurations only takes effect during the deep sleep, you can customize the configurations to save more power. The configurations will be reset to the previous set after waking-up from the deep sleep. Please be aware that, not only deep sleep wake-up, but also light sleep wake-up will be enabled when the :cpp:member:`slp_wakeup_lvl` is :cpp:enumerator:`TOUCH_DEEP_SLEEP_WAKEUP`.
|
||||
.. list::
|
||||
|
||||
- Light sleep wake-up: you need to set :cpp:member:`slp_wakeup_lvl` to :cpp:enumerator:`TOUCH_LIGHT_SLEEP_WAKEUP` to enable the light sleep wake-up by touch sensor. Note that any registered touch channel can wake-up the chip from light sleep.
|
||||
:esp32: - Deep sleep wake-up: you need to set :cpp:member:`slp_wakeup_lvl` to :cpp:enumerator:`TOUCH_DEEP_SLEEP_WAKEUP` to enable the deep sleep wake-up by touch sensor. Note that in version {IDF_TARGET_TOUCH_SENSOR_VERSION}, enabling Deep-sleep wake-up will keep the RTC domain power on during the deep-sleep to maintain the operation of the touch sensor. At this time, any registered touch sensor channels can continue sampling and support waking up from Deep-sleep.
|
||||
:not esp32: - Deep sleep wake-up: beside setting :cpp:member:`slp_wakeup_lvl` to :cpp:enumerator:`TOUCH_DEEP_SLEEP_WAKEUP`, you need to specify :cpp:member:`deep_slp_chan` additionally. In order to reduce the power consumption, only the specified channel can wake-up the chip from the deep sleep when RTC_PREI power domain off. And also, the driver supports to store another set of configurations for the deep sleep via :cpp:member:`deep_slp_sens_cfg`, this set of configurations only takes effect during the deep sleep, you can customize the configurations to save more power. The configurations will be reset to the previous set after waking-up from the deep sleep. Please be aware that, not only deep sleep wake-up, but also light sleep wake-up will be enabled when the :cpp:member:`slp_wakeup_lvl` is :cpp:enumerator:`TOUCH_DEEP_SLEEP_WAKEUP`.
|
||||
|
||||
.. only:: not esp32
|
||||
|
||||
@ -437,11 +477,28 @@ Application Examples
|
||||
|
||||
- :example:`peripherals/touch_sensor/touch_sens_basic` demonstrates how to register touch channels and read the data, including hardware requirements and project configuration instructions.
|
||||
|
||||
Application Notes
|
||||
-----------------
|
||||
|
||||
Touch Sensor Power Consumption Issues
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Due to the capacitive charging and discharging operation in the touch sensor measurements, it is a relatively high power-consuming peripheral. In applications with high power consumption requirements, the following methods can be helpful to reduce the power consumption.
|
||||
|
||||
.. list::
|
||||
|
||||
- Reduce the number of touch channels: Multiple functions (such as single-press, double-press, long press, etc.) can be multiplexed on the same channel, thereby reducing the number of touch sensors.
|
||||
- Increase the measurement interval: By increasing the measurement interval :cpp:member:`touch_sensor_config_t::meas_interval_us`, the measurement frequency will be reduced, thereby lowering down the power consumption.
|
||||
:esp32: - Reduce single measurement duration: By decreasing the single measurement duration :cpp:member:`touch_sensor_sample_config_t::charge_duration_ms`, the number of charging and discharging cycles is reduced, resulting in lower power consumption.
|
||||
:not esp32: - Reduce single measurement charging and discharging cycles: By lowering down the single measurement charging and discharging cycles :cpp:member:`touch_sensor_sample_config_t::charge_times`, power consumption will be decreased.
|
||||
:esp32s2 or esp32s3: - Set the current bias type to self-bias: By configuring :cpp:member:`touch_sensor_sample_config_t::bias_type` to :cpp:enumerator:`touch_bias_type_t::TOUCH_BIAS_TYPE_SELF` to use self-bias, which is more power-saving but less stable.
|
||||
:esp32 or esp32s2 or esp32s3: - Lower down the charging and discharging amplitudes: :cpp:member:`touch_sensor_sample_config_t::charge_volt_lim_l` and :cpp:member:`touch_sensor_sample_config_t::charge_volt_lim_h` can specify the lower voltage limit during the discharging and the upper voltage limit during the charging. Reducing both voltage limitations and the voltage error between them can also decrease the power consumption.
|
||||
:esp32 or esp32s2 or esp32s3: - Reduce the current bias intensity: Lowering down :cpp:member:`touch_channel_config_t::charge_speed` (i.e., the current magnitude of the current bias) can help to reduce the power consumption.
|
||||
:esp32p4: - Lower down the LDO voltage biasing intensity: Decreasing :cpp:member:`touch_channel_config_t::bias_volt` can reduce the power consumption.
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. 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
|
||||
|
||||
49
docs/en/api-reference/peripherals/cap_touch_sens/esp32.inc
Normal file
49
docs/en/api-reference/peripherals/cap_touch_sens/esp32.inc
Normal file
@ -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
|
||||
|
||||
* - Channel
|
||||
- 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 @@ Peripherals API
|
||||
:SOC_LP_I2S_SUPPORTED: lp_i2s
|
||||
:SOC_LP_VAD_SUPPORTED: vad
|
||||
: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 @@
|
||||
Touch Sensor
|
||||
============
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
{IDF_TARGET_TOUCH_SENSOR_VERSION:default="v2", esp32="v1"}
|
||||
|
||||
.. only:: esp32s2 or esp32s3
|
||||
|
||||
.. warning::
|
||||
|
||||
The touch driver in this document has been deprecated, please move to the new document for the latest touch driver: :doc:`Capacitive Touch Sensor </api-reference/peripherals/cap_touch_sens>`.
|
||||
|
||||
Introduction
|
||||
------------
|
||||
|
||||
A touch sensor system is built on a substrate which carries electrodes and relevant connections under a protective flat surface. When the surface is touched, the capacitance variation is used to evaluate if the touch was valid.
|
||||
|
||||
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
|
||||
|
||||
For more information about testing touch sensors in various configurations, please check the `Guide for ESP32-Sense-Kit <https://docs.espressif.com/projects/espressif-esp-dev-kits/en/latest/esp32/esp32-sense-kit/user_guide.html>`_.
|
||||
|
||||
Functionality Overview
|
||||
----------------------
|
||||
|
||||
Description of API is broken down into groups of functions to provide a quick overview of the following features:
|
||||
|
||||
- Initialization of touch pad driver
|
||||
- Configuration of touch pad GPIO pins
|
||||
- Taking measurements
|
||||
- Adjusting parameters of measurements
|
||||
- Filtering measurements
|
||||
- Touch detection methods
|
||||
- Setting up interrupts to report touch detection
|
||||
- Waking up from Sleep mode on interrupt
|
||||
|
||||
For detailed description of a particular function, please go to Section :ref:`touch_pad-api-reference`. Practical implementation of this API is covered in Section :ref:`Application Examples <touch_pad-api-examples>`.
|
||||
|
||||
Initialization
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
Before using a touch pad, you need to initialize the touch pad driver by calling the function :cpp:func:`touch_pad_init`. This function sets several ``.._DEFAULT`` driver parameters listed in :ref:`touch_pad-api-reference` under **Macros**. It also removes the information about which pads have been touched before, if any, and disables interrupts.
|
||||
|
||||
If the driver is not required anymore, deinitialize it by calling :cpp:func:`touch_pad_deinit`.
|
||||
|
||||
Configuration
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
Enabling the touch sensor functionality for a particular GPIO is done with :cpp:func:`touch_pad_config()`. The following 10 capacitive touch pads are supported for {IDF_TARGET_NAME}.
|
||||
|
||||
.. list-table::
|
||||
:align: center
|
||||
:widths: 50 50
|
||||
:header-rows: 1
|
||||
|
||||
* - Touch Pad
|
||||
- GPIO Pin
|
||||
* - 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
|
||||
|
||||
Enabling the touch sensor functionality for a particular GPIO is done with :cpp:func:`touch_pad_config()`. The following 14 capacitive touch pads are supported for {IDF_TARGET_NAME}.
|
||||
|
||||
.. list-table::
|
||||
:align: center
|
||||
:widths: 50 50
|
||||
:header-rows: 1
|
||||
|
||||
* - Touch Pad
|
||||
- GPIO Pin
|
||||
* - T0
|
||||
- Internal channel, not connect to a GPIO
|
||||
* - 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
|
||||
|
||||
Use the function :cpp:func:`touch_pad_set_fsm_mode` to select if touch pad measurement (operated by FSM) should be started automatically by a hardware timer, or by software. If software mode is selected, use :cpp:func:`touch_pad_sw_start` to start the FSM.
|
||||
|
||||
Touch State Measurements
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
The following two functions come in handy to read raw or filtered measurements from the sensor:
|
||||
|
||||
* :cpp:func:`touch_pad_read_raw_data`
|
||||
* :cpp:func:`touch_pad_read_filtered`
|
||||
|
||||
They 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.
|
||||
|
||||
.. note::
|
||||
|
||||
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 or esp32s3
|
||||
|
||||
The following function come in handy to read raw measurements from the sensor:
|
||||
|
||||
* :cpp:func:`touch_pad_read_raw_data`
|
||||
|
||||
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.
|
||||
|
||||
Method of Measurements
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
The touch sensor counts the number of charge/discharge cycles over a fixed period of time (specified by :cpp:func:`touch_pad_set_measurement_clock_cycles`). The count result is the raw data that read from :cpp:func:`touch_pad_read_raw_data`. After finishing one measurement, the touch sensor sleeps until the next measurement start, this interval between two measurements can be set by :cpp:func:`touch_pad_set_measurement_interval`.
|
||||
|
||||
.. note::
|
||||
|
||||
If the specified clock cycles for measurement is too small, the result may be inaccurate, but increasing clock cycles will increase the power consumption as well. Additionally, the response of the touch sensor will slow down if the total time of the interval and measurement is too long.
|
||||
|
||||
.. only:: esp32s2 or esp32s3
|
||||
|
||||
The touch sensor records the period of time (i.e., the number of clock cycles) over a fixed charge/discharge cycles (specified by :cpp:func:`touch_pad_set_charge_discharge_times`). The count result is the raw data that read from :cpp:func:`touch_pad_read_raw_data`. After finishing one measurement, the touch sensor sleeps until the next measurement start, this interval between two measurements can be set by :cpp:func:`touch_pad_set_measurement_interval`.
|
||||
|
||||
.. note::
|
||||
|
||||
If the specified charge and discharge cycles for measurement is too small, the result may be inaccurate, but increasing charge and discharge cycles will increase the power consumption as well. Additionally, the response of the touch sensor will slow down if the total time of the interval and measurement is too long.
|
||||
|
||||
Optimization of Measurements
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
A touch sensor has several configurable parameters to match the characteristics of a particular touch pad design. For instance, to sense smaller capacity changes, it is possible to narrow down the reference voltage range within which the touch pads are charged/discharged. The high and low reference voltages are set using the function :cpp:func:`touch_pad_set_voltage`.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
Besides the ability to discern smaller capacity changes, a positive side effect is reduction of power consumption for low power applications. A likely negative effect is an increase in measurement noise. If the dynamic range of obtained readings is still satisfactory, then further reduction of power consumption might be done by reducing the measurement time with :cpp:func:`touch_pad_set_measurement_clock_cycles`.
|
||||
|
||||
.. only:: esp32s2 or esp32s3
|
||||
|
||||
Besides the ability to discern smaller capacity changes, a positive side effect is reduction of power consumption for low power applications. A likely negative effect is an increase in measurement noise. If the dynamic range of obtained readings is still satisfactory, then further reduction of power consumption might be done by reducing the measurement time with :cpp:func:`touch_pad_set_charge_discharge_times`.
|
||||
|
||||
The following list summarizes available measurement parameters and corresponding 'set' functions:
|
||||
|
||||
* Touch pad charge / discharge parameters:
|
||||
|
||||
* voltage range: :cpp:func:`touch_pad_set_voltage`
|
||||
* speed (slope): :cpp:func:`touch_pad_set_cnt_mode`
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
* Clock cycles of one measurement: :cpp:func:`touch_pad_set_measurement_clock_cycles`
|
||||
|
||||
.. only:: esp32s2 or esp32s3
|
||||
|
||||
* Charge and discharge times of one measurement: :cpp:func:`touch_pad_set_charge_discharge_times`
|
||||
|
||||
Relationship between the voltage range (high/low reference voltages), speed (slope), and measurement time is shown in the figure below.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
.. figure:: ../../../_static/touch_pad-measurement-parameters.jpg
|
||||
:align: center
|
||||
:alt: Touch Pad - relationship between measurement parameters
|
||||
:figclass: align-center
|
||||
|
||||
Touch pad - relationship between measurement parameters
|
||||
|
||||
The last chart **Output** represents the touch sensor reading, i.e., the count of pulses collected within the measurement time.
|
||||
|
||||
.. only:: esp32s2 or esp32s3
|
||||
|
||||
.. figure:: ../../../_static/touch_pad-measurement-parameters-version2.png
|
||||
:align: center
|
||||
:alt: Touch Pad - relationship between measurement parameters
|
||||
:figclass: align-center
|
||||
|
||||
Touch pad - relationship between measurement parameters
|
||||
|
||||
The last chart **Output** represents the touch sensor reading, i.e., the time taken to accumulate the fixed number of cycles.
|
||||
|
||||
All functions are provided in pairs to **set** a specific parameter and to **get** the current parameter's value, e.g., :cpp:func:`touch_pad_set_voltage` and :cpp:func:`touch_pad_get_voltage`.
|
||||
|
||||
.. _touch_pad-api-filtering-of-measurements:
|
||||
|
||||
Filtering of Measurements
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
.. only:: esp32
|
||||
|
||||
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`.
|
||||
|
||||
The filter type is IIR (infinite impulse response), and it has a configurable period that can be set with the function :cpp:func:`touch_pad_set_filter_period`.
|
||||
|
||||
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 or esp32s3
|
||||
|
||||
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.
|
||||
|
||||
There is an internal touch channel that is not connected to any external GPIO. The measurements from this denoise pad can be used to filters out interference introduced on all channels, such as noise introduced by the power supply and external EMI.
|
||||
|
||||
The denoise parameters are set with the function :cpp:func:`touch_pad_denoise_set_config` and started by with :cpp:func:`touch_pad_denoise_enable`
|
||||
|
||||
There is also a configurable hardware implemented IIR-filter (infinite impulse response). This IIR-filter is configured with the function :cpp:func:`touch_pad_filter_set_config` and enabled by calling :cpp:func:`touch_pad_filter_enable`
|
||||
|
||||
Touch Detection
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
Touch detection is implemented in ESP32's hardware based on the user-configured threshold and raw measurements executed by FSM. Use the functions :cpp:func:`touch_pad_get_status` to check which pads have been touched and :cpp:func:`touch_pad_clear_status` to clear the touch status information.
|
||||
|
||||
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.
|
||||
|
||||
Touch Triggered Interrupts
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Before enabling an interrupt on a touch detection, you should establish a touch detection threshold. Use the functions described in `Touch State Measurements`_ to read and display sensor measurements when a pad is touched and released. Apply a filter if measurements are noisy and relative capacity changes are small. Depending on your application and environment conditions, test the influence of temperature and power supply voltage changes on measured values.
|
||||
|
||||
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
|
||||
|
||||
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`.
|
||||
|
||||
Finally, configure and manage interrupt calls using the following functions:
|
||||
|
||||
* :cpp:func:`touch_pad_isr_register` / :cpp:func:`touch_pad_isr_deregister`
|
||||
* :cpp:func:`touch_pad_intr_enable` / :cpp:func:`touch_pad_intr_disable`
|
||||
|
||||
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
|
||||
|
||||
.. 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
|
||||
|
||||
Wakeup from Sleep Mode
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If touch pad interrupts are used to wake up the chip from a sleep mode, you can select a certain configuration of pads (SET1 or both SET1 and SET2) that should be touched to trigger the interrupt and cause the subsequent wakeup. To do so, use the function :cpp:func:`touch_pad_set_trigger_source`.
|
||||
|
||||
Configuration of required bit patterns of pads may be managed for each 'SET' with:
|
||||
|
||||
* :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:
|
||||
|
||||
Application Examples
|
||||
--------------------
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
- :example:`peripherals/touch_sensor/touch_sensor_v1/touch_pad_read` demonstrates how to read and print raw or IIR filtered values from capacitive touch sensors on {IDF_TARGET_NAME}, and how to calibrate the sensors.
|
||||
- :example:`peripherals/touch_sensor/touch_sensor_v1/touch_pad_interrupt` demonstrates how to set up the {IDF_TARGET_NAME}'s capacitive touch pad to trigger an interrupt when touched, and how to use software detection for greater sensitivity, comparing the performance of hardware interrupt mode and software polling mode.
|
||||
|
||||
.. only:: esp32s2 or esp32s3
|
||||
|
||||
.. warning::
|
||||
|
||||
The example that uses legacy driver is removed, please see :example:`peripherals/touch_sensor/touch_sens_basic` for the usage of the new driver.
|
||||
|
||||
.. _touch_pad-api-reference:
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/touch_sensor.inc
|
||||
.. include-build-file:: inc/touch_sensor_common.inc
|
||||
|
||||
GPIO Lookup Macros
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Some useful macros can be used to specified the GPIO number of a touch pad channel, or vice versa. e.g.,
|
||||
|
||||
1. ``TOUCH_PAD_NUM5_GPIO_NUM`` is the GPIO number of channel 5 (12);
|
||||
2. ``TOUCH_PAD_GPIO4_CHANNEL`` is the channel number of GPIO 4 (channel 0).
|
||||
|
||||
.. include-build-file:: inc/touch_sensor_channel.inc
|
||||
.. include-build-file:: inc/touch_sensor_legacy_types.inc
|
||||
@ -7,3 +7,4 @@ Migration from 5.4 to 5.5
|
||||
:maxdepth: 1
|
||||
|
||||
system
|
||||
peripherals
|
||||
|
||||
27
docs/en/migration-guides/release-5.x/5.5/peripherals.rst
Normal file
27
docs/en/migration-guides/release-5.x/5.5/peripherals.rst
Normal file
@ -0,0 +1,27 @@
|
||||
Peripherals
|
||||
===========
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
.. only:: SOC_TOUCH_SENSOR_SUPPORTED
|
||||
|
||||
Touch Sensor
|
||||
------------
|
||||
|
||||
The touch sensor driver has been redesigned into :doc:`Capacitive Touch Sensor <../../../api-reference/peripherals/cap_touch_sens>`.
|
||||
|
||||
- The new driver is in ``esp_driver_touch_sens`` component and the include path is ``driver/touch_sens.h``.
|
||||
- The legacy driver is still available in the previous include path ``driver/touch_sensor.h``.
|
||||
|
||||
Although it is recommended to use the new driver APIs, the legacy driver is still available in the previous include path ``driver/touch_sensor.h``. However, by default, including ``driver/touch_sensor.h`` triggers the build warning below. The warning can be suppressed by the Kconfig option :ref:`CONFIG_TOUCH_SUPPRESS_DEPRECATE_WARN`.
|
||||
|
||||
The major changes are listed as follows:
|
||||
|
||||
Major Changes
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
- Now the touch sensor APIs based on different hardware version are integrated into one API set. And each sub-feature is configurable via its own individual API.
|
||||
- Almost all hardware configurations are public to provide enough flexibility, meanwhile the driver also offers some default configurations to save your time on figuring out a basic workable configuration.
|
||||
- The new touch driver implemented Finite-State Machine (FSM) to ensure a correct touch sensor operation. Please refer to the programming guide :doc:`Capacitive Touch Sensor <../../../api-reference/peripherals/cap_touch_sens>` for more details.
|
||||
- All new APIs are guaranteed to be thread-safe.
|
||||
- Implemented a software filter for the touch sensor V1 (ESP32), and open for customization.
|
||||
@ -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
|
||||
@ -7,3 +7,4 @@
|
||||
:maxdepth: 1
|
||||
|
||||
system
|
||||
peripherals
|
||||
|
||||
27
docs/zh_CN/migration-guides/release-5.x/5.5/peripherals.rst
Normal file
27
docs/zh_CN/migration-guides/release-5.x/5.5/peripherals.rst
Normal file
@ -0,0 +1,27 @@
|
||||
Peripherals
|
||||
===========
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
.. only:: SOC_TOUCH_SENSOR_SUPPORTED
|
||||
|
||||
Touch Sensor
|
||||
------------
|
||||
|
||||
电容式触摸传感器的驱动已更新为 :doc:`Capacitive Touch Sensor <../../../api-reference/peripherals/cap_touch_sens>`.
|
||||
|
||||
- The new driver is in ``esp_driver_touch_sens`` component and the include path is ``driver/touch_sens.h``.
|
||||
- The legacy driver is still available in the previous include path ``driver/touch_sensor.h``.
|
||||
|
||||
尽管我们推荐使用新的驱动 API， 旧版驱动仍然可用，其头文件引用路径为 ``driver/touch_sensor.h``。但是，引用 ``driver/touch_sensor.h`` 会默认触发如下编译警告，可通过配置 Kconfig 选项 :ref:`CONFIG_TOUCH_SUPPRESS_DEPRECATE_WARN` 关闭该警告。
|
||||
|
||||
使用方法上的主要更新如下所示：
|
||||
|
||||
主要使用方法更新
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- 基于不同硬件版本的触摸传感器 API 现已经整合为一套 API，每个子功能都有独立的 API 可配置。
|
||||
- 所有的硬件配置都可配置，以提供足够的灵活性，同时驱动程序还提供了一些默认配置，以便您不必花费时间去确定可用的基本配置。
|
||||
- 新的触摸驱动实现了有限状态机（FSM）以确保正确的触摸传感器操作。请参阅编程指南 :doc:`电容式触摸传感器 <../../../api-reference/peripherals/cap_touch_sens>` 了解更多详情。
|
||||
- 所有新的API都保证是线程安全的。
|
||||
- 为触摸传感器 V1（ESP32）实现了软件滤波器，并开放自定义滤波器接口。
|
||||
Loading…
x
Reference in New Issue
Block a user