brian.pilot.Pilot

brian.pilot

• Pilot
  • __init__
  • set_speed
  • get_default_speed
  • set_acceleration
  • get_default_acceleration
  • brake
  • hold
  • coast
  • wait_for_movement
  • movement_done
  • forward
  • backward
  • turn
  • arc
  • travel
  • wait_until_ready
  • distance_travelled_mm
  • heading_angle_deg
  • reset_distance_travelled
  • reset_heading_angle

Pilot class objects

class Pilot()

Differential-drive pilot for controlling a robot with left and right wheels.

Supports brake/hold/coast, forward/backward with optional distance, turn (small pivots), arc (large pivots), and travel (curved path). Movement methods wait for completion by default and return MovementEnd; timeout_ms semantics match wait_for_movement() (None = wait until done, 0 or negative = return from the wait immediately, often MovementEnd.TIMED_OUT if still moving). Speed and acceleration can be set once and used as defaults in movement commands. Odometry (distance and angle) is available with optional zeroing.

__init__

def __init__(left_motor: Motor,
             right_motor: Motor,
             wheelbase_mm: int,
             wheel_circumference_mm: int,
             gear_ratio: Optional[int] = None,
             aux_left_motor: Optional[Motor] = None,
             aux_right_motor: Optional[Motor] = None,
             left_motor_reversed: bool = False,
             right_motor_reversed: bool = False,
             aux_left_motor_reversed: bool = False,
             aux_right_motor_reversed: bool = False) -> None

Create a pilot for a differential-drive chassis.

Arguments:

• left_motor: Primary left motor.
• right_motor: Primary right motor.
• aux_left_motor: Optional secondary left motor.
• aux_right_motor: Optional secondary right motor.
• wheelbase_mm: Distance between left and right wheel (centre to centre), in mm.
• wheel_circumference_mm: Effective mm per revolution (circumference * gear ratio).
• gear_ratio: Optional gear ratio used by the drivetrain model.
• left_motor_reversed: Reverse primary left motor direction.
• right_motor_reversed: Reverse primary right motor direction.
• aux_left_motor_reversed: Reverse auxiliary left motor direction.
• aux_right_motor_reversed: Reverse auxiliary right motor direction.

Pilot type hints use ints for wheelbase and circumference; the underlying MicroPython binding may still accept floats.

Raises:

• ValueError: If numeric or topology arguments are invalid.
• brian.pilot.PilotAlreadyReservedError: If another active pilot already reserves PilotSync control.
• brian.pilot.PilotConfigurationError: If pilot creation fails for non-argument reasons.

set_speed

def set_speed(speed_mm_per_sec: int) -> None

Set the default linear speed used when a movement method is called without the optional speed argument.

Arguments:

• speed_mm_per_sec: Default speed in mm/s.

Raises:

• brian.pilot.PilotAlreadyClosedError: If the pilot instance is already closed.

get_default_speed

def get_default_speed() -> int

Get the current default linear speed used when movement methods are called without speed.

Returns:

Default speed in mm/s.

Raises:

• brian.pilot.PilotAlreadyClosedError: If the pilot instance is already closed.

set_acceleration

def set_acceleration(acceleration_mm_per_sec_sq: int) -> None

Set acceleration so callers do not pass it in every command.

Arguments:

• acceleration_mm_per_sec_sq: Acceleration in mm/s².

Raises:

• brian.pilot.PilotAlreadyClosedError: If the pilot instance is already closed.
• brian.pilot.PilotNotReadyError: If one of the controlled motors is not ready.

get_default_acceleration

def get_default_acceleration() -> int

Get the current default acceleration used by movement commands.

Returns:

Default acceleration in mm/s².

Raises:

• brian.pilot.PilotAlreadyClosedError: If the pilot instance is already closed.

brake

def brake() -> None

Apply passive braking on all registered motors (short the windings).

Raises:

• brian.pilot.PilotAlreadyClosedError: If the pilot instance is already closed.
• brian.pilot.PilotNotReadyError: If one of the controlled motors is not ready.

hold

def hold() -> None

Actively hold all registered motors at their current positions.

Raises:

• brian.pilot.PilotAlreadyClosedError: If the pilot instance is already closed.
• brian.pilot.PilotNotReadyError: If one of the controlled motors is not ready.

coast

def coast() -> None

Let all motors spin freely (float the windings).

Raises:

• brian.pilot.PilotAlreadyClosedError: If the pilot instance is already closed.
• brian.pilot.PilotNotReadyError: If one of the controlled motors is not ready.

wait_for_movement

def wait_for_movement(timeout_ms: Optional[int] = None) -> MovementEnd

Block until the current movement completes or the timeout expires.

Arguments:

• timeout_ms: Max wait in milliseconds. If None, wait until the move completes; if 0 or negative, return immediately.

Returns:

A value of brian.motors.MovementEnd (for example FINISHED, TIMED_OUT). Movement commands (forward, backward, turn, arc, travel) use the same timeout_ms rules for their internal wait.

Raises:

• brian.pilot.PilotAlreadyClosedError: If the pilot instance is already closed.
• brian.pilot.PilotNotReadyError: If one of the controlled motors is not ready.

movement_done

def movement_done() -> bool

Check whether the last movement has completed.

Returns:

True if no movement is in progress, False if still moving.

Raises:

• brian.pilot.PilotAlreadyClosedError: If the pilot instance is already closed.

forward

def forward(speed: Optional[int] = None,
            distance_mm: Optional[int] = None,
            timeout_ms: Optional[int] = None) -> MovementEnd

Drive forward and wait up to timeout_ms for the commanded move to finish.

Arguments:

• speed: Speed in mm/s. If None, uses default from set_speed(). Negative values reverse travel along the same circle.
• distance_mm: If None or 0, no limit (open-loop speed; returns quickly with FINISHED). Negative values flip direction by reversing speed; negative speed plus negative distance becomes forward.
• timeout_ms: Same as wait_for_movement.

Returns:

MovementEnd.FINISHED or MovementEnd.TIMED_OUT (script abort can also surface as TIMED_OUT if incomplete).

Raises:

• brian.pilot.PilotAlreadyClosedError: If the pilot instance is already closed.
• brian.pilot.PilotNotReadyError: If one of the controlled motors is not ready.

backward

def backward(speed: Optional[int] = None,
             distance_mm: Optional[int] = None,
             timeout_ms: Optional[int] = None) -> MovementEnd

Drive backward and wait up to timeout_ms for the commanded move to finish.

Arguments:

• speed: Speed in mm/s. If None, uses default from set_speed(). Negative values reverse travel along the same circle.
• distance_mm: If None or 0, no limit (open-loop speed; returns quickly with FINISHED). Negative values flip direction by reversing speed; negative speed plus negative distance becomes backward.
• timeout_ms: Same as wait_for_movement.

Returns:

MovementEnd value for how the wait ended.

Raises:

• brian.pilot.PilotAlreadyClosedError: If the pilot instance is already closed.
• brian.pilot.PilotNotReadyError: If one of the controlled motors is not ready.

turn

def turn(turn_rate: int,
         turn_radius_mm: Optional[int] = None,
         max_angle_deg: Optional[int] = None,
         timeout_ms: Optional[int] = None) -> MovementEnd

Turn and wait for completion (or timeout).

Arguments:

• turn_rate: Turn rate in degrees per second. Must be non-zero; positive and negative values select direction.
• turn_radius_mm: Turning radius in mm; 0 or None means turn on the spot (pivot).
• max_angle_deg: Optional cap in degrees; 0 or None means no limit. Negative values flip direction by reversing turn_rate; negative turn_rate plus negative max_angle_deg becomes a positive turn.
• timeout_ms: Same as wait_for_movement.

Returns:

MovementEnd value for how the wait ended.

Raises:

• ValueError: If turn_rate is zero.
• brian.pilot.PilotAlreadyClosedError: If the pilot instance is already closed.
• brian.pilot.PilotNotReadyError: If one of the controlled motors is not ready.

arc

def arc(radius_mm: int,
        max_distance_mm: Optional[int] = None,
        speed: Optional[int] = None,
        timeout_ms: Optional[int] = None) -> MovementEnd

Drive along an arc and wait for completion (or timeout).

Arguments:

• radius_mm: Turning radius in mm (from turn centre to robot centreline). 0 means turn around the robot centre; -wheelbase_mm/2 means the left wheel is stationary; +wheelbase_mm/2 means the right wheel is stationary. Negative values turn left, positive values turn right.
• max_distance_mm: Optional path length limit in mm; 0 or None means no limit. Negative values reverse travel along the same circle (equivalent to negating speed).
• speed: Speed in mm/s. If None, uses default from set_speed().
• timeout_ms: Same as wait_for_movement.

Returns:

MovementEnd value for how the wait ended.

Raises:

• ValueError: If called with values that make an internal turn invalid (for example zero turn rate).
• brian.pilot.PilotAlreadyClosedError: If the pilot instance is already closed.
• brian.pilot.PilotNotReadyError: If one of the controlled motors is not ready.

travel

def travel(turn_rate: int,
           max_distance_mm: Optional[int] = None,
           speed: Optional[int] = None,
           timeout_ms: Optional[int] = None) -> MovementEnd

Drive along a curved path and wait for completion (or timeout).

Arguments:

• turn_rate: Turn rate in degrees per second.
• max_distance_mm: Optional path length limit in mm; 0 or None means no limit. Negative values reverse travel along the same circle (equivalent to negating speed).
• speed: Speed in mm/s. If None, uses default from set_speed().
• timeout_ms: Same as wait_for_movement.

Returns:

MovementEnd value for how the wait ended.

Raises:

• brian.pilot.PilotAlreadyClosedError: If the pilot instance is already closed.
• brian.pilot.PilotNotReadyError: If one of the controlled motors is not ready.

wait_until_ready

def wait_until_ready(timeout_ms: Optional[int] = None,
                     optimism_level: Optional[MotorWaitOptimismLevel] = None) -> bool

Block until all configured pilot motors are ready or the timeout expires.

Arguments:

• timeout_ms: Max wait in milliseconds. If None, no per-call wall-clock limit; if 0 or negative, return immediately (same as brian.motors.Motor.wait_until_ready).
• optimism_level: Readiness strictness (same enum as brian.motors.Motor.wait_until_ready()).

Returns:

True if all motors became ready before timeout, False otherwise.

Raises:

• brian.pilot.PilotAlreadyClosedError: If the pilot instance is already closed.

distance_travelled_mm

def distance_travelled_mm() -> int

Signed integrated robot path distance (odometry), in mm, relative to the last reset_distance_travelled() call (or pilot start if never reset).

Returns:

Signed distance in mm.

Raises:

• brian.pilot.PilotAlreadyClosedError: If the pilot instance is already closed.

heading_angle_deg

def heading_angle_deg() -> int

Signed integrated heading change (odometry), in degrees, relative to the last reset_heading_angle() call (or pilot creation if never reset).

Returns:

Signed heading angle in degrees.

Raises:

• brian.pilot.PilotAlreadyClosedError: If the pilot instance is already closed.

reset_distance_travelled

def reset_distance_travelled(new_value_mm: int = 0) -> None

Set current integrated distance travelled to the provided value (in mm).

Raises:

• brian.pilot.PilotAlreadyClosedError: If the pilot instance is already closed.

reset_heading_angle

def reset_heading_angle(new_value_deg: int = 0) -> None

Set current integrated heading angle (in degrees) to the provided value.

Raises:

• brian.pilot.PilotAlreadyClosedError: If the pilot instance is already closed.