step.motion.characterize_drive_dsl
==================================

.. py:module:: step.motion.characterize_drive_dsl

.. autoapi-nested-parse::

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

   Source: characterize_drive.py



Classes
-------

.. autoapisummary::

   step.motion.characterize_drive_dsl.CharacterizeDriveBuilder


Functions
---------

.. autoapisummary::

   step.motion.characterize_drive_dsl.characterize_drive


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

.. py:class:: CharacterizeDriveBuilder

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


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


   .. py:method:: axes(value: list[str])


   .. py:method:: trials(value: int)


   .. py:method:: power_percent(value: int)


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


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


   .. py:method:: persist(value: bool)


.. py:function:: characterize_drive(axes: list[str] = None, trials: int = 3, power_percent: int = 100, accel_timeout: float = 3.0, decel_timeout: float = 3.0, persist: bool = True)

   Characterize the robot's physical drive limits at full motor power.

   Drives each axis at 100 %% raw PWM (open-loop ``setSpeed``) via the
   kinematics layer, completely bypassing both the library velocity PID and
   the firmware BEMF PID.  This reveals the true hardware ceiling for each
   degree of freedom.

   For each axis the step runs multiple independent trials consisting of two
   phases:

   1. **Acceleration phase** -- commands 100 %% power and records odometry at
      ~100 Hz until a velocity plateau is detected or the timeout expires.
      Max velocity and acceleration are extracted with 10 %%--90 %% rise-time
      analysis.

   2. **Deceleration phase** -- ramps back to full speed, then cuts power and
      records the coast-down.  Deceleration is computed from 90 %%--10 %%
      fall-time analysis.

   The median of all valid trials for each metric is taken as the final
   result.  Measured values are applied to the in-memory
   ``motion_pid_config`` immediately and, if ``persist`` is enabled, written
   to ``raccoon.project.yml`` under ``robot.motion_pid``.

   This step is intended for initial robot setup and should be run on a flat
   surface with enough room for the robot to accelerate to full speed.

   :param axes: Which axes to characterize. Options are ``"forward"``, ``"lateral"``, and ``"angular"``. Default ``["forward"]``.
   :param trials: Number of trials per axis. The median is used for robustness against outliers. Default 3.
   :param power_percent: Motor power percentage (1--100). Default 100 for true maximum characterization.
   :param accel_timeout: Maximum time in seconds to wait for the acceleration phase before giving up. Default 3.0.
   :param decel_timeout: Maximum time in seconds to record the deceleration (coast-down) phase. Default 3.0.
   :param persist: If ``True``, write the measured limits to ``raccoon.project.yml`` under ``robot.motion_pid``. Default ``True``.

   :returns: A CharacterizeDriveBuilder (chainable via ``.axes()``, ``.trials()``, ``.power_percent()``, ``.accel_timeout()``, ``.decel_timeout()``, ``.persist()``, ``.on_anomaly()``, ``.skip_timing()``).

   Example::

       from raccoon.step.motion import characterize_drive

       # Characterize forward axis at full power
       characterize_drive()

       # Characterize forward and angular axes with 5 trials each
       characterize_drive(
           axes=["forward", "angular"],
           trials=5,
       )

       # Characterize at 80% power without saving to disk (dry run)
       characterize_drive(
           axes=["forward", "lateral", "angular"],
           power_percent=80,
           persist=False,
       )