From dd39a2e00f87f713b8d179d14b2de86337f3eaed Mon Sep 17 00:00:00 2001
From: Laurens Valk <laurens@pybricks.com>
Date: Thu, 23 Jan 2020 17:58:24 +0100
Subject: [PATCH] api/robotics: update DriveBase API

Make arc a non-blocking function similar to drive. This allows users to drive the robot along an arc until a sensor (e.g. color) is triggered, instead of relying on the rotation sensors only.

This also lets us simplify the language of some other method docstrings.
---
 doc/api/robotics.rst | 12 ++++++-----
 pybricks/robotics.py | 48 ++++++++++++++++++++------------------------
 2 files changed, 29 insertions(+), 31 deletions(-)

diff --git a/doc/api/robotics.rst b/doc/api/robotics.rst
index 77c278f..824d38e 100644
--- a/doc/api/robotics.rst
+++ b/doc/api/robotics.rst
@@ -14,13 +14,11 @@
 
     .. automethod:: pybricks.robotics.DriveBase.turn
 
-    .. automethod:: pybricks.robotics.DriveBase.arc
-
-    .. automethod:: pybricks.robotics.DriveBase.set_drive_settings
-
     .. rubric:: Manual drive control
 
-    .. automethod:: pybricks.robotics.DriveBase.start
+    .. automethod:: pybricks.robotics.DriveBase.drive
+
+    .. automethod:: pybricks.robotics.DriveBase.arc
 
     .. automethod:: pybricks.robotics.DriveBase.stop
 
@@ -31,3 +29,7 @@
     .. automethod:: pybricks.robotics.DriveBase.angle
 
     .. automethod:: pybricks.robotics.DriveBase.reset
+
+    .. rubric:: Settings
+
+    .. automethod:: pybricks.robotics.DriveBase.set_drive_settings
diff --git a/pybricks/robotics.py b/pybricks/robotics.py
index 24f3223..59f90bd 100644
--- a/pybricks/robotics.py
+++ b/pybricks/robotics.py
@@ -21,13 +21,24 @@ class DriveBase():
 
         """
 
-    def start(self, drive_speed, turn_rate):
+    def drive(self, speed, steering):
         """Start driving at the specified speed and turn rate, both measured at
         the center point between the wheels of the robot.
 
         Arguments:
-            drive_speed (:ref:`linspeed`): Forward speed of the robot.
-            turn_rate (:ref:`speed`): Turn rate of the robot.
+            speed (:ref:`linspeed`): Forward speed of the robot.
+            steering (:ref:`speed`): Turn rate of the robot.
+        """
+        pass
+
+    def arc(self, speed, radius):
+        """Start driving along an arc/circle with a given radius.
+
+        Arguments:
+            drive_speed (:ref:`linspeed`): Speed of the robot along the arc.
+            radius (:ref:`dimension`): Radius of the arc. A positive radius
+                value makes your robot go right. A negative radius value makes
+                it go left.
         """
         pass
 
@@ -43,7 +54,7 @@ class DriveBase():
         pass
 
     def distance(self):
-        """Get the estimated accumulated driven distance.
+        """Get the estimated driven distance.
 
         Returns:
             :ref:`distance`: Driven distance since last reset.
@@ -51,7 +62,7 @@ class DriveBase():
         pass
 
     def angle(self):
-        """Get the estimated accumulated rotation angle of the drive base.
+        """Get the estimated rotation angle of the drive base.
 
         Returns:
             :ref:`angle`: Accumulated angle since last reset.
@@ -59,22 +70,20 @@ class DriveBase():
         pass
 
     def reset(self):
-        """Reset the accumulated driven distance and angle to 0."""
+        """Reset the estimated driven distance and angle to 0."""
         pass
 
     def set_drive_settings(self, drive_speed, drive_acceleration, turn_rate,
                            turn_acceleration, stop_type):
-        """Configure the behavior of the :meth:`.straight`, :meth:`.turn`,
-        and :meth:`.arc` methods.
+        """Configure the default speed and acceleration.
 
         Arguments:
-            drive_speed (:ref:`linspeed`): Forward speed of the robot.
-            drive_acceleration (:ref:`linacceleration`): Forward acceleration
+            drive_speed (:ref:`linspeed`): Drive speed of the robot.
+            drive_acceleration (:ref:`linacceleration`): Linear acceleration
                 of the robot.
-            turn_rate (:ref:`speed`): Turn rate of the robot. Applies
-                to :meth:`.turn` method only.
+            turn_rate (:ref:`speed`): Turn rate of the robot.
             turn_acceleration (:ref:`acceleration`): Angular acceleration of
-                the robot. Applies to :meth:`.turn` method only.
+                the robot.
             stop_type (Stop): Whether to coast, brake, or hold after
                 a given command is complete.
         """
@@ -95,16 +104,3 @@ class DriveBase():
             angle (:ref:`angle`): Angle of the turn.
         """
         pass
-
-    def arc(self, radius, angle):
-        """Drive along an arc with a given radius by a given angle. An arc is
-        a segment of a circle.
-
-        A positive radius value makes your robot go right. A negative radius
-        makes it go left.
-
-        Arguments:
-            radius (:ref:`dimension`): Radius of the circle.
-            angle (:ref:`angle`): Angle traversed along the circle.
-        """
-        pass