step.motion.auto_tune_dsl

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

Source: auto_tune.py

Classes

AutoTuneVelLpfBuilder	Builder for AutoTuneVelLpf. Auto-generated — do not edit.
AutoTuneStaticFrictionBuilder	Builder for AutoTuneStaticFriction. Auto-generated — do not edit.
AutoTuneBemfVelocityBuilder	Builder for AutoTuneBemfVelocity. Auto-generated — do not edit.
AutoTuneFirmwarePidBuilder	Builder for AutoTuneFirmwarePid. Auto-generated — do not edit.
AutoTuneVelocityBuilder	Builder for AutoTuneVelocity. Auto-generated — do not edit.
AutoTuneMotionBuilder	Builder for AutoTuneMotion. Auto-generated — do not edit.
AutoTuneBuilder	Builder for AutoTune. Auto-generated — do not edit.

Functions

auto_tune_vel_lpf([persist])	Tune the IIR velocity-filter alpha per motor (Phase 1).
auto_tune_static_friction([persist])	Measure per-motor static-friction threshold kS in PWM percent (Phase 2).
auto_tune_bemf_velocity([persist, pwm_min_percent, ...])	Calibrate per-motor ticks_to_rad (BEMF→rad) against the calibration board.
auto_tune_firmware_pid([persist, max_bemf_speeds, csv_dir])	Tune per-motor STM32 MAV-mode velocity PID via BEMF step response (Phase 3).
auto_tune_velocity([axes, persist])	Calibrate the MCU chassis velocity-command gain per axis (Phase 6).
auto_tune_motion([axes, persist])	Tune motion PID controllers via iterative real-world optimization (Phase 7).
auto_tune([vel_axes, characterize_axes, motion_axes, ...])	Run the full auto-tune pipeline.

Module Contents

class step.motion.auto_tune_dsl.AutoTuneVelLpfBuilder

Bases: raccoon.step.step_builder.StepBuilder

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

persist(value: bool)

step.motion.auto_tune_dsl.auto_tune_vel_lpf(persist: bool = True)

Tune the IIR velocity-filter alpha per motor (Phase 1).

Collects raw BEMF samples at a steady velocity, replays them through IIR low-pass filters with varying alpha, and applies the alpha that minimises a weighted noise+lag score. Runs first in the full pipeline because every downstream phase relies on the same velocity-feedback filter.

Parameters:

persist – Write tuned vel_lpf_alpha values to raccoon.project.yml. Default True.

Returns:

A AutoTuneVelLpfBuilder (chainable via .persist(), .on_anomaly(), .skip_timing()).

Example:

from raccoon.step.motion import auto_tune_vel_lpf

auto_tune_vel_lpf()

class step.motion.auto_tune_dsl.AutoTuneStaticFrictionBuilder

Bases: raccoon.step.step_builder.StepBuilder

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

persist(value: bool)

step.motion.auto_tune_dsl.auto_tune_static_friction(persist: bool = True)

Measure per-motor static-friction threshold kS in PWM percent (Phase 2).

For each drive motor the PWM is swept from a low starting percentage upward in both directions. The first PWM level where the median BEMF exceeds a motion threshold is recorded as kS.

Parameters:

persist – Reserved for future YAML persistence. Currently logs only.

Returns:

A AutoTuneStaticFrictionBuilder (chainable via .persist(), .on_anomaly(), .skip_timing()).

Example:

from raccoon.step.motion import auto_tune_static_friction

auto_tune_static_friction()

class step.motion.auto_tune_dsl.AutoTuneBemfVelocityBuilder

Bases: raccoon.step.step_builder.StepBuilder

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

persist(value: bool)

pwm_min_percent(value: int)

pwm_max_percent(value: int)

pwm_steps(value: int)

sweeps(value: int)

step.motion.auto_tune_dsl.auto_tune_bemf_velocity(persist: bool = True, pwm_min_percent: int = 30, pwm_max_percent: int = 90, pwm_steps: int = 6, sweeps: int = 3)

Calibrate per-motor ticks_to_rad (BEMF→rad) against the calibration board.

Fully automatic. Drives the chassis straight forward at a sweep of open-loop PWM levels (back-and-forth, staying near the start) and, for each level, compares the ground-truth distance travelled — read from the external calibration board’s optical-flow + IMU odometry — against the accumulated BEMF ticks per motor. From that it derives, per motor, ticks_to_rad = (distance / wheel_radius) / Δticks.

Crucially it does not assume the ADC-BEMF↔velocity relationship is linear: it computes the per-motor coefficient of variation of ticks_to_rad across the speed range plus an ω-vs-BEMF linear fit (slope/intercept/R²) and reports whether a single scale actually holds. If the relationship is clearly curved or offset, that is logged as a warning rather than silently persisting a misleading single value.

Prerequisites:

• The calibration board must be connected. This step temporarily requests calibration-board odometry for the tune and restores the previous preference afterward; the tuner aborts if the board still is not the active source.

• Roughly 1 m of clear runway forward/back.

Parameters:

• persist – Write tuned ticks_to_rad per motor to raccoon.project.yml. Default True.

• pwm_min_percent – Lowest PWM level in the sweep (percent). Default 30.

• pwm_max_percent – Highest PWM level in the sweep (percent). Default 90.

• pwm_steps – Number of evenly spaced PWM levels. Default 6.

• sweeps – Number of full sweeps to run; points from all sweeps are pooled into one per-motor fit. More sweeps stabilise the extrapolated bemf_offset (the ω=0 intercept is noise-sensitive). Default 3.

Returns:

A AutoTuneBemfVelocityBuilder (chainable via .persist(), .pwm_min_percent(), .pwm_max_percent(), .pwm_steps(), .sweeps(), .on_anomaly(), .skip_timing()).

Example:

from raccoon.step.motion import auto_tune_bemf_velocity

auto_tune_bemf_velocity()

class step.motion.auto_tune_dsl.AutoTuneFirmwarePidBuilder

Bases: raccoon.step.step_builder.StepBuilder

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

persist(value: bool)

max_bemf_speeds(value: dict[int, int] | None)

csv_dir(value: str | None)

step.motion.auto_tune_dsl.auto_tune_firmware_pid(persist: bool = True, max_bemf_speeds: dict[int, int] | None = None, csv_dir: str | None = '/tmp/auto_tune')

Tune per-motor STM32 MAV-mode velocity PID via BEMF step response (Phase 3).

For each drive motor: record a BEMF step response, fit a FOPDT plant, derive CHR PID gains, push them to the firmware. Gains are accepted only when the tuned ISE is strictly smaller than the baseline ISE.

Parameters:

• persist – Unused — gains are applied directly to firmware state.

• max_bemf_speeds – Optional {port: max_bemf_speed} map. If unset, the C++ side runs a brief power sweep to estimate it.

• csv_dir – When set, every step-response sample is dumped to a CSV under this directory (one per motor + phase) plus a summary CSV with the plant fit and gains. Default "/tmp/auto_tune".

Returns:

A AutoTuneFirmwarePidBuilder (chainable via .persist(), .max_bemf_speeds(), .csv_dir(), .on_anomaly(), .skip_timing()).

Example:

from raccoon.step.motion import auto_tune_firmware_pid

auto_tune_firmware_pid()

class step.motion.auto_tune_dsl.AutoTuneVelocityBuilder

Bases: raccoon.step.step_builder.StepBuilder

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

axes(value: list[str] | None)

persist(value: bool)

step.motion.auto_tune_dsl.auto_tune_velocity(axes: list[str] | None = None, persist: bool = True)

Calibrate the MCU chassis velocity-command gain per axis (Phase 6).

With the chassis velocity loop running on the coprocessor (forward kinematics + per-wheel MAV PID), there is no host velocity PID left to tune. What this phase tunes instead is the chassis-level command ACCURACY: it commands a mid-range body velocity, measures the achieved velocity against external ground truth (the calib board), and folds a per-axis correction gain into the STM32 forward-kinematics matrix so commanded == achieved. This compensates drivetrain efficiency the ideal geometry ignores (most notably mecanum roller slip, where wheels track their BEMF setpoint correctly yet the chassis travels less than predicted). The candidate gain is validated by re-measuring and accepted only if the effective gain moved closer to 1.0.

Prerequisites: Phase 5 (drive characterization) should have run first so a max-velocity-per-axis is known. Phases 1–4 (LPF, static friction, firmware MAV PID, ticks_to_rad) should also have run so the inner loop is stable. A calib board must be connected for the external measurement.

Parameters:

• axes – Velocity axes to tune ("vx", "vy", "wz"). Default auto-detects from kinematics.

• persist – Write accepted gains to raccoon.project.yml (robot.drive.kinematics.velocity_command_gain). Default True.

Returns:

A AutoTuneVelocityBuilder (chainable via .axes(), .persist(), .on_anomaly(), .skip_timing()).

Example:

from raccoon.step.motion import auto_tune_velocity

auto_tune_velocity()
auto_tune_velocity(axes=["vx"])

class step.motion.auto_tune_dsl.AutoTuneMotionBuilder

Bases: raccoon.step.step_builder.StepBuilder

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

axes(value: list[str] | None)

persist(value: bool)

step.motion.auto_tune_dsl.auto_tune_motion(axes: list[str] | None = None, persist: bool = True)

Tune motion PID controllers via iterative real-world optimization (Phase 7).

Uses Hooke-Jeeves coordinate descent on the distance/heading PID kp & kd via real LinearMotion and TurnMotion trials with constraint-aware scoring.

Prerequisites: velocity controllers tuned (Phase 6) and drive limits characterized (Phase 5).

Parameters:

• axes – Motion parameters to tune ("distance", "lateral", "heading"). Default auto-detects from kinematics.

• persist – Write final gains to raccoon.project.yml. Default True.

Returns:

A AutoTuneMotionBuilder (chainable via .axes(), .persist(), .on_anomaly(), .skip_timing()).

Example:

from raccoon.step.motion import auto_tune_motion

auto_tune_motion()
auto_tune_motion(axes=["heading"])

class step.motion.auto_tune_dsl.AutoTuneBuilder

Bases: raccoon.step.step_builder.StepBuilder

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

vel_axes(value: list[str] | None)

characterize_axes(value: list[str] | None)

motion_axes(value: list[str] | None)

tune_bemf_velocity(value: bool)

tune_vel_lpf(value: bool)

tune_static_friction(value: bool)

tune_firmware_pid(value: bool)

tune_encoder_cal(value: bool)

tune_characterize(value: bool)

tune_velocity(value: bool)

tune_motion(value: bool)

tune_tolerances(value: bool)

pwm_min_percent(value: int)

pwm_max_percent(value: int)

pwm_steps(value: int)

sweeps(value: int)

characterize_trials(value: int)

characterize_power_percent(value: int)

persist(value: bool)

step_confirm(value: bool)

step.motion.auto_tune_dsl.auto_tune(vel_axes: list[str] | None = None, characterize_axes: list[str] | None = None, motion_axes: list[str] | None = None, tune_bemf_velocity: bool = True, tune_vel_lpf: bool = True, tune_static_friction: bool = True, tune_firmware_pid: bool = True, tune_encoder_cal: bool = False, tune_characterize: bool = True, tune_velocity: bool = True, tune_motion: bool = True, tune_tolerances: bool = True, pwm_min_percent: int = 30, pwm_max_percent: int = 90, pwm_steps: int = 6, sweeps: int = 2, characterize_trials: int = 3, characterize_power_percent: int = 100, persist: bool = True, step_confirm: bool = True)

Run the full auto-tune pipeline.

Drives the C++ AutoTuner one phase at a time so UI confirmations can pause between phases. Each phase reads its inputs from the live drive / motors / motion-config objects and writes back to those same objects, so state stays coherent without Python having to shuttle calibration values.

Only the phases that are currently validated run by default. The remaining phases are kept but disabled — pass the matching tune_*=True to re-enable.

Default-enabled phases:

• bemf_velocity — per-motor ticks_to_rad against the calibration board (the big validated win; supersedes the IMU encoder_cal).

• vel_lpf — per-motor IIR alpha for velocity feedback.

• static_friction — kS per motor (PWM percent).

• firmware_pid — STM32 MAV-mode inner velocity loop.

• characterize — max velocity / accel / decel per axis at 100% PWM, measured against calib-board ground truth (frame-independent straight-line distance).

• velocity — MCU chassis velocity-command gain per axis: makes commanded body velocity match the calib-board-measured achieved velocity.

• motion — distance / heading PID via real LinearMotion/TurnMotion trials (Hooke-Jeeves); linear trials return to start between runs.

• tolerances — distance/angle tolerances derived from motion residuals.

Default-disabled phases (re-enable explicitly):

• encoder_cal — IMU ticks_to_rad; superseded by bemf_velocity.

Parameters:

• vel_axes – Override the auto-detected velocity axis list.

• characterize_axes – Override the auto-detected characterize axis list.

• motion_axes – Override the auto-detected motion-parameter list.

• tune_bemf_velocity – Enable BEMF→velocity ticks_to_rad calibration against the calibration board. Default True.

• tune_vel_lpf – Enable vel LPF alpha tuning. Default True.

• tune_static_friction – Enable static friction measurement. Default True.

• tune_firmware_pid – Enable firmware velocity PID tuning. Default True.

• tune_encoder_cal – Enable IMU encoder calibration. Default False.

• tune_characterize – Enable drive characterization (max vel/accel/decel per axis vs calib board). Default True.

• tune_velocity – Enable MCU chassis velocity-command-gain calibration (commanded == achieved body velocity). Default True.

• tune_motion – Enable motion PID tuning (distance / heading) via real LinearMotion/TurnMotion trials; linear trials return to start after each so the robot stays in place. Default True.

• tune_tolerances – Enable tolerance derivation from motion residuals. Default True.

• pwm_min_percent – Lowest PWM level for the bemf_velocity sweep. Default 30.

• pwm_max_percent – Highest PWM level for the bemf_velocity sweep. Default 90.

• pwm_steps – Number of bemf_velocity sweep PWM levels. Default 6.

• sweeps – Number of bemf_velocity sweeps to pool. Default 2.

• characterize_trials – Number of characterize trials per axis. Default 3.

• characterize_power_percent – Raw PWM for characterize trials (1–100). Default 100.

• persist – Write phase results to raccoon.project.yml. Default True.

• step_confirm – Pause for a button press before every phase. Default True.

Returns:

A AutoTuneBuilder (chainable via .vel_axes(), .characterize_axes(), .motion_axes(), .tune_bemf_velocity(), .tune_vel_lpf(), .tune_static_friction(), .tune_firmware_pid(), .tune_encoder_cal(), .tune_characterize(), .tune_velocity(), .tune_motion(), .tune_tolerances(), .pwm_min_percent(), .pwm_max_percent(), .pwm_steps(), .sweeps(), .characterize_trials(), .characterize_power_percent(), .persist(), .step_confirm(), .on_anomaly(), .skip_timing()).

Example:

from raccoon.step.motion import auto_tune

auto_tune()