libstp.step.motion.wall_align ============================= .. py:module:: libstp.step.motion.wall_align .. autoapi-nested-parse:: 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 ------- .. autoapisummary:: libstp.step.motion.wall_align.WallDirection libstp.step.motion.wall_align.BumpResult libstp.step.motion.wall_align.WallAlign Functions --------- .. autoapisummary:: libstp.step.motion.wall_align.wall_align_forward libstp.step.motion.wall_align.wall_align_backward libstp.step.motion.wall_align.wall_align_strafe_left libstp.step.motion.wall_align.wall_align_strafe_right Module Contents --------------- .. py:class:: WallDirection(*args, **kwds) Bases: :py:obj:`enum.Enum` Direction to drive into a wall. .. py:attribute:: FORWARD :value: 'forward' .. py:attribute:: BACKWARD :value: 'backward' .. py:attribute:: STRAFE_LEFT :value: 'strafe_left' .. py:attribute:: STRAFE_RIGHT :value: 'strafe_right' .. py:class:: BumpResult Information about a detected wall impact. .. py:attribute:: accel_magnitude :type: float XY acceleration magnitude at impact in m/s². .. py:attribute:: impact_angle_deg :type: 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. .. py:attribute:: heading_correction_deg :type: 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. .. py:class:: WallAlign(direction: WallDirection, speed: float, accel_threshold: float, settle_duration: float, max_duration: float, grace_period: float) Bases: :py:obj:`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. .. py:attribute:: direction .. py:attribute:: speed .. py:attribute:: accel_threshold .. py:attribute:: settle_duration .. py:attribute:: max_duration .. py:attribute:: grace_period .. py:attribute:: bump_result :type: Optional[BumpResult] :value: None .. py:method:: on_start(robot: libstp.robot.api.GenericRobot) -> None .. py:method:: on_update(robot: libstp.robot.api.GenericRobot, dt: float) -> bool .. py:function:: 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. :param speed: Drive speed in m/s (default 1.0). :param 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. :param settle_duration: Seconds to keep pushing after the bump is detected, letting the chassis rotate flush (default 0.2). :param max_duration: Safety timeout in seconds — the step finishes even if no bump is detected (default 5.0). :param 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) .. py:function:: 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. :param speed: Drive speed in m/s (default 1.0). :param accel_threshold: Minimum XY linear-acceleration magnitude in m/s² to classify as a bump (default 0.5). :param settle_duration: Seconds to keep pushing after impact (default 0.2). :param max_duration: Safety timeout in seconds (default 5.0). :param 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()]) .. py:function:: 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. :param speed: Strafe speed in m/s (default 0.5). :param accel_threshold: Minimum XY linear-acceleration magnitude in m/s² to classify as a bump (default 0.5). :param settle_duration: Seconds to keep pushing after impact (default 0.2). :param max_duration: Safety timeout in seconds (default 5.0). :param 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) .. py:function:: 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. :param speed: Strafe speed in m/s (default 0.5). :param accel_threshold: Minimum XY linear-acceleration magnitude in m/s² to classify as a bump (default 0.5). :param settle_duration: Seconds to keep pushing after impact (default 0.2). :param max_duration: Safety timeout in seconds (default 5.0). :param 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)