Motor and Motor Group #

Introduction #

The Motor and Motor Group methods allow you to control and monitor individual motors or motor groups on your V5 robot. These methods can spin, stop, or move motors to specific positions, as well as report their velocity, torque, power, and temperature.

This page uses motor_1 and motor_group_1 as the example motor and motor group name respectively. Replace them with your own configured names as needed.

Below is a list of available methods:

Actions – Control the movement of motors.

spin – Rotates the selected motor or motor group indefinitely.
spin_for – Rotates a motor or motor group for a specific distance in degrees or turns.
spin_to_position – Rotates a motor or motor group to a set position.
stop – Stops a specific motor or motor group from spinning.

Mutators – Change attributes of motors.

set_position – Sets the position (encoder value) of a motor or motor group.
set_velocity – Sets the speed of a motor or motor group as a percentage.
set_stopping – Sets the stop behavior (brake, coast, or hold) or the motor or motor group.
set_max_torque – Limits the maximum torque the motor or motor group can apply.
set_timeout – Limits how long a motor or motor group function waits before giving up if movement is blocked.
set_reversed – Sets only a motor to have its direction be reversed.
reset_position – Sets only a motor’s position to 0.

Getters – Return data from motors.

is_done – Returns a Boolean indicating whether the motor or motor group is no longer spinning.
is_spinning – Returns a Boolean indicating whether the motor or motor group is currently spinning.
position – Returns the motor’s or motor group’s current rotational position in degrees or turns.
velocity – Returns the motor’s or motor group’s current velocity in % or rpm.
current – Returns the current drawn by the motor or motor group.
power – Returns the amount of electrical power the motor or motor group is consuming.
torque – Returns the amount of torque currently being applied by the motor or motor group.
efficiency – Returns the current efficiency of the motor or motor group.
temperature – Returns the current temperature of the motor or motor group.
count – Returns the amount of motors in a motor group.
get_timeout – Returns only a motor’s current timeout duration.

Constructor – Manually initialize a Motor or Motor Group.

Motor – Creates a single motor.
MotorGroup – Creates a motor group.

Actions #

spin #

spin rotates a selected motor or motor group in a specified direction using the current motor velocity.

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

Parameters	Description
`direction`	The direction in which to spin the motor or motor group: `FORWARD` – By default, this is counterclockwise `REVERSE` – By default, this is clockwise
`velocity`	Optional. The velocity at which the motor or motor group will spin as a float or integer. If the velocity is not specified or previously set, the default velocity is 50%. If `VOLT` is used in `units`, this will accept a range from -12.0 to 12.0 where a negative value will spin opposite to the given `direction`.
`units`	Optional. The unit that represents the velocity: `PERCENT` `RPM` (default) – Rotations per minute `VelocityUnits.DPS` – Degrees per second `VOLT` – Will spin the motor or motor group at a specified voltage.

Parameters

Description

direction

The direction in which to spin the motor or motor group:

FORWARD – By default, this is counterclockwise
REVERSE – By default, this is clockwise

velocity

Optional. The velocity at which the motor or motor group will spin as a float or integer. If the velocity is not specified or previously set, the default velocity is 50%.

If VOLT is used in units, this will accept a range from -12.0 to 12.0 where a negative value will spin opposite to the given direction.

units

Optional. The unit that represents the velocity:

PERCENT
RPM (default) – Rotations per minute
VelocityUnits.DPS – Degrees per second
VOLT – Will spin the motor or motor group at a specified voltage.

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

spin_for #

spin_for rotates a motor or motor group for a specific amount of rotation using the current motor velocity, measured in degrees or turns.

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

Parameters	Description
`direction`	The direction in which to spin the motor or motor group: `FORWARD` `REVERSE`
`angle`	The amount of degrees the motor or motor group will spin as a float or integer.
`units`	Optional. The unit that represents the rotational value: `DEGREES` (default) `TURNS`
`velocity`	Optional. The velocity at which the motor or motor group will spin as a float or integer. If the velocity is not specified or previously set, the default velocity is 50%.
`units_v`	Optional. The unit that represents the velocity: `PERCENT` `RPM` (default) – Rotations per minute
`wait`	Optional. `wait=True` (default) – The project waits until `spin_for` is complete before executing the next line of code. `wait=False` - The project starts the action and moves on to the next line of code right away, without waiting for `spin_for` to finish.

# 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 rotates a motor or motor group to a specific absolute position using the current motor velocity and motor position.

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

Parameters	Description
`rotation`	The position to spin the motor or motor group to as a float or integer.
`units`	The unit that represents the rotational value: `DEGREES` `TURNS`
`velocity`	Optional. The velocity at which the motor or motor group will spin as a float or integer. If the velocity is not specified or previously set, the default velocity is 50%.
`units_v`	Optional. The unit that represents the velocity: `PERCENT` `RPM` – Rotations per minute `VelocityUnits.DPS` – Degrees per second
`wait`	Optional. `wait=True` (default) – The project waits until `spin_to_position` is complete before executing the next line of code. `wait=False` - The project starts the action and moves on to the next line of code right away, without waiting for `spin_to_position` to finish.

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

stop #

stop immediately stops the selected motor or motor group.

Usage:
motor_1.stop(mode)

Parameters	Description
mode	Optional. The stopping behavior to use when the motor stops: `BRAKE` – Stops immediately. `COAST` – Slows gradually to a stop. `HOLD` – Stops and resists movement using motor feedback. If the stopping mode is not specified or previously set, the default behavior is `BRAKE`.

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

Mutators #

set_position #

set_position sets a specific position value to a motor or motor group, which updates the encoder reading.

Usage: motor_1.set_position(position, units)

Parameters	Description
`position`	The new position as an integer.
`units`	Optional. The unit that represents the rotational value: `DEGREES` (default) `TURNS`

Parameters

Description

position

The new position as an integer.

units

Optional. The unit that represents the rotational value:

DEGREES (default)
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 sets the default spinning speed for all subsequent motor or motor group functions in the project.

Usage:
motor_1.set_velocity(velocity, units)

Parameters	Description
`velocity`	The velocity at which the motor or motor group will spin as a float or integer.
`units`	Optional. The unit that represents the velocity: `PERCENT` `RPM` (default) – Rotations per minute `VelocityUnits.DPS` – Degrees per second

Parameters

Description

velocity

The velocity at which the motor or motor group will spin as a float or integer.

units

Optional. The unit that represents the velocity:

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 behaves when it stops.

Usage:
motor_1.set_stopping(mode)

Parameters	Description
`mode`	How the motor or motor group will stop: `BRAKE` – Stops immediately. `COAST` – Slows gradually to a stop. `HOLD` – Stops and resists movement using motor feedback.

Parameters

Description

mode

How the motor or motor group will stop:

BRAKE – Stops immediately.
COAST – Slows gradually to a stop.
HOLD – Stops and resists movement using motor feedback.

set_max_torque #

set_max_torque sets how much force a motor or motor group can exert.

Usage:
motor_1.set_max_torque(value, units)

Parameters	Description
`value`	The new maximum torque for a motor or motor group as a float or integer.
`units`	Optional. The unit that represents the torque: `PERCENT` `TorqueUnits.NM` (default) – Newton Meters `TorqueUnits.INLB` – Inch Pounds `CurrentUnits.AMP`

Parameters

Description

value

The new maximum torque for a motor or motor group as a float or integer.

units

Optional. The unit that represents the torque:

PERCENT
TorqueUnits.NM (default) – Newton Meters
TorqueUnits.INLB – Inch Pounds
CurrentUnits.AMP

set_timeout #

set_timeout sets a time limit for how long a motor or motor group function will wait to reach its target. If the motor or motor group cannot complete the movement within the set time, it will stop automatically and continue with the next block.

Usage:
motor_1.set_timeout(value, units)

Parameters	Description
`value`	The maximum number of seconds a motor function will run before stopping and moving to the next function as an integer or float.
`units`	Optional. The unit that represents the time: `SECONDS` `MSEC` (default) – Milliseconds

Parameters

Description

value

The maximum number of seconds a motor function will run before stopping and moving to the next function as an integer or float.

units

Optional. The unit that represents the time:

SECONDS
MSEC (default) – Milliseconds

set_reversed #

set_reversed sets the motor to be reversed so that the FORWARD direction will spin clockwise. 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`	Boolean value to set the direction reversed or not: `True` – Reverse the motor’s direction `False` – Return the motor’s direction to its default

Parameters

Description

value

Boolean value to set the direction reversed or not:

True – Reverse the motor’s direction
False – Return the motor’s direction to its default

reset_position #

reset_position sets the motor or motor group’s position to 0.

Usage:
motor_1.reset_position()

Parameters	Description
	This method has no parameters.

Getters #

is_done #

is_done returns a Boolean indicating whether the motor or motor group is not spinning.

True - The motor is not spinning.
False - The motor is spinning.

Note: is_done only detects movement from methods that have a wait parameter.

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 a Boolean indicating whether the motor or motor group is spinning.

True - The motor is spinning.
False - The motor is not spinning.

Note: is_spinning only detects movement from methods that have a wait parameter.

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 #

position returns the total distance the selected motor or motor group has rotated. This value can be positive or negative depending on the motor’s or motor group’s configuration.

Usage:
motor_1.position(units)

Parameters	Description
`units`	Optional. The unit that represents the rotational value: `DEGREES` (default) `TURNS`

Parameters

Description

units

Optional. The unit that represents the rotational value:

DEGREES (default)
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 the current rotational speed of the motor or motor group in a range from -100% to 100% or -127 rpm to 127 rpm.

Usage:
motor_1.velocity(units)

Parameters	Description
`units`	Optional. The unit that represents the velocity: `PERCENT` `RPM` (default) – Rotations per minute `VelocityUnits.DPS` (Degrees per second)

Parameters

Description

units

Optional. The unit that represents the velocity:

PERCENT
RPM (default) – Rotations per minute
VelocityUnits.DPS (Degrees per second)

current #

current returns the amount of electrical current the motor or motor group in a range from 0.0 to 1.2 amps (amperes).

Usage:
motor_1.current(units)

Parameters	Description
`units`	Optional. The unit that represents the current: `CurrentUnits.AMP` (default) – Amps

Parameters

Description

units

Optional. The unit that represents the current:

CurrentUnits.AMP (default) – Amps

power #

power returns the amount of electrical power the motor or motor group is consuming in a range from 0.0 to 22.0 watts.

Usage:
motor_1.power(units)

Parameters	Description
`units`	Optional. The unit that represents the power: `PowerUnits.WATT` (default) – Watt

Parameters

Description

units

Optional. The unit that represents the power:

PowerUnits.WATT (default) – Watt

torque #

torque returns the amount of torque currently being applied by the motor or motor group in a range from 0.0 to 22.0 inch-pounds (InLb) or 0.0 to 2.1 Newton-meters (Nm).

Usage:
motor_1.torque(units)

Parameters	Description
`units`	The unit that represents the torque: `TorqueUnits.NM` (default) – Newton meters `TorqueUnits.INLB` – Inch pounds

Parameters

Description

units

The unit that represents the torque:

TorqueUnits.NM (default) – Newton meters
TorqueUnits.INLB – Inch pounds

efficiency #

efficiency returns the current efficiency of the motor or motor group as a percent.

Usage:
motor_1.efficiency(units)

Parameters	Description
`units`	Optional. The unit that represents the efficiency: `PERCENT` (default)

Parameters

Description

units

Optional. The unit that represents the efficiency:

PERCENT (default)

temperature #

temperature returns the current temperature of the motor or motor group.

Usage:
motor_1.temperature(units)

Parameters	Description
`units`	Optional. The units that represent the temperature: `TemperatureUnits.CELSIUS` (default) `TemperatureUnits.FAHRENHEIT` `PERCENT`

Parameters

Description

units

Optional. The units that represent the temperature:

TemperatureUnits.CELSIUS (default)
TemperatureUnits.FAHRENHEIT
PERCENT

count #

count returns the number of motors in a motor group as an integer.

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 currently set timeout in milliseconds.

motor_1.get_timeout()

Parameters	Description
	This method has no parameters.

Constructors #

Constructors are used to manually create Motor and MotorGroup objects, which are necessary for configuring a motor or motor group outside of VEXcode.

Motor #

Motor creates a single 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 number of the port.
`gears`	Optional. The motor’s gear ratio: `GearSetting.RATIO_1_1` (default) – 1:1 Ration `GearSetting.RATIO_2_1` – 2:1 Ratio `GearSetting.RATIO_3_1` – 3:1 Ratio
`reverse`	Optional. Sets whether the motor’s spin should be reversed. `True` – `FORWARD` will spin clockwise `False` (default) – `FORWARD` will spin counterclockwise

Parameter

Description

port

The Smart Port that the motor is connected to, written as Ports.PORTx where x is the number of the port.

gears

Optional. The motor’s gear ratio:

GearSetting.RATIO_1_1 (default) – 1:1 Ration
GearSetting.RATIO_2_1 – 2:1 Ratio
GearSetting.RATIO_3_1 – 3:1 Ratio

reverse

Optional. Sets whether the motor’s spin should be reversed.

True – FORWARD will spin clockwise
False (default) – FORWARD will 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
- 2:1 ratio
- Reversed
"""
motor_1 = Motor(Ports.PORT1, GearSetting.RATIO_2_1, True)

MotorGroup #

MotorGroup creates a motor group.

Usage:
MotorGroup(motors)

Parameter	Description
`motors`	The names of previously created `Motor` objects to be 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)