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] | None)
trials(value: int)
power_percent(value: int)
accel_timeout(value: float)
decel_timeout(value: float)
sample_hz(value: int)
operating_velocity_frac(value: float)
persist(value: bool)
step.motion.characterize_drive_dsl.characterize_drive(axes: list[str] | None = None, trials: int = 3, power_percent: int = 100, accel_timeout: float = 3.0, decel_timeout: float = 3.0, sample_hz: int = 500, operating_velocity_frac: float = 0.6, 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 up to 500 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.

  • sample_hz – Position sampling rate in Hz for the C++ measurement loop. Default 500. Higher values give better accel/decel resolution.

  • operating_velocity_frac – Fraction of the measured peak velocity that is written back as max_velocity (and applied to the in-memory motion config). The peak measured at 100 %% PWM is the hardware ceiling, not a sensible operating speed — running the motion controllers at the ceiling means saturated wheels, no headroom for closed-loop correction, and unstable behaviour. Default 0.6 (≈30 cm/s for a robot that peaks at 50 cm/s).

  • 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(), .sample_hz(), .operating_velocity_frac(), .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,
)