encoder.py: improve tracking of detents.

peterhinch · peterhinch · commit 60547a7a21b7 · 2022-04-21T13:49:38.000+01:00
diff --git a/v3/docs/DRIVERS.md b/v3/docs/DRIVERS.md
@@ -442,21 +442,21 @@ Constructor arguments:
  as `Pin.IN` and have pullups.
  2. `pin_y` Ditto.
  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` 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
+ 4. `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 can enable
  tracking of mechanical detents - typical values are then 4 or 2 pulses per
  click.
- 7. `callback=lambda a, b : None` Optional callback function. The callback
+ 5. `vmin=None` By default the `value` of the encoder can vary without limit.
+ Optionally maximum and/or minimum limits can be set.
+ 6. `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.
+ 7. `mod=None` An integer `N > 0` causes the divided value to be reduced modulo
+ `N` - useful for controlling rotary devices.
+ 8. `callback=lambda a, b : None` Optional callback function. The callback
  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.
- 8. `args=()` An optional tuple of positionl args for the callback.
- 9. `mod=0` An integer `N > 0` causes the divided value to be reduced modulo
- `N` - useful for controlling rotary devices.
+ 9. `args=()` An optional tuple of positionl args for the callback.
 
 Synchronous method:  
  * `value` No args. Returns an integer being the virtual encoder's current
diff --git a/v3/primitives/encoder.py b/v3/primitives/encoder.py
@@ -7,15 +7,15 @@
 from machine import Pin
 
 class Encoder:
-    delay = 100  # Pause (ms) for motion to stop
+    delay = 100  # Pause (ms) for motion to stop/limit callback frequency
 
-    def __init__(self, pin_x, pin_y, v=0, vmin=None, vmax=None, div=1,
-                 callback=lambda a, b : None, args=(), mod=0):
+    def __init__(self, pin_x, pin_y, v=0, div=1, vmin=None, vmax=None,
+                 mod=None, callback=lambda a, b : None, args=()):
         self._pin_x = pin_x
         self._pin_y = pin_y
         self._x = pin_x()
         self._y = pin_y()
-        self._v = 0  # Hardware value always starts at 0
+        self._v = v * div  # Initialise hardware value
         self._cv = v  # Current (divided) value
         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')
@@ -44,33 +44,31 @@ def _y_cb(self, pin_y):
             self._v -= 1 if y ^ self._pin_x() else -1
             self._tsf.set()
 
-    async def _run(self, vmin, vmax, div, modulo, cb, args):
+    async def _run(self, vmin, vmax, div, mod, 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
+        pcv = self._cv  # Prior divided value passed to callback
+        lcv = pcv  # Current value after limits applied
+        plcv = pcv  # Previous value after limits applied
         delay = self.delay
         while True:
             await self._tsf.wait()
-            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)
-            if modulo:
-                cv %= modulo
-            self._cv = cv  # For value()
-            if cv != pcv:
-                cb(cv, cv - pcv, *args)  # User CB in uasyncio context
+            await asyncio.sleep_ms(delay)  # Wait for motion to stop.
+            hv = self._v  # Sample hardware (atomic read).
+            if hv == pv:  # A change happened but was negated before
+                continue  # this got scheduled. Nothing to do.
+            pv = hv
+            cv = round(hv / div)  # cv is divided value.
+            if not (dv := cv - pcv):  # dv is change in divided value.
+                continue  # No change
+            lcv += dv  # lcv: divided value with limits/mod applied
+            lcv = lcv if vmax is None else min(vmax, lcv)
+            lcv = lcv if vmin is None else max(vmin, lcv)
+            lcv = lcv if mod is None else lcv % mod
+            self._cv = lcv  # update ._cv for .value() before CB.
+            if lcv != plcv:
+                cb(lcv, lcv - plcv, *args)  # Run user CB in uasyncio context
             pcv = cv
+            plcv = lcv
 
     def value(self):
         return self._cv
