step.motion.drive_to_analog_target
==================================

.. py:module:: step.motion.drive_to_analog_target

.. autoapi-nested-parse::

   Drive until an analog sensor reaches its calibrated reference value.

   Loads the target raw value stored by ``calibrate_analog_sensor()`` and drives
   the robot forward or backward until the sensor reading crosses that threshold.
   Direction is determined automatically at start time by comparing the current
   reading to the calibrated target.



Classes
-------

.. autoapisummary::

   step.motion.drive_to_analog_target.DriveToAnalogTarget


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

.. py:class:: DriveToAnalogTarget(sensor: raccoon.hal.AnalogSensor, speed: float = 0.3, set_name: str = 'default', timeout_cm: Optional[float] = None)

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


   Drive until an analog sensor reaches its calibrated reference value.

   Reads the reference raw value stored by ``calibrate_analog_sensor()`` for
   the given sensor and set name, then drives forward or backward at the
   specified speed until ``sensor.read()`` crosses that threshold.  Direction
   is chosen automatically: if the current reading is below the target the
   robot drives forward (toward the target); if it is already above the
   target the robot drives backward.

   A ``timeout_cm`` can be provided as a safety backstop — the step stops
   after that distance even if the sensor has not reached the target.

   Prerequisites:
       ``calibrate_analog_sensor(sensor, set_name=...)`` must have been run
       (or a stored calibration must exist) before this step executes.
       Raises ``RuntimeError`` if no calibration data is found.

   :param sensor: The analog sensor used to detect the target position.
   :param speed: Drive speed as a fraction of maximum (0.0–1.0, default 0.3).
                 Use a slow speed for precise positioning.
   :param set_name: Which stored calibration point to target
                    (default ``"default"``).
   :param timeout_cm: Maximum distance to drive in centimetres before giving
                      up.  ``None`` disables the distance limit (default).

   :returns: A DriveToAnalogTarget instance.

   :raises RuntimeError: If no calibration data exists for the given sensor and
       set name.

   Example::

       from raccoon.step.motion import drive_to_analog_target

       # Drive to the default calibrated ET-sensor position
       drive_to_analog_target(robot.defs.et_sensor)

       # Slower approach to a named position with 30 cm safety backstop
       drive_to_analog_target(
           robot.defs.et_sensor,
           speed=0.2,
           set_name="near",
           timeout_cm=30,
       )


   .. 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

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