pybricks.robotics.DriveBase: Document curve and reset updates.

doc/main/robotics.rst

@@ -27,9 +27,24 @@
 
     .. automethod:: pybricks.robotics.DriveBase.turn
 
-    .. blockimg:: pybricks_blockDriveBaseDrive_drivebase_drive_curve
+    .. versionchanged:: 3.6
 
-    .. automethod:: pybricks.robotics.DriveBase.curve
+        The ``curve()`` Python method will be replaced by the :meth:`.arc`
+        method. It can still make curves, but it uses different definitions
+        for drive and turn direction. Existing code with ``curve()`` continues
+        to work the same, but you should use :meth:`.arc` for new code.
+        If you use block code, you can pick a new block from the palette to
+        update your code. The old block will still work, but it displays a
+        warning icon to remind you to upgrade. The updated `curve` option uses
+        the direction definitions given below. The new `veer` option lets
+        you drive along a circle by a given distance, which is useful for
+        veering slightly in one direction.
+
+    .. blockimg:: pybricks_blockDriveBaseDrive2_drivebase_drive_arc_angle
+
+    .. blockimg:: pybricks_blockDriveBaseDrive2_drivebase_drive_arc_distance
+
+    .. automethod:: pybricks.robotics.DriveBase.arc
 
     .. blockimg:: pybricks_blockDriveBaseConfigure_drivebase_straight_speed
 
@@ -81,6 +96,12 @@
 
     .. automethod:: pybricks.robotics.DriveBase.state
 
+    .. versionchanged:: 3.6
+
+        Now stops the drive base. You can now use nonzero values.
+
+    .. blockimg:: pybricks_blockDriveBaseResetWithValues
+
     .. automethod:: pybricks.robotics.DriveBase.reset
 
     .. automethod:: pybricks.robotics.DriveBase.stalled
@@ -114,7 +135,7 @@
     ``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.
+    :meth:`curve <pybricks.robotics.DriveBase.arc>` command.
 
     .. _measuring:
 

src/pybricks/robotics.py

@@ -119,10 +119,19 @@ class DriveBase:
             Tuple of distance, drive speed, angle, and turn rate of the robot.
         """
 
-    def reset(self) -> None:
-        """reset()
+    def reset(self, distance=0, angle=0) -> None:
+        """reset(distance=0, angle=0)
 
-        Resets the estimated driven distance and angle to 0."""
+        Resets the estimated driven distance and heading angle.
+
+        This also calls :meth:`.stop` to stop ongoing movements.
+        If your robot is controlled with :meth:`.use_gyro` set to ``True``,
+        calling this method will `also` set the gyro to the given angle.
+
+        Arguments:
+            distance (Number, mm): Speed of the robot.
+            angle (Number, deg): Heading angle of the robot.
+        """
 
     @overload
     def settings(
@@ -191,6 +200,40 @@ class DriveBase:
                          with the rest of the program.
         """
 
+    def arc(
+        self,
+        radius: Number,
+        angle: Number = None,
+        distance: Number = None,
+        then: Stop = Stop.HOLD,
+        wait: bool = True,
+    ) -> MaybeAwaitable:
+        """arc(radius, angle=None, distance=None, then=Stop.HOLD, wait=True)
+
+        Drives an arc (a partial circle) with a given radius. You can specify
+        how far to drive using either an angle or a distance.
+
+        With a positive radius, the robot drives along a circle to its right.
+        With a negative radius, the robot drives along a circle to its left.
+
+        You can specify how far to travel along that circle as an angle
+        (degrees) or distance (mm). A positive value means driving forward
+        along the circle. Negative means driving in reverse.
+
+        Arguments:
+            radius (Number, mm): Radius of the circle.
+            angle (Number, deg): Angle to drive along the circle.
+            distance (Number, mm): Distance to drive along the circle,
+                                   measured at the center of the robot.
+            then (Stop): What to do after coming to a standstill.
+            wait (bool): Wait for the maneuver to complete before continuing
+                         with the rest of the program.
+        Raises:
+            ValueError:
+                You must specify ``angle`` or ``distance``, but not both. The
+                radius cannot be zero. Use :meth:`.turn` for in-place turns.
+        """
+
     def curve(
         self, radius: Number, angle: Number, then: Stop = Stop.HOLD, wait: bool = True
     ) -> MaybeAwaitable:
@@ -224,7 +267,7 @@ class DriveBase:
         with the maximum actuation signal.
 
         Returns:
-            ``True`` if the drivebase is stalled, ``False`` if not.
+            ``True`` if the drive base is stalled, ``False`` if not.
         """
 
     def use_gyro(self, use_gyro: bool) -> None:
@@ -234,6 +277,9 @@ class DriveBase:
         straight. Choose ``False`` to rely only on the motor's built-in
         rotation sensors.
 
+        This method will automatically call :meth:`.stop` to stop ongoing
+        movements.
+
         Arguments:
             use_gyro (bool): ``True`` to enable, ``False`` to disable.
         """