pybricks.robotics: Add GyroDriveBase.

CHANGELOG.md

@@ -10,6 +10,7 @@
   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

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/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:
@@ -113,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_import.py

@@ -159,9 +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():

src/pybricks/robotics.py

@@ -222,6 +222,12 @@ def stalled(self) -> bool:
         """
 
 
+class GyroDriveBase(DriveBase):
+    """A robotic vehicle with two powered wheels and an optional support
+    wheel or caster. It measures the heading using the hub's built-in gyroscope,
+    which can make turning and driving straight more accurate."""
+
+
 # HACK: hide from jedi
 if TYPE_CHECKING:
     del Motor