Update IMU API

CHANGELOG.md

@@ -5,11 +5,16 @@
 ## Unreleased
 
 ### Added
-- Documented `positive_direction` in `DriveBase`.
-- Document deceleration setter in `DriveBase`.
 - Documented ``integral_deadzone`` in ``Control.pid()``.
 - Documented ``Motor.model``. This can be used to view the estimated motor
   state and change its settings.
+- Added `rotation`, `orientation`, `ready`, `stationary`
+  and `settings`  methods to `IMU` class.
+- Added `GyroDriveBase` class to `pybricks.robotics`.
+
+### Changed
+- Change implementation status of `IMU.heading` and `IMU.reset_heading`. They
+  are now implemented, with some limitations as noted in a note box.
 
 ## 3.2.0 - 2022-12-20
 

doc/common/extensions/requirements-static.py

@@ -24,10 +24,10 @@
 HUB_FEATURES = {
     "movehub": {"movehub"} | FEATURES_SMALL,
     "cityhub": {"cityhub"} | FEATURES_MEDIUM,
-    "technichub": {"technichub"} | FEATURES_MEDIUM,
-    "primehub": {"primehub", "inventorhub", "light-matrix"} | FEATURES_LARGE,
-    "inventorhub": {"primehub", "inventorhub", "light-matrix"} | FEATURES_LARGE,
-    "essentialhub": {"essentialhub"} | FEATURES_LARGE,
+    "technichub": {"technichub", "gyro"} | FEATURES_MEDIUM,
+    "primehub": {"primehub", "inventorhub", "light-matrix", "gyro"} | FEATURES_LARGE,
+    "inventorhub": {"primehub", "inventorhub", "light-matrix", "gyro"} | FEATURES_LARGE,
+    "essentialhub": {"essentialhub", "gyro"} | FEATURES_LARGE,
 }
 
 

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/hubs/essentialhub.rst

@@ -25,6 +25,10 @@ Essential Hub
 
     .. rubric:: Using the IMU
 
+    .. automethod:: pybricks.hubs::EssentialHub.imu.ready
+
+    .. automethod:: pybricks.hubs::EssentialHub.imu.stationary
+
     .. automethod:: pybricks.hubs::EssentialHub.imu.up
 
     .. automethod:: pybricks.hubs::EssentialHub.imu.tilt
@@ -37,6 +41,12 @@ Essential Hub
 
     .. automethod:: pybricks.hubs::EssentialHub.imu.reset_heading
 
+    .. automethod:: pybricks.hubs::EssentialHub.imu.rotation
+
+    .. automethod:: pybricks.hubs::EssentialHub.imu.orientation
+
+    .. automethod:: pybricks.hubs::EssentialHub.imu.settings
+
     .. rubric:: Using the battery
 
     .. automethod:: pybricks.hubs::EssentialHub.battery.voltage

doc/main/hubs/primehub.rst

@@ -59,6 +59,10 @@ Prime Hub / Inventor Hub
 
     .. rubric:: Using the IMU
 
+    .. automethod:: pybricks.hubs::PrimeHub.imu.ready
+
+    .. automethod:: pybricks.hubs::PrimeHub.imu.stationary
+
     .. automethod:: pybricks.hubs::PrimeHub.imu.up
 
     .. automethod:: pybricks.hubs::PrimeHub.imu.tilt
@@ -71,6 +75,12 @@ Prime Hub / Inventor Hub
 
     .. automethod:: pybricks.hubs::PrimeHub.imu.reset_heading
 
+    .. automethod:: pybricks.hubs::PrimeHub.imu.rotation
+
+    .. automethod:: pybricks.hubs::PrimeHub.imu.orientation
+
+    .. automethod:: pybricks.hubs::PrimeHub.imu.settings
+
     .. rubric:: Using the speaker
 
     .. automethod:: pybricks.hubs::PrimeHub.speaker.volume

doc/main/hubs/technichub.rst

@@ -21,6 +21,10 @@ Technic Hub
 
     .. rubric:: Using the IMU
 
+    .. automethod:: pybricks.hubs::TechnicHub.imu.ready
+
+    .. automethod:: pybricks.hubs::TechnicHub.imu.stationary
+
     .. automethod:: pybricks.hubs::TechnicHub.imu.up
 
     .. automethod:: pybricks.hubs::TechnicHub.imu.tilt
@@ -33,6 +37,12 @@ Technic Hub
 
     .. automethod:: pybricks.hubs::TechnicHub.imu.reset_heading
 
+    .. automethod:: pybricks.hubs::TechnicHub.imu.rotation
+
+    .. automethod:: pybricks.hubs::TechnicHub.imu.orientation
+
+    .. automethod:: pybricks.hubs::TechnicHub.imu.settings
+
     .. rubric:: Using the battery
 
     .. automethod:: pybricks.hubs::TechnicHub.battery.voltage

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

doc/main/robotics.rst

@@ -1,11 +1,10 @@
-.. pybricks-requirements::
-
 :mod:`robotics <pybricks.robotics>` -- Robotics and drive bases
 ===============================================================
 
 .. automodule:: pybricks.robotics
     :no-members:
 
+.. pybricks-requirements::
 
 .. autoclass:: pybricks.robotics.DriveBase
     :no-members:
@@ -103,9 +102,6 @@
     the default speed and acceleration for straight maneuvers and turns.
     Use the following attributes to adjust more advanced control settings.
 
-    You can only change the settings while the robot is stopped. This is
-    either before you begin driving or after you call :meth:`.stop`.
-
     .. autoattribute:: pybricks.robotics.DriveBase.distance_control
         :annotation:
 
@@ -116,11 +112,47 @@
 
         The :meth:`done` and :meth:`stalled` methods have been moved.
 
+
+.. pybricks-requirements:: gyro
+
+.. class:: GyroDriveBase
+
+    This class works just like the :class:`DriveBase`, but it uses the hub's
+    built-in gyroscope to drive straight and turn more accurately.
+
+    If your hub is not mounted flat in your robot, make sure to specify
+    the ``top_side`` and ``front_side`` parameters when you initialize the
+    :class:`PrimeHub() <pybricks.hubs.PrimeHub>`,
+    :class:`InventorHub() <pybricks.hubs.PrimeHub>`,
+    :class:`EssentialHub() <pybricks.hubs.EssentialHub>`, or
+    :class:`TechnicHub() <pybricks.hubs.TechnicHub>`. This way your robot
+    knows which rotation to measure when turning.
+
+    The gyro in each hub is a bit different, which can cause it to be a few
+    degrees off for big turns, or many small turns in the same
+    direction. For example, you may need to use
+    :meth:`turn(357) <pybricks.robotics.DriveBase.turn>` or
+    :meth:`turn(362) <pybricks.robotics.DriveBase.turn>`
+    on your robot to make a full turn.
+
+    By default, this class tries to maintain the robot's position after a move
+    completes. This means the wheels will spin if you pick the robot up, in an
+    effort to maintain its heading angle. To avoid this, you can choose
+    ``then=Stop.COAST`` in your last
+    :meth:`straight <pybricks.robotics.DriveBase.straight>`,
+    :meth:`turn <pybricks.robotics.DriveBase.turn>`, or
+    :meth:`curve <pybricks.robotics.DriveBase.curve>` command.
+
 Examples
 -------------------
 
 Driving straight and turning in place
 **********************************************
 
+The following program shows the basics of driving and turning.
+
+To use the built-in gyro, just replace the two occurences of
+:class:`DriveBase` with :class:`GyroDriveBase`.
+
 .. literalinclude::
     ../../examples/pup/robotics/drivebase_basics.py

examples/pup/robotics/drivebase_basics.py

@@ -14,10 +14,10 @@
 # Drive forward by 500mm (half a meter).
 drive_base.straight(500)
 
-# Turn around clockwise (180 degrees)
+# Turn around clockwise by 180 degrees.
 drive_base.turn(180)
 
-# Drive forward again to drive back.
+# Drive forward again to get back to the start.
 drive_base.straight(500)
 
 # Turn around counterclockwise.

jedi/tests/test_complete_essential_hub.py

@@ -79,7 +79,12 @@ def test_hub_dot_imu_dot():
         "acceleration",
         "angular_velocity",
         "heading",
+        "orientation",
+        "ready",
         "reset_heading",
+        "rotation",
+        "settings",
+        "stationary",
         "tilt",
         "up",
     ]

jedi/tests/test_complete_import.py

@@ -159,7 +159,7 @@ def test_from_pybricks_pupdevices_import():
 def test_from_pybricks_robotics_import():
     code = "from pybricks.robotics import "
     completions: list[CompletionItem] = json.loads(complete(code, 1, len(code) + 1))
-    assert [c["insertText"] for c in completions] == ["DriveBase"]
+    assert [c["insertText"] for c in completions] == ["DriveBase", "GyroDriveBase"]
 
 
 def test_from_pybricks_tools_import():

jedi/tests/test_complete_prime_hub.py

@@ -97,7 +97,12 @@ def test_hub_dot_imu_dot():
         "acceleration",
         "angular_velocity",
         "heading",
+        "orientation",
+        "ready",
         "reset_heading",
+        "rotation",
+        "settings",
+        "stationary",
         "tilt",
         "up",
     ]

jedi/tests/test_complete_technic_hub.py

@@ -67,7 +67,12 @@ def test_hub_dot_imu_dot():
         "acceleration",
         "angular_velocity",
         "heading",
+        "orientation",
+        "ready",
         "reset_heading",
+        "rotation",
+        "settings",
+        "stationary",
         "tilt",
         "up",
     ]

jedi/tests/test_get_signature.py

@@ -148,7 +148,6 @@ def _get_constructor_signature(module: str, type: str) -> SignatureHelp:
                 "right_motor: Motor",
                 "wheel_diameter: Number",
                 "axle_track: Number",
-                "positive_direction: Direction=Direction.CLOCKWISE",
             ]
         ],
     ),
@@ -308,12 +307,19 @@ def _get_method_signature(module: str, type: str, method: str) -> SignatureHelp:
         [(["axis: Axis"], "float"), ([], "Matrix")],
     ),
     pytest.param("pybricks.hubs", "TechnicHub", "imu.heading", [([], "float")]),
+    pytest.param("pybricks.hubs", "TechnicHub", "imu.orientation", [([], "Matrix")]),
     pytest.param(
         "pybricks.hubs",
         "TechnicHub",
         "imu.reset_heading",
         [(["angle: Number"], "None")],
     ),
+    pytest.param(
+        "pybricks.hubs",
+        "TechnicHub",
+        "imu.rotation",
+        [(["axis: Axis"], "float")],
+    ),
     pytest.param("pybricks.hubs", "TechnicHub", "battery.voltage", [([], "int")]),
     pytest.param("pybricks.hubs", "TechnicHub", "battery.current", [([], "int")]),
     pytest.param(
@@ -400,12 +406,19 @@ def _get_method_signature(module: str, type: str, method: str) -> SignatureHelp:
         [(["axis: Axis"], "float"), ([], "Matrix")],
     ),
     pytest.param("pybricks.hubs", "PrimeHub", "imu.heading", [([], "float")]),
+    pytest.param("pybricks.hubs", "PrimeHub", "imu.orientation", [([], "Matrix")]),
     pytest.param(
         "pybricks.hubs",
         "PrimeHub",
         "imu.reset_heading",
         [(["angle: Number"], "None")],
     ),
+    pytest.param(
+        "pybricks.hubs",
+        "PrimeHub",
+        "imu.rotation",
+        [(["axis: Axis"], "float")],
+    ),
     pytest.param(
         "pybricks.hubs",
         "PrimeHub",
@@ -483,12 +496,19 @@ def _get_method_signature(module: str, type: str, method: str) -> SignatureHelp:
         [(["axis: Axis"], "float"), ([], "Matrix")],
     ),
     pytest.param("pybricks.hubs", "EssentialHub", "imu.heading", [([], "float")]),
+    pytest.param("pybricks.hubs", "EssentialHub", "imu.orientation", [([], "Matrix")]),
     pytest.param(
         "pybricks.hubs",
         "EssentialHub",
         "imu.reset_heading",
         [(["angle: Number"], "None")],
     ),
+    pytest.param(
+        "pybricks.hubs",
+        "EssentialHub",
+        "imu.rotation",
+        [(["axis: Axis"], "float")],
+    ),
     pytest.param("pybricks.hubs", "EssentialHub", "battery.voltage", [([], "int")]),
     pytest.param("pybricks.hubs", "EssentialHub", "battery.current", [([], "int")]),
     pytest.param("pybricks.hubs", "EssentialHub", "charger.connected", [([], "bool")]),
@@ -522,7 +542,12 @@ def _get_method_signature(module: str, type: str, method: str) -> SignatureHelp:
         "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",