step.motion.characterize_drive

Characterize drive limits by commanding raw motor power and measuring response.

Bypasses ALL velocity control (library PID and firmware BEMF PID) to discover the robot’s true physical limits: max velocity, acceleration, and deceleration for each axis. Motors are driven at 100% PWM via the kinematics layer’s applyPowerCommand, which uses inverse kinematics to compute per-wheel direction signs while commanding raw open-loop power.

Results are persisted to raccoon.project.yml under robot.motion_pid and applied in-memory.

Classes

AxisResult	Measured limits for a single axis.
CharacterizeDrive	Characterize the robot's physical drive limits at full motor power.

Module Contents

class step.motion.characterize_drive.AxisResult

Measured limits for a single axis.

max_velocity: float = 0.0

acceleration: float = 0.0

deceleration: float = 0.0

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

Bases: step.Step

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.

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

axes = None

trials

power_percent

accel_timeout = 3.0

decel_timeout = 3.0

persist = True

results: dict[str, AxisResult]