pybricks 3.5.0b2__tar.gz → 3.6.0__tar.gz

{pybricks-3.5.0b2 → pybricks-3.6.0}/PKG-INFO

@@ -1,8 +1,7 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: pybricks
-Version: 3.5.0b2
+Version: 3.6.0
 Summary: Documentation and user-API stubs for Pybricks MicroPython
-Home-page: https://pybricks.com
 License: MIT
 Author: The Pybricks Authors
 Author-email: team@pybricks.com
@@ -16,8 +15,10 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: Implementation :: MicroPython
 Project-URL: Documentation, https://docs.pybricks.com
+Project-URL: Homepage, https://pybricks.com
 Project-URL: Repository, https://github.com/pybricks/pybricks-api
 Description-Content-Type: text/x-rst
 

{pybricks-3.5.0b2 → pybricks-3.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pybricks"
-version = "3.5.0b2"
+version = "3.6.0"
 description = "Documentation and user-API stubs for Pybricks MicroPython"
 authors = ["The Pybricks Authors <team@pybricks.com>"]
 maintainers = ["Laurens Valk <laurens@pybricks.com>", "David Lechner <david@pybricks.com>" ]

{pybricks-3.5.0b2 → pybricks-3.6.0}/src/pybricks/_common.py

@@ -69,32 +69,6 @@ class System:
 
         Stops your program and shuts the hub down."""
 
-    def reset_reason(self) -> int:
-        """reset_reason() -> int
-
-        Finds out how and why the hub (re)booted. This can be useful to
-        diagnose some problems.
-
-        Returns:
-            * ``0`` if the hub was previously powered off
-              normally.
-            * ``1`` if the hub rebooted automatically, like
-              after a firmware update.
-            * ``2`` if the hub previously
-              crashed due to a watchdog timeout, which indicates a firmware
-              issue.
-        """
-
-    def name(self) -> str:
-        """name() -> str
-
-        Gets the hub name. This is the name you see when connecting
-        via Bluetooth.
-
-        Returns:
-            The hub name.
-        """
-
     @overload
     def storage(self, offset: int, *, read: int) -> bytes: ...
 
@@ -131,6 +105,40 @@ class System:
                 If you try to read or write data outside of the allowed range.
         """
 
+    def reset_storage(self) -> None:
+        """reset_storage()
+
+        Resets all user settings to default values and erases user programs.
+        """
+
+    def info(self) -> dict:
+        """info() -> dict
+
+        Gets information about the hub as a dictionary with the following keys:
+
+         - ``"name"``: The hub name. This is the name you see when connecting
+           via Bluetooth.
+         - ``"reset_reason"``: Why the hub (re)booted. It is ``0`` if the hub
+           was previously powered off normally. It is ``1`` if the hub rebooted
+           automatically, like after a firmware update. It is ``2`` if the hub
+           previously crashed due to a watchdog timeout, which indicates a
+           firmware issue.
+         - ``"host_connected_ble"``: Whether the hub is connected to a computer,
+           tablet, or phone via Bluetooth.
+         - ``"program_start_type"``: It is ``1`` if the program started
+           automatically when the hub was powered on. It is ``2`` if the program
+           was started with the hub buttons. It is ``3`` if the program was
+           started from your connected computer.
+
+        Returns:
+            A dictionary with system info.
+
+        .. versionchanged:: 3.6
+            The name and reset reason where previously available as separate
+            methods. Now they are included in the info dictionary. The methods
+            are still available for compatibility.
+        """
+
 
 class DCMotor:
     """Generic class to control simple motors without rotation sensors, such
@@ -471,6 +479,11 @@ class Motor(DCMotor):
 
         Sets the accumulated rotation angle of the motor to a desired value.
 
+        If this motor is also being used by a drive base, its distance and
+        angle values will also be affected. You might want to
+        use its :meth:`reset <pybricks.robotics.DriveBase.reset>`
+        method instead.
+
         Arguments:
             angle (Number, deg): Value to which the angle should be reset.
         """
@@ -1013,34 +1026,67 @@ class SimpleAccelerometer:
         """
 
 
-class Accelerometer(SimpleAccelerometer):
-    """Get measurements from an accelerometer."""
+class IMU:
+
+    def up(self, calibrated: bool = True) -> Side:
+        """up(calibrated=True) -> Side
+
+        Checks which side of the hub currently faces upward.
+
+        Arguments:
+            calibrated (bool): Choose ``True`` to use calibrated gyroscope and
+                accelerometer data to determine which way is up. Choose
+                ``False`` to use raw acceleration values.
+
+        Returns:
+            ``Side.TOP``, ``Side.BOTTOM``, ``Side.LEFT``, ``Side.RIGHT``,
+            ``Side.FRONT`` or ``Side.BACK``.
+        """
+
+    def tilt(self, calibrated: bool = True) -> Tuple[int, int]:
+        """tilt(calibrated=True) -> Tuple[int, int]
+
+        Gets the pitch and roll angles. This is relative to the
+        :ref:`user-specified neutral orientation <robotframe>`.
+
+        The order of rotation is pitch-then-roll. This is equivalent to a
+        positive rotation along the robot y-axis and then a positive rotation
+        along the x-axis.
+
+        Arguments:
+            calibrated (bool): Choose ``True`` to use calibrated gyroscope and
+                accelerometer data to determine the tilt. Choose ``False``
+                to use raw acceleration values.
+
+        Returns:
+            Tuple of pitch and roll angles in degrees.
+        """
 
     @overload
-    def acceleration(self, axis: Axis) -> float: ...
+    def acceleration(self, axis: Axis = None, calibrated: bool = True) -> float: ...
 
     @overload
-    def acceleration(self) -> Matrix: ...
+    def acceleration(self, calibrated: bool = True) -> Matrix: ...
 
     def acceleration(self, *args):
         """
-        acceleration(axis) -> float: mm/s²
-        acceleration() -> vector: mm/s²
-
+        acceleration(axis, calibrated=True) -> float: mm/s²
+        acceleration(calibrated=True) -> vector: mm/s²
 
         Gets the acceleration of the device along a given axis in the
         :ref:`robot reference frame <robotframe>`.
 
         Arguments:
             axis (Axis): Axis along which the acceleration should be
-                         measured.
+                measured, or ``None`` to get a vector along all axes.
+            calibrated (bool): Choose ``True`` to use calibrated acceleration
+                values. Choose ``False`` to use raw acceleration values.
+
         Returns:
             Acceleration along the specified axis. If you specify no axis,
             this returns a vector of accelerations along all axes.
         """
 
-
-class IMU(Accelerometer):
     def ready(self) -> bool:
         """ready() -> bool
 
@@ -1068,38 +1114,91 @@ class IMU(Accelerometer):
     @overload
     def settings(
         self,
+        *,
         angular_velocity_threshold: float = None,
         acceleration_threshold: float = None,
+        heading_correction: float = None,
+        angular_velocity_bias: Tuple[float, float, float] = None,
+        angular_velocity_scale: Tuple[float, float, float] = None,
+        acceleration_correction: Tuple[float, float, float, float, float, float] = None,
     ) -> None: ...
 
     @overload
-    def settings(self) -> Tuple[float, float]: ...
+    def settings(
+        self,
+    ) -> Tuple[
+        float,
+        float,
+        float,
+        Tuple[float, float, float],
+        Tuple[float, float, float],
+        Tuple[float, float, float, float, float, float],
+    ]: ...
 
     def settings(self, *args):
         """
-        settings(angular_velocity_threshold, acceleration_threshold)
-        settings() -> Tuple[float, float]
+        settings(*, angular_velocity_threshold, acceleration_threshold, heading_correction, angular_velocity_bias, angular_velocity_scale, acceleration_correction)
+        settings() -> Tuple
 
         Configures the IMU settings. If no arguments are given,
-        this returns the current values.
+        this returns the current values. Use keyword arguments for each value
+        to ensure correct behavior because settings may be added or changed in
+        future releases.
+
+        These IMU settings are saved on the hub. They will keep their values
+        until you change them again. The values will be reset to default values
+        if you update the hub to a different firmware version or call the
+        ``hub.system.reset_storage`` method.
 
         The ``angular_velocity_threshold`` and ``acceleration_threshold``
         define when the hub is considered stationary. If all
         measurements stay below these thresholds for one second, the IMU
-        will recalibrate itself.
-
-        In a noisy room with high ambient vibrations (such as a
-        competition hall), it is recommended to increase the thresholds
+        will recalibrate itself. In a noisy room with high ambient vibrations (such as a
+        competition hall), you can increase the thresholds
         slightly to give your robot the chance to calibrate.
         To verify that your settings are working as expected, test that
         the ``stationary()`` method gives ``False`` if your robot is moving,
-        and ``True`` if it is sitting still for at least a second.
+        and ``True`` if it is sitting still.
+
+        The gyroscope measures how fast the hub rotates to estimate the total
+        angle. Due to variations in the production process, each
+        hub consistently reports a different value for a full rotation. For
+        example, your hub might consistently report `357` degrees for every
+        `360` degree turn. You can measure this value
+        with ``hub.imu.rotation(-Axis.Z, calibrated=False)`` and enter it as
+        the ``heading_correction`` setting. Then, the ``hub.imu.heading()``
+        method will take it into account going forward, correctly scaling it
+        to 360 degrees for a full rotation.
 
         Arguments:
             angular_velocity_threshold (Number, deg/s): The threshold for
-                angular velocity. The default value is 1.5 deg/s.
-            acceleration_threshold (Number, mm/s²): The threshold for angular
-                velocity. The default value is 250 mm/s².
+                variations in the angular velocity below which the hub is
+                considered stationary enough to calibrate.
+                After a reset the value is 2 deg/s.
+            acceleration_threshold (Number, mm/s²): The threshold for
+                variations in acceleration below which the hub is considered
+                stationary enough to calibrate. After a reset the value
+                is 2500 mm/s².
+            heading_correction (Number, deg): Number of degrees
+                reported by for one full rotation of your robot.
+                After a reset the value is 360 degrees. This is applied on top
+                of any scaling that is done by the ``angular_velocity_scale``
+                setting.
+            angular_velocity_bias (tuple, deg/s): Initial bias for angular
+                velocity measurements along x, y, and z immediately after boot.
+                After a reset the value is (0, 0, 0) deg/s.
+            angular_velocity_scale (tuple, deg): Scale adjustment for x, y, and
+                z rotation to account for manufacturing differences. After a
+                reset the value is (360, 360, 360) deg/s. The correct values
+                can be obtained using `hub.imu.rotation(Axis.X, calibrated=False)`
+                and repeating it for each axis.
+            acceleration_correction (tuple, mm/s²): Scale adjustment for x, y,
+                and z gravity magnitude in both directions to account for
+                manufacturing differences. After a reset the
+                value is (9806.65, -9806.65, 9806.65, -9806.65, 9806.65, -9806.65) mm/s².
+                The correct values can be
+                obtained using `hub.imu.acceleration(Axis.X, calibrated=False)`
+                and repeating it for all axes in both directions.
         """
 
     def heading(self) -> float:
@@ -1117,11 +1216,11 @@ class IMU(Accelerometer):
                   the robot is on a flat surface.*
 
                   This means that the value is
-                  no longer correct if you lift it from the table. To solve
-                  this, you can call ``reset_heading`` to reset the heading to
-                  a known value *after* you put it back down. For example, you
-                  could align your robot with the side of the competition table
-                  and reset the heading 90 degrees as the new starting point.
+                  no longer correct if you lift it from the table or turn on
+                  a ramp. Try ``hub.imu.heading('3D')`` for a heading value
+                  that compensates for this. This will become the default in a
+                  future release. If you try it, please let us know on our
+                  forums!
 
         Returns:
             Heading angle relative to starting orientation.
@@ -1133,35 +1232,50 @@ class IMU(Accelerometer):
 
         Resets the accumulated heading angle of the robot.
 
+        This cannot be called while a drive base is using the gyro to drive or
+        hold position.
+        Use :meth:`DriveBase.reset() <pybricks.robotics.DriveBase.reset>`
+        instead, which will stop the robot and then set the new heading value.
+
+        .. versionchanged:: 3.6 Resetting the angle while driving is not allowed. Stop first.
+
         Arguments:
             angle (Number, deg): Value to which the heading should be reset.
+
+        Raises:
+            OSError:
+                There is a drive base that is currently using the gyro.
         """
 
     @overload
-    def angular_velocity(self, axis: Axis) -> float: ...
+    def angular_velocity(self, axis: Axis = None, calibrated: bool = True) -> float: ...
 
     @overload
-    def angular_velocity(self) -> Matrix: ...
+    def angular_velocity(self, calibrated: bool = True) -> Matrix: ...
 
     def angular_velocity(self, *args):
         """
-        angular_velocity(axis) -> float: deg/s
-        angular_velocity() -> vector: deg/s
+        angular_velocity(axis, calibrated=True) -> float: deg/s
+        angular_velocity(calibrated=True) -> vector: deg/s
 
         Gets the angular velocity of the device along a given axis in
         the :ref:`robot reference frame <robotframe>`.
 
         Arguments:
             axis (Axis): Axis along which the angular velocity should be
-                         measured.
+                measured, or ``None`` to get a vector along all axes.
+            calibrated (bool): Choose ``True`` to compensate for the estimated
+                bias and configured scale of the gyroscope. Choose ``False``
+                to get raw angular velocity values.
+
         Returns:
             Angular velocity along the specified axis. If you specify no axis,
             this returns a vector of accelerations along all axes.
         """
 
-    def rotation(self, axis: Axis) -> float:
+    def rotation(self, axis: Axis, calibrated: bool = True) -> float:
         """
-        rotation(axis) -> float: deg
+        rotation(axis, calibrated=True) -> float: deg
 
         Gets the rotation of the device along a given axis in
         the :ref:`robot reference frame <robotframe>`.
@@ -1170,10 +1284,11 @@ class IMU(Accelerometer):
         axis. For general three-dimensional motion, use the
         ``orientation()`` method instead.
 
-        The value starts counting from ``0`` when you initialize this class.
-
         Arguments:
             axis (Axis): Axis along which the rotation should be measured.
+            calibrated (bool): Choose ``True`` to compensate for configured
+                scale of the gyroscope. Choose ``False`` to get unscaled values.
+
         Returns:
             The rotation angle.
         """
@@ -1188,10 +1303,8 @@ class IMU(Accelerometer):
         It returns a rotation matrix whose columns represent the ``X``, ``Y``,
         and ``Z`` axis of the robot.
 
-        .. note:: This method is not yet implemented.
-
         Returns:
-            The rotation matrix.
+            The 3x3 rotation matrix.
         """
 
 
@@ -1335,14 +1448,14 @@ class BLE:
     .. versionadded:: 3.3
     """
 
-    def broadcast(self, data: Union[bool, int, float, str, bytes]) -> None:
+    def broadcast(self, data: Union[bool, int, float, str, bytes]) -> MaybeAwaitable:
         """broadcast(data)
 
         Starts broadcasting the given data on
         the ``broadcast_channel`` you selected when initializing the hub.
 
         Data may be of type ``int``, ``float``, ``str``, ``bytes``,
-        ``True``, or ``False``, or a list thereof.
+        ``True``, or ``False``. It can also be a list or tuple of these.
 
         Choose ``None`` to stop broadcasting. This helps improve performance
         when you don't need the broadcast feature, especially when observing

{pybricks-3.5.0b2 → pybricks-3.6.0}/src/pybricks/hubs.py

@@ -44,9 +44,9 @@ class MoveHub:
     ble = _common.BLE()
 
     def __init__(
-        self, broadcast_channel: int = 0, observe_channels: Sequence[int] = []
+        self, broadcast_channel: int = None, observe_channels: Sequence[int] = []
     ):
-        """MoveHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=0, observe_channels=[])
+        """MoveHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=None, observe_channels=[])
 
         Arguments:
             top_side (Axis): The axis that passes through the *top side* of
@@ -54,8 +54,8 @@ class MoveHub:
             front_side (Axis): The axis that passes through the *front side* of
                 the hub.
             broadcast_channel:
-                A value from 0 to 255 indicating which channel ``hub.ble.broadcast()``
-                will use. Default is channel 0.
+                Channel number (0 to 255) used to broadcast data.
+                Choose ``None`` when not using broadcasting.
             observe_channels:
                 A list of channels to listen to when ``hub.ble.observe()`` is
                 called. Listening to more channels requires more memory.
@@ -78,14 +78,14 @@ class CityHub:
     ble = _common.BLE()
 
     def __init__(
-        self, broadcast_channel: int = 0, observe_channels: Sequence[int] = []
+        self, broadcast_channel: int = None, observe_channels: Sequence[int] = []
     ):
-        """CityHub(broadcast_channel=0, observe_channels=[])
+        """CityHub(broadcast_channel=None, observe_channels=[])
 
         Arguments:
             broadcast_channel:
-                A value from 0 to 255 indicating which channel ``hub.ble.broadcast()``
-                will use. Default is channel 0.
+                Channel number (0 to 255) used to broadcast data.
+                Choose ``None`` when not using broadcasting.
             observe_channels:
                 A list of channels to listen to when ``hub.ble.observe()`` is
                 called. Listening to more channels requires more memory.
@@ -112,10 +112,10 @@ class TechnicHub:
         self,
         top_side: Axis = Axis.Z,
         front_side: Axis = Axis.X,
-        broadcast_channel: int = 0,
+        broadcast_channel: int = None,
         observe_channels: Sequence[int] = [],
     ):
-        """TechnicHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=0, observe_channels=[])
+        """TechnicHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=None, observe_channels=[])
 
         Initializes the hub. Optionally, specify how the hub is
         :ref:`placed in your design <robotframe>` by saying in which
@@ -128,8 +128,8 @@ class TechnicHub:
             front_side (Axis): The axis that passes through the *front side* of
                 the hub.
             broadcast_channel:
-                A value from 0 to 255 indicating which channel ``hub.ble.broadcast()``
-                will use. Default is channel 0.
+                Channel number (0 to 255) used to broadcast data.
+                Choose ``None`` when not using broadcasting.
             observe_channels:
                 A list of channels to listen to when ``hub.ble.observe()`` is
                 called. Listening to more channels requires more memory.
@@ -157,10 +157,10 @@ class EssentialHub:
         self,
         top_side: Axis = Axis.Z,
         front_side: Axis = Axis.X,
-        broadcast_channel: int = 0,
+        broadcast_channel: int = None,
         observe_channels: Sequence[int] = [],
     ):
-        """EssentialHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=0, observe_channels=[])
+        """EssentialHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=None, observe_channels=[])
 
         Initializes the hub. Optionally, specify how the hub is
         :ref:`placed in your design <robotframe>` by saying in which
@@ -173,8 +173,8 @@ class EssentialHub:
             front_side (Axis): The axis that passes through the *front side* of
                 the hub.
             broadcast_channel:
-                A value from 0 to 255 indicating which channel ``hub.ble.broadcast()``
-                will use. Default is channel 0.
+                Channel number (0 to 255) used to broadcast data.
+                Choose ``None`` when not using broadcasting.
             observe_channels:
                 A list of channels to listen to when ``hub.ble.observe()`` is
                 called. Listening to more channels requires more memory.
@@ -212,10 +212,10 @@ class PrimeHub:
         self,
         top_side: Axis = Axis.Z,
         front_side: Axis = Axis.X,
-        broadcast_channel: int = 0,
+        broadcast_channel: int = None,
         observe_channels: Sequence[int] = [],
     ):
-        """PrimeHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=0, observe_channels=[])
+        """PrimeHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=None, observe_channels=[])
 
         Initializes the hub. Optionally, specify how the hub is
         :ref:`placed in your design <robotframe>` by saying in which
@@ -228,8 +228,8 @@ class PrimeHub:
             front_side (Axis): The axis that passes through the *front side* of
                 the hub.
             broadcast_channel:
-                A value from 0 to 255 indicating which channel ``hub.ble.broadcast()``
-                will use. Default is channel 0.
+                Channel number (0 to 255) used to broadcast data.
+                Choose ``None`` when not using broadcasting.
             observe_channels:
                 A list of channels to listen to when ``hub.ble.observe()`` is
                 called. Listening to more channels requires more memory.

{pybricks-3.5.0b2 → pybricks-3.6.0}/src/pybricks/parameters.py

@@ -112,6 +112,10 @@ class Color:
         The brightness value.
         """
 
+    def __iter__(self):
+        """Allows unpacking of the Color instance into h, s, and v."""
+        return iter((self.h, self.s, self.v))
+
     def __repr__(self):
         return "Color(h={}, s={}, v={})".format(self.h, self.s, self.v)
 

{pybricks-3.5.0b2 → pybricks-3.6.0}/src/pybricks/pupdevices.py

@@ -86,11 +86,15 @@ class Motor(_common.Motor):
 
         Sets the accumulated rotation angle of the motor to a desired value.
 
-        If you don't specify an angle, the absolute angle
-        will be used if your motor supports it.
+        If this motor is also being used by a drive base, its distance and
+        angle values will also be affected. You might want to
+        use its :meth:`reset <pybricks.robotics.DriveBase.reset>`
+        method instead.
 
         Arguments:
             angle (Number, deg): Value to which the angle should be reset.
+                                 Choose ``None`` to reset it to the absolute
+                                 value of the motor.
         """
 
 

{pybricks-3.5.0b2 → pybricks-3.6.0}/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: Number = 0, angle: Number = 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.
         """