Motor and Motor Group

Introduction

Motors and motor groups control how parts of a robot move. A Motor controls one configured Smart Motor, while a MotorGroup controls multiple configured Smart Motors together so they move in tandem. Motors and motor groups can be used to raise an arm, turn a claw, spin a wheel, or move another part of a build. Two or four motors can work together as a drivetrain to move and turn the whole robot.

Each motor or motor group is configured in the Devices window. Depending on the build, motor and motor group names can change. This page uses motor_1 and motor_group_1 as example names. Replace them with your own configured names as needed.

By default, FORWARD spins a motor counterclockwise, and REVERSE spins a motor clockwise. If a motor is set to reverse, those directions will be switched.

There are many ways to code motors and motor groups. Below is a list of all Motor and Motor Group methods:

Actions — Stop and spin motors and motor groups.

• spin — Spins a motor or motor group forward or reverse forever.

• spin_for — Spins a motor or motor group for a specific distance.

• spin_to_position — Spins a motor or motor group to a specific position.

• stop — Stops a motor or motor group from spinning.

Mutators — Adjust motor and motor group settings.

• set_position — Changes the motor or motor group’s current position to a new value.

• set_velocity — Tells a motor or motor group how fast to spin.

• set_stopping — Sets how a motor or motor group will stop moving: by braking, coasting, or holding.

• set_max_torque — Sets how hard a motor or motor group is allowed to push while spinning.

• set_timeout — Sets how much time a motor or motor group will try to finish a movement.

• set_reversed — Changes whether a motor’s spin direction is reversed.

• reset_position — Changes a motor or motor group’s current position to 0.

Getters — Check motor and motor group status.

• is_done — Returns whether the motor or motor group is finished moving, as a Boolean value.

• is_spinning — Returns whether the motor or motor group is spinning, as a Boolean value.

• position — Returns the motor or motor group’s current position.

• velocity — Returns how fast the motor or motor group is spinning.

• current — Returns how much electrical current the motor or motor group is using.

• power — Returns how much power the motor or motor group is using.

• torque — Returns how much torque the motor or motor group is using.

• efficiency — Returns how efficiently the motor or motor group is using power.

• temperature — Returns the temperature of the motor or motor group.

• count — Returns the number of motors in a motor group.

• get_timeout — Returns the motor or motor group’s current timeout duration.

Constructors — Manually initialize and configure motors and motor groups.

• Motor — Creates a motor.

• MotorGroup — Creates a motor group.

Actions

spin

spin spins a motor or motor group forward or reverse forever. The motor or motor group will continue to spin until it is given another action, like spinning in a different direction or stopping.

Usage:
motor_1.spin(direction, velocity, units)

Parameters	Description
direction	The direction the motor or motor group spins: FORWARD or REVERSE.
velocity	Optional. The velocity to spin with from 0% to 100% when using PERCENT. This can be an integer or decimal (float). If VOLT is used in units, this value can be from -12.0 to 12.0. A negative value spins opposite the given direction.
units	Optional. The velocity unit: PERCENT RPM (default) — Rotations per minute VelocityUnits.DPS — Degrees per second VOLT — Voltage

# Spin the motor, then stop
motor_1.spin(FORWARD)
wait(1, SECONDS)
motor_1.stop()

spin_for

spin_for spins a motor or motor group for a specific distance. The spin is relative to the current position of the motor or motor group. The project will wait until the motor or motor group is done spinning before the next line of code runs.

Usage:
motor_1.spin_for(direction, angle, units, velocity, units_v, wait)

Parameters	Description
direction	The direction the motor or motor group spins: FORWARD or REVERSE.
angle	The distance the motor or motor group spins. This can be an integer or decimal (float).
units	Optional. The distance unit: DEGREES (default) or TURNS.
velocity	Optional. The velocity to spin with from 0% to 100% when using PERCENT. This can be an integer or decimal (float).
units_v	Optional. The velocity unit: PERCENT RPM (default) — Rotations per minute
wait	Optional. wait=True (default) — Makes the project wait until the motor or motor group is done spinning before the next line of code runs. wait=False — Makes the next line of code run right away.

# Spin the motor forward once, then reset
motor_1.spin_for(FORWARD, 90, DEGREES)
wait(1, SECONDS)
motor_1.spin_for(REVERSE, 90, DEGREES)

spin_to_position

spin_to_position spins a motor or motor group to a specific position.

A motor or motor group’s position is how far it has spun, measured in DEGREES or TURNS. One turn is equal to 360 degrees. At the beginning of a project, the motor or motor group position is set to 0 degrees. The motor or motor group position can also be set using the set_position method.

Position values are absolute. This means the direction of the spin depends on the motor or motor group’s current position.

Usage:
motor_1.spin_to_position(rotation, units, velocity, units_v, wait)

Parameters	Description
rotation	The position value the motor or motor group will spin to. This can be an integer or decimal (float).
units	The position unit: DEGREES or TURNS.
velocity	Optional. The velocity to spin with from 0% to 100% when using PERCENT. This can be an integer or decimal (float).
units_v	Optional. The velocity unit: PERCENT RPM — Rotations per minute VelocityUnits.DPS — Degrees per second
wait	Optional. wait=True (default) — Makes the project wait until the motor or motor group is done spinning before the next line of code runs. wait=False — Makes the next line of code run right away.

# Spin the motor to the new 0 position
motor_1.set_position(180, DEGREES)
motor_1.spin_to_position(0, DEGREES)

stop

stop stops a motor or motor group from spinning.

Usage:
motor_1.stop(mode)

Parameters	Description
mode	Optional. How the motor or motor group will stop: BRAKE — Stops immediately. COAST — Slows to a stop. HOLD — Stops immediately and holds the motor’s position.

# Spin the motor, then stop
motor_1.spin(FORWARD)
wait(1, SECONDS)
motor_1.stop()

Mutators

set_position

A motor or motor group’s position is how far it has spun, measured in DEGREES or TURNS. One turn is equal to 360 degrees. set_position changes the motor or motor group’s current position to a new value.

For example, if a motor or motor group has spun to 180 degrees, setting the position to 0 degrees will reset that position from 180 to 0 degrees. Then the motor or motor group can spin to positions based on that new value.

Usage:
motor_1.set_position(position, units)

Parameters	Description
position	The position value to set for the motor or motor group. This can be an integer or decimal (float).
units	Optional. The position unit: DEGREES (default) or TURNS.

# Spin the motor to the new 0 position
motor_1.set_position(180, DEGREES)
motor_1.spin_to_position(0, DEGREES)

set_velocity

set_velocity tells a motor or motor group how fast to spin. A higher percentage makes the motor or motor group spin faster and a lower percentage makes the motor or motor group spin slower.

Every project begins with each motor or motor group spinning at 50% velocity by default.

Note: A higher velocity makes the motor or motor group spin faster, but it may be less precise. A lower velocity makes the motor or motor group spin slower, but it can be more precise.

Usage:
motor_1.set_velocity(velocity, units)

Parameters	Description
velocity	The speed the motor or motor group will spin at. PERCENT uses values from 0% to 100%. RPM uses values from 0 to 127. This can be an integer or decimal (float).
units	Optional. The velocity unit: PERCENT RPM (default) — Rotations per minute VelocityUnits.DPS — Degrees per second

# Spin forward at the default velocity
motor_1.spin_for(FORWARD, 100)
wait(1, SECONDS)

# Spin slower
motor_1.set_velocity(20, PERCENT)
motor_1.spin_for(FORWARD, 100)
wait(1, SECONDS)

# Spin faster
motor_1.set_velocity(100, PERCENT)
motor_1.spin_for(FORWARD, 100)
wait(1, SECONDS)

set_stopping

set_stopping sets how a motor or motor group will stop moving: by braking, coasting, or holding.

Usage:
motor_1.set_stopping(mode)

Parameters	Description
mode	How the motor or motor group will stop: BRAKE — Stops immediately. COAST — Slows to a stop. HOLD — Stops immediately and holds the motor’s position.

set_max_torque

Torque shows how hard a motor or motor group can push or pull while it spins.

set_max_torque sets the most torque a motor or motor group is allowed to use.

A higher percentage lets the motor or motor group push harder, like when lifting a heavy object. A lower percentage limits how hard the motor or motor group can push. This can help protect the robot if the motor or motor group gets stuck or reaches the end of how far it can move.

Every project begins with each motor or motor group’s torque at 50% by default.

Usage:
motor_1.set_max_torque(value, units)

Parameters	Description
value	The max torque the motor or motor group can use. PERCENT uses integers from 0% to 100%. For TorqueUnits.NM, use a float from 0.0 to 2.1 (Newton-meters). For TorqueUnits.INLB, use a float from 0.0 to 22.0 (inch-pounds).
units	Optional. The torque unit: PERCENT TorqueUnits.NM (default) — Newton meters TorqueUnits.INLB — Inch pounds CurrentUnits.AMP

set_timeout

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

Usage:
motor_1.set_timeout(value, units)

Parameters	Description
value	The amount of time the motor or motor group can try to finish a movement. This can be a positive integer or decimal (float).
units	Optional. The unit of time: SECONDS MSEC (default) — Milliseconds

set_reversed

set_reversed changes whether a motor’s spin direction is reversed. This method works the same as setting the reverse parameter to True when constructing a Motor.

Note: This method will only work with a motor and not a motor group.

Usage:
motor_1.set_reversed(value)

Parameters	Description
value	Whether the motor’s direction is reversed: True — Reverses the motor’s direction. False — Returns the motor’s direction to its default.

reset_position

reset_position changes the motor or motor group’s current position to 0.

Usage:
motor_1.reset_position()

Parameters	Description
	This method has no parameters.

Getters

is_done

is_done returns whether the motor or motor group is finished moving, as a Boolean value. This can be used to control the timing of other behaviors based on the motor’s movement.

• True — The motor or motor group is finished moving.

• False — The motor or motor group is still moving.

This method works together with the following Motion methods that have the wait parameter: spin_for and spin_to_position.

Usage:
motor_1.is_done()

Parameters	Description
	This method has no parameters.

# Drive forward until the motor is done spinning
motor_1.spin_for(FORWARD, 200, wait=False)
while True:
  if motor_1.is_done():
    drivetrain.stop()
  else:
    drivetrain.drive(FORWARD)

is_spinning

is_spinning returns whether the motor or motor group is spinning, as a Boolean value. This can be used to control the timing of other behaviors based on the motor’s movement.

• True — The motor or motor group is spinning.

• False — The motor or motor group is not spinning.

This method works together with the following Motion methods that have the wait parameter: spin_for and spin_to_position.

Usage:
motor_1.is_spinning()

Parameters	Description
	This method has no parameters.

# Drive forward until the motor is done spinning
motor_1.spin_for(FORWARD, 200, wait=False)
while True:
  if motor_1.is_spinning():
    drivetrain.drive(FORWARD)
  else:
    drivetrain.stop()

position

A motor or motor group’s position is how far it has spun, measured in DEGREES or TURNS. One turn is equal to 360 degrees. position returns the motor or motor group’s current position.

At the beginning of a project, the motor or motor group position is set to 0 degrees. If the motor or motor group spins one turn forward, the position will be 360 degrees or 1 turn. If the motor or motor group spins the other direction, the position will be negative.

Usage:
motor_1.position(units)

Parameters	Description
units	Optional. The unit to return the motor or motor group position in: DEGREES (default) or TURNS.

# Display the motor's position after spinning
brain.screen.print(motor_1.position())
brain.screen.next_row()

motor_1.spin(FORWARD)
wait(1, SECONDS)
brain.screen.print(motor_1.position())

motor_1.stop()

velocity

velocity returns how fast the motor or motor group is spinning, as a percentage from -100% to 100% or as rotations per minute from -127 rpm to 127 rpm.

A positive value means the motor or motor group is spinning forward. A negative value means it is spinning in reverse.

Usage:
motor_1.velocity(units)

Parameters	Description
units	Optional. The velocity unit to return: PERCENT RPM (default) — Revolutions per minute VelocityUnits.DPS — Degrees per second

current

current returns how much electrical current the motor or motor group is using, measured in amps from 0.0 to 1.2 A. Current is the amount of electricity flowing through the motor or motor group.

A higher current value means the motor or motor group is using more electrical current. This can happen when the motor or motor group is lifting something heavy, pushing against an object, or trying to move when it is stuck.

This can be used to check if the motor or motor group is struggling during a movement. If current stays high, the motor may get warmer or use power less efficiently.

Usage:
motor_1.current(units)

Parameters	Description
units	Optional. The current unit to return: CurrentUnits.AMP (default) — Amps

power

power returns how much power the motor or motor group is using, measured in watts from 0.0 to 11.0 W. Power shows how quickly the motor or motor group is using energy.

A higher power value means the motor or motor group is using energy faster. This can happen when the motor or motor group is lifting something heavy, pushing against an object, or trying to move when it is stuck.

This can be used to compare movements or check if the motor or motor group is struggling. If power stays high, the motor may get warmer or use energy less efficiently.

Usage:
motor_1.power(units)

Parameters	Description
units	Optional. The power unit to return: PowerUnits.WATT (default) — Watt

torque

Torque shows how hard a motor or motor group is twisting, pushing, or pulling while it spins.

torque returns how much torque the motor or motor group is using, measured in inch-pounds (InLb) from 0.0 to 22.0 or Newton-meters (Nm) from 0.0 to 2.1.

A higher torque value means the motor or motor group is pushing or pulling harder. This can happen when the motor or motor group is lifting something heavy, pushing against an object, or trying to move when it is stuck.

This can be used to check if the motor or motor group is struggling or to compare how much push different movements need.

To set the torque of a motor or motor group, use set_max_torque.

Usage:
motor_1.torque(units)

Parameters	Description
units	The torque unit to return: TorqueUnits.NM (default) — Newton meters TorqueUnits.INLB — Inch pounds

efficiency

efficiency returns how efficiently the motor or motor group is using power, as a percentage from 0% to 100%.

Efficiency shows how much of the motor or motor group’s power is being used for movement. A higher efficiency value means more of the motor or motor group’s power is being used to move. A lower efficiency value can happen when the motor or motor group is working hard but not moving much, like when it is stuck or pushing against an object.

This can be used to compare movements or check if the motor or motor group is wasting power instead of using it for movement.

Usage:
motor_1.efficiency(units)

Parameters	Description
units	Optional. The efficiency unit to return: PERCENT (default)

temperature

temperature returns the temperature of the motor or motor group.

Motor temperature shows how warm the motor or motor group is. A higher temperature means the motor or motor group is getting warmer while it works. The motor should stay below 55°C to keep working at full performance.

If the motor or motor group gets too hot, it will lower its maximum current to protect itself. At 70°C, a motor will stop running until it cools down.

This can be used to check if the motor or motor group is getting too hot during repeated movements, long runs, or when it is pushing against an object.

Usage:
motor_1.temperature(units)

Parameters	Description
units	Optional. The temperature unit to return: TemperatureUnits.CELSIUS (default) TemperatureUnits.FAHRENHEIT PERCENT

count

count returns the number of motors in a motor group.

Note: This method will only work with a motor group.

Usage:
motor_group_1.count()

Parameters	Description
	This method has no parameters.

get_timeout

get_timeout returns the motor or motor group’s current timeout in milliseconds.

Usage:
motor_1.get_timeout()

Parameters	Description
	This method has no parameters.

Constructors

Constructors are used to manually create Motor and MotorGroup objects outside of the Devices window.

Motor

Motor creates a motor.

Usage:
Motor(port, gears, reverse)

Parameter	Description
port	The Smart Port that the motor is connected to, written as Ports.PORTx, where x is the port number.
gears	Optional. The motor’s gear ratio: GearSetting.RATIO_18_1 (default) — 18:1 ratio GearSetting.RATIO_36_1 — 36:1 ratio GearSetting.RATIO_6_1 — 6:1 ratio
reverse	Optional. Sets whether the motor’s spin direction is reversed: True — Makes FORWARD spin clockwise. False (default) — Makes FORWARD spin counterclockwise.

# Create a Motor in Port 1 with default values
motor_1 = Motor(Ports.PORT1)

"""
Create a motor with the following values:
- In Port 1
- 36:1 ratio
- Reversed
"""
motor_1 = Motor(Ports.PORT1, GearSetting.RATIO_36_1, True)

MotorGroup

MotorGroup creates a motor group.

Usage:
MotorGroup(motors)

Parameter	Description
motors	The names of previously created Motor objects to put in the motor group, separated by commas (,). Up to 12 Motor objects can be added to the group.

# Create the Motors
motor_1 = Motor(Ports.PORT1)
motor_2 = Motor(Ports.PORT2)

# Create a Motor Group
motor_group_1 = MotorGroup(motor_1, motor_2)