Touch Sensor IDF Refactoring (#6194)

Summary

Touch Sensor refactoring to be based on IDF 4.4.
Adds support to ESP32S2 and future ESP32S3.

Adds some new APIs:

For all chips:

void touchAttachInterruptArg(uint8_t pin, void (*userFunc)(void*), void *arg, uint32_t threshold);
This function allows the user to add and pass a void* parameter to the ISR user callback.

void touchDetachInterrupt(uint8_t pin);
This function detaches ISR call back for the touch pad pin.

Only ESP32 chip

void touchInterruptSetThresholdDirection(bool mustbeLower);
This function allows the user to set if the ISR callback will be activated when the touch sensor readings are lower or higher than the threshold defined. See example TouchButton.ino.

Only ESP32-S2 and ESP32-S3 chips

bool touchInterruptGetLastStatus(uint8_t pin);
This function reports if the touch pad pin is touched or untouched. It can be used with ISR to identify when it is touched and untouched (released). See example TouchButtonV2.ino.

Impact

None. ll original APIs and examples now run on ESP32 and ESP32-S2.

Related links

Fix #6095
Fix #6034
Fix #5799
Fix #5745
Fix #5527
Fix #5493
Fix #4321
Fix #4044
Fix #2722
Fix #2625

cores/esp32/esp32-hal-touch.h

@@ -24,8 +24,21 @@
 extern "C" {
 #endif
 
+#include "soc/soc_caps.h"
 #include "esp32-hal.h"
 
+#if SOC_TOUCH_SENSOR_NUM > 0
+
+#if !defined(SOC_TOUCH_VERSION_1) && !defined(SOC_TOUCH_VERSION_2)
+#error Touch IDF driver Not supported!
+#endif
+
+#if SOC_TOUCH_VERSION_1 // ESP32
+typedef uint16_t touch_value_t;
+#elif SOC_TOUCH_VERSION_2 // ESP32S2 ESP32S3
+typedef uint32_t touch_value_t;
+#endif
+
 /*
  * Set cycles that measurement operation takes
  * The result from touchRead, threshold and detection
@@ -40,17 +53,44 @@ void touchSetCycles(uint16_t measure, uint16_t sleep);
  * You can use this method to chose a good threshold value
  * to use as value for touchAttachInterrupt
  * */
-uint16_t touchRead(uint8_t pin);
+touch_value_t touchRead(uint8_t pin);
 
 /*
- * Set function to be called if touch pad value falls
- * below the given threshold. Use touchRead to determine
- * a proper threshold between touched and untouched state
+ * Set function to be called if touch pad value falls (ESP32)
+ * below the given threshold / rises (ESP32-S2/S3) by given increment (threshold). 
+ * Use touchRead to determine a proper threshold between touched and untouched state
  * */
-void touchAttachInterrupt(uint8_t pin, void (*userFunc)(void), uint16_t threshold);
+void touchAttachInterrupt(uint8_t pin, void (*userFunc)(void), touch_value_t threshold);
+void touchAttachInterruptArg(uint8_t pin, void (*userFunc)(void*), void *arg, touch_value_t threshold);
+void touchDetachInterrupt(uint8_t pin);
+
+/*
+ * Specific functions to ESP32 
+ * Tells the driver if it shall activate the ISR if the sensor is Lower or Higher than the Threshold
+ * Default if Lower.
+ **/
+
+#if SOC_TOUCH_VERSION_1     // Only for ESP32 SoC
+void touchInterruptSetThresholdDirection(bool mustbeLower);
+#endif
+
+
+/*
+ * Specific functions to ESP32-S2 and ESP32-S3
+ * Returns true when the latest ISR status for the Touchpad is that it is touched (Active)
+ * and false when the Touchpad is untoouched (Inactive)
+ * This function can be used in conjunction with ISR User callback in order to take action 
+ * as soon as the touchpad is touched and/or released
+ **/
+
+#if SOC_TOUCH_VERSION_2     // Only for ESP32S2 and ESP32S3
+// returns true if touch pad has been and continues pressed and false otherwise 
+bool touchInterruptGetLastStatus(uint8_t pin);
+#endif
+
+#endif // SOC_TOUCH_SENSOR_NUM > 0
 
 #ifdef __cplusplus
 }
 #endif
-
 #endif /* MAIN_ESP32_HAL_TOUCH_H_ */

libraries/ESP32/examples/Touch/TouchButton/TouchButton.ino

+/*
+
+This is an example how to use Touch Intrrerupts
+The sketh will tell when it is touched and then relesased as like a push-button
+
+This method based on touchInterruptSetThresholdDirection() is only available for ESP32
+*/
+
+#include "Arduino.h"
+
+int threshold = 40;
+bool touchActive = false;
+bool lastTouchActive = false;
+bool testingLower = true;
+
+void gotTouchEvent(){
+  if (lastTouchActive != testingLower) {
+    touchActive = !touchActive;
+    testingLower = !testingLower;
+    // Touch ISR will be inverted: Lower <--> Higher than the Threshold after ISR event is noticed
+    touchInterruptSetThresholdDirection(testingLower);
+  }
+}
+
+void setup() {
+  Serial.begin(115200);
+  delay(1000); // give me time to bring up serial monitor
+  Serial.println("ESP32 Touch Interrupt Test");
+  touchAttachInterrupt(T2, gotTouchEvent, threshold);
+
+  // Touch ISR will be activated when touchRead is lower than the Threshold
+  touchInterruptSetThresholdDirection(testingLower);
+}
+
+void loop(){
+  if(lastTouchActive != touchActive){
+    lastTouchActive = touchActive;
+    if (touchActive) {
+      Serial.println("  ---- Touch was Pressed");
+    } else {
+      Serial.println("  ---- Touch was Released");
+    }
+  }
+  Serial.printf("T2 pin2 = %d \n", touchRead(T2));
+  delay(125);
+}

libraries/ESP32/examples/Touch/TouchButtonV2/TouchButtonV2.ino

+/*
+
+This is an example how to use Touch Intrrerupts
+The sketh will tell when it is touched and then relesased as like a push-button
+
+This method based on touchInterruptGetLastStatus() is only available for ESP32 S2 and S3
+*/
+
+#include "Arduino.h"
+
+int threshold = 1500;   // ESP32S2 
+bool touch1detected = false;
+bool touch2detected = false;
+
+void gotTouch1() {
+  touch1detected = true;
+}
+
+void gotTouch2() {
+  touch2detected = true;
+}
+
+void setup() {
+  Serial.begin(115200);
+  delay(1000); // give me time to bring up serial monitor
+
+  Serial.println("\n ESP32 Touch Interrupt Test\n");
+  touchAttachInterrupt(T1, gotTouch1, threshold); 
+  touchAttachInterrupt(T2, gotTouch2, threshold);
+}
+
+void loop() {
+  static uint32_t count = 0;
+
+  if (touch1detected) {
+    touch1detected = false;
+    if (touchInterruptGetLastStatus(T1)) {
+        Serial.println(" --- T1 Touched");
+    } else {
+        Serial.println(" --- T1 Released");
+    }
+  }
+  if (touch2detected) {
+    touch2detected = false;
+    if (touchInterruptGetLastStatus(T2)) {
+        Serial.println(" --- T2 Touched");
+    } else {
+        Serial.println(" --- T2 Released");
+    }
+  }
+
+  delay(80);
+}