Upstream/esphome-docs
1
0
Fork 0
mirror of https://github.com/esphome/esphome-docs.git synced 2025-03-01 03:51:36 +01:00
Code Issues Projects Releases Wiki Activity

Update esp32_touch docs for ESP32-S2/S3 support (#3077)

Browse Source
This commit is contained in:
Keith Burzinski 2023-08-06 20:54:29 -05:00 committed by GitHub
parent 5934f07397
commit 0440eabaa9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 135 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

197
components/binary_sensor/esp32_touch.rst
View File

@ -2,16 +2,23 @@ ESP32 Touch Pad
===============
.. seo::
:description: Instructions for setting up the touch pad on the ESP32.
:description: Instructions for setting up the touch pad on the ESP32
:image: touch.svg
Capacitive touch detection is possible on ESP32, ESP32-S2 or ESP32-S3 processors.
In ESPHome, it is configured in two parts:
- :ref:`esp32-touch-component`
- :ref:`esp32-touch-binary-sensor`
.. _esp32-touch-component:
Component/Hub
-------------
The ``esp32_touch`` component creates a global hub for detecting touches on
the eight touch pads of the ESP32 as :ref:`binary sensors <esp32-touch-binary-sensor>`.
The ``esp32_touch`` component creates a global hub enabling (capacitive) touch detection on GPIO pins
:ref:`supported by ESP32, ESP32-S2 or ESP32-S3 processors <esp32-touch-pad-pins>`. With this enabled,
:ref:`binary sensors <esp32-touch-binary-sensor>` may then be configured to permit touch detection.
.. code-block:: yaml
@ -19,42 +26,85 @@ the eight touch pads of the ESP32 as :ref:`binary sensors <esp32-touch-binary-se
esp32_touch:
setup_mode: false
binary_sensor:
- platform: esp32_touch
name: "ESP32 Touch Pad GPIO27"
pin: GPIO27
threshold: 1000
Configuration variables:
************************
- **setup_mode** (*Optional*, boolean): Whether debug messages with the touch pad value should
be displayed in the logs. Useful for finding out suitable thresholds for the binary sensors, but
spam the logs. See :ref:`setting up touch pads <esp32-touch-binary-sensor>`
for more information. Defaults to false.
will spam the logs. See :ref:`setting up touch pads <esp32-touch-binary-sensor>`
for more information. Defaults to ``false``.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for code generation.
Advanced options (the defaults are usually quite good, but if you're having accuracy issues, use these):
**Advanced options**
These variables may be added to the hub component's configuration (above) and are useful for fine-tuning and/or when
the sensors aren't behaving as expected.
*All processors:*
- **iir_filter** (*Optional*, :ref:`config-time`): Optionally set up an
`Infinite Impulse Response <https://en.wikipedia.org/wiki/Infinite_impulse_response>`__
filter should be applied to all touch pads. This can increase the accuracy of the touch pads a lot, but
higher values decrease the response time. A good value to start with is ``10ms``. Default is no IIR filter.
- **sleep_duration** (*Optional*, :ref:`config-time`): Set a time period
denoting the amount of time the touch peripheral should sleep between measurements. This can decrease
power usage but make the sensor slower. Default is about 27 milliseconds.
- **measurement_duration** (*Optional*, :ref:`config-time`): Set the conversion
time for all touch pads. A longer conversion time means that more charge/discharge cycles of the touch pad
can be performed, therefore increasing accuracy. Default is about 8ms, the maximum amount.
- **low_voltage_reference** (*Optional*): The low voltage reference to use for the charge cycles. See
the `esp-idf docs <https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/peripherals/touch_pad.html#optimization-of-measurements>`__
for a nice explanation of this. One of ``0.5V``, ``0.6V``, ``0.7V``, ``0.8V``. Default is ``0.5V``.
- **high_voltage_reference** (*Optional*): The high voltage reference to use for the charge cycles. See
the `esp-idf docs <https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/peripherals/touch_pad.html#optimization-of-measurements>`__
for a nice explanation of this. One of ``2.4V``, ``2.5V``, ``2.6V``, ``2.7V``. Default is ``2.7V``.
- **voltage_attenuation** (*Optional*): The voltage attenuation to use for the charge cycles. See
the `esp-idf docs <https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/peripherals/touch_pad.html#optimization-of-measurements>`__
for a nice explanation of this. One of ``1.5V``, ``1V``, ``0.5V``, ``0V``. Default is ``0V``.
- **low_voltage_reference** (*Optional*): The low voltage reference to use for the charge cycles. One of ``0.5V``,
``0.6V``, ``0.7V``, ``0.8V``. Default is ``0.5V``.
- **high_voltage_reference** (*Optional*): The high voltage reference to use for the charge cycles. One of ``2.4V``,
``2.5V``, ``2.6V``, ``2.7V``. Default is ``2.7V``.
- **voltage_attenuation** (*Optional*): The voltage attenuation to use for the charge cycles. One of ``1.5V``, ``1V``,
``0.5V``, ``0V``. Default is ``0V``.
For a more detailed explanation of the parameters above, please see the
`ESP-IDF documentation. <https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/peripherals/touch_pad.html#optimization-of-measurements>`__
*ESP32 only*
- **iir_filter** (*Optional*, :ref:`config-time`): Optionally set up an
`Infinite Impulse Response <https://en.wikipedia.org/wiki/Infinite_impulse_response>`__
filter should be applied to all touch pads. This can increase the accuracy of the touch pads a lot, but higher values
decrease the response time. A good value to start with is ``10ms``. By default, the IIR filter is inactive.
*ESP32-S2 and ESP32-S3 only*
**For each configuration category below, if one option is specified, all options must be specified.** The configuration
options below do not have any default values; in other words, they are inactive by default.
Filter configuration:
- **filter_mode** (*Optional*): Sets the filter mode. Must be one of ``IIR_4``, ``IIR_8``, ``IIR_16``,
``IIR_32``, ``IIR_64``, ``IIR_128``, ``IIR_256`` or ``JITTER``.
- **debounce_count** (*Optional*, ``int`` range 0-7): Sets the debounce count; if the measured values continue to
exceed the threshold for ``n + 1`` times, the touch sensor state changes.
- **noise_threshold** (*Optional*, ``int`` range 0-3): Noise threshold coefficient. Higher = More noise resistance. The
actual noise should be less than (noise coefficient * touch threshold). The coefficient is 0: 4/8; 1: 3/8; 2: 2/8; 3: 1.
- **jitter_step** (*Optional*, ``int`` range 0-15): Set jitter filter step size.
- **smooth_mode** (*Optional*): Level of filter applied on the original data against large noise interference.
Must be one of ``OFF``, ``IIR_2``, ``IIR_4`` or ``IIR_8``.
For a more detailed explanation of the filter configuration, please see the
`ESP-IDF documentation. <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-reference/peripherals/touch_pad.html#_CPPv419touch_filter_config>`__
Denoise configuration:
- **denoise_grade** (*Optional*): Sets the denoise range of the denoise channel. Determined by measuring the noise
amplitude of the denoise channel. Must be one of ``BIT12``, ``BIT10``, ``BIT8`` or ``BIT4``.
- **denoise_cap_level** (*Optional*): Select internal reference capacitance of denoise channel. Must be one
of ``L0``, ``L1``, ``L2``, ``L3``, ``L4``, ``L5``, ``L6`` or ``L7``.
For a more detailed explanation of the denoise configuration, please see the
`ESP-IDF documentation. <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-reference/peripherals/touch_pad.html#_CPPv417touch_pad_denoise>`__
Waterproof configuration:
- **waterproof_guard_ring** (*Optional*, :ref:`config-pin`): Sets the touch channel to use for the guard pad. The guard
pad is used to detect the large area of water covering the touch panel.
- **waterproof_shield_driver** (*Optional*): Shield channel drive capability configuration; the larger the
parasitic capacitance on the shielding channel, the higher the drive capability needs to be set. Must be one of
``L0``, ``L1``, ``L2``, ``L3``, ``L4``, ``L5``, ``L6`` or ``L7``.
For a more detailed explanation of the waterproof configuration, please see the
`ESP-IDF documentation. <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-reference/peripherals/touch_pad.html#_CPPv420touch_pad_waterproof>`__
.. _esp32-touch-binary-sensor:
@ -89,47 +139,51 @@ Configuration variables:
- **pin** (**Required**, :ref:`config-pin`): The pin to detect touch
events on.
- **threshold** (**Required**, int): The threshold to use to detect touch events. Smaller values mean
a higher probability that the pad is being touched.
- **threshold** (**Required**, ``int``): The threshold to use to detect touch events. See
:ref:`esp32-finding-thresholds` below for help determining this value.
- **name** (**Required**, string): The name of the binary sensor.
- **id** (*Optional*,
:ref:`config-id`): Manually specify
the ID used for code generation.
- **wakeup_threshold** (*Optional*, int): The threshold to use to detect touch events to wakeup from deep
sleep. Smaller values mean a higher probability that the pad is being touched. All touch pad sensors that
should trigger a wakeup from deep sleep must specify this value. The :ref:`deep_sleep-component` must also
be configured to enable a wakeup from a touch event. Note that no filter is active during deep sleep.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **wakeup_threshold** (*Optional*, ``int``): The threshold to use to detect touch events to wake-up from deep sleep.
See :ref:`esp32-finding-thresholds` below for help determining this value. Touch pad sensors that should trigger a
wake-up from deep sleep must specify this value. The :ref:`deep_sleep-component` must also be configured to enable
wake-up from a touch event. Note that no filter(s) is/are active during deep sleep.
- All other options from :ref:`Binary Sensor <config-binary_sensor>`.
.. _esp32-touch-pad-pins:
Touch Pad Pins
--------------
8 pins on the ESP32 can be used to detect touches. These are (in the default "raw" pin names):
Various pins on the ESP32, ESP32-S2 and ESP32-S3 can be used to detect touches. They are as follows (using the default
"raw" pin names/numbers):
- ``GPIO0``
- ``GPIO2``
- ``GPIO4``
- ``GPIO12``
- ``GPIO13``
- ``GPIO14``
- ``GPIO15``
- ``GPIO27``
- ``GPIO32``
- ``GPIO33``
.. list-table::
:header-rows: 1
Finding thresholds
* - ESP32
- ESP32-S2
- ESP32-S3
* - GPIO4, GPIO0, GPIO2, GPIO15, GPIO13, GPIO12, GPIO14, GPIO27, GPIO33, GPIO32
- GPIO1 - GPIO14
- GPIO1 - GPIO14
.. _esp32-finding-thresholds:
Finding Thresholds
------------------
For each touch pad you want to monitor, you need to find a threshold first. This threshold is
used to determine if a pad is being touched or not using the raw values from the sensor. Lower
raw values mean that it is more likely that a touch is happening. For example, values around
1000 to 1600 usually mean the pad is not being touched, and values in the range of 600 and less
mean the pad is probably being touched.
For each touch pad you want to monitor, you need to find a threshold value first. This threshold is used to determine
if a pad is being touched or not using the raw values read from the processor's internal sensor hardware. When no
contact is made with the sensor, the values will typically hover within a certain range; when the sensor's pad is
touched, the value will change significantly, enabling the touch to be detected.
To find suitable threshold values, first configure the :ref:`ESP32 touch hub <esp32-touch-component>`
to output measured values using the ``setup_mode:`` configuration option. Next, add some binary sensors
for the touch pads you want to observe. Also put some threshold in the configuration as seen below
to make the validator happy, we are going to find good thresholds in a moment anyway.
Exact values reported by the sensor hardware will vary based on the processor, PCB layout and potentially even
environmental factors.
To find suitable threshold values, first configure the :ref:`ESP32 touch hub <esp32-touch-component>` to log measured
values using the ``setup_mode:`` configuration option. Next, add some binary sensors for the touch pads you want to
observe. You'll also need to put some (temporary) threshold values into the configuration (as shown below) to make the
validator happy; we'll replace these in a moment once we determine suitable values.
.. code-block:: yaml
@ -143,17 +197,36 @@ to make the validator happy, we are going to find good thresholds in a moment an
pin: GPIO27
threshold: 1000
Then upload the program and open the logs, you will see values like these. Try touching the pins
and you will (hopefully) see the value decreasing a bit. Play around with different amounts of
force you put on the touch pad until you find a good value that can differentiate between
touch/non-touch events.
Upload the program/configuration and watch the device's logs; you'll see values being logged by the hub component.
Touching the sensor's pins/pads should result in a (significant) change in the values being logged. Experiment with
different amounts of force applied to the touch pad; a pattern should emerge, revealing a value that falls between
"touched" and "not touched" which the binary sensor will then use to differentiate between the two states.
.. figure:: images/esp32_touch-finding_thresholds.png
:align: center
Finally, put your threshold parameter in the configuration. Do not forget to disable the ``setup_mode``
option again by setting it to ``false``. Otherwise you will end up spamming the logs and slowing the device
down.
Once you've determined an appropriate value, update the threshold parameter in your configuration and test the updated
configuration. You may need to repeat this process a few times to fine-tune the behavior and get it just right.
Finally, don't forget to disable the ``setup_mode`` option by setting it back to ``false``; leaving it enabled will
reduce the ESP's overall performance.
.. _esp32-note-about-variants:
A Note About S2 and S3 Variants
-------------------------------
If you're familiar with the ESP32 hardware and pick up an S2 or S3 variant, you're likely to notice some behavioral
differences between them. In particular:
- Raw touch sensor readings on the S2 and S3 variants will generally return larger numeric values than the original
ESP32 hardware.
- Contact with the touch sensor on the S2 and S3 variants will result in the raw sensor value reading *increasing*; on
the original ESP32, contact would cause this value to *decrease*.
These behavioral differences are due to changes in the hardware and software (ESP-IDF) interfaces and should be
expected -- if you are moving your configuration from an original ESP32 to an S2 or S3 variant, expect that you'll need
to make some adjustments to your configuration to accommodate this behavior.
See Also
--------