Udated code + added documentation

code:
- changed order of device settings
- added changelog

docs/source/Plugin/P097.rst

@@ -24,21 +24,58 @@ Used libraries: |P097_usedlibraries|
 Description
 -----------
 
-Touch pin support for ESP32.
+Touch pin support for ESP32 based devices. (EPS32Classic, ESP32S2, ESP32S3)
+
+The ESP32Classic does have support for 10 touch pads and ESP32S2 and ESP32S3 have support for 14 touch pads.
+
+.. note:: For ESP32S2 and ESP32S3, the touchpad support from ``T10`` to ``T14`` has been disabled due to stability issues.
 
-The ESP32 does have support for 10 touch pads.
 Such a touch pad can be as simple as a wire or a PCB pad connected to 
 one of the GPIO pins labelled with ``T0`` ... ``T9``.
 
-A touch pad pin can be considered as an analog input pin.
-When not touched, the reported value is "High", for example 100.
 
+A touch pad pin can be considered as an analog input pin.
+If the pin is not touched, it will report a relatively high value on an ESP32Classic (e.g. 100) and a relatively low value on an ESP32S2 or ESP32S3 (e.g. 15000) compared to the value when the pin is touched.
+This value is displayed in the settings of the touch plugin ("current pressue") and is reported as the first taskvalue (default name is "touch") whenever the pin is touched or released.
+
+
+Task settings
+~~~~~~~~~~~~~
+
+* **Device**: Name of plugin
+* **Name**: Name of the task
+* **Enable**: Should the task be enabled or not
+
+Device Settings
+^^^^^^^^^^^^^^^
+* **Analog Pin**: Choose the pin to be used
+* **Toggle State**: When the pin is touched, the value of the second taskvalue (default: "state") toggles between 0 and 1.
+* **Send Long Press Event**: A long press event is sent when the pin is pressed for longer than the time specified in the Long Press Time setting. The second taskvalue becomes 10
+* **Long Press Time:**: The time that you need to press the button before the long press event is triggered.
+* **Wake Up from Sleep**: The device will wake up from sleep when the pin is touched.
+
+Touch Settings
+^^^^^^^^^^^^^^
+* **Send Touch Event:**: An event is sent when the pin is touched 
+* **Send Release Event**: An event is sent when the pin is released
+* **Send Duration Event**: After release, the duration of the touch is sent as an event
+* **Touch Threshold**: see Threshold section...
+* **Current Pressure**: The current pressure is the same as the first taskvalue.
+
+Threshold:
+~~~~~~~~~~
+**ESP32Classic**:
 When touched, the capacity of the pin increases, which in return lowers the number of charge/discharge cycles.
-A typical value for a touched pin is lower than 20.
+A typical value for a touched pin is lower than 20 (compared to the initial threshold value).
+A touch event occures when the touch value is lower then the  "base value" minus the threshold value.
 
-The user has to set a threshold value for when to consider a pin being touched.
-The best value has to be determined by trial and error and may differ per use case.
 
+**ESP32S2** and **ESP32S3**:
+When touched, the threshold value increases.
+A typical value for a touched pin is higher than 1500 (compared to the initial threshold value).
+A touch event occures when the touch value is greater then the  "base value" plus the threshold value.
+
+The best value has to be determined by trial and error and may differ per use case.
 
 Events
 ~~~~~~
@@ -54,3 +91,6 @@ Change log
   ...
 
   |added| 2020-04-25
+
+  |improved| 2023/12/11 Added all settings, a distinction between ESP32 models and the event for <taskvar2>.
+

docs/source/Plugin/P097_events.repl

@@ -3,15 +3,15 @@
    :widths: 30, 20
 
    "
-   ``<taskname>#<taskvar>``
+   ``<taskname>#<taskvar1>``
 
    The regular events like in every other task. Only difference here is that you may have an event either when the touch pad is touched, released or both.
    ","
 
    .. code-block:: none
 
       on touch#Touch do
-       GPIO,2,1 //LED on
+       LogEntry,'Touch value %eventvalue%'
       endon
 
    "
@@ -39,3 +39,22 @@
       6553655 : Info  : Touch Duration 460 ms
 
    "
+   "
+   ``<taskname>#<taskvar2>``
+
+   An event is sent every time the state of <taskvar2> changes. 
+
+   The state can be either **0** for released, **1** for touched and **10** for long press.
+   ","
+
+   .. code-block:: none
+
+      on touch#State do
+       if %eventvalue% != 10
+         GPIO,2,%eventvalue% //LED on or off 
+       else
+         GPIO,3,1 // on longpress turn on another LED
+       endif
+      endon
+
+   "

src/_P097_Esp32Touch.ino

@@ -1,11 +1,15 @@
 #include "_Plugin_Helper.h"
-
 #ifdef USES_P097
 
 // #######################################################################################################
 // #################################### Plugin 097: ESP32 Touch ##########################################
 // #######################################################################################################
 
+/** Changelog:
+ * 2024-12-11 chromoxdor: Added extra routine for ESP32S2 and ESP32S3.
+ *                        Added "Wake Up from Sleep", Switch like behaviour + toggle and long press option.
+ */
+
 
 # if defined(ESP32) && !defined(ESP32C2) && !defined(ESP32C3) && !defined(ESP32C6)
 
@@ -31,7 +35,6 @@
 #  define PLUGIN_VALUENAME2_097      "State"
 #  define P097_MAX_LONGPRESS_VALUE   10000
 
-
 #  define P097_SEND_TOUCH_EVENT      PCONFIG(0)
 #  define P097_SEND_RELEASE_EVENT    PCONFIG(1)
 #  define P097_SEND_DURATION_EVENT   PCONFIG(2)
@@ -111,14 +114,14 @@ boolean Plugin_097(uint8_t function, struct EventStruct *event, String& string)
       addFormNote(F("For now touch pins T10 to T14 are not supported!"));
       #  endif // if (defined(ESP32S2) || defined(ESP32S3)) && !HASS_T10_TO_T14
 
-      addFormCheckBox(F("Toggle State"),       F("typetoggle"),  P097_TYPE_TOGGLE);
+      addFormCheckBox(F("Toggle State"),          F("typetoggle"),    P097_TYPE_TOGGLE);
+      addFormCheckBox(F("Send Long Press Event"), F("sendlongpress"), P097_SEND_LONG_PRESS_EVENT);
+      addFormNumericBox(F("Long Press Time"), F("longpress"), P097_LONG_PRESS_TIME, 500, P097_MAX_LONGPRESS_VALUE);
+      addUnit(F("500..10000 msec."));
       addFormCheckBox(F("Wake Up from Sleep"), F("sleepwakeup"), P097_SLEEP_WAKEUP);
       #  if defined(ESP32S2) || defined(ESP32S3)
       addFormNote(F("Wake up from sleep is only supported on one touch pin!"));
       #  endif // if defined(ESP32S2) || defined(ESP32S3)
-      addFormCheckBox(F("Send Long Press Event"), F("sendlongpress"), P097_SEND_LONG_PRESS_EVENT);
-      addFormNumericBox(F("Long Press Time"), F("longpress"), P097_LONG_PRESS_TIME, 500, P097_MAX_LONGPRESS_VALUE);
-      addUnit(F("500..10000 msec."));
 
       addFormSubHeader(F("Touch Settings"));