libstp.step.motion.wall_align

Wall alignment step with IMU-based bump detection.

Drives toward a wall at constant velocity without heading correction. Uses the IMU’s gravity-compensated linear acceleration to detect the moment of impact, then optionally continues pushing for a short settle period so the robot can rotate flush against the wall surface.

Classes

WallDirection

Direction to drive into a wall.

BumpResult

Information about a detected wall impact.

WallAlign

Drive into a wall using IMU bump detection, then settle flush.

Functions

wall_align_forward(→ WallAlign)

Drive forward into a wall and align the front of the robot.

wall_align_backward(→ WallAlign)

Drive backward into a wall and align the back of the robot.

wall_align_strafe_left(→ WallAlign)

Strafe left into a wall and align the left side of the robot.

wall_align_strafe_right(→ WallAlign)

Strafe right into a wall and align the right side of the robot.

Module Contents

class libstp.step.motion.wall_align.WallDirection(*args, **kwds)

Bases: enum.Enum

Direction to drive into a wall.

FORWARD = 'forward'
BACKWARD = 'backward'
STRAFE_LEFT = 'strafe_left'
STRAFE_RIGHT = 'strafe_right'
class libstp.step.motion.wall_align.BumpResult

Information about a detected wall impact.

accel_magnitude: float

XY acceleration magnitude at impact in m/s².

impact_angle_deg: float

Wall misalignment angle in degrees. 0 = hit the wall square-on. Positive = wall surface angled CCW from perpendicular. Computed from the peak accel vector; may be noisy on single samples.

heading_correction_deg: float

How many degrees the robot actually rotated during the settle push to become flush with the wall. This is the reliable metric — it comes from the IMU heading, not a single accel sample.

class libstp.step.motion.wall_align.WallAlign(direction: WallDirection, speed: float, accel_threshold: float, settle_duration: float, max_duration: float, grace_period: float)

Bases: libstp.step.motion.motion_step.MotionStep

Drive into a wall using IMU bump detection, then settle flush.

The robot drives at constant velocity without heading correction. When the horizontal linear acceleration exceeds a threshold (indicating a collision), it records the impact and continues pushing for a settle period to let the chassis rotate flush against the wall.

direction
speed
accel_threshold
settle_duration
max_duration
grace_period
bump_result: BumpResult | None = None
on_start(robot: libstp.robot.api.GenericRobot) → None
on_update(robot: libstp.robot.api.GenericRobot, dt: float) → bool
libstp.step.motion.wall_align.wall_align_forward(speed: float = 1.0, accel_threshold: float = 0.5, settle_duration: float = 0.2, max_duration: float = 5.0, grace_period: float = 0.3) → WallAlign

Drive forward into a wall and align the front of the robot.

Apply constant forward velocity without heading correction so the robot naturally rotates flush against the wall surface. The step monitors gravity-compensated linear acceleration from the IMU and stops once a collision spike is detected followed by a short settle period.

The grace period prevents false triggers from the initial acceleration transient when the robot starts moving.

After the step completes, step.bump_result contains the impact magnitude, estimated wall misalignment angle, and the heading correction applied during the settle push.

Parameters:

  • speed – Drive speed in m/s (default 1.0).

  • accel_threshold – Minimum XY linear-acceleration magnitude in m/s² to classify as a bump (default 0.5). Lower values are more sensitive but may false-trigger on rough surfaces.

  • settle_duration – Seconds to keep pushing after the bump is detected, letting the chassis rotate flush (default 0.2).

  • max_duration – Safety timeout in seconds — the step finishes even if no bump is detected (default 5.0).

  • grace_period – Seconds to ignore acceleration after starting, so the robot’s own acceleration doesn’t trigger detection (default 0.3).

Returns:

A WallAlign step driving forward with bump detection.

Example:

from libstp.step.motion import wall_align_forward, drive_forward

# Drive near the wall, then bump-align against it
seq([drive_forward(30), wall_align_forward()])

# More sensitive detection at slower speed
wall_align_forward(speed=0.3, accel_threshold=0.3)
libstp.step.motion.wall_align.wall_align_backward(speed: float = 1.0, accel_threshold: float = 0.5, settle_duration: float = 0.2, max_duration: float = 5.0, grace_period: float = 0.3) → WallAlign

Drive backward into a wall and align the back of the robot.

Apply constant backward velocity without heading correction so the robot naturally rotates flush against the wall surface. Uses IMU bump detection to know when the wall has been reached.

Parameters:

  • speed – Drive speed in m/s (default 1.0).

  • accel_threshold – Minimum XY linear-acceleration magnitude in m/s² to classify as a bump (default 0.5).

  • settle_duration – Seconds to keep pushing after impact (default 0.2).

  • max_duration – Safety timeout in seconds (default 5.0).

  • grace_period – Seconds to ignore acceleration at start (default 0.3).

Returns:

A WallAlign step driving backward with bump detection.

Example:

from libstp.step.motion import wall_align_backward, drive_backward

# Drive to the wall in reverse, then align against it
seq([drive_backward(30), wall_align_backward()])
libstp.step.motion.wall_align.wall_align_strafe_left(speed: float = 0.5, accel_threshold: float = 0.5, settle_duration: float = 0.2, max_duration: float = 5.0, grace_period: float = 0.3) → WallAlign

Strafe left into a wall and align the left side of the robot.

Apply constant leftward velocity without heading correction so the robot naturally rotates flush against the wall surface. Uses IMU bump detection. Requires a mecanum or omni drivetrain capable of lateral movement.

Parameters:

  • speed – Strafe speed in m/s (default 0.5).

  • accel_threshold – Minimum XY linear-acceleration magnitude in m/s² to classify as a bump (default 0.5).

  • settle_duration – Seconds to keep pushing after impact (default 0.2).

  • max_duration – Safety timeout in seconds (default 5.0).

  • grace_period – Seconds to ignore acceleration at start (default 0.3).

Returns:

A WallAlign step strafing left with bump detection.

Example:

from libstp.step.motion import wall_align_strafe_left

# Strafe-align the left side against a wall
wall_align_strafe_left(speed=0.4)
libstp.step.motion.wall_align.wall_align_strafe_right(speed: float = 0.5, accel_threshold: float = 0.5, settle_duration: float = 0.2, max_duration: float = 5.0, grace_period: float = 0.3) → WallAlign

Strafe right into a wall and align the right side of the robot.

Apply constant rightward velocity without heading correction so the robot naturally rotates flush against the wall surface. Uses IMU bump detection. Requires a mecanum or omni drivetrain capable of lateral movement.

Parameters:

  • speed – Strafe speed in m/s (default 0.5).

  • accel_threshold – Minimum XY linear-acceleration magnitude in m/s² to classify as a bump (default 0.5).

  • settle_duration – Seconds to keep pushing after impact (default 0.2).

  • max_duration – Safety timeout in seconds (default 5.0).

  • grace_period – Seconds to ignore acceleration at start (default 0.3).

Returns:

A WallAlign step strafing right with bump detection.

Example:

from libstp.step.motion import wall_align_strafe_right

# Strafe-align the right side against a wall
wall_align_strafe_right(speed=0.4)