DRIVERS.md: Improve encoder doc, add encoder_stop.py

peterhinch · peterhinch · commit 85dd861c84dc · 2022-05-08T18:40:01.000+01:00
diff --git a/v3/docs/DRIVERS.md b/v3/docs/DRIVERS.md
@@ -465,7 +465,9 @@ Synchronous method:
 Class variable:  
  * `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.
+ the callback is invoked. 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.
 
 Not all combinations of arguments make mathematical sense. The order in which
 operations are applied is:
diff --git a/v3/primitives/tests/encoder_stop.py b/v3/primitives/tests/encoder_stop.py
@@ -0,0 +1,39 @@
+# encoder_stop.py Demo of callback which occurs after motion has stopped.
+
+from machine import Pin
+import uasyncio as asyncio
+from primitives.encoder import Encoder
+from primitives.delay_ms import Delay_ms
+
+px = Pin('X1', Pin.IN, Pin.PULL_UP)
+py = Pin('X2', Pin.IN, Pin.PULL_UP)
+
+tim = Delay_ms(duration=400)  # High value for test
+d = 0
+
+def tcb(pos, delta):  # User callback gets args of encoder cb
+    global d
+    d = 0
+    print(pos, delta)
+
+def cb(pos, delta):  # Encoder callback occurs rapidly
+    global d
+    tim.trigger()  # Postpone the user callback
+    tim.callback(tcb, (pos, d := d + delta))  # and update its args
+
+async def main():
+    while True:
+        await asyncio.sleep(1)
+
+def test():
+    print('Running encoder test. Press ctrl-c to teminate.')
+    Encoder.delay = 0  # No need for this delay
+    enc = Encoder(px, py, callback=cb)
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        print('Interrupted')
+    finally:
+        asyncio.new_event_loop()
+
+test()
