From 99d52103133cd56d56dec00ecaae13ef470f2f11 Mon Sep 17 00:00:00 2001
From: Laurens Valk <laurens@pybricks.com>
Date: Fri, 2 Dec 2022 12:32:15 +0100
Subject: [PATCH] pybricks.robotics.DriveBase: Add stalled, done.

---
 CHANGELOG.md             |  1 +
 doc/main/robotics.rst    |  7 +++++--
 src/pybricks/robotics.py | 21 +++++++++++++++++++++
 3 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e2f41f6..e3d7dbd 100644
--- a/CHANGELOG.md
+++ b/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
diff --git a/doc/main/robotics.rst b/doc/main/robotics.rst
index 68ab5ab..49b11d9 100644
--- a/doc/main/robotics.rst
+++ b/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
diff --git a/src/pybricks/robotics.py b/src/pybricks/robotics.py
index 5668cb5..f898cb3 100644
--- a/src/pybricks/robotics.py
+++ b/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: