libstp.step.motion.tune_drive
=============================

.. py:module:: libstp.step.motion.tune_drive

.. autoapi-nested-parse::

   Drive telemetry collection for PID tuning.

   Runs test drives at specified distances and speeds, collecting per-cycle
   telemetry (commanded vs measured vs predicted position/velocity, PID outputs,
   saturation state) into CSV files for offline analysis.



Attributes
----------

.. autoapisummary::

   libstp.step.motion.tune_drive.CSV_HEADER


Classes
-------

.. autoapisummary::

   libstp.step.motion.tune_drive.TuneDrive


Functions
---------

.. autoapisummary::

   libstp.step.motion.tune_drive.tune_drive


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

.. py:data:: CSV_HEADER
   :value: ['time_s', 'dt', 'target_m', 'position_m', 'setpoint_position_m', 'setpoint_velocity_mps',...


.. py:class:: TuneDrive(distances_cm: list[float], speeds: list[float], csv_dir: str, axis: libstp.motion.LinearAxis = LinearAxis.Forward, settle_time: float = 1.5, timeout: float = 15.0)

   Bases: :py:obj:`libstp.step.Step`


   Run test drives and collect per-cycle telemetry into CSV files.

   Iterates over every (distance, speed) combination, executing a real
   ``LinearMotion`` drive at 50 Hz and capturing detailed telemetry
   (position, velocity, PID outputs, saturation state, heading error, etc.).
   Each run produces a separate CSV file and a console summary with final
   position error, peak velocity, cross-track error, and heading error.
   Intended for offline analysis and PID gain tuning during robot setup.


   .. py:attribute:: distances_cm


   .. py:attribute:: speeds


   .. py:attribute:: csv_dir


   .. py:attribute:: axis


   .. py:attribute:: settle_time
      :value: 1.5



   .. py:attribute:: timeout
      :value: 15.0



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

   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 ``TuneDrive`` step that executes the test matrix and writes CSV
             files.

   Example::

       from libstp.step.motion import tune_drive

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

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

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