libstp.step.motion.at_distance
==============================

.. py:module:: libstp.step.motion.at_distance

.. autoapi-nested-parse::

   Wait until the robot has driven a certain distance from origin.

   Designed to run inside a parallel() branch alongside a drive step:

       parallel(
           drive_forward(50),
           seq([wait_until_distance(30), servo_open()]),
       )

   Multiple distance-triggered actions:

       parallel(
           drive_forward(50),
           seq([wait_until_distance(20), arm_lower()]),
           seq([wait_until_distance(30), servo_open()]),
           seq([wait_until_distance(45), servo_close()]),
       )

   Polls odometry at 100Hz.  Because LinearMotion.start() resets odometry,
   the distance is measured from the start of the concurrent drive step.



Classes
-------

.. autoapisummary::

   libstp.step.motion.at_distance.WaitUntilDistance


Functions
---------

.. autoapisummary::

   libstp.step.motion.at_distance.wait_until_distance


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

.. py:class:: WaitUntilDistance(distance_cm: float, hz: int = 100)

   Bases: :py:obj:`libstp.step.Step`


   Block until odometry straight-line distance exceeds a threshold.


.. py:function:: wait_until_distance(cm: float) -> WaitUntilDistance

   Wait until the robot has driven at least the given distance.

   Polls odometry straight-line distance from the origin at 100 Hz.
   Designed to run inside a ``parallel()`` branch alongside a drive step,
   enabling actions to trigger at specific distances during a drive.

   :param cm: Distance threshold in centimeters.

   :returns: A WaitUntilDistance step.

   Example::

       from libstp.step import parallel, seq
       from libstp.step.motion import drive_forward, wait_until_distance
       from libstp.step.servo import servo

       # Open a servo after driving 30 cm into a 50 cm drive
       parallel([
           drive_forward(50),
           seq([wait_until_distance(30), servo(claw, 90)]),
       ])