step.motion.motion_step
=======================

.. py:module:: step.motion.motion_step

.. autoapi-nested-parse::

   Base class for motion steps with a unified fixed-rate update loop.

   All motion steps share the same async timing pattern: dt calculation, near-zero
   dt skip, sleep, and hard_stop cleanup. MotionStep owns this loop and exposes
   on_start / on_update / on_stop lifecycle hooks for subclasses.



Classes
-------

.. autoapisummary::

   step.motion.motion_step.MotionLoopStats
   step.motion.motion_step.MotionStep


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

.. py:class:: MotionLoopStats

   Summary of the fixed-rate loop timing observed during one motion step.


   .. py:attribute:: iterations
      :type:  int


   .. py:attribute:: elapsed_s
      :type:  float


   .. py:attribute:: avg_hz
      :type:  float


   .. py:attribute:: min_dt_ms
      :type:  float


   .. py:attribute:: max_dt_ms
      :type:  float


.. py:class:: MotionStep

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


   Base class for all motion steps. Handles the fixed-rate update loop.


   .. py:attribute:: hz
      :type:  int
      :value: 100



   .. py:method:: required_resources() -> frozenset[str]

      Return the hardware resources this step requires exclusive access to.

      For leaf steps (drive, motor, servo), return the resources this step
      directly uses.  Composite steps override ``collected_resources``
      instead to include children — ``required_resources`` stays empty for
      composites because they don't touch hardware themselves.



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

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



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


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



   .. py:method:: on_stop(robot: raccoon.robot.api.GenericRobot) -> None

      Called after loop exits. Default: hard_stop.