libstp.step.timing.wait_for_checkpoint
======================================

.. py:module:: libstp.step.timing.wait_for_checkpoint


Classes
-------

.. autoapisummary::

   libstp.step.timing.wait_for_checkpoint.WaitForCheckpoint


Functions
---------

.. autoapisummary::

   libstp.step.timing.wait_for_checkpoint.wait_for_checkpoint


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

.. py:class:: WaitForCheckpoint(checkpoint_seconds: Union[float, int])

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


   Wait until the robot synchronizer reaches a mission-relative checkpoint.


   .. py:attribute:: checkpoint_seconds


.. py:function:: wait_for_checkpoint(checkpoint_seconds: float) -> WaitForCheckpoint

   Wait until a mission-relative time checkpoint is reached.

   Pauses execution until the robot's global synchronizer clock reaches
   the specified number of seconds since mission start. If the
   checkpoint time has already passed, the step returns immediately.
   This is useful for synchronizing actions to absolute times within a
   timed Botball run (e.g. "at T=20s, start collecting").

   Prerequisites:
       The robot must have a ``synchronizer`` configured. The synchronizer
       clock starts when the mission begins.

   :param checkpoint_seconds: The mission-relative time (in seconds) to
                              wait for. Must be non-negative.

   :returns: A step that blocks until the checkpoint time.
   :rtype: WaitForCheckpoint

   Example::

       from libstp.step.timing import wait_for_checkpoint

       seq([
           drive_forward(50),
           # Ensure we don't start the next action before T=10s
           wait_for_checkpoint(10.0),
           pick_up_tribble(),
           # Gate the final action to T=25s
           wait_for_checkpoint(25.0),
           drive_to_bin(),
       ])