libstp.step.motion.line_follow ============================== .. py:module:: libstp.step.motion.line_follow .. autoapi-nested-parse:: Line following using IR sensors. This module provides steps for following lines using one or two IR sensors with PID-based steering control. Two families of steps are available: 1. **Profiled line follow** (``follow_line``, ``follow_line_single``, etc.) — built on ``LinearMotion`` for trapezoidal-profiled distance control along a single axis. 2. **Directional line follow** (``directional_follow_line``, ``strafe_follow_line``, etc.) — uses direct ``ChassisVelocity`` control with independent heading and strafe speed inputs, allowing line following while strafing, driving diagonally, or any combination. Classes ------- .. autoapisummary:: libstp.step.motion.line_follow.LineFollowConfig libstp.step.motion.line_follow.LineSide libstp.step.motion.line_follow.SingleLineFollowConfig libstp.step.motion.line_follow.SingleLineFollowUntilBlackConfig libstp.step.motion.line_follow.LineFollow libstp.step.motion.line_follow.SingleSensorLineFollow libstp.step.motion.line_follow.SingleSensorLineFollowUntilBlack libstp.step.motion.line_follow.DirectionalLineFollowConfig libstp.step.motion.line_follow.DirectionalLineFollow libstp.step.motion.line_follow.DirectionalSingleLineFollowConfig libstp.step.motion.line_follow.DirectionalSingleLineFollow Functions --------- .. autoapisummary:: libstp.step.motion.line_follow.follow_line libstp.step.motion.line_follow.follow_line_until_both_black libstp.step.motion.line_follow.follow_line_single libstp.step.motion.line_follow.follow_line_single_until_black libstp.step.motion.line_follow.directional_follow_line libstp.step.motion.line_follow.directional_follow_line_until_both_black libstp.step.motion.line_follow.strafe_follow_line libstp.step.motion.line_follow.strafe_follow_line_until_both_black libstp.step.motion.line_follow.strafe_follow_line_single libstp.step.motion.line_follow.strafe_follow_line_single_until_black libstp.step.motion.line_follow.directional_follow_line_single libstp.step.motion.line_follow.directional_follow_line_single_until_black Module Contents --------------- .. py:class:: LineFollowConfig Configuration for LineFollow step with two sensors. .. py:attribute:: left_sensor :type: libstp.sensor_ir.IRSensor .. py:attribute:: right_sensor :type: libstp.sensor_ir.IRSensor .. py:attribute:: speed_scale :type: float .. py:attribute:: distance_cm :type: float | None :value: None .. py:attribute:: kp :type: float :value: 0.75 .. py:attribute:: ki :type: float :value: 0.0 .. py:attribute:: kd :type: float :value: 0.5 .. py:attribute:: both_black_threshold :type: float :value: 0.7 .. py:class:: LineSide(*args, **kwds) Bases: :py:obj:`enum.Enum` Which edge of the line to track with a single sensor. .. py:attribute:: LEFT :value: 'left' .. py:attribute:: RIGHT :value: 'right' .. py:class:: SingleLineFollowConfig Configuration for single-sensor line following. The sensor tracks the edge of a line using PID control. ``side`` selects which edge: LEFT means the sensor approaches from the left (steers right when it sees black), RIGHT is the opposite. .. py:attribute:: sensor :type: libstp.sensor_ir.IRSensor .. py:attribute:: speed_scale :type: float .. py:attribute:: distance_cm :type: float .. py:attribute:: side :type: LineSide .. py:attribute:: kp :type: float :value: 1.0 .. py:attribute:: ki :type: float :value: 0.0 .. py:attribute:: kd :type: float :value: 0.3 .. py:class:: SingleLineFollowUntilBlackConfig Configuration for single-sensor line following that stops when a second sensor sees black. The ``sensor`` tracks the line edge using PID control, while ``stop_sensor`` is monitored each cycle. When the stop sensor's probabilityOfBlack exceeds ``stop_threshold``, the step finishes. .. py:attribute:: sensor :type: libstp.sensor_ir.IRSensor .. py:attribute:: stop_sensor :type: libstp.sensor_ir.IRSensor .. py:attribute:: speed_scale :type: float .. py:attribute:: side :type: LineSide .. py:attribute:: stop_threshold :type: float :value: 0.7 .. py:attribute:: kp :type: float :value: 1.0 .. py:attribute:: ki :type: float :value: 0.0 .. py:attribute:: kd :type: float :value: 0.3 .. py:class:: LineFollow(config: LineFollowConfig) Bases: :py:obj:`libstp.step.motion.motion_step.MotionStep` Follow a line using two IR sensors with PID steering. Computes a steering error as the difference between the left and right sensors' ``probabilityOfBlack()`` readings and feeds it through a PID controller. The PID output is applied as an angular velocity (omega) override on the underlying ``LinearMotion``, which handles profiled distance control and odometry integration. Supports two modes: fixed-distance (stop after traveling a set distance) and until-both-black (stop when both sensors see black simultaneously, indicating an intersection). .. py:attribute:: config .. py:method:: to_simulation_step() -> libstp.step.SimulationStep .. py:method:: on_start(robot: libstp.robot.api.GenericRobot) -> None .. py:method:: on_update(robot: libstp.robot.api.GenericRobot, dt: float) -> bool .. py:class:: SingleSensorLineFollow(config: SingleLineFollowConfig) Bases: :py:obj:`libstp.step.motion.motion_step.MotionStep` Follow a line edge using a single IR sensor with PID edge-tracking. Targets ``probabilityOfBlack() = 0.5`` (the line edge) as the setpoint. The ``side`` configuration flips the error sign to select left vs. right edge tracking. The PID output overrides the angular velocity on the underlying ``LinearMotion``, which handles profiled distance control and odometry integration. Terminates when the configured distance has been traveled. .. py:attribute:: config .. py:method:: to_simulation_step() -> libstp.step.SimulationStep .. py:method:: on_start(robot: libstp.robot.api.GenericRobot) -> None .. py:method:: on_update(robot: libstp.robot.api.GenericRobot, dt: float) -> bool .. py:class:: SingleSensorLineFollowUntilBlack(config: SingleLineFollowUntilBlackConfig) Bases: :py:obj:`libstp.step.motion.motion_step.MotionStep` Follow a line edge using one sensor, stopping when a second sensor sees black. Combines single-sensor edge tracking (targeting ``probabilityOfBlack() = 0.5``) with an event-based stop condition. The tracking sensor feeds a PID controller whose output overrides angular velocity on the underlying ``LinearMotion``. Each cycle, the stop sensor is checked; when its ``probabilityOfBlack()`` exceeds the configured threshold the step finishes immediately. .. py:attribute:: config .. py:method:: to_simulation_step() -> libstp.step.SimulationStep .. py:method:: on_start(robot: libstp.robot.api.GenericRobot) -> None .. py:method:: on_update(robot: libstp.robot.api.GenericRobot, dt: float) -> bool .. py:function:: follow_line(left_sensor: libstp.sensor_ir.IRSensor, right_sensor: libstp.sensor_ir.IRSensor, distance_cm: float, speed: float = 0.5, kp: float = 0.75, ki: float = 0.0, kd: float = 0.5) -> LineFollow Follow a line for a specified distance using two IR sensors for steering. Drives forward while a PID controller steers the robot to keep it centered on a line. The error signal is the difference between the left and right sensors' ``probabilityOfBlack()`` readings. A positive error (left sees more black) steers the robot back toward center. The underlying ``LinearMotion`` handles profiled velocity control and odometry-based distance tracking, while the PID output overrides the heading command as an angular velocity (omega). Both sensors must be calibrated (white/black thresholds set) before use. :param left_sensor: Left IR sensor instance, positioned to the left of the line. :param right_sensor: Right IR sensor instance, positioned to the right of the line. :param distance_cm: Distance to follow in centimeters. The step finishes when this distance has been traveled according to odometry. :param speed: Fraction of max velocity (0.0--1.0). Lower speeds give the PID more time to correct but are slower overall. Default 0.5. :param kp: Proportional gain for steering PID. Higher values produce sharper corrections. Default 0.75. :param ki: Integral gain for steering PID. Typically left at 0.0 unless there is a persistent drift. Default 0.0. :param kd: Derivative gain for steering PID. Damps oscillation around the line. Default 0.5. :returns: A ``LineFollow`` step configured for distance-based line following. Example:: from libstp.step.motion import follow_line # Follow a line for 80 cm at half speed step = follow_line( left_sensor=robot.left_ir, right_sensor=robot.right_ir, distance_cm=80.0, speed=0.5, ) # Tighter tracking with higher kp step = follow_line( left_sensor=robot.left_ir, right_sensor=robot.right_ir, distance_cm=120.0, speed=0.3, kp=1.2, kd=0.8, ) .. py:function:: follow_line_until_both_black(left_sensor: libstp.sensor_ir.IRSensor, right_sensor: libstp.sensor_ir.IRSensor, speed: float = 0.5, kp: float = 0.75, ki: float = 0.0, kd: float = 0.5, both_black_threshold: float = 0.7) -> LineFollow Follow a line until both sensors detect black, indicating an intersection. Drives forward with PID-based steering (same as ``follow_line``) but instead of stopping after a fixed distance, the step monitors both sensors each cycle. When *both* ``probabilityOfBlack()`` readings exceed ``both_black_threshold`` simultaneously, the robot has reached a perpendicular line or intersection and the step finishes. Internally the distance target is set very large so ``LinearMotion`` never finishes on its own -- the both-black condition is the sole termination criterion. Both sensors must be calibrated (white/black thresholds set) before use. :param left_sensor: Left IR sensor instance, positioned to the left of the line. :param right_sensor: Right IR sensor instance, positioned to the right of the line. :param speed: Fraction of max velocity (0.0--1.0). Default 0.5. :param kp: Proportional gain for steering PID. Default 0.75. :param ki: Integral gain for steering PID. Default 0.0. :param kd: Derivative gain for steering PID. Default 0.5. :param both_black_threshold: The ``probabilityOfBlack()`` value that both sensors must exceed to trigger the stop. Default 0.7. :returns: A ``LineFollow`` step that stops when an intersection is detected. Example:: from libstp.step.motion import follow_line_until_both_black # Follow a line until hitting a cross-line step = follow_line_until_both_black( left_sensor=robot.left_ir, right_sensor=robot.right_ir, speed=0.4, ) # More sensitive intersection detection step = follow_line_until_both_black( left_sensor=robot.left_ir, right_sensor=robot.right_ir, speed=0.3, both_black_threshold=0.6, ) .. py:function:: follow_line_single(sensor: libstp.sensor_ir.IRSensor, distance_cm: float, speed: float = 0.5, side: LineSide = LineSide.LEFT, kp: float = 1.0, ki: float = 0.0, kd: float = 0.3) -> SingleSensorLineFollow Follow a line edge using a single IR sensor for a specified distance. The sensor tracks the boundary between the line and the background, where ``probabilityOfBlack()`` is approximately 0.5. The PID controller drives the error ``(reading - 0.5)`` toward zero, keeping the sensor positioned right on the edge. The ``side`` parameter controls which edge: ``LEFT`` means the sensor is to the left of the line (steers right when it sees black), and ``RIGHT`` is the opposite. This variant is useful when only one sensor is available, or when the line is too narrow for two sensors. The underlying ``LinearMotion`` handles profiled velocity and odometry-based distance tracking. The sensor must be calibrated (white/black thresholds set) before use. :param sensor: The IR sensor instance used for edge tracking. :param distance_cm: Distance to follow in centimeters. The step finishes when this distance has been traveled. :param speed: Fraction of max velocity (0.0--1.0). Default 0.5. :param side: Which edge of the line to track. ``LineSide.LEFT`` (default) or ``LineSide.RIGHT``. :param kp: Proportional gain for steering PID. Default 1.0. :param ki: Integral gain for steering PID. Default 0.0. :param kd: Derivative gain for steering PID. Default 0.3. :returns: A ``SingleSensorLineFollow`` step. Example:: from libstp.step.motion import follow_line_single, LineSide # Follow the left edge of a line for 60 cm step = follow_line_single( sensor=robot.front_ir, distance_cm=60.0, speed=0.4, side=LineSide.LEFT, ) # Follow the right edge with custom PID gains step = follow_line_single( sensor=robot.front_ir, distance_cm=100.0, speed=0.5, side=LineSide.RIGHT, kp=1.5, kd=0.5, ) .. py:function:: follow_line_single_until_black(sensor: libstp.sensor_ir.IRSensor, stop_sensor: libstp.sensor_ir.IRSensor, speed: float = 0.5, side: LineSide = LineSide.LEFT, stop_threshold: float = 0.7, kp: float = 1.0, ki: float = 0.0, kd: float = 0.3) -> SingleSensorLineFollowUntilBlack Follow a line edge using one sensor, stopping when a second sensor sees black. Combines single-sensor edge tracking with an event-based stop condition. The ``sensor`` tracks the line edge (targeting ``probabilityOfBlack() ~ 0.5``) using PID control, while the ``stop_sensor`` is polled each cycle. When the stop sensor's ``probabilityOfBlack()`` exceeds ``stop_threshold``, the step finishes immediately. This is useful for following a line until the robot reaches a perpendicular marker or a specific position detected by a second sensor (e.g., a side- mounted sensor that crosses a branch line). Both sensors must be calibrated (white/black thresholds set) before use. :param sensor: The IR sensor used for edge-tracking along the line. :param stop_sensor: A second IR sensor monitored for the stop condition. The step finishes when this sensor's ``probabilityOfBlack()`` exceeds ``stop_threshold``. :param speed: Fraction of max velocity (0.0--1.0). Default 0.5. :param side: Which edge of the line to track. ``LineSide.LEFT`` (default) or ``LineSide.RIGHT``. :param stop_threshold: The ``probabilityOfBlack()`` value the stop sensor must exceed to trigger the stop. Default 0.7. :param kp: Proportional gain for steering PID. Default 1.0. :param ki: Integral gain for steering PID. Default 0.0. :param kd: Derivative gain for steering PID. Default 0.3. :returns: A ``SingleSensorLineFollowUntilBlack`` step. Example:: from libstp.step.motion import follow_line_single_until_black, LineSide # Follow left edge until the right sensor hits a cross-line step = follow_line_single_until_black( sensor=robot.left_ir, stop_sensor=robot.right_ir, speed=0.4, side=LineSide.LEFT, ) # Lower stop threshold for earlier detection step = follow_line_single_until_black( sensor=robot.front_ir, stop_sensor=robot.side_ir, speed=0.3, stop_threshold=0.5, kp=1.2, ) .. py:class:: DirectionalLineFollowConfig Configuration for directional line following with two sensors. Allows independent heading (forward/backward) and strafe (left/right) speed components. The PID controller steers via angular velocity based on the difference between left and right sensor readings. .. py:attribute:: left_sensor :type: libstp.sensor_ir.IRSensor .. py:attribute:: right_sensor :type: libstp.sensor_ir.IRSensor .. py:attribute:: heading_speed :type: float .. py:attribute:: strafe_speed :type: float .. py:attribute:: distance_cm :type: float | None :value: None .. py:attribute:: kp :type: float :value: 0.75 .. py:attribute:: ki :type: float :value: 0.0 .. py:attribute:: kd :type: float :value: 0.5 .. py:attribute:: both_black_threshold :type: float :value: 0.7 .. py:class:: DirectionalLineFollow(config: DirectionalLineFollowConfig) Bases: :py:obj:`libstp.step.motion.motion_step.MotionStep` Follow a line with independent heading and strafe velocity components. Uses direct ``ChassisVelocity`` control instead of ``LinearMotion``, enabling line following while strafing, driving diagonally, or any combination. A PID controller computes angular velocity from the difference between the left and right sensors' ``probabilityOfBlack()`` readings. Distance is tracked via odometry as euclidean distance from the start position. Supports two stop modes: fixed distance and until-both-black. .. py:attribute:: config .. py:method:: to_simulation_step() -> libstp.step.SimulationStep .. py:method:: on_start(robot: libstp.robot.api.GenericRobot) -> None .. py:method:: on_update(robot: libstp.robot.api.GenericRobot, dt: float) -> bool .. py:class:: DirectionalSingleLineFollowConfig Configuration for directional single-sensor line following. The sensor tracks the edge of a line using PID control while the robot moves with the given heading and strafe velocity components. .. py:attribute:: sensor :type: libstp.sensor_ir.IRSensor .. py:attribute:: heading_speed :type: float .. py:attribute:: strafe_speed :type: float .. py:attribute:: distance_cm :type: float | None :value: None .. py:attribute:: side :type: LineSide .. py:attribute:: stop_sensor :type: libstp.sensor_ir.IRSensor | None :value: None .. py:attribute:: stop_threshold :type: float :value: 0.7 .. py:attribute:: kp :type: float :value: 1.0 .. py:attribute:: ki :type: float :value: 0.0 .. py:attribute:: kd :type: float :value: 0.3 .. py:class:: DirectionalSingleLineFollow(config: DirectionalSingleLineFollowConfig) Bases: :py:obj:`libstp.step.motion.motion_step.MotionStep` Follow a line edge with independent heading and strafe velocity. Targets ``probabilityOfBlack() = 0.5`` (the line edge) as the setpoint. The ``side`` configuration flips the error sign to select left vs. right edge tracking. The PID output controls angular velocity while heading and strafe velocities are set directly via ``ChassisVelocity``. Supports distance-based and stop-sensor-based termination. .. py:attribute:: config .. py:method:: to_simulation_step() -> libstp.step.SimulationStep .. py:method:: on_start(robot: libstp.robot.api.GenericRobot) -> None .. py:method:: on_update(robot: libstp.robot.api.GenericRobot, dt: float) -> bool .. py:function:: directional_follow_line(left_sensor: libstp.sensor_ir.IRSensor, right_sensor: libstp.sensor_ir.IRSensor, distance_cm: float, heading_speed: float = 0.0, strafe_speed: float = 0.0, kp: float = 0.75, ki: float = 0.0, kd: float = 0.5) -> DirectionalLineFollow Follow a line for a distance with independent heading and strafe speeds. Drive along a line using any combination of forward and lateral velocity while a PID controller steers the robot via angular velocity. The error signal is the difference between the left and right sensors' ``probabilityOfBlack()`` readings. Distance is tracked via odometry as the euclidean distance from the start position. Unlike ``follow_line`` which only drives forward, this step accepts both ``heading_speed`` (forward/backward) and ``strafe_speed`` (left/right) as independent fractions of max velocity, enabling line following while strafing or driving diagonally. Both sensors must be calibrated (white/black thresholds set) before use. Requires a mecanum or omni-wheel drivetrain if ``strafe_speed`` is nonzero. :param left_sensor: Left IR sensor instance, positioned to the left of the line. :param right_sensor: Right IR sensor instance, positioned to the right of the line. :param distance_cm: Distance to follow in centimeters. The step finishes when this euclidean distance has been traveled. :param heading_speed: Forward/backward speed as a fraction of max velocity (-1.0 to 1.0). Positive = forward, negative = backward. Default 0.0. :param strafe_speed: Lateral speed as a fraction of max velocity (-1.0 to 1.0). Positive = right, negative = left. Default 0.0. :param kp: Proportional gain for steering PID. Default 0.75. :param ki: Integral gain for steering PID. Default 0.0. :param kd: Derivative gain for steering PID. Default 0.5. :returns: A ``DirectionalLineFollow`` step. Example:: from libstp.step.motion import directional_follow_line # Strafe right while following a line for 50 cm directional_follow_line( left_sensor=robot.left_ir, right_sensor=robot.right_ir, distance_cm=50.0, strafe_speed=0.5, ) # Drive diagonally forward-right along a line directional_follow_line( left_sensor=robot.left_ir, right_sensor=robot.right_ir, distance_cm=80.0, heading_speed=0.3, strafe_speed=0.4, ) .. py:function:: directional_follow_line_until_both_black(left_sensor: libstp.sensor_ir.IRSensor, right_sensor: libstp.sensor_ir.IRSensor, heading_speed: float = 0.0, strafe_speed: float = 0.0, kp: float = 0.75, ki: float = 0.0, kd: float = 0.5, both_black_threshold: float = 0.7) -> DirectionalLineFollow Follow a line with heading and strafe until both sensors detect black. Same as ``directional_follow_line`` but instead of stopping after a fixed distance, the step monitors both sensors each cycle and finishes when both ``probabilityOfBlack()`` readings exceed ``both_black_threshold`` simultaneously, indicating an intersection. Both sensors must be calibrated (white/black thresholds set) before use. Requires a mecanum or omni-wheel drivetrain if ``strafe_speed`` is nonzero. :param left_sensor: Left IR sensor instance. :param right_sensor: Right IR sensor instance. :param heading_speed: Forward/backward speed fraction (-1.0 to 1.0). Default 0.0. :param strafe_speed: Lateral speed fraction (-1.0 to 1.0). Default 0.0. :param kp: Proportional gain for steering PID. Default 0.75. :param ki: Integral gain for steering PID. Default 0.0. :param kd: Derivative gain for steering PID. Default 0.5. :param both_black_threshold: ``probabilityOfBlack()`` value that both sensors must exceed to trigger the stop. Default 0.7. :returns: A ``DirectionalLineFollow`` step that stops at an intersection. Example:: from libstp.step.motion import directional_follow_line_until_both_black # Strafe right along a line until hitting a cross-line directional_follow_line_until_both_black( left_sensor=robot.left_ir, right_sensor=robot.right_ir, strafe_speed=0.4, ) .. py:function:: strafe_follow_line(left_sensor: libstp.sensor_ir.IRSensor, right_sensor: libstp.sensor_ir.IRSensor, distance_cm: float, speed: float = 0.5, kp: float = 0.75, ki: float = 0.0, kd: float = 0.5) -> DirectionalLineFollow Follow a line by strafing right for a specified distance. Convenience wrapper around ``directional_follow_line`` for pure lateral line following. The robot strafes right at the given speed while PID steering keeps it centered on the line using two sensors. Both sensors must be calibrated. Requires a mecanum or omni-wheel drivetrain. :param left_sensor: Left IR sensor instance. :param right_sensor: Right IR sensor instance. :param distance_cm: Distance to strafe in centimeters. :param speed: Strafe speed as fraction of max lateral velocity (0.0 to 1.0). Default 0.5. Use negative values to strafe left. :param kp: Proportional gain for steering PID. Default 0.75. :param ki: Integral gain for steering PID. Default 0.0. :param kd: Derivative gain for steering PID. Default 0.5. :returns: A ``DirectionalLineFollow`` step configured for lateral motion. Example:: from libstp.step.motion import strafe_follow_line # Strafe right along a line for 40 cm strafe_follow_line( left_sensor=robot.left_ir, right_sensor=robot.right_ir, distance_cm=40.0, speed=0.4, ) # Strafe left along a line for 30 cm strafe_follow_line( left_sensor=robot.left_ir, right_sensor=robot.right_ir, distance_cm=30.0, speed=-0.4, ) .. py:function:: strafe_follow_line_until_both_black(left_sensor: libstp.sensor_ir.IRSensor, right_sensor: libstp.sensor_ir.IRSensor, speed: float = 0.5, kp: float = 0.75, ki: float = 0.0, kd: float = 0.5, both_black_threshold: float = 0.7) -> DirectionalLineFollow Follow a line by strafing right until both sensors detect black. Convenience wrapper around ``directional_follow_line_until_both_black`` for pure lateral line following until an intersection is reached. Both sensors must be calibrated. Requires a mecanum or omni-wheel drivetrain. :param left_sensor: Left IR sensor instance. :param right_sensor: Right IR sensor instance. :param speed: Strafe speed as fraction of max lateral velocity (0.0 to 1.0). Default 0.5. Use negative values to strafe left. :param kp: Proportional gain for steering PID. Default 0.75. :param ki: Integral gain for steering PID. Default 0.0. :param kd: Derivative gain for steering PID. Default 0.5. :param both_black_threshold: ``probabilityOfBlack()`` value that both sensors must exceed to trigger the stop. Default 0.7. :returns: A ``DirectionalLineFollow`` step that stops at an intersection. Example:: from libstp.step.motion import strafe_follow_line_until_both_black # Strafe right along a line until a cross-line strafe_follow_line_until_both_black( left_sensor=robot.left_ir, right_sensor=robot.right_ir, speed=0.4, ) .. py:function:: strafe_follow_line_single(sensor: libstp.sensor_ir.IRSensor, distance_cm: float, speed: float = 0.5, side: LineSide = LineSide.LEFT, kp: float = 1.0, ki: float = 0.0, kd: float = 0.3) -> DirectionalSingleLineFollow Follow a line edge by strafing right using a single sensor. Convenience wrapper around ``directional_follow_line_single`` for pure lateral single-sensor line following. The robot strafes at the given speed while PID edge-tracking keeps the sensor on the line boundary. The sensor must be calibrated. Requires a mecanum or omni-wheel drivetrain. :param sensor: IR sensor for edge tracking. :param distance_cm: Distance to strafe in centimeters. :param speed: Strafe speed as fraction of max lateral velocity (0.0 to 1.0). Default 0.5. Use negative values to strafe left. :param side: Which edge of the line to track. Default ``LineSide.LEFT``. :param kp: Proportional gain for steering PID. Default 1.0. :param ki: Integral gain for steering PID. Default 0.0. :param kd: Derivative gain for steering PID. Default 0.3. :returns: A ``DirectionalSingleLineFollow`` step configured for lateral motion. Example:: from libstp.step.motion import strafe_follow_line_single, LineSide # Strafe right along a line edge for 40 cm strafe_follow_line_single( sensor=robot.front_ir, distance_cm=40.0, speed=0.4, side=LineSide.LEFT, ) # Strafe left along a line edge for 30 cm strafe_follow_line_single( sensor=robot.front_ir, distance_cm=30.0, speed=-0.4, side=LineSide.RIGHT, ) .. py:function:: strafe_follow_line_single_until_black(sensor: libstp.sensor_ir.IRSensor, stop_sensor: libstp.sensor_ir.IRSensor, speed: float = 0.5, side: LineSide = LineSide.LEFT, stop_threshold: float = 0.7, kp: float = 1.0, ki: float = 0.0, kd: float = 0.3) -> DirectionalSingleLineFollow Follow a line edge by strafing, stopping when a second sensor sees black. Convenience wrapper around ``directional_follow_line_single_until_black`` for pure lateral single-sensor line following with a stop-sensor trigger. Both sensors must be calibrated. Requires a mecanum or omni-wheel drivetrain. :param sensor: IR sensor for edge tracking. :param stop_sensor: Second IR sensor for the stop condition. :param speed: Strafe speed as fraction of max lateral velocity (0.0 to 1.0). Default 0.5. Use negative values to strafe left. :param side: Which edge of the line to track. Default ``LineSide.LEFT``. :param stop_threshold: ``probabilityOfBlack()`` the stop sensor must exceed. Default 0.7. :param kp: Proportional gain for steering PID. Default 1.0. :param ki: Integral gain for steering PID. Default 0.0. :param kd: Derivative gain for steering PID. Default 0.3. :returns: A ``DirectionalSingleLineFollow`` step that stops on sensor trigger. Example:: from libstp.step.motion import strafe_follow_line_single_until_black, LineSide # Strafe right along a line edge until the stop sensor hits a cross-line strafe_follow_line_single_until_black( sensor=robot.left_ir, stop_sensor=robot.right_ir, speed=0.4, side=LineSide.LEFT, ) .. py:function:: directional_follow_line_single(sensor: libstp.sensor_ir.IRSensor, distance_cm: float, heading_speed: float = 0.0, strafe_speed: float = 0.0, side: LineSide = LineSide.LEFT, kp: float = 1.0, ki: float = 0.0, kd: float = 0.3) -> DirectionalSingleLineFollow Follow a line edge with a single sensor and independent heading/strafe speeds. The sensor tracks the boundary between the line and the background, where ``probabilityOfBlack()`` is approximately 0.5. The ``side`` parameter selects which edge to track. The PID output controls angular velocity while heading and strafe velocities are set independently. The sensor must be calibrated (white/black thresholds set) before use. Requires a mecanum or omni-wheel drivetrain if ``strafe_speed`` is nonzero. :param sensor: IR sensor for edge tracking. :param distance_cm: Distance to follow in centimeters. :param heading_speed: Forward/backward speed fraction (-1.0 to 1.0). Default 0.0. :param strafe_speed: Lateral speed fraction (-1.0 to 1.0). Default 0.0. :param side: Which edge of the line to track. Default ``LineSide.LEFT``. :param kp: Proportional gain for steering PID. Default 1.0. :param ki: Integral gain for steering PID. Default 0.0. :param kd: Derivative gain for steering PID. Default 0.3. :returns: A ``DirectionalSingleLineFollow`` step. Example:: from libstp.step.motion import directional_follow_line_single, LineSide # Strafe right while tracking the left edge of a line directional_follow_line_single( sensor=robot.front_ir, distance_cm=50.0, strafe_speed=0.4, side=LineSide.LEFT, ) .. py:function:: directional_follow_line_single_until_black(sensor: libstp.sensor_ir.IRSensor, stop_sensor: libstp.sensor_ir.IRSensor, heading_speed: float = 0.0, strafe_speed: float = 0.0, side: LineSide = LineSide.LEFT, stop_threshold: float = 0.7, kp: float = 1.0, ki: float = 0.0, kd: float = 0.3) -> DirectionalSingleLineFollow Follow a line edge with heading/strafe, stopping when a second sensor sees black. Combines single-sensor edge tracking with an event-based stop condition. The ``sensor`` tracks the line edge using PID control while the ``stop_sensor`` is polled each cycle. Both sensors must be calibrated before use. Requires a mecanum or omni-wheel drivetrain if ``strafe_speed`` is nonzero. :param sensor: IR sensor for edge tracking. :param stop_sensor: Second IR sensor for the stop condition. :param heading_speed: Forward/backward speed fraction (-1.0 to 1.0). Default 0.0. :param strafe_speed: Lateral speed fraction (-1.0 to 1.0). Default 0.0. :param side: Which edge of the line to track. Default ``LineSide.LEFT``. :param stop_threshold: ``probabilityOfBlack()`` the stop sensor must exceed. Default 0.7. :param kp: Proportional gain for steering PID. Default 1.0. :param ki: Integral gain for steering PID. Default 0.0. :param kd: Derivative gain for steering PID. Default 0.3. :returns: A ``DirectionalSingleLineFollow`` step. Example:: from libstp.step.motion import directional_follow_line_single_until_black, LineSide # Strafe right along a line edge until the stop sensor hits a cross-line directional_follow_line_single_until_black( sensor=robot.left_ir, stop_sensor=robot.right_ir, strafe_speed=0.4, side=LineSide.LEFT, )