Drivetrain#

Introduction #

The 123 Robot has a two-wheel drivetrain that lets it drive and turn. The Drivetrain methods control how the robot moves.

The drivetrain can measure distance in two ways: steps and mm (millimeters). One step is one square on a 123 Field.

There are many ways to code the drivetrain. Below is a list of all Drivetrain methods:

Actions — Move and turn the robot.

drive — Moves the robot forward or reverse forever.
drive_for — Moves the robot forward or reverse for a specific distance.
drive_until — Moves the robot forward or reverse until it detects an object, crash, or line.
turn — Turns the robot left or right forever.
turn_for — Turns the robot left or right for a specific number of degrees.
turn_to_heading — Turns the robot to face a specific heading from -359 to 359 degrees.
stop — Stops the robot’s movement.

Mutators — Adjust drivetrain settings.

set_timeout — Sets how long the robot will try to finish a movement.
set_heading — Changes the robot’s current heading to a new heading.

Getters — Check movement status.

is_stopped — Returns whether the robot has stopped moving, as a Boolean value.
get_heading — Returns the robot’s current heading from 0 to 359 degrees.

Actions #

drive #

drive moves the robot forward or reverse forever. The robot will continue to move until it is given another action, like turning or stopping.

Usage:
robot.drive(direction)

Parameters	Description
`direction`	The direction the robot moves: `FORWARD` or `REVERSE`.

# Drive for 2 seconds.
robot.drive(FORWARD)
wait(2, SECONDS)
robot.stop()

drive_for #

drive_for moves the robot forward or reverse for a specific distance. The project will wait until the robot is done moving before the next line of code runs.

Usage:
robot.drive_for(direction, distance, unit)

Parameters	Description
`direction`	The direction the robot moves: `FORWARD` or `REVERSE`.
`distance`	The distance the robot drives. This can be an integer or decimal.
`unit`	The distance unit: `MM` (millimeters) or `STEPS` (one square on a 123 Field).

# Drive back and forth.
robot.drive_for(FORWARD, 3, STEPS)
robot.drive_for(REVERSE, 3, STEPS)

drive_until #

drive_until moves the robot forward or reverse until it detects an object, a crash, or a line.

Usage:
robot.drive_until(direction)

Parameters	Description
`direction`	The direction the robot moves: `FORWARD` or `REVERSE`.

# Reverse after a crash.
robot.drive_until(FORWARD)
robot.drive_for(REVERSE, 1, STEPS)

turn #

turn turns the robot left or right forever. The robot will continue to turn until it is given another action, like driving or stopping.

Usage:
robot.turn(direction)

Parameters	Description
`direction`	The direction the robot turns: `LEFT` or `RIGHT`.

# Turn for 2 seconds.
robot.turn(RIGHT)
wait(2, SECONDS)
robot.stop()

turn_for #

turn_for turns the robot left or right for a specific number of degrees. The project will wait until the robot is done turning before the next line of code runs.

Usage:
robot.turn_for(direction, degrees)

Parameters	Description
`direction`	The direction the robot turns: `LEFT` or `RIGHT`.
`degrees`	The number of degrees to turn. This can be an integer or decimal.

# Turn left, then turn around to the right.
robot.turn_for(LEFT, 90)
robot.turn_for(RIGHT, 180)

turn_to_heading #

turn_to_heading turns the robot to face a specific heading from -359 to 359 degrees. The robot will turn the shortest direction to reach the target heading.

The starting heading is 0 degrees.

The project will wait until the robot is done turning before the next line of code runs.

Usage:
robot.turn_to_heading(heading)

Parameters	Description
`heading`	The heading the robot should face, from -359 to 359 degrees.

# Turn to face the cardinal directions.
robot.turn_to_heading(90)
wait(2, SECONDS)
robot.turn_to_heading(180)
wait(2, SECONDS)
robot.turn_to_heading(270)
wait(2, SECONDS)
robot.turn_to_heading(0)
wait(2, SECONDS)

stop #

stop stops the robot’s movement.

Usage:
robot.stop()

Parameters	Description
	This method has no parameters.

# Stop driving after 4 seconds.
robot.drive(FORWARD)
wait(4, SECONDS)
robot.stop()

set_timeout sets how many seconds the robot will try to finish a movement. If the robot cannot finish in that time, it will stop trying and move on to the next line of code. This keeps the robot from getting stuck on a movement.

Usage:
robot.set_timeout(time, unit)

Parameters	Description
`time`	The amount of time to allow for a movement. This can be an integer or decimal.
`unit`	The time unit: `MSEC` or `SECONDS`.

# Turn right after driving for 1 second.
robot.set_timeout(1, SECONDS)
robot.drive_for(FORWARD, 1000, MM)
robot.turn_for(RIGHT, 90)

set_heading #

set_heading changes the robot’s current heading to a new heading value.

For example, if the robot has turned to face right, setting the heading to 0 degrees makes that right-facing position the new 0 degrees.

Usage:
robot.set_heading(heading)

Parameters	Description
`heading`	The heading value, in degrees, to set for the robot.

# Face the new 0 degree heading.
robot.set_heading(90)
robot.turn_to_heading(0)

Getters #

is_stopped #

is_stopped returns a Boolean that reports whether the robot has stopped moving.

True — The robot is stopped.
False — The robot is still moving.

Usage:
robot.is_stopped()

Parameters	Description
	This method has no parameters.

# Glow blue after a crash.
robot.drive_until(FORWARD)
while True:
    if robot.is_stopped():
        robot.led.glow(BLUE)
    else:
        robot.led.glow(GREEN)
    wait(0.05, SECONDS)

get_heading #

get_heading returns the direction the robot is currently facing as a whole number from 0 to 359 degrees.

The robot’s starting heading is 0 degrees.

Usage:
robot.get_heading()

Parameters	Description
	This method has no parameters.

# Display the heading after turning.
robot.turn_for(RIGHT, 450)
console.print(robot.get_heading())