pybricks.robotics.DriveBase: Add stalled, done.

CHANGELOG.md

@@ -7,6 +7,7 @@
 ### Added
 - Documented ``Stop.NONE`` and ``Stop.COAST_SMART``.
 - Documented ``ujson`` module.
+- Added `done` and `stalled` methods for `DriveBase`.
 
 ### Changed
 - Changed `PrimeHub.display.image()` to `PrimeHub.display.icon()` and renamed

doc/main/robotics.rst

@@ -10,7 +10,7 @@
 .. autoclass:: pybricks.robotics.DriveBase
     :no-members:
 
-    .. rubric:: Driving for a given distance or by an angle
+    .. rubric:: Driving by a given distance or angle
 
     Use the following commands to drive a given distance, or turn by a
     given angle.
@@ -26,6 +26,8 @@
 
     .. automethod:: pybricks.robotics.DriveBase.settings
 
+    .. automethod:: pybricks.robotics.DriveBase.done
+
     .. rubric:: Drive forever
 
     Use :meth:`.drive` to begin driving at a desired speed and steering.
@@ -48,6 +50,8 @@
 
     .. automethod:: pybricks.robotics.DriveBase.reset
 
+    .. automethod:: pybricks.robotics.DriveBase.stalled
+
     .. rubric:: Measuring and validating the robot dimensions
 
     As a first estimate, you can measure the ``wheel_diameter`` and the
@@ -89,7 +93,6 @@
     :meth:`.turn` command.
     To deactivate the :class:`.DriveBase`, call :meth:`.stop`.
 
-
     .. rubric:: Advanced settings
 
     The :meth:`.settings` method is used to adjust commonly used settings like

src/pybricks/robotics.py

@@ -189,6 +189,27 @@ class DriveBase:
                          with the rest of the program.
         """
 
+    def done(self) -> bool:
+        """done() -> bool
+
+        Checks if an ongoing command or maneuver is done.
+
+        Returns:
+            ``True`` if the command is done, ``False`` if not.
+        """
+
+    def stalled(self) -> bool:
+        """stalled() -> bool
+
+        Checks if the drive base is currently stalled.
+
+        It is stalled when it cannot reach the target speed or position, even
+        with the maximum actuation signal.
+
+        Returns:
+            ``True`` if the drivebase is stalled, ``False`` if not.
+        """
+
 
 # HACK: hide from jedi
 if TYPE_CHECKING: