step.calibration.calibrate_analog_sensor_dsl
============================================

.. py:module:: step.calibration.calibrate_analog_sensor_dsl

.. autoapi-nested-parse::

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

   Source: calibrate_analog_sensor.py



Classes
-------

.. autoapisummary::

   step.calibration.calibrate_analog_sensor_dsl.CalibrateAnalogSensorBuilder


Functions
---------

.. autoapisummary::

   step.calibration.calibrate_analog_sensor_dsl.calibrate_analog_sensor


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

.. py:class:: CalibrateAnalogSensorBuilder

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


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


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


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


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


.. py:function:: calibrate_analog_sensor(sensor: AnalogSensor = _UNSET, set_name: str = 'default', sample_duration: float = 3.0)

   Capture a reference analog sensor reading at a target robot position.

   Guides the operator to position the robot at a reference location, then
   samples the analog sensor for a short period to derive a stable reference
   raw value.  The result is persisted in ``racoon.calibration.yml`` under the
   ``analog-sensor`` section and consumed at runtime by
   ``drive_to_analog_target()``.

   Typical use: position the robot next to an object, run this step during
   setup, then use ``drive_to_analog_target()`` in the mission to reliably
   drive to that sensor distance every run.

   Supports ``--no-calibrate``: loads the stored reference without running
   the interactive flow when the flag is active and data already exists.

   Prerequisites:
       The sensor must be passed directly.  No auto-discovery from
       ``robot.defs`` is performed.

   :param sensor: The analog sensor to calibrate (e.g. an ``ETSensor``).
   :param set_name: Label for this calibration point (default ``"default"``). Use different names for multiple reference distances on the same sensor port.
   :param sample_duration: How long to sample the sensor in seconds. Longer durations produce more stable averages.

   :returns: A CalibrateAnalogSensorBuilder (chainable via ``.sensor()``, ``.set_name()``, ``.sample_duration()``, ``.on_anomaly()``, ``.skip_timing()``).

   Example::

       from raccoon.step.calibration import calibrate_analog_sensor

       # Calibrate ET sensor at the default target position
       calibrate_analog_sensor(robot.defs.et_sensor)

       # Two named positions on the same sensor
       calibrate_analog_sensor(robot.defs.et_sensor, set_name="near")
       calibrate_analog_sensor(robot.defs.et_sensor, set_name="far")