Add Touch Pad support (#178)

Author: Ellerbach

README.md

@@ -12,6 +12,100 @@
 |:-|---|---|
 | nanoFramework.Hardware.Esp32 | [![Build Status](https://dev.azure.com/nanoframework/nanoFramework.Hardware.Esp32/_apis/build/status/nanoFramework.Hardware.Esp32?repoName=nanoframework%2FnanoFramework.Hardware.Esp32&branchName=main)](https://dev.azure.com/nanoframework/nanoFramework.Hardware.Esp32/_build/latest?definitionId=11&repoName=nanoframework%2FnanoFramework.Hardware.Esp32&branchName=main) | [![NuGet](https://img.shields.io/nuget/v/nanoFramework.Hardware.Esp32.svg?label=NuGet&style=flat&logo=nuget)](https://www.nuget.org/packages/nanoFramework.Hardware.Esp32/)  |
 
+## Touch Pad essentials
+
+This section will give you essential elements about how to use Touch Pad pins on ESP32 and ESP32-S2.
+
+### Touch Pad vs GPIO pins
+
+Touch Pad pins numbering is different from GPIO pin. You can check which GPIO pins correspond to which GPIO pin using the following:
+
+```csharp
+const int TouchPadNumber = 5;
+var pinNum = TouchPad.GetGpioNumberFromTouchNumber(TouchPadNumber);
+Console.WriteLine($"Pad {TouchPadNumber} is GPIO{pinNum}");
+```
+
+The pin numbering is different on ESP32 and S2. There are 10 valid touch pad on ESP32 (0 to 9) and 13 on S2 (1 to 13).
+
+In this example touch pad 5 will be GPIO 12 on ESP32 and GPIO 5 on S2.
+
+### Basic usage ESP32
+
+On ESP32, if you touch the sensor, the values will be lower, so you have to set a threshold that is lower than the calibration data:
+
+```csharp
+TouchPad touchpad = new(TouchPadNumber);
+Console.WriteLine($"Calibrating touch pad {touchpad.TouchPadNumber}, DO NOT TOUCH it during the process.");
+var calib = touchpad.GetCalibrationData();
+Console.WriteLine($"calib: {calib} vs Calibration {touchpad.CalibrationData}");
+// On ESP32: Setup a threshold, usually 2/3 or 80% is a good value.
+touchpad.Threshold = (uint)(touchpad.CalibrationData * 2 / 3);
+touchpad.ValueChanged += TouchpadValueChanged;
+
+Thread.Sleep(Timeout.Infinite);
+
+private static void TouchpadValueChanged(object sender, TouchPadEventArgs e)
+{
+    Console.WriteLine($"Touchpad {e.PadNumber} is {(e.Touched ? "touched" : "not touched")}");
+}
+```
+
+### Basic usage S2
+
+On S2, if you touch the sensor, the values will be higher, so you have to set a threshold that is higher than the calibration data and set trigger mode as above:
+
+```csharp
+TouchPad touchpad = new(TouchPadNumber);
+Console.WriteLine($"Calibrating touch pad {touchpad.TouchPadNumber}, DO NOT TOUCH it during the process.");
+var calib = touchpad.GetCalibrationData();
+Console.WriteLine($"calib: {calib} vs Calibration {touchpad.CalibrationData}");
+// On S2/S3, the actual read values will be higher, so let's use 20% more
+TouchPad.TouchTriggerMode = TouchTriggerMode.AboveThreshold;
+touchpad.Threshold = (uint)(touchpad.CalibrationData * 1.2);
+
+touchpad.ValueChanged += TouchpadValueChanged;
+
+Thread.Sleep(Timeout.Infinite);
+
+private static void TouchpadValueChanged(object sender, TouchPadEventArgs e)
+{
+    Console.WriteLine($"Touchpad {e.PadNumber} is {(e.Touched ? "touched" : "not touched")}");
+}
+```
+
+### Other features
+
+You have quite a lot of other features available, filters, some specific denoising. You can check the sample repository for more details.
+
+## Sleep mode
+
+You can wake up your ESP32 or ESP32-S2 by touch.
+
+### Sleep modes on ESP32
+
+ESP32 can be woke up by 1 or 2 touch pad. Here is how to do it with 1:
+
+```csharp
+Sleep.EnableWakeupByTouchPad(PadForSleep1, thresholdCoefficient: 80);
+```
+
+And with 2 pads:
+
+```csharp
+Sleep.EnableWakeupByTouchPad(PadForSleep1, PadForSleep2);
+```
+
+Note that the coefficient can be adjusted by doing couple of tests, there is default value of 80 that seems to work in all cases. The coefficient represent a percentage value.
+
+### Sleep modes on S2
+
+S2 can only be woke up with 1 touch pad. It is recommended to do tests to find the best coefficient:
+
+```csharp
+Sleep.EnableWakeupByTouchPad(PadForSleep, thresholdCoefficient: 90);
+```
+
 ## Feedback and documentation
 
 For documentation, providing feedback, issues and finding out how to contribute please refer to the [Home repo](https://github.com/nanoframework/Home).

nanoFramework.Hardware.Esp32/Properties/AssemblyInfo.cs

@@ -12,7 +12,7 @@
 
 ////////////////////////////////////////////////////////////////
 // update this whenever the native assembly signature changes //
-[assembly: AssemblyNativeVersion("100.0.7.3")]
+[assembly: AssemblyNativeVersion("100.0.8.0")]
 ////////////////////////////////////////////////////////////////
 
 // Setting ComVisible to false makes the types in this assembly not visible 

nanoFramework.Hardware.Esp32/Sleep.cs

@@ -175,68 +175,7 @@ public enum WakeupGpioPin : UInt64
             /// Gpio Pin 39 used for wakeup.
             /// </summary>
             Pin39 = (UInt64)1 << 39
-        }
-
-        /// <summary>
-        /// Enumeration of Touchpad numbers.
-        /// </summary>
-        public enum TouchPad
-        {
-            /// <summary>
-            ///  Touchpad channel 0 is GPIO4.
-            /// </summary>
-            Num0 = 0,
-
-            /// <summary>
-            /// Touchpad channel 1 is GPIO0.
-            /// </summary>
-            Num1,
-
-            /// <summary>
-            /// Touchpad channel 2 is GPIO2.
-            /// </summary>
-            Num2,
-
-            /// <summary>
-            /// Touchpad channel 3 is GPIO15.
-            /// </summary>
-            Num3,
-
-            /// <summary>
-            /// Touchpad channel 4 is GPIO13.
-            /// </summary>
-            Num4,
-
-            /// <summary>
-            /// Touchpad channel 5 is GPIO12.
-            /// </summary>
-            Num5,
-
-            /// <summary>
-            /// Touchpad channel 6 is GPIO14.
-            /// </summary>
-            Num6,
-
-            /// <summary>
-            /// Touchpad channel 7 is GPIO27.
-            /// </summary>
-            Num7,
-
-            /// <summary>
-            /// Touchpad channel 8 is GPIO33.
-            /// </summary>
-            Num8,
-
-            /// <summary>
-            /// Touchpad channel 9 is GPIO32.
-            /// </summary>
-            Num9,
-
-            /// <summary>
-            /// Number returned when no Touchpad used on wakeup.
-            /// </summary>
-            None
-        }
+        }        
 
         /// <summary>
         /// Enable Wakeup by Timer.
@@ -279,10 +218,14 @@ public static EspNativeError EnableWakeupByMultiPins(WakeupGpioPin pins, WakeupM
         /// <summary>
         /// Enable wakeup by Touchpad.
         /// </summary>
+        /// <param name="padNumber1">A valid pad number to wake up the device.</param>
+        /// <param name="padNumber2">If a valid pad number, will be used in comibation of the first pad number.</param>
+        /// <param name="thresholdCoefficient">Threshold coefficient for automatic calibration. Percentage from 0 to 100. Default value is 80% seems to work in most cases.</param>
+        /// <remarks>See <see cref="Touch.TouchPad.GetGpioNumberFromTouchNumber(int)"/> to understand which GPIO maps with which pad.</remarks>
         /// <returns>Returns ESP32 native error enumeration.</returns>
-        public static EspNativeError EnableWakeupByTouchPad()
+        public static EspNativeError EnableWakeupByTouchPad(int padNumber1, int padNumber2 = -1, byte thresholdCoefficient = 80)
         {
-            return NativeEnableWakeupByTouchPad();
+            return NativeEnableWakeupByTouchPad(padNumber1, padNumber2, thresholdCoefficient);
         }
 
         /// <summary>
@@ -338,7 +281,7 @@ public static WakeupGpioPin GetWakeupGpioPin()
         /// Get the Touchpad which caused the wakeup. 
         /// </summary>
         /// <returns>Returns TouchPad number which caused the wakeup, else <see cref="WakeupGpioPin.None"/>.</returns>
-        public static TouchPad GetWakeupTouchpad()
+        public static int GetWakeupTouchpad()
         {
             return NativeGetWakeupTouchpad();
         }
@@ -355,7 +298,7 @@ public static TouchPad GetWakeupTouchpad()
         private static extern EspNativeError NativeEnableWakeupByMultiPins(WakeupGpioPin pins, WakeupMode mode);
 
         [MethodImpl(MethodImplOptions.InternalCall)]
-        private static extern EspNativeError NativeEnableWakeupByTouchPad();
+        private static extern EspNativeError NativeEnableWakeupByTouchPad(int padNumber1, int padNumber2, byte thresholdCoefficient);
 
         [MethodImpl(MethodImplOptions.InternalCall)]
         private static extern EspNativeError NativeStartLightSleep();
@@ -370,7 +313,7 @@ public static TouchPad GetWakeupTouchpad()
         private static extern WakeupGpioPin NativeGetWakeupGpioPin();
 
         [MethodImpl(MethodImplOptions.InternalCall)]
-        private static extern TouchPad NativeGetWakeupTouchpad();
+        private static extern int NativeGetWakeupTouchpad();
 
         #endregion
     }

nanoFramework.Hardware.Esp32/Touch/DenoiseCapacitance.cs

@@ -0,0 +1,35 @@
+// Copyright(c).NET Foundation and Contributors
+// See LICENSE file in the project root for full license information.
+
+namespace nanoFramework.Hardware.Esp32.Touch
+{
+    /// <summary>
+    /// Specific to S2/S3, the denoise capacitance used to denoise the touch pad.
+    /// </summary>
+    public enum DenoiseCapacitance
+    {
+        /// <summary>Denoise channel internal reference capacitance is 5pf.</summary>
+        Cap5pf = 0,
+
+        /// <summary>Denoise channel internal reference capacitance is 6.4pf.</summary>
+        Cap6pf4 = 1,
+
+        /// <summary>Denoise channel internal reference capacitance is 7.8pf.</summary>
+        Cap7pf8 = 2,
+
+        /// <summary>Denoise channel internal reference capacitance is 9.2pf.</summary>
+        Cap9pf2 = 3,
+
+        /// <summary>Denoise channel internal reference capacitance is 10.6pf.</summary>
+        Cap10pf6 = 4,
+
+        /// <summary>Denoise channel internal reference capacitance is 12.0pf.</summary>
+        Cap12pf0 = 5,
+
+        /// <summary>Denoise channel internal reference capacitance is 13.4pf.</summary>
+        Cap13pf4 = 6,
+
+        /// <summary>Denoise channel internal reference capacitance is 14.8pf.</summary>
+        Cap14pf8 = 7,
+    }
+}

nanoFramework.Hardware.Esp32/Touch/DenoiseRange.cs

@@ -0,0 +1,24 @@
+// Copyright(c).NET Foundation and Contributors
+// See LICENSE file in the project root for full license information.
+
+namespace nanoFramework.Hardware.Esp32.Touch
+{
+    /// <summary>
+    /// Specific to S2/S3, the denoise range used to denoise the touch pad.
+    /// </summary>
+    public enum DenoiseRange
+    {
+        /// <summary>Denoise range is 12bit.</summary>
+        Bit12 = 0,
+
+        /// <summary>Denoise range is 10bit.</summary>
+        Bit10 = 1,
+
+        /// <summary>Denoise range is 8bit.</summary>
+        Bit8 = 2,
+
+        /// <summary>Denoise range is 4bit.</summary>
+        Bit4 = 3,
+
+    }
+}

nanoFramework.Hardware.Esp32/Touch/DenoiseSetting.cs

@@ -0,0 +1,38 @@
+// Copyright (c) .NET Foundation and Contributors
+// See LICENSE file in the project root for full license information.
+
+namespace nanoFramework.Hardware.Esp32.Touch
+{
+    /// <summary>
+    /// Specific to S2/S3, the denoise capacitance used to denoise the touch pad.
+    /// </summary>
+    public class DenoiseSetting
+    {
+        private DenoiseCapacitance _denoiseCapacitance;
+        private DenoiseRange _denoiseRange;
+
+        /// <summary>
+        /// Gets or sets the denoise capacitance.
+        /// </summary>
+        public DenoiseCapacitance DenoiseCapacitance
+        {
+            get => _denoiseCapacitance;
+            set
+            {
+                _denoiseCapacitance = value;
+            }
+        }
+
+        /// <summary>
+        /// Gets or sets the denoise range.
+        /// </summary>
+        public DenoiseRange DenoiseRange
+        {
+            get => _denoiseRange;
+            set
+            {
+                _denoiseRange = value;
+            }
+        }
+    }
+}

nanoFramework.Hardware.Esp32/Touch/Esp32FilterSetting.cs

@@ -0,0 +1,25 @@
+// Copyright (c) .NET Foundation and Contributors
+// See LICENSE file in the project root for full license information.
+
+namespace nanoFramework.Hardware.Esp32.Touch
+{
+    /// <summary>
+    /// ESP32 filter setting class.
+    /// </summary>
+    public class Esp32FilterSetting : IFilterSetting
+    {
+        private uint _period;
+
+        /// <summary>
+        /// The period in milliseconds for the filtering.
+        /// </summary>
+        public uint Period
+        {
+            get => _period;
+            set
+            {
+                _period = value;
+            }
+        }
+    }
+}

nanoFramework.Hardware.Esp32/Touch/FilterSettingDebounce.cs

@@ -0,0 +1,37 @@
+// Copyright (c) .NET Foundation and Contributors
+// See LICENSE file in the project root for full license information.
+
+using System;
+
+namespace nanoFramework.Hardware.Esp32.Touch
+{
+    /// <summary>
+    /// Set debounce count, such as n. If the measured values continue to exceed the threshold for n+1 times, the touch sensor state changes. Range: 0 ~ 7
+    /// </summary>
+    public enum FilterSettingDebounce
+    {
+        /// <summary>No debounce</summary>
+        NoDebounce = 0,
+
+        /// <summary>1 period.</summary>
+        One,
+
+        /// <summary>2 periods.</summary>
+        Two,
+
+        /// <summary>3 periods.</summary>
+        Three,
+
+        /// <summary>4 periods.</summary>
+        Four,
+
+        /// <summary>5 periods.</summary>
+        Five,
+
+        /// <summary>6 periods.</summary>
+        Six,
+
+        /// <summary>7 periods.</summary>
+        Seven,
+    }
+}