step.calibration.calibrate_analog_sensor
========================================

.. py:module:: step.calibration.calibrate_analog_sensor

.. autoapi-nested-parse::

   Analog sensor (ET/distance) position calibration step.

   Captures a reference raw reading from any AnalogSensor at a user-defined
   robot position so that ``drive_to_analog_target()`` can reproduce the same
   sensor-distance during a mission.



Attributes
----------

.. autoapisummary::

   step.calibration.calibrate_analog_sensor.ANALOG_SENSOR_STORE_SECTION


Classes
-------

.. autoapisummary::

   step.calibration.calibrate_analog_sensor.AnalogSensorCalibration
   step.calibration.calibrate_analog_sensor.CalibrateAnalogSensor


Functions
---------

.. autoapisummary::

   step.calibration.calibrate_analog_sensor.analog_sensor_store_key


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

.. py:data:: ANALOG_SENSOR_STORE_SECTION
   :value: 'analog-sensor'


.. py:function:: analog_sensor_store_key(sensor: raccoon.hal.AnalogSensor, set_name: str) -> str

   Return the CalibrationStore set key for *sensor* / *set_name*.


.. py:class:: AnalogSensorCalibration

   Reference reading captured during calibration.


   .. py:attribute:: target_value
      :type:  float


   .. py:attribute:: std
      :type:  float


   .. py:attribute:: sample_count
      :type:  int


.. py:class:: CalibrateAnalogSensor(sensor: raccoon.hal.AnalogSensor, set_name: str = 'default', sample_duration: float = 3.0)

   Bases: :py:obj:`step.calibration.calibrate_step.CalibrateStep`\ [\ :py:obj:`AnalogSensorCalibration`\ ]


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

   :raises RuntimeError: If the sensor has no valid reading during sampling.

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