step.motion.tune_drive

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

CSV_HEADER

Classes

TuneDrive

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

Module Contents

step.motion.tune_drive.CSV_HEADER = ['time_s', 'dt', 'target_m', 'position_m', 'setpoint_position_m', 'setpoint_velocity_mps',...

class step.motion.tune_drive.TuneDrive(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)

Bases: step.Step

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.

Parameters:

• distances_cm – List of distances to test, in centimeters. Negative values drive in reverse. Default [10, 25, 50, 100].

• 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].

• csv_dir – Directory where CSV files are written. Created automatically if it does not exist. Default "/tmp/drive_telemetry".

• axis – Drive axis to test: "forward" or "lateral". Default "forward".

• settle_time – Seconds to wait between runs for the robot to come to rest. Default 1.5.

• timeout – Maximum seconds per run before the drive is aborted. Default 15.0.

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

distances_cm = None

speeds = None

csv_dir = '/tmp/drive_telemetry'

axis

settle_time = 1.5

timeout = 15.0