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

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 ``esp32_touch`` component creates a global hub enabling (capacitive) touch detection on GPIO pins
-the eight touch pads of the ESP32 as :ref:`binary sensors <esp32-touch-binary-sensor>`.
+: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>`
+   will spam the logs. See :ref:`setting up touch pads <esp32-touch-binary-sensor>`
-   for more information. Defaults to false.
+   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
+- **low_voltage_reference** (*Optional*): The low voltage reference to use for the charge cycles. One of ``0.5V``,
-  the `esp-idf docs <https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/peripherals/touch_pad.html#optimization-of-measurements>`__
+  ``0.6V``, ``0.7V``, ``0.8V``. Default is ``0.5V``.
-  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. One of ``2.4V``,
-- **high_voltage_reference** (*Optional*): The high voltage reference to use for the charge cycles. See
+  ``2.5V``, ``2.6V``, ``2.7V``. Default is ``2.7V``.
-  the `esp-idf docs <https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/peripherals/touch_pad.html#optimization-of-measurements>`__
+- **voltage_attenuation** (*Optional*): The voltage attenuation to use for the charge cycles. One of ``1.5V``, ``1V``,
-  for a nice explanation of this. One of ``2.4V``, ``2.5V``, ``2.6V``, ``2.7V``. Default is ``2.7V``.
+  ``0.5V``, ``0V``. Default is ``0V``.
-- **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 more detailed explanation of the parameters above, please see the
-  for a nice explanation of this. One of ``1.5V``, ``1V``, ``0.5V``, ``0V``. Default is ``0V``.
+`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
+-  **threshold** (**Required**, ``int``): The threshold to use to detect touch events. See
-   a higher probability that the pad is being touched.
+   :ref:`esp32-finding-thresholds` below for help determining this value.
 -  **name** (**Required**, string): The name of the binary sensor.
--  **id** (*Optional*,
+-  **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
-   :ref:`config-id`): Manually specify
+-  **wakeup_threshold** (*Optional*, ``int``): The threshold to use to detect touch events to wake-up from deep sleep.
-   the ID used for code generation.
+   See :ref:`esp32-finding-thresholds` below for help determining this value. Touch pad sensors that should trigger a
--  **wakeup_threshold** (*Optional*, int): The threshold to use to detect touch events to wakeup from deep
+   wake-up from deep sleep must specify this value. The :ref:`deep_sleep-component` must also be configured to enable
-   sleep. Smaller values mean a higher probability that the pad is being touched. All touch pad sensors that
+   wake-up from a touch event. Note that no filter(s) is/are active during deep sleep.
-   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.
 -  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``
+.. list-table::
--  ``GPIO2``
+    :header-rows: 1
--  ``GPIO4``
--  ``GPIO12``
--  ``GPIO13``
--  ``GPIO14``
--  ``GPIO15``
--  ``GPIO27``
--  ``GPIO32``
--  ``GPIO33``
 
-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
+For each touch pad you want to monitor, you need to find a threshold value first. This threshold is used to determine
-used to determine if a pad is being touched or not using the raw values from the sensor. Lower
+if a pad is being touched or not using the raw values read from the processor's internal sensor hardware. When no
-raw values mean that it is more likely that a touch is happening. For example, values around
+contact is made with the sensor, the values will typically hover within a certain range; when the sensor's pad is
-1000 to 1600 usually mean the pad is not being touched, and values in the range of 600 and less
+touched, the value will change significantly, enabling the touch to be detected.
-mean the pad is probably being touched.
 
-To find suitable threshold values, first configure the :ref:`ESP32 touch hub <esp32-touch-component>`
+Exact values reported by the sensor hardware will vary based on the processor, PCB layout and potentially even
-to output measured values using the ``setup_mode:`` configuration option. Next, add some binary sensors
+environmental factors.
-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.
+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
+Upload the program/configuration and watch the device's logs; you'll see values being logged by the hub component.
-and you will (hopefully) see the value decreasing a bit. Play around with different amounts of
+Touching the sensor's pins/pads should result in a (significant) change in the values being logged. Experiment with
-force you put on the touch pad until you find a good value that can differentiate between
+different amounts of force applied to the touch pad; a pattern should emerge, revealing a value that falls between
-touch/non-touch events.
+"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``
+Once you've determined an appropriate value, update the threshold parameter in your configuration and test the updated
-option again by setting it to ``false``. Otherwise you will end up spamming the logs and slowing the device
+configuration. You may need to repeat this process a few times to fine-tune the behavior and get it just right.
-down.
+
+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
 --------