Add wait_all, ESwitch and Ebutton.

Author: peterhinch

v3/docs/TUTORIAL.md

@@ -705,15 +705,15 @@ constant creation of tasks. Arguably the `Barrier` class is the best approach.
 
 ### 3.2.1 Wait on multiple events
 
-The `wait_any` primitive allows a task to wait on a list of events. When one
+The `WaitAny` primitive allows a task to wait on a list of events. When one
 of the events is triggered, the task continues. It is effectively a logical
 `or` of events.
 ```python
-from primitives import wait_any
+from primitives import WaitAny
 evt1 = Event()
 evt2 = Event()
 # Launch tasks that might trigger these events
-evt = await wait_any((evt1, evt2))
+evt = await WaitAny((evt1, evt2))
 # One or other was triggered
 if evt == evt1:
     evt1.clear()
@@ -722,6 +722,18 @@ else:
     evt2.clear()
     # evt2 was triggered
 ```
+The `WaitAll` primitive is similar except that the calling task will pause
+until all passed `Event`s have been set:
+```python
+from primitives import WaitAll
+evt1 = Event()
+evt2 = Event()
+wa = WaitAll((evt1, evt2))  # 
+# Launch tasks that might trigger these events
+await wa
+# Both were triggered
+```
+Awaiting `WaitAll` or `WaitAny` may be cancelled or subject to a timeout.
 
 ###### [Contents](./TUTORIAL.md#contents)
 

v3/primitives/__init__.py

@@ -1,6 +1,6 @@
 # __init__.py Common functions for uasyncio primitives
 
-# Copyright (c) 2018-2020 Peter Hinch
+# Copyright (c) 2018-2022 Peter Hinch
 # Released under the MIT License (MIT) - see LICENSE file
 
 try:
@@ -30,20 +30,6 @@ def _handle_exception(loop, context):
     loop = asyncio.get_event_loop()
     loop.set_exception_handler(_handle_exception)
 
-async def wait_any(events):
-    evt = asyncio.Event()
-    trig_event = None
-    async def wt(event):
-        nonlocal trig_event
-        await event.wait()
-        evt.set()
-        trig_event = event
-    tasks = [asyncio.create_task(wt(event)) for event in events]
-    await evt.wait()
-    for task in tasks:
-        task.cancel()
-    return trig_event
-
 _attrs = {
     "AADC": "aadc",
     "Barrier": "barrier",
@@ -57,6 +43,10 @@ async def wt(event):
     "Semaphore": "semaphore",
     "BoundedSemaphore": "semaphore",
     "Switch": "switch",
+    "WaitAll": "events",
+    "WaitAny": "events",
+    "ESwitch": "events",
+    "EButton": "events",
 }
 
 # Copied from uasyncio.__init__.py

v3/primitives/events.py

@@ -0,0 +1,154 @@
+# events.py Event based primitives
+
+# Copyright (c) 2022 Peter Hinch
+# Released under the MIT License (MIT) - see LICENSE file
+
+import uasyncio as asyncio
+from . import Delay_ms
+
+# An Event-like class that can wait on an iterable of Event instances.
+# .wait pauses until any passed event is set.
+class WaitAny:
+    def __init__(self, events):
+        self.events = events
+        self.trig_event = None
+        self.evt = asyncio.Event()
+
+    async def wait(self):
+        tasks = [asyncio.create_task(self.wt(event)) for event in self.events]
+        try:
+            await self.evt.wait()
+        finally:
+            self.evt.clear()
+            for task in tasks:
+                task.cancel()
+        return self.trig_event
+
+    async def wt(self, event):
+        await event.wait()
+        self.evt.set()
+        self.trig_event = event
+ 
+    def event(self):
+        return self.trig_event
+
+# An Event-like class that can wait on an iterable of Event instances,
+# .wait pauses until all passed events have been set.
+class WaitAll:
+    def __init__(self, events):
+        self.events = events
+
+    async def wait(self):
+        async def wt(event):
+            await event.wait()
+        tasks = (asyncio.create_task(wt(event)) for event in self.events)
+        try:
+            await asyncio.gather(*tasks)
+        finally:  # May be subject to timeout or cancellation
+            for task in tasks:
+                task.cancel()
+
+# Minimal switch class having an Event based interface
+class ESwitch:
+    debounce_ms = 50
+
+    def __init__(self, pin, lopen=1):  # Default is n/o switch returned to gnd
+        self._pin = pin # Should be initialised for input with pullup
+        self._lopen = lopen  # Logic level in "open" state
+        self.open = asyncio.Event()
+        self.close = asyncio.Event()
+        self._state = self._pin() ^ self._lopen  # Get initial state
+        asyncio.create_task(self._poll(ESwitch.debounce_ms))
+
+    async def _poll(self, dt):  # Poll the button
+        while True:
+            if (s := self._pin() ^ self._lopen) != self._state:
+                self._state = s
+                self._of() if s else self._cf()
+            await asyncio.sleep_ms(dt)  # Wait out bounce
+
+    def _of(self):
+        self.open.set()
+
+    def _cf(self):
+        self.close.set()
+
+    # ***** API *****
+    # Return current state of switch (0 = pressed)
+    def __call__(self):
+        return self._state
+
+    def deinit(self):
+        self._poll.cancel()
+
+# Minimal pushbutton class having an Event based interface
+class EButton:
+    debounce_ms = 50  # Attributes can be varied by user
+    long_press_ms = 1000
+    double_click_ms = 400
+
+    def __init__(self, pin, suppress=False, sense=None):
+        self._pin = pin  # Initialise for input
+        self._supp = suppress
+        self._sense = pin() if sense is None else sense
+        self._state = self.rawstate()  # Initial logical state
+        self._ltim = Delay_ms(duration = EButton.long_press_ms)
+        self._dtim = Delay_ms(duration = EButton.double_click_ms)
+        self.press = asyncio.Event()  # *** API ***
+        self.double = asyncio.Event()
+        self.long = asyncio.Event()
+        self.release = asyncio.Event()  # *** END API ***
+        self._tasks = [asyncio.create_task(self._poll(EButton.debounce_ms))]  # Tasks run forever. Poll contacts
+        self._tasks.append(asyncio.create_task(self._ltf()))  # Handle long press
+        if suppress:
+            self._tasks.append(asyncio.create_task(self._dtf()))  # Double timer
+
+    async def _poll(self, dt):  # Poll the button
+        while True:
+            if (s := self.rawstate()) != self._state:
+                self._state = s
+                self._pf() if s else self._rf()
+            await asyncio.sleep_ms(dt)  # Wait out bounce
+
+    def _pf(self):  # Button press
+        if not self._supp:
+            self.press.set()  # User event
+        if not self._ltim():  # Don't retrigger long timer if already running
+            self._ltim.trigger()
+        if self._dtim():  # Press occurred while _dtim is running
+            self.double.set()  # User event
+            self._dtim.stop()  # _dtim's Event is only used if suppress
+        else:
+            self._dtim.trigger()
+
+    def _rf(self):  # Button release
+        self._ltim.stop()
+        if not self._supp or not self._dtim():  # If dtim running postpone release otherwise it
+            self.release.set()  # is set before press
+
+    async def _ltf(self):  # Long timeout
+        while True:
+            await self._ltim.wait()
+            self._ltim.clear()  # Clear the event
+            self.long.set()  # User event
+            
+    async def _dtf(self):  # Double timeout (runs if suppress is set)
+        while True:
+            await self._dtim.wait()
+            self._dtim.clear()  # Clear the event
+            if not self._ltim():  # Button was released
+                self.press.set()  # User events
+                self.release.set()
+
+    # ****** API ******
+    # Current non-debounced logical button state: True == pressed
+    def rawstate(self):
+        return bool(self._pin() ^ self._sense)
+
+    # Current debounced state of button (True == pressed)
+    def __call__(self):
+        return self._state
+
+    def deinit(self):
+        for task in self._tasks:
+            task.cancel()