libstp.step.motion.move_until.core

Core MoveUntil step and configuration.

Moves (drive, turn, strafe) until an IR sensor condition is met.

Classes

SurfaceColor	Target surface color for sensor-based motion.
MoveUntilConfig	Configuration for MoveUntil step.
MoveUntil	Move until a sensor detects a specified color (black or white).

Functions

move_until(→ MoveUntil)

Move with any combination of velocities until any sensor detects the target color.

Module Contents

class libstp.step.motion.move_until.core.SurfaceColor(*args, **kwds)

Bases: enum.Enum

Target surface color for sensor-based motion.

BLACK = 'black'

WHITE = 'white'

class libstp.step.motion.move_until.core.MoveUntilConfig

Configuration for MoveUntil step.

sensor: libstp.sensor_ir.IRSensor | list[libstp.sensor_ir.IRSensor]

target: SurfaceColor

forward_speed: float = 0.0

angular_speed: float = 0.0

strafe_speed: float = 0.0

confidence_threshold: float = 0.7

scale_speed_on_approach: bool = True

class libstp.step.motion.move_until.core.MoveUntil(config: MoveUntilConfig)

Bases: libstp.step.motion.motion_step.MotionStep

Move until a sensor detects a specified color (black or white).

Supports any combination of forward, angular, and strafe velocities. Can accept a single sensor or a list of sensors - triggers when ANY sensor detects.

config

triggered_sensor: libstp.sensor_ir.IRSensor | None = None

to_simulation_step() → libstp.step.SimulationStep

Convert this step to a simulation-friendly summary.

The default implementation uses timing history only when it can query the tracker synchronously; otherwise it returns conservative defaults. Override in subclasses that know their motion delta or exact duration.

on_start(robot: libstp.robot.api.GenericRobot) → None

Called once before the loop. Override to set up motion/velocity.

on_update(robot: libstp.robot.api.GenericRobot, dt: float) → bool

Called each cycle with dt in seconds. Return True when motion is complete.

libstp.step.motion.move_until.core.move_until(sensor: libstp.sensor_ir.IRSensor | list[libstp.sensor_ir.IRSensor], target: SurfaceColor, forward_speed: float = 0.0, angular_speed: float = 0.0, strafe_speed: float = 0.0, confidence_threshold: float = 0.7, scale_speed_on_approach: bool = True) → MoveUntil

Move with any combination of velocities until any sensor detects the target color.

This is the most general “move until” factory. It accepts arbitrary forward, strafe, and angular velocity components simultaneously, allowing complex motions such as arcing turns or diagonal drives while waiting for a sensor trigger. Each control cycle the given IR sensor(s) are polled, and the step completes as soon as any sensor’s probability for the target color meets or exceeds confidence_threshold.

For simpler cases, prefer the dedicated helpers (drive_forward_until_black, turn_left_until_white, strafe_right_until_black, etc.).

Parameters:

• sensor – A single IRSensor or a list of sensors. The step triggers when any sensor in the list detects the target color.

• target – The surface color to detect – SurfaceColor.BLACK or SurfaceColor.WHITE.

• forward_speed – Forward/backward speed in m/s. Positive = forward, negative = backward. Defaults to 0.0.

• angular_speed – Rotational speed in rad/s. Positive = counter-clockwise, negative = clockwise. Defaults to 0.0.

• strafe_speed – Lateral speed in m/s. Positive = left, negative = right. Requires a mecanum or holonomic drivetrain. Defaults to 0.0.

• confidence_threshold – Minimum probability (0.0 – 1.0) that the sensor must report for the target color before the step considers the condition met. Defaults to 0.7.

• scale_speed_on_approach – If True, reduce velocity as the sensor reading approaches the threshold to allow more precise stopping. Defaults to True.

Returns:

A configured motion step that can be executed by the step runner.

Return type:

MoveUntil

Example:

from libstp.sensor_ir import IRSensor
from libstp.step.motion.move_until.core import SurfaceColor

front_ir = IRSensor(0)

# Arc forward-left while looking for black
step = move_until(
    front_ir,
    target=SurfaceColor.BLACK,
    forward_speed=0.3,
    angular_speed=0.2,
)

# Strafe right with high confidence threshold
step = move_until(
    front_ir,
    target=SurfaceColor.WHITE,
    strafe_speed=-0.2,
    confidence_threshold=0.9,
)