From 25bfd0e80e4a41f8d7bb8ab52ea64fbb64e2990e Mon Sep 17 00:00:00 2001 From: Laurens Valk Date: Mon, 24 Feb 2025 10:25:22 +0100 Subject: [PATCH] pybricks.robotics.DriveBase: Document curve and reset updates. --- ...eBaseDrive2_drivebase_drive_arc_angle.svg} | 9 +- ...aseDrive2_drivebase_drive_arc_distance.svg | 994 ++++++++++++++++++ ...pybricks_blockDriveBaseResetWithValues.svg | 994 ++++++++++++++++++ doc/main/robotics.rst | 27 +- src/pybricks/robotics.py | 54 +- 5 files changed, 2069 insertions(+), 9 deletions(-) rename doc/main/blockimg/{pybricks_blockDriveBaseDrive_drivebase_drive_curve.svg => pybricks_blockDriveBaseDrive2_drivebase_drive_arc_angle.svg} (81%) create mode 100644 doc/main/blockimg/pybricks_blockDriveBaseDrive2_drivebase_drive_arc_distance.svg create mode 100644 doc/main/blockimg/pybricks_blockDriveBaseResetWithValues.svg diff --git a/doc/main/blockimg/pybricks_blockDriveBaseDrive_drivebase_drive_curve.svg b/doc/main/blockimg/pybricks_blockDriveBaseDrive2_drivebase_drive_arc_angle.svg similarity index 81% rename from doc/main/blockimg/pybricks_blockDriveBaseDrive_drivebase_drive_curve.svg rename to doc/main/blockimg/pybricks_blockDriveBaseDrive2_drivebase_drive_arc_angle.svg index db9b753..1f21449 100644 --- a/doc/main/blockimg/pybricks_blockDriveBaseDrive_drivebase_drive_curve.svg +++ b/doc/main/blockimg/pybricks_blockDriveBaseDrive2_drivebase_drive_arc_angle.svg @@ -48,7 +48,7 @@ color: #fff; stroke: #ffffff; } .pybricks_renderer-renderer.pybricks-zelos-light-theme .blocklyDisabled > .blocklyOutlinePath { -fill: url(#blocklyDisabledPattern5439580434912636) +fill: url(#blocklyDisabledPattern21868021983049069) } .pybricks_renderer-renderer.pybricks-zelos-light-theme .blocklyInsertionMarker>.blocklyPath { fill-opacity: 0.2; @@ -949,6 +949,11 @@ input[type=number] { } +.blocklyMultilineText { + fill: #fff !important; +} + + .blocklyMultiselect>image, .blocklyMultiselect>svg>image { opacity: .2; } @@ -986,4 +991,4 @@ input[type=number] { filter: invert(1); } -100mm90°holddrive base**drivecurvewith radiusbythen \ No newline at end of file +100mm90°holddrive basedrivecurvewith radiusbythen \ No newline at end of file diff --git a/doc/main/blockimg/pybricks_blockDriveBaseDrive2_drivebase_drive_arc_distance.svg b/doc/main/blockimg/pybricks_blockDriveBaseDrive2_drivebase_drive_arc_distance.svg new file mode 100644 index 0000000..ff43909 --- /dev/null +++ b/doc/main/blockimg/pybricks_blockDriveBaseDrive2_drivebase_drive_arc_distance.svg @@ -0,0 +1,994 @@ + +500mm250mmholddrive basedriveveerwith radiusbythen \ No newline at end of file diff --git a/doc/main/blockimg/pybricks_blockDriveBaseResetWithValues.svg b/doc/main/blockimg/pybricks_blockDriveBaseResetWithValues.svg new file mode 100644 index 0000000..c5bac7d --- /dev/null +++ b/doc/main/blockimg/pybricks_blockDriveBaseResetWithValues.svg @@ -0,0 +1,994 @@ + +drive base0mm0°reset distanceangle \ No newline at end of file diff --git a/doc/main/robotics.rst b/doc/main/robotics.rst index 739c978..35af6cc 100644 --- a/doc/main/robotics.rst +++ b/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 `, :meth:`turn `, or - :meth:`curve ` command. + :meth:`curve ` command. .. _measuring: diff --git a/src/pybricks/robotics.py b/src/pybricks/robotics.py index 776ade8..1380251 100644 --- a/src/pybricks/robotics.py +++ b/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. """