step.motion.drive_to_analog_target_dsl
======================================

.. py:module:: step.motion.drive_to_analog_target_dsl

.. autoapi-nested-parse::

   Auto-generated step builders and DSL functions — DO NOT EDIT.

   Source: drive_to_analog_target.py



Classes
-------

.. autoapisummary::

   step.motion.drive_to_analog_target_dsl.DriveToAnalogTargetBuilder


Functions
---------

.. autoapisummary::

   step.motion.drive_to_analog_target_dsl.drive_to_analog_target


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

.. py:class:: DriveToAnalogTargetBuilder

   Bases: :py:obj:`raccoon.step.step_builder.StepBuilder`


   Builder for DriveToAnalogTarget. Auto-generated — do not edit.


   .. py:method:: sensor(value: AnalogSensor)


   .. py:method:: speed(value: float)


   .. py:method:: set_name(value: str)


   .. py:method:: timeout_cm(value: Optional[float])


.. py:function:: drive_to_analog_target(sensor: AnalogSensor = _UNSET, speed: float = 0.3, set_name: str = 'default', timeout_cm: Optional[float] = None)

   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 DriveToAnalogTargetBuilder (chainable via ``.sensor()``, ``.speed()``, ``.set_name()``, ``.timeout_cm()``, ``.on_anomaly()``, ``.skip_timing()``).

   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,
       )