libstp.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 and collect per-cycle telemetry into CSV files.

Functions

tune_drive(→ TuneDrive)

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

Module Contents

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

class libstp.step.motion.tune_drive.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: 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.

distances_cm

speeds

csv_dir

axis

settle_time = 1.5

timeout = 15.0

libstp.step.motion.tune_drive.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.

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.

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