Pushbutton: suppress release on long and double clicks.

Author: peterhinch

DRIVERS.md

@@ -16,8 +16,7 @@ events.
  and also a software retriggerable delay object. Pushbuttons are a
  generalisation of switches providing logical rather than physical status along
  with double-clicked and long pressed events.
- 3. `asyn.py` Provides synchronisation primitives. Required by `aswitch.py`.
- 4. `astests.py` Test/demonstration programs for `aswitch.py`.
+ 3. `astests.py` Test/demonstration programs for `aswitch.py`.
 
 # 3. Module aswitch.py
 
@@ -104,7 +103,7 @@ scheduled for execution and will run asynchronously.
 Constructor arguments:
 
  1. `pin` Mandatory. The initialised Pin instance.
- 2. `lpmode` Default `False`. See below.
+ 2. `suppress` Default `False`. See 3.2.1 below.
 
 Methods:
 
@@ -148,17 +147,28 @@ loop = asyncio.get_event_loop()
 loop.run_until_complete(my_app())  # Run main application code
 ```
 
-The `lpmode` constructor argument modifies the behaviour of `press_func` in the
-event that a `long_func` is specified.
-
-If `lpmode` is `False`, if a button press occurs `press_func` runs immediately;
-`long_func` runs if the button is still pressed when the timeout has elapsed.
-If `lpmode` is `True`, `press_func` is delayed until button release. If, at the
-time of release, `long_func` has run, `press_func` will be suppressed.
-
-The default provides for low latency but a long button press will trigger
-`press_func` and `long_func`. `lpmode` = `True` prevents `press_func` from
-running.
+### 3.2.1 The suppress constructor argument
+
+When the button is pressed `press_func` runs immediately. This minimal latency
+is ideal for applications such as games, but does imply that in the event of a
+long press, both `press_func` and `long_func` run: `press_func` immediately and
+`long_func` if the button is still pressed when the timer has elapsed. Similar
+reasoning applies to the double click function.
+
+There can be a need for a **function** which runs if a button is pressed but
+only if a doubleclick or long press function does not run. The soonest that the
+absence of a long press can be detected is on button release. The absence of a
+double click can only be detected when the double click timer times out without
+a second press occurring.
+
+This **function** is the `release_func`. If the `suppress` constructor arg is
+set, `release_func` will be launched as follows:
+ 1. If `double_func` does not exist on rapid button release.
+ 2. If `double_func` exists, after the expiration of the doubleclick timer.
+ 3. If `long_func` exists and the press duration causes `long_func` to be
+ launched, `release_func` will not be launched.
+ 4. If `double_func` exists and a double click occurs, `release_func` will not
+ be launched.
 
 ## 3.3 Delay_ms class
 
@@ -192,6 +202,7 @@ Methods:
  2. `stop` No argument. Cancels the timeout, setting the `running` status
  `False`. The timer can be restarted by issuing `trigger` again.
  3. `running` No argument. Returns the running status of the object.
+ 4. `__call__` Alias for running.
 
 If the `trigger` method is to be called from an interrupt service routine the
 `can_alloc` constructor arg should be `False`. This causes the delay object
@@ -236,11 +247,18 @@ of its behaviour if the switch is toggled rapidly.
 
 Demonstrates the use of callbacks to toggle the red and green LED's.
 
-## 4.3 Function test_btn()
+## 4.3 Function test_btn(lpmode=False)
 
 This will flash the red LED on button push, and the green LED on release. A
 long press will flash the blue LED and a double-press the yellow one.
 
+Test the launching of coroutines and also the `suppress` constructor arg.
+
+It takes three optional positional boolean args:
+ 1. `Suppresss=False` If `True` sets the `suppress` constructor arg.
+ 2. `lf=True` Declare a long press coro.
+ 3. `df=true` Declare a double click coro.
+
 The note below on race conditions applies.
 
 ## 4.4 Function test_btncb()
@@ -268,3 +286,6 @@ In the case of this test program it might be to ignore events while a similar
 one is running, or to extend the timer to prolong the LED illumination.
 Alternatively a subsequent button press might be required to terminate the
 illumination. The "right" behaviour is application dependent.
+
+A further consequence of scheduling new coroutine instances when one or more
+are already running is that the `uasyncio` queue can fill causing an exception.

astests.py

@@ -2,7 +2,7 @@
 # Tested on Pyboard but should run on other microcontroller platforms
 # running MicroPython with uasyncio library.
 # Author: Peter Hinch.
-# Copyright Peter Hinch 2017 Released under the MIT license.
+# Copyright Peter Hinch 2017-2018 Released under the MIT license.
 
 from machine import Pin
 from pyb import LED
@@ -60,20 +60,22 @@ def test_swcb():
     loop.run_until_complete(killer())
 
 # Test for the Pushbutton class (coroutines)
-# Pass True to test lpmode
-def test_btn(lpmode=False):
+# Pass True to test suppress
+def test_btn(suppress=False, lf=True, df=True):
     print('Test of pushbutton scheduling coroutines.')
     print(helptext)
     pin = Pin('X1', Pin.IN, Pin.PULL_UP)
     red = LED(1)
     green = LED(2)
     yellow = LED(3)
     blue = LED(4)
-    pb = Pushbutton(pin, lpmode)
+    pb = Pushbutton(pin, suppress)
     pb.press_func(pulse, (red, 1000))
     pb.release_func(pulse, (green, 1000))
-    pb.double_func(pulse, (yellow, 1000))
-    pb.long_func(pulse, (blue, 1000))
+    if df:
+        pb.double_func(pulse, (yellow, 1000))
+    if lf:
+        pb.long_func(pulse, (blue, 1000))
     loop = asyncio.get_event_loop()
     loop.run_until_complete(killer())
 

aswitch.py

@@ -67,6 +67,8 @@ def trigger(self, duration=0):  # Update end time
     def running(self):
         return self.tstop is not None
 
+    __call__ = running
+
     async def killer(self):
         twait = time.ticks_diff(self.tstop, time.ticks_ms())
         while twait > 0:  # Must loop here: might be retriggered
@@ -118,34 +120,37 @@ class Pushbutton(object):
     debounce_ms = 50
     long_press_ms = 1000
     double_click_ms = 400
-    def __init__(self, pin, lpmode=False):
+    def __init__(self, pin, suppress=False):
         self.pin = pin # Initialise for input
-        self._lpmode = lpmode
-        self._press_pend = False
-        self._true_func = False
-        self._false_func = False
-        self._double_func = False
-        self._long_func = False
+        self._supp = suppress
+        self._dblpend = False  # Doubleclick waiting for 2nd click
+        self._dblran = False  # Doubleclick executed user function
+        self._tf = False
+        self._ff = False
+        self._df = False
+        self._lf = False
+        self._ld = False  # Delay_ms instance for long press
+        self._dd = False  # Ditto for doubleclick
         self.sense = pin.value()  # Convert from electrical to logical value
         self.buttonstate = self.rawstate()  # Initial state
         loop = asyncio.get_event_loop()
         loop.create_task(self.buttoncheck())  # Thread runs forever
 
     def press_func(self, func, args=()):
-        self._true_func = func
-        self._true_args = args
+        self._tf = func
+        self._ta = args
 
     def release_func(self, func, args=()):
-        self._false_func = func
-        self._false_args = args
+        self._ff = func
+        self._fa = args
 
     def double_func(self, func, args=()):
-        self._double_func = func
-        self._double_args = args
+        self._df = func
+        self._da = args
 
     def long_func(self, func, args=()):
-        self._long_func = func
-        self._long_args = args
+        self._lf = func
+        self._la = args
 
     # Current non-debounced logical button state: True == pressed
     def rawstate(self):
@@ -155,42 +160,55 @@ def rawstate(self):
     def __call__(self):
         return self.buttonstate
 
+    def _ddto(self):  # Doubleclick timeout: no doubleclick occurred
+        self._dblpend = False
+        if self._supp:
+            if not self._ld or (self._ld and not self._ld()):
+                launch(self._ff, self._fa)
+
+    def _ldip(self):  # True if a long delay exists and is running
+        d = self._ld
+        return d and d()
+
     async def buttoncheck(self):
         loop = asyncio.get_event_loop()
-        if self._long_func:
-            longdelay = Delay_ms(self._long_func, self._long_args)
-        if self._double_func:
-            doubledelay = Delay_ms()
+        if self._lf:
+            self._ld = Delay_ms(self._lf, self._la)
+        if self._df:
+            self._dd = Delay_ms(self._ddto)
         while True:
             state = self.rawstate()
             # State has changed: act on it now.
             if state != self.buttonstate:
                 self.buttonstate = state
                 if state:
                     # Button is pressed
-                    if self._long_func and not longdelay.running():
+                    if self._lf:
                         # Start long press delay
-                        longdelay.trigger(Pushbutton.long_press_ms)
-                    if self._double_func:
-                        if doubledelay.running():
-                            launch(self._double_func, self._double_args)
+                        self._ld.trigger(Pushbutton.long_press_ms)
+                    if self._df:
+                        if self._dd():
+                            self._dd.stop()
+                            self._dblpend = False
+                            self._dblran = True  # Prevent suppressed launch on release
+                            launch(self._df, self._da)
                         else:
                             # First click: start doubleclick timer
-                            doubledelay.trigger(Pushbutton.double_click_ms)
-                    if self._true_func:
-                        if self._long_func and self._lpmode:
-                            self._press_pend = True  # Delay launch until release
-                        else:
-                            launch(self._true_func, self._true_args)
+                            self._dd.trigger(Pushbutton.double_click_ms)
+                            self._dblpend = True  # Prevent suppressed launch on release
+                    if self._tf:
+                        launch(self._tf, self._ta)
                 else:
                     # Button release
-                    if longdelay.running():
+                    if self._ff:
+                        if self._supp:
+                            if self._ldip() and not self._dblpend and not self._dblran:
+                                launch(self._ff, self._fa)
+                        else:
+                            launch(self._ff, self._fa)
+                    if self._ldip():
                         # Avoid interpreting a second click as a long push
-                        longdelay.stop()
-                        if self._press_pend:
-                            launch(self._true_func, self._true_args)
-                    if self._false_func:
-                        launch(self._false_func, self._false_args)
-                    self._press_pend = False
+                        self._ld.stop()
+                    self._dblran = False
             # Ignore state changes until switch has settled
             await asyncio.sleep_ms(Pushbutton.debounce_ms)