Doc task group. Callback interface for ESP32 touchpads.

Author: peterhinch

v3/docs/DRIVERS.md

@@ -24,6 +24,7 @@ goes outside defined bounds.
   4.1 [Pushbutton class](./DRIVERS.md#41-pushbutton-class)  
        4.1.1 [The suppress constructor argument](./DRIVERS.md#411-the-suppress-constructor-argument)  
        4.1.2 [The sense constructor argument](./DRIVERS.md#412-the-sense-constructor-argument)  
+  4.2 [ESP32Touch class](./DRIVERS.md#42-esp32touch-class)  
  5. [ADC monitoring](./DRIVERS.md#5-adc-monitoring) Pause until an ADC goes out of bounds  
   5.1 [AADC class](./DRIVERS.md#51-aadc-class)  
   5.2 [Design note](./DRIVERS.md#52-design-note)  
@@ -321,6 +322,42 @@ the `closed` state of the button is active `high` or active `low`.
 See [Advanced use of callbacks](./DRIVERS.md#8-advanced-use-of-callbacks) for
 ways to retrieve a result from a callback and to cancel a task.
 
+## 4.2 ESP32Touch class
+
+This subclass of `Pushbutton` supports ESP32 touchpads providing a callback
+based interface. See the
+[official docs](http://docs.micropython.org/en/latest/esp32/quickref.html#capacitive-touch).
+
+API and usage are as per `Pushbutton` with the following provisos:
+ 1. The `sense` constructor arg is not supported.
+ 2. The `Pin` instance passed to the constructor must support the touch
+ interface. It is instantiated without args, as per the example below.
+ 3. There is an additional class variable `sensitivity` which should be a float
+ in range 0.0..1.0. The value `v` returned by the touchpad is read on
+ initialisation. The touchpad is polled and if the value drops below
+ `v * sensitivity` the pad is assumed to be pressed.
+
+Example usage:
+```python
+from machine import Pin
+from primitives import ESP32Touch
+import uasyncio as asyncio
+
+async def main():
+    tb = ESP32Touch(Pin(15), suppress=True)
+    tb.press_func(lambda : print("press"))
+    tb.double_func(lambda : print("double"))
+    tb.long_func(lambda : print("long"))
+    tb.release_func(lambda : print("release"))
+    while True:
+        await asyncio.sleep(1)
+
+asyncio.run(main())
+```
+If a touchpad is touched on initialisation no callbacks will occur even when
+the pad is released. Initial button state is always `False`. Normal behaviour
+will commence with subsequent touches.
+
 ###### [Contents](./DRIVERS.md#1-contents)
 
 # 5. ADC monitoring

v3/docs/TUTORIAL.md

@@ -38,7 +38,7 @@ REPL.
   3.8 [Delay_ms](./TUTORIAL.md#38-delay_ms-class) Software retriggerable delay.  
   3.9 [Message](./TUTORIAL.md#39-message)  
   3.10 [Synchronising to hardware](./TUTORIAL.md#310-synchronising-to-hardware)
-  Debouncing switches, pushbuttons and encoder knobs. Taming ADC's.  
+  Debouncing switches, pushbuttons, ESP32 touchpads and encoder knobs. Taming ADC's.  
  4. [Designing classes for asyncio](./TUTORIAL.md#4-designing-classes-for-asyncio)  
   4.1 [Awaitable classes](./TUTORIAL.md#41-awaitable-classes)  
        4.1.1 [Use in context managers](./TUTORIAL.md#411-use-in-context-managers)  

v3/primitives/__init__.py

@@ -38,6 +38,7 @@ def _handle_exception(loop, context):
     "Encode": "encoder_async",
     "Message": "message",
     "Pushbutton": "pushbutton",
+    "ESP32Touch": "pushbutton",
     "Queue": "queue",
     "Semaphore": "semaphore",
     "BoundedSemaphore": "semaphore",

v3/primitives/pushbutton.py

@@ -5,12 +5,12 @@
 
 import uasyncio as asyncio
 import utime as time
-from . import launch
-from primitives.delay_ms import Delay_ms
+from . import launch, Delay_ms
+try:
+    from machine import TouchPad
+except ImportError:
+    pass
 
-
-# An alternative Pushbutton solution with lower RAM use is available here
-# https://github.com/kevinkk525/pysmartnode/blob/dev/pysmartnode/utils/abutton.py
 class Pushbutton:
     debounce_ms = 50
     long_press_ms = 1000
@@ -109,3 +109,25 @@ async def buttoncheck(self):
 
     def deinit(self):
         self._run.cancel()
+
+
+class ESP32Touch(Pushbutton):
+    sensitivity = 0.9
+    def __init__(self, pin, suppress=False):
+        self._thresh = 0  # Detection threshold
+        self._rawval = 0
+        try:
+            self._pad = TouchPad(pin)
+        except ValueError:
+            raise ValueError(pin)  # Let's have a bit of information :)
+        super().__init__(pin, suppress, False)
+
+    # Current logical button state: True == touched
+    def rawstate(self):
+        rv = self._pad.read()  # ~220μs
+        if rv > self._rawval:  # Either initialisation or pad was touched
+            self._rawval = rv  # when initialised and has now been released
+            self._thresh = round(rv * ESP32Touch.sensitivity)
+            return False  # Untouched
+        return rv < self._thresh
+