diff --git a/components/binary_sensor/esp32_touch.rst b/components/binary_sensor/esp32_touch.rst index 30b301d9b..e5bbcd2ed 100644 --- a/components/binary_sensor/esp32_touch.rst +++ b/components/binary_sensor/esp32_touch.rst @@ -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 `. +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 `. With this enabled, +:ref:`binary sensors ` 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 ` - for more information. Defaults to false. + will spam the logs. See :ref:`setting up touch pads ` + 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 `__ - 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 `__ - 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 `__ - 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 `__ - 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. `__ + +*ESP32 only* + +- **iir_filter** (*Optional*, :ref:`config-time`): Optionally set up an + `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. `__ + +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. `__ + +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. `__ .. _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 `. +.. _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 ` -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 ` 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 --------