step.motion.tune_drive_dsl
==========================

.. py:module:: step.motion.tune_drive_dsl

.. autoapi-nested-parse::

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

   Source: tune_drive.py



Classes
-------

.. autoapisummary::

   step.motion.tune_drive_dsl.TuneDriveBuilder


Functions
---------

.. autoapisummary::

   step.motion.tune_drive_dsl.tune_drive


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

.. py:class:: TuneDriveBuilder

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


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


   .. py:method:: distances_cm(value: list[float])


   .. py:method:: speeds(value: list[float])


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


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


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


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


.. py:function:: tune_drive(distances_cm: list[float] = None, speeds: list[float] = None, csv_dir: str = '/tmp/drive_telemetry', axis: str = 'forward', settle_time: float = 1.5, timeout: float = 15.0)

   Run test drives at various distances and speeds, saving telemetry to CSV.

   Executes every combination of (distance, speed) as a real ``LinearMotion``
   drive, collecting per-cycle telemetry at 50 Hz. Each run produces a CSV
   file containing columns such as ``time_s``, ``position_m``,
   ``setpoint_position_m``, ``setpoint_velocity_mps``, ``distance_error_m``,
   ``actual_error_m``, ``filtered_velocity_mps``, ``cmd_vx_mps``,
   ``pid_primary_raw``, ``heading_rad``, ``saturated``, and more (see
   ``CSV_HEADER`` in the module source for the full list).

   The CSV files are intended for offline analysis -- plot position vs.
   setpoint to check tracking, examine PID outputs for saturation, compare
   overshoot across speeds, etc. This is a diagnostic/tuning tool used
   during robot setup, not during competition runs.

   The robot must have enough clear space to drive the longest requested
   distance.

   :param distances_cm: List of distances to test, in centimeters. Negative values drive in reverse. Default ``[10, 25, 50, 100]``.
   :param speeds: List of speed scales to test (0.0--1.0). Each distance is driven at each speed. Default ``[0.3, 0.6, 1.0]``.
   :param csv_dir: Directory where CSV files are written. Created automatically if it does not exist. Default ``"/tmp/drive_telemetry"``.
   :param axis: Drive axis to test: ``"forward"`` or ``"lateral"``. Default ``"forward"``.
   :param settle_time: Seconds to wait between runs for the robot to come to rest. Default 1.5.
   :param timeout: Maximum seconds per run before the drive is aborted. Default 15.0.

   :returns: A TuneDriveBuilder (chainable via ``.distances_cm()``, ``.speeds()``, ``.csv_dir()``, ``.axis()``, ``.settle_time()``, ``.timeout()``, ``.on_anomaly()``, ``.skip_timing()``).

   Example::

       from raccoon.step.motion import tune_drive

       # Quick test at a single distance and speed
       tune_drive(
           distances_cm=[50],
           speeds=[0.5],
           csv_dir="/tmp/quick_test",
       )

       # Full sweep for forward axis tuning
       tune_drive(
           distances_cm=[10, 25, 50, 100],
           speeds=[0.3, 0.6, 1.0],
       )

       # Lateral axis characterization
       tune_drive(
           distances_cm=[20, 40],
           speeds=[0.3, 0.6],
           axis="lateral",
       )