Encoder primitive now has div arg.

Author: peterhinch

v3/docs/DRIVERS.md

@@ -353,15 +353,22 @@ must be tracked.
 
 This driver runs the user supplied callback in an `asyncio` context, so it runs
 only when other tasks have yielded to the scheduler. This ensures that the
-callback can run safely. The driver allows limits to be assigned to the control
-so that a dial running from (say) 0 to 100 may be implemented. If limits are
-used, encoder values no longer represent absolute angles.
+callback can run safely, even if it triggers complex application behaviour.
 
-The callback only runs if a change in position has occurred.
+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.
 
-A consequence of the callback running in an `asyncio` context is that, by the
-time it runs, the encoder's position may have changed by more than one
-increment. 
+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 arenused,
+encoder values no longer represent absolute angles, as the user might continue
+to rotate the dial when it is "stuck" at an endstop.
+
+The callback only runs if a change in position of the virtual encoder has
+occurred. In consequence of the callback running in an `asyncio` context, by
+the time it is scheduled, the encoder's position may have changed by more than
+one increment. The callback receives two args, the absolute value of the
+virtual encoder and the signed change since the previous callback run.
 
 ## 6.1 Encoder class
 
@@ -372,18 +379,39 @@ Constructor arguments:
  3. `v=0` Initial value.
  4. `vmin=None` By default the `value` of the encoder can vary without limit.
  Optionally maximum and/or minimum limits can be set.
- 5. `vmax=None`
- 6. `callback=lambda *_ : None` Optional callback function. The callback
+ 5. `vmax=None` As above. If `vmin` and/or `vmax` are specified, a `ValueError`
+ will be thrown if the initial value `v` does not conform with the limits.
+ 6. `div=1` A value > 1 causes the motion rate of the encoder to be divided
+ down, to produce a virtual encoder with lower resolution. This was found usefl
+ in some applications with the Adafruit encoder.
+ 7. `callback=lambda a, b : None` Optional callback function. The callback
  receives two args, `v` being the 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.
- 7. `args=()` An optional tuple of args for the callback.
+ 8. `args=()` An optional tuple of args for the callback.
 
 Synchronous method:  
  * `value` No args. Returns an integer being the `Encoder` current value.
 
 Class variable:  
- * `LATENCY=50` This sets a minumum period (in ms) between callback runs.
+ * `delay=100` After motion is detected the driver waits for `delay` ms before
+ reading the current position. This was found useful with the Adafruit encoder
+ which has mechanical detents, which span multiple increments or decrements. A
+ delay gives time for motion to stop, enabling just one call to the callback.
+
+#### Note
+
+The driver works by maintaining an internal value `._v` which uses hardware
+interrupts to track the absolute position of the physical encoder. In theory
+this should be precise, but on ESP32 with the Adafruit encoder it is not.
+
+Currently under investigation: it may be a consequence of ESP32's use of soft
+IRQ's.
+
+This is probably of little practical consequence as encoder knobs are usually
+used in systems where there is user feedback. In a practical application
+([ugui](https://github.com/peterhinch/micropython-micro-gui)) I can see no
+evidence of the missed pulses.
 
 ###### [Contents](./DRIVERS.md#1-contents)
 

v3/primitives/encoder.py

@@ -3,29 +3,32 @@
 # Copyright (c) 2021 Peter Hinch
 # Released under the MIT License (MIT) - see LICENSE file
 
-# This driver is intended for encoder-based control knobs. It is not
-# suitable for NC machine applications. Please see the docs.
+# This driver is intended for encoder-based control knobs. It is
+# unsuitable for NC machine applications. Please see the docs.
 
 import uasyncio as asyncio
 from machine import Pin
 
 class Encoder:
-    LATENCY = 50
+    delay = 100  # Pause (ms) for motion to stop
 
-    def __init__(self, pin_x, pin_y, v=0, vmin=None, vmax=None,
+    def __init__(self, pin_x, pin_y, v=0, vmin=None, vmax=None, div=1,
                  callback=lambda a, b : None, args=()):
         self._pin_x = pin_x
         self._pin_y = pin_y
-        self._v = v
+        self._v = 0  # Hardware value always starts at 0
+        self._cv = v  # Current (divided) value
+        if ((vmin is not None) and v < min) or ((vmax is not None) and v > vmax):
+            raise ValueError('Incompatible args: must have vmin <= v <= vmax')
         self._tsf = asyncio.ThreadSafeFlag()
+        trig = Pin.IRQ_RISING | Pin.IRQ_FALLING
         try:
-            xirq = pin_x.irq(trigger=Pin.IRQ_RISING | Pin.IRQ_FALLING, handler=self._x_cb, hard=True)
-            yirq = pin_y.irq(trigger=Pin.IRQ_RISING | Pin.IRQ_FALLING, handler=self._y_cb, hard=True)
-        except TypeError:
-            xirq = pin_x.irq(trigger=Pin.IRQ_RISING | Pin.IRQ_FALLING, handler=self._x_cb)
-            yirq = pin_y.irq(trigger=Pin.IRQ_RISING | Pin.IRQ_FALLING, handler=self._y_cb)
-        asyncio.create_task(self._run(vmin, vmax, callback, args))
-
+            xirq = pin_x.irq(trigger=trig, handler=self._x_cb, hard=True)
+            yirq = pin_y.irq(trigger=trig, handler=self._y_cb, hard=True)
+        except TypeError:  # hard arg is unsupported on some hosts
+            xirq = pin_x.irq(trigger=trig, handler=self._x_cb)
+            yirq = pin_y.irq(trigger=trig, handler=self._y_cb)
+        asyncio.create_task(self._run(vmin, vmax, div, callback, args))
 
     # Hardware IRQ's
     def _x_cb(self, pin):
@@ -38,21 +41,32 @@ def _y_cb(self, pin):
         self._v += 1 if fwd else -1
         self._tsf.set()
 
-    async def _run(self, vmin, vmax, cb, args):
-        pv = self._v  # Prior value
+    async def _run(self, vmin, vmax, div, cb, args):
+        pv = self._v  # Prior hardware value
+        cv = self._cv  # Current divided value as passed to callback
+        pcv = cv  # Prior divided value passed to callback
+        mod = 0
+        delay = self.delay
         while True:
             await self._tsf.wait()
-            cv = self._v  # Current value
+            await asyncio.sleep_ms(delay)  # Wait for motion to stop
+            new = self._v  # Sample hardware (atomic read)
+            a = new - pv  # Hardware change
+            # Ensure symmetrical bahaviour for + and - values
+            q, r = divmod(abs(a), div)
+            if a < 0:
+                r = -r
+                q = -q
+            pv = new - r  # Hardware value when local value was updated
+            cv += q
             if vmax is not None:
                 cv = min(cv, vmax)
             if vmin is not None:
                 cv = max(cv, vmin)
-            self._v = cv
-            #print(cv, pv)
-            if cv != pv:
-                cb(cv, cv - pv, *args)  # User CB in uasyncio context
-                pv = cv
-            await asyncio.sleep_ms(self.LATENCY)
+            self._cv = cv  # For value()
+            if cv != pcv:
+                cb(cv, cv - pcv, *args)  # User CB in uasyncio context
+            pcv = cv
 
     def value(self):
-        return self._v
+        return self._cv