step.motion.drive
=================

.. py:module:: step.motion.drive


Classes
-------

.. autoapisummary::

   step.motion.drive.DriveForward
   step.motion.drive.DriveBackward
   step.motion.drive.StrafeLeft
   step.motion.drive.StrafeRight


Module Contents
---------------

.. py:class:: DriveForward(cm: float = None, speed: float = 1.0, until: step.condition.StopCondition = None, heading: float = None)

   Bases: :py:obj:`_ConditionalDrive`


   Drive forward with distance or condition-based termination.

   Uses profiled PID motion control with a trapezoidal velocity profile.
   The robot accelerates, cruises, and decelerates while maintaining
   heading via IMU feedback. When ``heading`` is given, the controller
   holds that absolute heading (degrees from heading reference) instead
   of the heading at start, preventing drift accumulation across
   consecutive drives.

   Requires ``calibrate_distance()`` for distance-based mode.
   Requires ``mark_heading_reference()`` when using ``heading``.

   :param heading: Absolute heading in degrees from the heading reference
                   to hold during this drive. ``None`` (default) holds the
                   heading at the start of the drive (relative mode).

   Example::

       drive_forward(25)                            # 25 cm, relative heading
       drive_forward(25, heading=90)                # hold 90° absolute
       drive_forward(speed=0.8).until(on_black(s))  # until sensor


.. py:class:: DriveBackward(cm: float = None, speed: float = 1.0, until: step.condition.StopCondition = None, heading: float = None)

   Bases: :py:obj:`_ConditionalDrive`


   Drive backward with distance or condition-based termination.

   Identical to ``drive_forward()`` but in reverse. Uses profiled PID
   motion control while maintaining heading via IMU feedback. Supports
   the same ``heading`` parameter for absolute heading hold.

   Requires ``calibrate_distance()`` for distance-based mode.
   Requires ``mark_heading_reference()`` when using ``heading``.

   :param heading: Absolute heading in degrees from the heading reference
                   to hold during this drive. ``None`` (default) holds the
                   heading at the start of the drive (relative mode).

   Example::

       drive_backward(20)
       drive_backward(20, heading=0)                # hold 0° absolute
       drive_backward(speed=0.5).until(on_white(s))


.. py:class:: StrafeLeft(cm: float = None, speed: float = 1.0, until: step.condition.StopCondition = None, heading: float = None)

   Bases: :py:obj:`_ConditionalDrive`


   Strafe left with distance or condition-based termination.

   Requires a mecanum or omni-wheel drivetrain. The robot moves
   laterally to the left while maintaining heading via IMU feedback.
   Supports the same ``heading`` parameter for absolute heading hold.

   Requires ``mark_heading_reference()`` when using ``heading``.

   :param heading: Absolute heading in degrees from the heading reference
                   to hold during this strafe. ``None`` (default) holds the
                   heading at the start of the strafe (relative mode).

   Example::

       strafe_left(15)
       strafe_left(15, heading=90)                  # hold 90° absolute
       strafe_left(speed=0.6).until(on_black(s))


.. py:class:: StrafeRight(cm: float = None, speed: float = 1.0, until: step.condition.StopCondition = None, heading: float = None)

   Bases: :py:obj:`_ConditionalDrive`


   Strafe right with distance or condition-based termination.

   Requires a mecanum or omni-wheel drivetrain. The robot moves
   laterally to the right while maintaining heading via IMU feedback.
   Supports the same ``heading`` parameter for absolute heading hold.

   Requires ``mark_heading_reference()`` when using ``heading``.

   :param heading: Absolute heading in degrees from the heading reference
                   to hold during this strafe. ``None`` (default) holds the
                   heading at the start of the strafe (relative mode).

   Example::

       strafe_right(15)
       strafe_right(15, heading=0)                  # hold 0° absolute
       strafe_right(speed=0.6).until(on_black(s))