Encoder: Improve driver, document.

Author: peterhinch

v3/docs/DRIVERS.md

@@ -866,7 +866,7 @@ behaviour.
 
 The `Encoder` can be instantiated in such a way that its effective resolution
 can be reduced. A virtual encoder with lower resolution can be useful in some
-applications.
+applications. In particular it can track the "clicks" of a mechanical detent.
 
 The driver allows limits to be assigned to the virtual encoder's value so that
 a dial running from (say) 0 to 100 may be implemented. If limits are used,
@@ -908,10 +908,10 @@ Constructor arguments:
  receives two integer args, `v` being the virtual encoder's current value and
  `delta` being the signed difference between the current value and the previous
  one. Further args may be appended by the following.
- 9. `args=()` An optional tuple of positionl args for the callback.
+ 9. `args=()` An optional tuple of positional args for the callback.
  10. `delay=100` After motion is detected the driver waits for `delay` ms before
- reading the current position. A delay can be used to limit the rate at which
- the callback is invoked. This is a minimal approach. See
+ reading the current position. A delay limits the rate at which the callback is
+ invoked and improves debouncing. This is a minimal approach. See
  [this script](https://github.com/peterhinch/micropython-async/blob/master/v3/primitives/tests/encoder_stop.py)
  for a way to create a callback which runs only when the encoder stops moving.
 

v3/docs/TUTORIAL.md

@@ -1163,13 +1163,14 @@ async def foo(tsf):  # Periodically set the ThreadSafeFlag
         await asyncio.sleep(1)
         tsf.set()
 
-def ready(tsf, poller):
-    poller.register(tsf, POLLIN)
+    def ready(tsf, poller):
+        r = (tsf, POLLIN)
+        poller.register(*r)
 
-    def is_rdy():
-        return len([t for t in poller.ipoll(0) if t[0] is tsf]) > 0
+        def is_rdy():
+            return r in poller.ipoll(0)
 
-    return is_rdy
+        return is_rdy
 
 async def test():
     tsf = asyncio.ThreadSafeFlag()

v3/primitives/encoder.py

@@ -1,9 +1,9 @@
 # encoder.py Asynchronous driver for incremental quadrature encoder.
 
-# Copyright (c) 2021-2022 Peter Hinch
+# Copyright (c) 2021-2023 Peter Hinch
 # Released under the MIT License (MIT) - see LICENSE file
 
-# For an explanation of the design please see 
+# For an explanation of the design please see
 # [ENCODERS.md](https://github.com/peterhinch/micropython-samples/blob/master/encoders/ENCODERS.md)
 
 # Thanks are due to the following collaborators:
@@ -19,11 +19,33 @@
 
 import uasyncio as asyncio
 from machine import Pin
+from select import poll, POLLIN
 
-class Encoder:
 
-    def __init__(self, pin_x, pin_y, v=0, div=1, vmin=None, vmax=None,
-                 mod=None, callback=lambda a, b : None, args=(), delay=100):
+def ready(tsf, poller):
+    r = (tsf, POLLIN)
+    poller.register(*r)
+
+    def is_rdy():
+        return r in poller.ipoll(0)
+
+    return is_rdy
+
+
+class Encoder:
+    def __init__(
+        self,
+        pin_x,
+        pin_y,
+        v=0,
+        div=1,
+        vmin=None,
+        vmax=None,
+        mod=None,
+        callback=lambda a, b: None,
+        args=(),
+        delay=100,
+    ):
         self._pin_x = pin_x
         self._pin_y = pin_y
         self._x = pin_x()
@@ -34,8 +56,9 @@ def __init__(self, pin_x, pin_y, v=0, div=1, vmin=None, vmax=None,
         self._trig = asyncio.Event()
 
         if ((vmin is not None) and v < vmin) or ((vmax is not None) and v > vmax):
-            raise ValueError('Incompatible args: must have vmin <= v <= vmax')
+            raise ValueError("Incompatible args: must have vmin <= v <= vmax")
         self._tsf = asyncio.ThreadSafeFlag()
+        self._tsf_ready = ready(self._tsf, poll())  # Create a ready function
         trig = Pin.IRQ_RISING | Pin.IRQ_FALLING
         try:
             xirq = pin_x.irq(trigger=trig, handler=self._x_cb, hard=True)
@@ -67,6 +90,8 @@ async def _run(self, vmin, vmax, div, mod, cb, args):
         plcv = pcv  # Previous value after limits applied
         delay = self.delay
         while True:
+            if delay > 0 and self._tsf_ready():  # Ensure ThreadSafeFlag is clear
+                await self._tsf.wait()
             await self._tsf.wait()
             await asyncio.sleep_ms(delay)  # Wait for motion to stop.
             hv = self._v  # Sample hardware (atomic read).