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

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


Attributes
----------

.. autoapisummary::

   libstp.step.motion.drive.Strafe


Classes
-------

.. autoapisummary::

   libstp.step.motion.drive.Drive


Functions
---------

.. autoapisummary::

   libstp.step.motion.drive.drive_forward
   libstp.step.motion.drive.drive_backward
   libstp.step.motion.drive.strafe_left
   libstp.step.motion.drive.strafe_right


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

.. py:class:: Drive(config: libstp.motion.LinearMotionConfig)

   Bases: :py:obj:`libstp.step.motion.motion_step.MotionStep`


   Step wrapper around the native `LinearMotion` controller.


   .. py:attribute:: config


   .. py:method:: to_simulation_step() -> libstp.step.SimulationStep

      Convert this step to a simulation-friendly summary.

      The default implementation uses timing history only when it can query
      the tracker synchronously; otherwise it returns conservative defaults.
      Override in subclasses that know their motion delta or exact duration.



   .. py:method:: on_start(robot: libstp.robot.api.GenericRobot) -> None

      Called once before the loop. Override to set up motion/velocity.



   .. py:method:: on_update(robot: libstp.robot.api.GenericRobot, dt: float) -> bool

      Called each cycle with dt in seconds. Return True when motion is complete.



.. py:data:: Strafe

.. py:function:: drive_forward(cm: float, speed: float = 1.0) -> Drive

   Drive forward a specified distance using profiled PID motion control.

   The robot accelerates, cruises, and decelerates along a trapezoidal
   velocity profile while maintaining heading via IMU feedback. Odometry
   tracks the distance traveled and the step completes when the target
   is reached.

   Requires ``calibrate_distance()`` to have been run first so that
   encoder-to-meter conversion is accurate.

   :param cm: Distance to drive in centimeters.
   :param speed: Fraction of max speed, 0.0 to 1.0 (default 1.0).

   :returns: A Drive step configured for forward motion.

   :raises CalibrationRequiredError: If ``calibrate_distance()`` has not been run.

   Example::

       from libstp.step.motion import drive_forward

       # Drive forward 50 cm at full speed
       drive_forward(50)

       # Drive forward 30 cm at half speed
       drive_forward(30, speed=0.5)


.. py:function:: drive_backward(cm: float, speed: float = 1.0) -> Drive

   Drive backward a specified distance using profiled PID motion control.

   Identical to ``drive_forward()`` but in reverse. The robot drives
   backward while maintaining heading via IMU feedback.

   Requires ``calibrate_distance()`` to have been run first.

   :param cm: Distance to drive in centimeters.
   :param speed: Fraction of max speed, 0.0 to 1.0 (default 1.0).

   :returns: A Drive step configured for backward motion.

   :raises CalibrationRequiredError: If ``calibrate_distance()`` has not been run.

   Example::

       from libstp.step.motion import drive_backward

       # Back up 20 cm
       drive_backward(20)


.. py:function:: strafe_left(cm: float, speed: float = 1.0) -> Drive

   Strafe left by a specified distance using profiled PID motion control.

   Requires a mecanum or omni-wheel drivetrain. The robot moves laterally
   to the left while maintaining heading via IMU feedback.

   :param cm: Distance to strafe in centimeters.
   :param speed: Fraction of max speed, 0.0 to 1.0 (default 1.0).

   :returns: A Drive step configured for leftward lateral motion.

   Example::

       from libstp.step.motion import strafe_left

       # Strafe left 15 cm to dodge an obstacle
       strafe_left(15)


.. py:function:: strafe_right(cm: float, speed: float = 1.0) -> Drive

   Strafe right by a specified distance using profiled PID motion control.

   Requires a mecanum or omni-wheel drivetrain. The robot moves laterally
   to the right while maintaining heading via IMU feedback.

   :param cm: Distance to strafe in centimeters.
   :param speed: Fraction of max speed, 0.0 to 1.0 (default 1.0).

   :returns: A Drive step configured for rightward lateral motion.

   Example::

       from libstp.step.motion import strafe_right

       # Strafe right 15 cm to align with a game piece
       strafe_right(15)