api/robotics/DriveBase: add state getter

doc/api/robotics.rst

@@ -11,7 +11,7 @@
     .. rubric:: Driving for a given distance or by an angle
 
     Use these commands to drive a given distance, or turn by a given angle.
-    
+
     This is measured using the internal rotation sensors. Because wheels may
     slip while moving, the traveled distance and angle are only estimates.
 
@@ -23,7 +23,7 @@
     .. rubric:: Drive forever
 
     Use :meth:`.drive` to begin driving at a desired speed and steering.
-    
+
     It keeps going until you use :meth:`.stop` or change course by
     using :meth:`.drive` again. For example, you can drive until a
     sensor is triggered and then stop or turn around.
@@ -38,6 +38,8 @@
 
     .. automethod:: pybricks.robotics.DriveBase.angle
 
+    .. automethod:: pybricks.robotics.DriveBase.state
+
     .. automethod:: pybricks.robotics.DriveBase.reset
 
     .. rubric:: Settings

pybricks/robotics.py

@@ -69,13 +69,24 @@ class DriveBase():
         """
         pass
 
+    def state(self):
+        """Get the instantaneous physical state.
+
+        This returns the current :meth:`.distance`, the drive speed, the
+        :meth:`.angle`, and the turn rate.
+
+        :returns: Distance, drive speed, angle, turn rate
+        :rtype: (:ref:`distance`, :ref:`linspeed`, :ref:`angle`, :ref:`speed`)
+        """
+        pass
+
     def reset(self):
         """Reset the estimated driven distance and angle to 0."""
         pass
 
     def settings(self, drive_speed, drive_acceleration, turn_rate,
                  turn_acceleration, stop_type):
-        """Configure the acceleration and maximum speed used 
+        """Configure the acceleration and maximum speed used
         by :meth:`.straight`, :meth:`.turn`, and :meth:`.drive`.
 
         If you give no arguments, this returns the current values as a tuple.