step.motion.characterize_drive_dsl

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

Source: characterize_drive.py

Classes

CharacterizeDriveBuilder

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

Functions

characterize_drive([axes, trials, power_percent, ...])

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

Module Contents

class step.motion.characterize_drive_dsl.CharacterizeDriveBuilder

Bases: raccoon.step.step_builder.StepBuilder

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

axes(value: list[str])
trials(value: int)
power_percent(value: int)
accel_timeout(value: float)
decel_timeout(value: float)
persist(value: bool)
step.motion.characterize_drive_dsl.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.

Parameters:

  • axes – Which axes to characterize. Options are "forward", "lateral", and "angular". Default ["forward"].

  • trials – Number of trials per axis. The median is used for robustness against outliers. Default 3.

  • power_percent – Motor power percentage (1–100). Default 100 for true maximum characterization.

  • accel_timeout – Maximum time in seconds to wait for the acceleration phase before giving up. Default 3.0.

  • decel_timeout – Maximum time in seconds to record the deceleration (coast-down) phase. Default 3.0.

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