libstp.step.motion.lineup.forward ================================= .. py:module:: libstp.step.motion.lineup.forward .. autoapi-nested-parse:: Forward/backward lineup on lines using two IR sensors. Drives until both sensors hit a line, measures the distance between hits, then computes and executes a corrective turn angle. Classes ------- .. autoapisummary:: libstp.step.motion.lineup.forward.TimingBasedLineUp Functions --------- .. autoapisummary:: libstp.step.motion.lineup.forward.lineup libstp.step.motion.lineup.forward.forward_lineup_on_black libstp.step.motion.lineup.forward.forward_lineup_on_white libstp.step.motion.lineup.forward.backward_lineup_on_black libstp.step.motion.lineup.forward.backward_lineup_on_white Module Contents --------------- .. py:class:: TimingBasedLineUp(left_sensor: libstp.sensor_ir.IRSensor, right_sensor: libstp.sensor_ir.IRSensor, target: libstp.step.motion.move_until.SurfaceColor = SurfaceColor.BLACK, forward_speed: float = 1.0, detection_threshold: float = 0.9) Bases: :py:obj:`libstp.step.motion.motion_step.MotionStep` Drive forward or backward until both left and right IR sensors detect a line. The robot drives at ``forward_speed`` while polling both sensors each update cycle. When the first sensor crosses the target-colored line its odometry position is recorded. Driving continues until the second sensor also crosses. The distance traveled between the two hits is stored in ``results`` as ``(first_sensor_name, distance_m)`` so a downstream step can compute the corrective turn angle. This is an internal building-block step -- use the public ``forward_lineup_on_black`` / ``backward_lineup_on_white`` (etc.) factory functions instead. :param left_sensor: IR sensor mounted on the left side of the chassis. :param right_sensor: IR sensor mounted on the right side of the chassis. :param target: The surface color to detect (BLACK or WHITE). :param forward_speed: Driving speed in m/s. Positive = forward, negative = backward. :param detection_threshold: Confidence value (0--1) a sensor must reach to count as having detected the target color. .. py:attribute:: left_sensor .. py:attribute:: right_sensor .. py:attribute:: target .. py:attribute:: forward_speed :value: 1.0 .. py:attribute:: threshold :value: 0.9 .. py:attribute:: distance_between_hits_m :type: float :value: 0.0 .. py:attribute:: results :type: tuple :value: (None, 0.0) .. py:method:: on_start(robot: libstp.robot.api.GenericRobot) -> None Called once before the loop. Override to set up motion/velocity. .. py:method:: on_update(robot: libstp.robot.api.GenericRobot, dt: float) -> bool Called each cycle with dt in seconds. Return True when motion is complete. .. py:method:: on_stop(robot: libstp.robot.api.GenericRobot) -> None Called after loop exits. Default: hard_stop. .. py:function:: lineup(left_sensor: libstp.sensor_ir.IRSensor, right_sensor: libstp.sensor_ir.IRSensor, target: libstp.step.motion.move_until.SurfaceColor = SurfaceColor.BLACK, forward_speed: float = 1.0, detection_threshold: float = 0.7) -> libstp.step.Sequential Measure angular skew from a line using two IR sensors, then correct with a turn. Composes a ``TimingBasedLineUp`` measurement phase with a deferred corrective turn. During the measurement the robot drives until both sensors cross the target line. The distance between the two hit positions and the known physical gap between the sensors are used to compute a corrective turn angle via ``atan(distance_driven / sensor_gap)``. The turn is then executed to align the robot perpendicular to the line. This is an internal helper -- prefer the public ``forward_lineup_on_black`` family of functions. :param left_sensor: IR sensor on the left side of the chassis. :param right_sensor: IR sensor on the right side of the chassis. :param target: Surface color to detect (BLACK or WHITE). :param forward_speed: Driving speed in m/s (negative for backward). :param detection_threshold: Confidence (0--1) required to register a hit. :returns: A two-step sequence (measure + corrective turn). :rtype: Sequential .. py:function:: forward_lineup_on_black(left_sensor: libstp.sensor_ir.IRSensor, right_sensor: libstp.sensor_ir.IRSensor, detection_threshold: float = 0.7) -> libstp.step.Sequential Drive forward onto a black line, align perpendicular, then clear to white. The robot drives forward until both IR sensors detect a black line. The stagger distance between the two sensor hits is used to compute a corrective turn that aligns the chassis perpendicular to the line. After the turn the robot creeps forward at half speed until both sensors see white, leaving it just past the line and squared up. Prerequisites: Two IR line sensors mounted on the left and right sides of the chassis, with the robot's ``distance_between_sensors`` configured. :param left_sensor: IR sensor on the left side of the chassis. :param right_sensor: IR sensor on the right side of the chassis. :param detection_threshold: Confidence value (0--1) each sensor must reach to count as detecting a line. Lower values trigger earlier but are more susceptible to noise. :returns: measure + corrective turn + drive-until-white. :rtype: Sequential Example:: from libstp.step.motion.lineup.forward import forward_lineup_on_black step = forward_lineup_on_black( left_sensor=robot.left_line_sensor, right_sensor=robot.right_line_sensor, detection_threshold=0.8, ) step.run(robot) .. py:function:: forward_lineup_on_white(left_sensor: libstp.sensor_ir.IRSensor, right_sensor: libstp.sensor_ir.IRSensor, detection_threshold: float = 0.7) -> libstp.step.Sequential Drive forward onto a white line, align perpendicular, then clear to black. The robot drives forward until both IR sensors detect a white surface. The stagger distance between the two sensor hits is used to compute a corrective turn that aligns the chassis perpendicular to the line edge. After the turn the robot creeps forward at half speed until both sensors see black, leaving it just past the white region and squared up. Prerequisites: Two IR line sensors mounted on the left and right sides of the chassis, with the robot's ``distance_between_sensors`` configured. :param left_sensor: IR sensor on the left side of the chassis. :param right_sensor: IR sensor on the right side of the chassis. :param detection_threshold: Confidence value (0--1) each sensor must reach to count as detecting a white surface. Lower values trigger earlier but are more susceptible to noise. :returns: measure + corrective turn + drive-until-black. :rtype: Sequential Example:: from libstp.step.motion.lineup.forward import forward_lineup_on_white step = forward_lineup_on_white( left_sensor=robot.left_line_sensor, right_sensor=robot.right_line_sensor, ) step.run(robot) .. py:function:: backward_lineup_on_black(left_sensor: libstp.sensor_ir.IRSensor, right_sensor: libstp.sensor_ir.IRSensor, detection_threshold: float = 0.7) -> libstp.step.Sequential Drive backward onto a black line, align perpendicular, then clear to white. Identical to ``forward_lineup_on_black`` but the robot reverses into the line instead of driving forward. The corrective turn direction is automatically mirrored to account for the reversed geometry. After alignment the robot continues backward at half speed until both sensors see white. Prerequisites: Two IR line sensors mounted on the left and right sides of the chassis, with the robot's ``distance_between_sensors`` configured. :param left_sensor: IR sensor on the left side of the chassis. :param right_sensor: IR sensor on the right side of the chassis. :param detection_threshold: Confidence value (0--1) each sensor must reach to count as detecting a line. :returns: measure (backward) + corrective turn + drive-until-white (backward). :rtype: Sequential Example:: from libstp.step.motion.lineup.forward import backward_lineup_on_black step = backward_lineup_on_black( left_sensor=robot.left_line_sensor, right_sensor=robot.right_line_sensor, detection_threshold=0.7, ) step.run(robot) .. py:function:: backward_lineup_on_white(left_sensor: libstp.sensor_ir.IRSensor, right_sensor: libstp.sensor_ir.IRSensor, detection_threshold: float = 0.7) -> libstp.step.Sequential Drive backward onto a white line, align perpendicular, then clear to black. Identical to ``forward_lineup_on_white`` but the robot reverses into the line instead of driving forward. The corrective turn direction is automatically mirrored to account for the reversed geometry. After alignment the robot continues backward at half speed until both sensors see black. Prerequisites: Two IR line sensors mounted on the left and right sides of the chassis, with the robot's ``distance_between_sensors`` configured. :param left_sensor: IR sensor on the left side of the chassis. :param right_sensor: IR sensor on the right side of the chassis. :param detection_threshold: Confidence value (0--1) each sensor must reach to count as detecting a white surface. :returns: measure (backward) + corrective turn + drive-until-black (backward). :rtype: Sequential Example:: from libstp.step.motion.lineup.forward import backward_lineup_on_white step = backward_lineup_on_white( left_sensor=robot.left_line_sensor, right_sensor=robot.right_line_sensor, ) step.run(robot)