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.

# 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

# 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

# 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.

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

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

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

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

# 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)

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

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

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

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)

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

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

# 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)