Merge pull request #923 from pimoroni/patch/inventor_encoders

Added example for reading speeds from Inventor 2040W's encoders

micropython/examples/inventor2040w/README.md

@@ -4,6 +4,7 @@
   - [Read ADCs](#read-adcs)
   - [Read GPIOs](#read-gpios)
   - [Read Encoders](#read-encoders)
+  - [Read Speeds](#read-speeds)
   - [LED Rainbow](#led-rainbow)
   - [Reset Inventor](#reset-inventor)
 - [Motor Examples](#motor-examples)
@@ -22,13 +23,14 @@
   - [Velocity Tuning](#velocity-tuning)
   - [Position on Velocity Tuning](#position-on-velocity-tuning)
 - [Servo Examples](#servo-examples)
-  - [Single Servos](#single-servo)
+  - [Single Servo](#single-servo)
   - [Multiple Servos](#multiple-servos)
   - [Simple Easing](#simple-easing)
   - [Servo Wave](#servo-wave)
   - [Calibration](#calibration)
 - [Audio Examples](#audio-examples)
   - [Tone Song](#tone-song)
+  - [Motor Song](#motor-song)
 
 ## Function Examples
 
@@ -50,6 +52,12 @@ Shows how to initialise and read the 6 GPIO headers of Inventor 2040 W.
 Demonstrates how to read the angles of Inventor 2040 W's two encoders.
 
 
+### Read Speeds
+[read_speeds.py](read_speeds.py)
+
+Demonstrates how to read the speeds of Inventor 2040 W's two encoders.
+
+
 ### LED Rainbow
 [led_rainbow.py](led_rainbow.py)
 

micropython/examples/inventor2040w/read_speeds.py

@@ -0,0 +1,46 @@
+import time
+from inventor import Inventor2040W, NUM_MOTORS  # , MOTOR_A, MOTOR_B
+# from pimoroni import REVERSED_DIR
+
+"""
+Demonstrates how to read the speeds of Inventor 2040 W's two encoders.
+
+Press "User" to exit the program.
+"""
+
+# Wheel friendly names
+NAMES = ["LEFT", "RIGHT"]
+
+# Constants
+GEAR_RATIO = 50                         # The gear ratio of the motor
+SPEED = 1.0                             # The speed to drive the motors at
+SLEEP = 0.1                             # The time to sleep between each capture
+
+# Create a new Inventor2040W
+board = Inventor2040W(motor_gear_ratio=GEAR_RATIO)
+
+# Uncomment the below lines (and the top imports) to
+# reverse the counting direction of an encoder
+# encoders[MOTOR_A].direction(REVERSED_DIR)
+# encoders[MOTOR_B].direction(REVERSED_DIR)
+
+# Set both motors driving
+for motor in board.motors:
+    motor.speed(SPEED)
+
+# Variables for storing encoder captures
+captures = [None] * NUM_MOTORS
+
+# Read the encoders until the user button is pressed
+while not board.switch_pressed():
+
+    # Capture the state of all the encoders since the last capture, SLEEP seconds ago
+    for i in range(NUM_MOTORS):
+        captures[i] = board.encoders[i].capture()
+
+    # Print out the speeds from each encoder
+    for i in range(NUM_MOTORS):
+        print(NAMES[i], "=", captures[i].revolutions_per_second, end=", ")
+    print()
+
+    time.sleep(SLEEP)

micropython/modules/encoder/README.md

@@ -6,6 +6,7 @@ This library offers an `Encoder` class that uses Programmable IO (PIO) hardware
 
 
 ## Table of Content
+- [Table of Content](#table-of-content)
 - [Encoder](#encoder)
   - [Getting Started](#getting-started)
   - [Count and Angle](#count-and-angle)
@@ -102,7 +103,22 @@ degrees_per_second
 radians_per_second
 ```
 
-Internally `.capture()` does the same up-front reading of values but does so more optimally within the underlying C++ driver. As an added bonus, it calculates encoder speeds too, by using the captured `delta` along with timing information returned by the PIO, more accurately than estimating a speed from the `delta` alone.
+Internally `.capture()` does the same up-front reading of values but does so more optimally within the underlying C++ driver. It calculates encoder speeds too, by using the difference between the current `count` and the **last capture's** `count` (aka the `delta`), along with timing information returned by the PIO. This produces speed readings that are more accurate than estimating a speed from the `delta` alone.
+
+:information_source: **It is recommended to perform captures frequently and at a consistent rate.** If this is not possible for your project, consider performing a dummy capture at the start of the time window you actually wish to measure the encoder's speed over.
+
+```python
+# Perform a dummy capture to clear the encoder
+enc.capture()
+
+# Wait for the capture time to pass
+time.sleep(CAPTURE_TIME)
+
+# Perform a capture and read the measured speed
+capture = enc.capture()
+
+print("Speed =", capture.revolutions_per_second)
+```
 
 
 ### State