pybricks.pupdevices.Motor: Document speed time window.

doc/main/ev3devices.rst

@@ -20,12 +20,12 @@ Motors
 
     .. rubric:: Measuring
 
-    .. automethod:: pybricks.ev3devices.Motor.speed
-
     .. automethod:: pybricks.ev3devices.Motor.angle
 
     .. automethod:: pybricks.ev3devices.Motor.reset_angle
 
+    .. automethod:: pybricks.ev3devices.Motor.speed
+
     .. automethod:: pybricks.ev3devices.Motor.load
 
     .. automethod:: pybricks.ev3devices.Motor.stalled

doc/main/pupdevices/motor.rst

@@ -18,12 +18,12 @@ Motors with rotation sensors
 
     .. rubric:: Measuring
 
-    .. automethod:: pybricks.pupdevices.Motor.speed
-
     .. automethod:: pybricks.pupdevices.Motor.angle
 
     .. automethod:: pybricks.pupdevices.Motor.reset_angle
 
+    .. automethod:: pybricks.pupdevices.Motor.speed
+
     .. automethod:: pybricks.pupdevices.Motor.load
 
     .. automethod:: pybricks.pupdevices.Motor.stalled

jedi/tests/test_get_signature.py

@@ -543,7 +543,12 @@ METHOD_PARAMS = [
         "settings",
         [(["max_voltage: Number"], "None"), ([], "Tuple[int]")],
     ),
-    pytest.param("pybricks.pupdevices", "Motor", "speed", [([], "int")]),
+    pytest.param(
+        "pybricks.pupdevices",
+        "Motor",
+        "speed",
+        [(["window: Number=100"], "int")],
+    ),
     pytest.param("pybricks.pupdevices", "Motor", "angle", [([], "int")]),
     pytest.param(
         "pybricks.pupdevices",

src/pybricks/_common.py

@@ -408,11 +408,19 @@ class Motor(DCMotor):
             Motor angle.
         """
 
-    def speed(self) -> int:
-        """speed() -> int: deg/s
+    def speed(self, window: Number = 100) -> int:
+        """speed(window=100) -> int: deg/s
 
         Gets the speed of the motor.
 
+        The speed is measured as the change in the motor angle during the
+        given time window. A short window makes the speed value more
+        responsive to motor movement, but less steady. A long window makes the
+        speed value less responsive, but more steady.
+
+        Arguments:
+            window (Number, ms): The time window used to determine the speed.
+
         Returns:
             Motor speed.