step.motion.line_follow_dsl¶

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

Source: line_follow.py

Classes¶

`FollowLineBuilder`	Builder for FollowLine. Auto-generated — do not edit.
`FollowLineSingleBuilder`	Builder for FollowLineSingle. Auto-generated — do not edit.
`DirectionalFollowLineBuilder`	Builder for DirectionalFollowLine. Auto-generated — do not edit.
`StrafeFollowLineBuilder`	Builder for StrafeFollowLine. Auto-generated — do not edit.
`StrafeFollowLineSingleBuilder`	Builder for StrafeFollowLineSingle. Auto-generated — do not edit.
`DirectionalFollowLineSingleBuilder`	Builder for DirectionalFollowLineSingle. Auto-generated — do not edit.

Functions¶

`follow_line`([left_sensor, right_sensor, distance_cm, ...])	Follow a line using two IR sensors for steering.
`follow_line_single`([sensor, distance_cm, speed, side, ...])	Follow a line edge using a single IR sensor.
`directional_follow_line`([left_sensor, right_sensor, ...])	Follow a line with independent heading and strafe speeds.
`strafe_follow_line`([left_sensor, right_sensor, ...])	Follow a line forward, correcting position by strafing left/right.
`strafe_follow_line_single`([sensor, distance_cm, ...])	Follow a line edge forward, correcting position by strafing.
`directional_follow_line_single`([sensor, distance_cm, ...])	Follow a line edge with a single sensor and independent heading/strafe speeds.

Module Contents¶

class step.motion.line_follow_dsl.FollowLineBuilder¶

Bases: raccoon.step.step_builder.StepBuilder

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

left_sensor(value: raccoon.sensor_ir.IRSensor)¶

right_sensor(value: raccoon.sensor_ir.IRSensor)¶

distance_cm(value: float | None)¶

speed(value: float)¶

kp(value: float)¶

ki(value: float)¶

kd(value: float)¶

until(value: raccoon.step.condition.StopCondition | None)¶

step.motion.line_follow_dsl.follow_line(left_sensor: raccoon.sensor_ir.IRSensor = _UNSET, right_sensor: raccoon.sensor_ir.IRSensor = _UNSET, distance_cm: float | None = None, speed: float = 0.5, kp: float = 0.4, ki: float = 0.0, kd: float = 0.1, until: raccoon.step.condition.StopCondition | None = None)¶

Follow a line 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).

Supports distance-based termination, composable StopCondition via .until(), or both (whichever triggers first). At least one of distance_cm or until must be provided.

Both sensors must be calibrated (white/black thresholds set) before use.

Parameters:

left_sensor – Left IR sensor instance, positioned to the left of the line.
right_sensor – Right IR sensor instance, positioned to the right of the line.
distance_cm – Distance to follow in centimeters. The step finishes when this distance has been traveled according to odometry. Optional if until is provided.
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.
kp – Proportional gain for steering PID. Higher values produce sharper corrections. Default 0.75.
ki – Integral gain for steering PID. Typically left at 0.0 unless there is a persistent drift. Default 0.0.
kd – Derivative gain for steering PID. Damps oscillation around the line. Default 0.5.
until – Composable stop condition (e.g., on_black(left) & on_black(right)). Can also be chained via the .until() builder method.

Returns:

A FollowLineBuilder (chainable via .left_sensor(), .right_sensor(), .distance_cm(), .speed(), .kp(), .ki(), .kd(), .until(), .on_anomaly(), .skip_timing()).

Example:

from raccoon.step.motion import FollowLine
from raccoon.step.condition import on_black

# Follow a line for 80 cm at half speed
follow_line(left_sensor=left, right_sensor=right, distance_cm=80, speed=0.5)

# Follow until both sensors see black (intersection)
follow_line(left, right, speed=0.5).until(on_black(left) & on_black(right))

# Distance + early termination
follow_line(left, right, distance_cm=100, speed=0.5).until(on_black(third))

class step.motion.line_follow_dsl.FollowLineSingleBuilder¶

Bases: raccoon.step.step_builder.StepBuilder

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

sensor(value: raccoon.sensor_ir.IRSensor)¶

distance_cm(value: float | None)¶

speed(value: float)¶

side(value: step.motion.line_follow.LineSide)¶

kp(value: float)¶

ki(value: float)¶

kd(value: float)¶

until(value: raccoon.step.condition.StopCondition | None)¶

step.motion.line_follow_dsl.follow_line_single(sensor: raccoon.sensor_ir.IRSensor = _UNSET, distance_cm: float | None = None, speed: float = 0.5, side: step.motion.line_follow.LineSide = LineSide.LEFT, kp: float = 0.4, ki: float = 0.0, kd: float = 0.1, until: raccoon.step.condition.StopCondition | None = None)¶

Follow a line edge using a single IR sensor.

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.

Supports distance-based termination, composable StopCondition via .until(), or both (whichever triggers first). At least one of distance_cm or until must be provided.

The sensor must be calibrated (white/black thresholds set) before use.

Parameters:

sensor – The IR sensor instance used for edge tracking.
distance_cm – Distance to follow in centimeters. The step finishes when this distance has been traveled. Optional if until is provided.
speed – Fraction of max velocity (0.0–1.0). Default 0.5.
side – Which edge of the line to track. LineSide.LEFT (default) or LineSide.RIGHT.
kp – Proportional gain for steering PID. Default 1.0.
ki – Integral gain for steering PID. Default 0.0.
kd – Derivative gain for steering PID. Default 0.3.
until – Composable stop condition (e.g., on_black(stop_sensor)). Can also be chained via the .until() builder method.

Returns:

A FollowLineSingleBuilder (chainable via .sensor(), .distance_cm(), .speed(), .side(), .kp(), .ki(), .kd(), .until(), .on_anomaly(), .skip_timing()).

Example:

from raccoon.step.motion import FollowLineSingle, LineSide
from raccoon.step.condition import on_black

# Follow left edge for 60 cm
follow_line_single(sensor=front_ir, distance_cm=60, speed=0.4)

# Follow until stop sensor sees black
follow_line_single(front_ir, speed=0.4, side=LineSide.LEFT).until(on_black(stop))

# Distance + early termination with timeout
follow_line_single(front_ir, distance_cm=100).until(on_black(stop) | after_seconds(10))

class step.motion.line_follow_dsl.DirectionalFollowLineBuilder¶

Bases: raccoon.step.step_builder.StepBuilder

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

left_sensor(value: raccoon.sensor_ir.IRSensor)¶

right_sensor(value: raccoon.sensor_ir.IRSensor)¶

distance_cm(value: float | None)¶

heading_speed(value: float)¶

strafe_speed(value: float)¶

kp(value: float)¶

ki(value: float)¶

kd(value: float)¶

until(value: raccoon.step.condition.StopCondition | None)¶

step.motion.line_follow_dsl.directional_follow_line(left_sensor: raccoon.sensor_ir.IRSensor = _UNSET, right_sensor: raccoon.sensor_ir.IRSensor = _UNSET, distance_cm: float | None = None, heading_speed: float = 0.0, strafe_speed: float = 0.0, kp: float = 0.4, ki: float = 0.0, kd: float = 0.1, until: raccoon.step.condition.StopCondition | None = None)¶

Follow a line 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 FollowLine 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.

Supports distance-based termination, composable StopCondition via .until(), or both (whichever triggers first). At least one of distance_cm or until must be provided.

Both sensors must be calibrated (white/black thresholds set) before use. Requires a mecanum or omni-wheel drivetrain if strafe_speed is nonzero.

Parameters:

left_sensor – Left IR sensor instance, positioned to the left of the line.
right_sensor – Right IR sensor instance, positioned to the right of the line.
distance_cm – Distance to follow in centimeters. The step finishes when this euclidean distance has been traveled. Optional if until is provided.
heading_speed – Forward/backward speed as a fraction of max velocity (-1.0 to 1.0). Positive = forward, negative = backward. Default 0.0.
strafe_speed – Lateral speed as a fraction of max velocity (-1.0 to 1.0). Positive = right, negative = left. Default 0.0.
kp – Proportional gain for steering PID. Default 0.75.
ki – Integral gain for steering PID. Default 0.0.
kd – Derivative gain for steering PID. Default 0.5.
until – Composable stop condition. Can also be chained via the .until() builder method.

Returns:

A DirectionalFollowLineBuilder (chainable via .left_sensor(), .right_sensor(), .distance_cm(), .heading_speed(), .strafe_speed(), .kp(), .ki(), .kd(), .until(), .on_anomaly(), .skip_timing()).

Example:

from raccoon.step.motion import DirectionalFollowLine
from raccoon.step.condition import on_black

# Strafe right while following a line for 50 cm
directional_follow_line(left, right, distance_cm=50, strafe_speed=0.5)

# Follow until both sensors see black
directional_follow_line(left, right, strafe_speed=0.4).until(
    on_black(left) & on_black(right)
)

class step.motion.line_follow_dsl.StrafeFollowLineBuilder¶

Bases: raccoon.step.step_builder.StepBuilder

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

left_sensor(value: raccoon.sensor_ir.IRSensor)¶

right_sensor(value: raccoon.sensor_ir.IRSensor)¶

distance_cm(value: float | None)¶

speed(value: float)¶

kp(value: float)¶

ki(value: float)¶

kd(value: float)¶

until(value: raccoon.step.condition.StopCondition | None)¶

step.motion.line_follow_dsl.strafe_follow_line(left_sensor: raccoon.sensor_ir.IRSensor = _UNSET, right_sensor: raccoon.sensor_ir.IRSensor = _UNSET, distance_cm: float | None = None, speed: float = 0.5, kp: float = 0.4, ki: float = 0.0, kd: float = 0.1, until: raccoon.step.condition.StopCondition | None = None)¶

Follow a line forward, correcting position by strafing left/right.

The robot drives forward at the given speed while a PID controller corrects lateral position using two sensors. Unlike FollowLine which steers by rotating, this step keeps the robot’s heading constant and corrects by strafing, which is useful when the robot must maintain a fixed orientation (e.g. to keep a side-mounted mechanism aligned).

Supports distance-based termination, composable StopCondition via .until(), or both (whichever triggers first). At least one of distance_cm or until must be provided.

Both sensors must be calibrated. Requires a mecanum or omni-wheel drivetrain.

Parameters:

left_sensor – Left IR sensor instance.
right_sensor – Right IR sensor instance.
distance_cm – Distance to follow in centimeters. Optional if until is provided.
speed – Forward speed as fraction of max velocity (0.0 to 1.0). Default 0.5. Use negative values to drive backward.
kp – Proportional gain for lateral PID. Default 0.75.
ki – Integral gain for lateral PID. Default 0.0.
kd – Derivative gain for lateral PID. Default 0.5.
until – Composable stop condition. Can also be chained via the .until() builder method.

Returns:

A StrafeFollowLineBuilder (chainable via .left_sensor(), .right_sensor(), .distance_cm(), .speed(), .kp(), .ki(), .kd(), .until(), .on_anomaly(), .skip_timing()).

Example:

from raccoon.step.motion import StrafeFollowLine
from raccoon.step.condition import on_black

# Follow a line for 40 cm, correcting via strafe
strafe_follow_line(left, right, distance_cm=40, speed=0.4)

# Follow until both sensors see black
strafe_follow_line(left, right, speed=0.4).until(
    on_black(left) & on_black(right)
)

class step.motion.line_follow_dsl.StrafeFollowLineSingleBuilder¶

Bases: raccoon.step.step_builder.StepBuilder

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

sensor(value: raccoon.sensor_ir.IRSensor)¶

distance_cm(value: float | None)¶

speed(value: float)¶

side(value: step.motion.line_follow.LineSide)¶

kp(value: float)¶

ki(value: float)¶

kd(value: float)¶

until(value: raccoon.step.condition.StopCondition | None)¶

step.motion.line_follow_dsl.strafe_follow_line_single(sensor: raccoon.sensor_ir.IRSensor = _UNSET, distance_cm: float | None = None, speed: float = 0.5, side: step.motion.line_follow.LineSide = LineSide.LEFT, kp: float = 0.4, ki: float = 0.0, kd: float = 0.1, until: raccoon.step.condition.StopCondition | None = None)¶

Follow a line edge forward, correcting position by strafing.

The robot drives forward at the given speed while a PID controller corrects lateral position using a single sensor tracking the line edge. Unlike FollowLineSingle which steers by rotating, this step keeps the robot’s heading constant and corrects by strafing.

Supports distance-based termination, composable StopCondition via .until(), or both (whichever triggers first). At least one of distance_cm or until must be provided.

The sensor must be calibrated. Requires a mecanum or omni-wheel drivetrain.

Parameters:

sensor – IR sensor for edge tracking.
distance_cm – Distance to follow in centimeters. Optional if until is provided.
speed – Forward speed as fraction of max velocity (0.0 to 1.0). Default 0.5. Use negative values to drive backward.
side – Which edge of the line to track. Default LineSide.LEFT.
kp – Proportional gain for lateral PID. Default 1.0.
ki – Integral gain for lateral PID. Default 0.0.
kd – Derivative gain for lateral PID. Default 0.3.
until – Composable stop condition. Can also be chained via the .until() builder method.

Returns:

A StrafeFollowLineSingleBuilder (chainable via .sensor(), .distance_cm(), .speed(), .side(), .kp(), .ki(), .kd(), .until(), .on_anomaly(), .skip_timing()).

Example:

from raccoon.step.motion import StrafeFollowLineSingle, LineSide
from raccoon.step.condition import on_black

# Follow a line edge for 40 cm, correcting via strafe
strafe_follow_line_single(front_ir, distance_cm=40, speed=0.4)

# Follow until stop sensor sees black
strafe_follow_line_single(front_ir, speed=0.4).until(on_black(stop))

class step.motion.line_follow_dsl.DirectionalFollowLineSingleBuilder¶

Bases: raccoon.step.step_builder.StepBuilder

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

sensor(value: raccoon.sensor_ir.IRSensor)¶

distance_cm(value: float | None)¶

heading_speed(value: float)¶

strafe_speed(value: float)¶

side(value: step.motion.line_follow.LineSide)¶

kp(value: float)¶

ki(value: float)¶

kd(value: float)¶

until(value: raccoon.step.condition.StopCondition | None)¶

step.motion.line_follow_dsl.directional_follow_line_single(sensor: raccoon.sensor_ir.IRSensor = _UNSET, distance_cm: float | None = None, heading_speed: float = 0.0, strafe_speed: float = 0.0, side: step.motion.line_follow.LineSide = LineSide.LEFT, kp: float = 0.4, ki: float = 0.0, kd: float = 0.1, until: raccoon.step.condition.StopCondition | None = None)¶

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.

Supports distance-based termination, composable StopCondition via .until(), or both (whichever triggers first). At least one of distance_cm or until must be provided.

The sensor must be calibrated (white/black thresholds set) before use. Requires a mecanum or omni-wheel drivetrain if strafe_speed is nonzero.

Parameters:

sensor – IR sensor for edge tracking.
distance_cm – Distance to follow in centimeters. Optional if until is provided.
heading_speed – Forward/backward speed fraction (-1.0 to 1.0). Default 0.0.
strafe_speed – Lateral speed fraction (-1.0 to 1.0). Default 0.0.
side – Which edge of the line to track. Default LineSide.LEFT.
kp – Proportional gain for steering PID. Default 1.0.
ki – Integral gain for steering PID. Default 0.0.
kd – Derivative gain for steering PID. Default 0.3.
until – Composable stop condition. Can also be chained via the .until() builder method.

Returns:

A DirectionalFollowLineSingleBuilder (chainable via .sensor(), .distance_cm(), .heading_speed(), .strafe_speed(), .side(), .kp(), .ki(), .kd(), .until(), .on_anomaly(), .skip_timing()).

Example:

from raccoon.step.motion import DirectionalFollowLineSingle, LineSide
from raccoon.step.condition import on_black

# Strafe right while tracking the left edge for 50 cm
directional_follow_line_single(front_ir, distance_cm=50, strafe_speed=0.4)

# Follow until stop sensor sees black
directional_follow_line_single(front_ir, strafe_speed=0.4).until(on_black(stop))

step.motion.line_follow_dsl¶

Classes¶

Functions¶

Module Contents¶

raccoon

Navigation

Related Topics