Motor#
Introduction#
The IQ Smart Motor can spin, hold position, and control velocity and torque with precision. It can be used individually or as part of a motor group.
Below is a list of all methods:
Methods – Control the movement and behavior of motors.
spin – Spins a motor or motor group in a specified direction indefinitely.
spin_for – Spins a motor or motor group for a specified distance.
spin_to_position – Spins a motor to an absolute position.
stop – Stops a motor or motor group with configurable behavior.
set_position – Sets the motor or motor group’s position to a specific value.
reset_position – Sets only a motor’s position to 0.
set_velocity – Sets the default velocity for the motor or motor group.
set_stopping – Sets the stop behavior (brake, coast, or hold).
set_max_torque – Sets the maximum torque for a motor or motor group.
set_timeout – Limits how long a motor function waits before giving up if movement is blocked.
get_timeout – Returns only a motor’s current timeout duration.
is_done – Returns whether a motor or motor group is currently not spinning.
is_spinning – Returns whether a motor or motor group is currently spinning.
position – Returns a motor or motor group’s current position.
velocity – Returns a motor or motor group’s current velocity.
current – Returns the current being used by a motor or motor group.
direction – Returns the spin direction of a motor or motor group.
power – Returns the amount of power being used by a motor or motor group.
torque – Returns the torque generated by a motor or motor group.
efficiency – Returns the efficiency of a motor or motor group.
temperature – Returns the temperature of a motor or motor group.
count – Returns the amount of motors in a motor group.
set_reversed – Sets only a motor to have its direction be reversed.
Constructors – Manually initialize and configure motors and motor groups.
Motor – Creates a motor.
MotorGroup – Creates a motor group.
Class Methods#
spin#
spin
spins a motor or motor group in the specified direction indefinitely.
Usage:
motor_1.spin(direction, velocity, units)
Parameters |
Description |
---|---|
direction |
The direction in which to spin the motor or motor group:
|
velocity |
Optional. The velocity at which the motor or motor group will spin as a float or integer. If the velocity is not specified, the default velocity is 50%. |
units |
Optional. The unit that represents the velocity:
|
# Spin the motor forward, then stop
motor_1.spin(FORWARD)
wait(1, SECONDS)
motor_1.stop()
spin_for#
spin_for
spins a motor or motor group in a specified direction for a set distance relative to its current position.
Usage:
spin_for(direction, angle, units, velocity, units_v, wait)
Parameters |
Description |
---|---|
direction |
The direction in which to spin the motor or motor group:
|
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:
|
velocity |
Optional. The velocity at which the motor or motor group will spin as a float or integer. If the velocity is not specified, the default velocity is 50%. |
units_v |
Optional. The unit that represents the velocity:
|
wait |
Optional.
|
# Spin the motor forward, then put it
# at 90 degrees
motor_1.spin(FORWARD)
wait(2, SECONDS)
motor_1.spin_to_position(90, DEGREES)
# Spin the motor and different
# velocities
# Using default velocity
motor_1.spin_for(FORWARD, 150, MM)
wait(1, SECONDS)
# Spin slower
motor_1.spin_for(REVERSE, 150, MM, 20, PERCENT)
wait(1, SECONDS)
# Spin faster
motor_1.spin_for(FORWARD, 150, MM, 100, PERCENT)
spin_to_position#
spin_to_position
spins a motor and motor group to an absolute position.
Usage:
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:
|
velocity |
Optional. The velocity at which the motor or motor group will spin as a float or integer. If the velocity is not specified, the default velocity is 50%. |
units_v |
Optional. The unit that represents the velocity:
|
wait |
Optional.
|
# Spin the motor forward, then
# put it at 90 degrees
motor_1.spin(FORWARD)
wait(2, SECONDS)
motor_1.spin_to_position(90, DEGREES)
# Spin forward then quickly reverse
# to 0 degrees
motor_1.spin(FORWARD)
wait(2, SECONDS)
motor_1.spin_to_position(0, DEGREES, 100, PERCENT, wait=True)
stop#
stop
stops a motor or motor group.
Usage:
stop(mode)
Parameters |
Description |
---|---|
mode |
Optional. How the motor or motor group will stop:
|
# Spin the motor forward, then stop
motor_1.spin(FORWARD)
wait(1, SECONDS)
motor_1.stop()
# Spin the motor and coast to a stop
motor_1.set_velocity(100, PERCENT)
motor_1.spin(FORWARD)
wait(2, SECONDS)
motor_1.stop(COAST)
set_position#
set_position
sets the position of a motor or motor group.
Usage:
set_position(position, units)
Parameters |
Description |
---|---|
position |
The new position as an integer. |
units |
The unit that represents the rotational value:
|
# Position the motor at the
# new 0 degrees
motor_1.set_position(180, DEGREES)
motor_1.spin_to_position(0)
reset_position#
reset_position
sets the motor or motor group’s position to 0.
Usage:
reset_position()
Parameters |
Description |
---|---|
This method has no parameters. |
# Reset the motor position after spinning
motor_1.spin(FORWARD)
wait(2, SECONDS)
motor_1.stop()
brain.screen.print(motor_1.position())
brain.screen.next_row()
wait(1, SECONDS)
motor_1.reset_position()
brain.screen.print(motor_1.position())
set_velocity#
set_velocity
sets the default velocity for a motor or motor group. This velocity setting will be used for subsequent calls to any motor functions if a specific velocity is not provided.
Usage:
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:
|
# Spin the motor and
# different velocities
# Using default velocity
motor_1.spin_for(FORWARD, 150, MM)
wait(1, SECONDS)
# Spin slower
motor_1.set_velocity(20, PERCENT)
motor_1.spin_for(REVERSE, 150, MM)
wait(1, SECONDS)
# Spin faster
motor_1.set_velocity(100, PERCENT)
motor_1.spin_for(FORWARD, 150, MM)
set_stopping#
set_stopping
sets the stopping mode for a motor or motor group.
Usage:
set_stopping(mode)
Parameters |
Description |
---|---|
mode |
How the motor or motor group will stop:
|
# Spin the motor and coast to a stop
motor_1.set_velocity(100, PERCENT)
motor_1.set_stopping(COAST)
motor_1.spin(FORWARD)
wait(2, SECONDS)
motor_1.stop()
set_max_torque#
set_max_torque
sets the maximum torque for a motor or motor group. The torque can be set as torque, current, or a percent of maximum torque.
Usage:
set_max_torque(value, units)
Parameters |
Description |
---|---|
value |
The new maximum torque for a motor or motor group as a float or integer. |
units |
The unit that represents the torque:
|
# Spin the motor at different
# torque values
# Default
motor_1.spin_to_position(45, DEGREES)
# Spin at a lower torque
motor_1.set_max_torque(20, PERCENT)
motor_1.spin_to_position(0, DEGREES)
# Spin at te max torque
motor_1.set_max_torque(100, PERCENT)
motor_1.spin_to_position(45, DEGREES)
set_timeout#
set_timeout
sets a time limit for how long a motor 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 function.
Note: The motor or motor group’s time limit is used to prevent motor functions that do not reach their target position from stopping the execution of the rest of the project.
Usage:
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:
|
# Spin the motor half a second and reset
motor_1.set_timeout(0.5, SECONDS)
motor_1.spin_for(FORWARD, 10, TURNS)
motor_1.spin_to_position(0)
get_timeout#
get_timeout
returns the current timeout for a motor in milliseconds.
Note: This method will only work with a motor and not a motor group.
Usage:
get_timeout()
Parameters |
Description |
---|---|
This method has no parameters. |
# Spin the motor half a second and reset, then display the timeout
motor_1.set_timeout(0.5, SECONDS)
motor_1.spin_for(FORWARD, 10, TURNS)
motor_1.spin_to_position(0)
brain.screen.print(motor_1.get_timeout())
is_done#
is_done
returns a Boolean indicating whether a motor or motor group is not currently spinning.
True
– The motor or motor group is not spinning.False
– The motor or motor group is spinning.
Usage:
is_done()
Parameters |
Description |
---|---|
This method has no parameters. |
# Drive forward while the motor
# is spinning
motor_1.spin_for(FORWARD, 200, DEGREES, wait=False)
while True:
if motor_1.is_done():
drivetrain.stop()
else:
drivetrain.drive(FORWARD)
is_spinning#
is_spinning
returns a Boolean indicating whether a motor or motor group is currently spinning.
True
– The motor or motor group is spinning.False
– The motor or motor group is not spinning.
Usage:
is_spinning()
Parameters |
Description |
---|---|
This method has no parameters. |
# Drive forward while the motor
# is spinning
motor_1.spin_for(FORWARD, 200, DEGREES, wait=False)
while motor_1.is_spinning():
drivetrain.drive(FORWARD)
drivetrain.stop()
position#
position
returns the current position of a motor or motor group as an integer or as a float.
Usage:
position(units)
Parameters |
Description |
---|---|
units |
Optional. The unit that represents the rotational value:
|
# Spin the motor and display the
# ending position
motor_1.spin(FORWARD)
wait(1, SECONDS)
motor_1.stop()
brain.screen.print(motor_1.position())
velocity#
velocity
returns the current velocity of a motor or motor group as an integer or as a float.
Usage:
velocity(units)
Parameters |
Description |
---|---|
units |
Optional. The unit that represents the velocity:
|
# Display the motor's velocity before
# and after spinning
brain.screen.print(motor_1.velocity())
brain.screen.next_row()
motor_1.spin(FORWARD)
wait(1, SECONDS)
brain.screen.print(motor_1.velocity())
motor_1.stop()
current#
current
returns the current of the motor or motor group in amps.
Usage:
motor_1.current(units)
Parameters |
Description |
---|---|
|
Optional. The unit that represents the current:
|
# Example coming soon
direction#
direction
returns the current direction a motor or motor group is spinning in.
FORWARD
REVERSE
Usage:
direction()
Parameters |
Description |
---|---|
This method has no parameters. |
# Spin the motor and print the spin direction
motor_1.set_position(50, DEGREES)
motor_1.spin_to_position(0, DEGREES)
if motor_1.direction() == DirectionType.FORWARD:
brain.screen.print('FORWARD')
elif motor_1.direction() == DirectionType.REVERSE:
brain.screen.print('REVERSE')
else:
brain.screen.print("Not Spinning.")
count#
count
returns the number of motors in a motor group as an integer.
Note: This method will only work with a motor group and not a motor.
Usage:
count()
Parameters |
Description |
---|---|
This method has no parameters. |
# Display the amount of motors in the group
brain.screen.print(motor_group_1.count())
set_reversed#
set_reversed
sets the motor to be 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:
set_reversed(value)
Parameters |
Description |
---|---|
value |
Boolean value to set the direction reversed or not:
|
# Change the reverse direction while spinning
motor_1.spin_for(FORWARD, 45)
motor_1.set_reversed(True)
motor_1.spin_for(FORWARD, 45)
Constructors#
Constructors are used to manually create Motor
and MotorGroup
objects, which are necessary for configuring a motor or motor group outside of VEXcode.
For the examples below, the configured motors will be named motor_1
and motor_2
, and the configured motor group will be named motor_group_a
, and will be used in all subsequent examples throughout this API documentation when referring to Motor
and MotorGroup
class methods.
Motor#
Motor
creates a motor.
Usage:
Motor(port, gears, reverse)
Parameter |
Description |
---|---|
|
Which Smart Port the motor is connected to, from 1 to 12. |
|
Optional. The motor’s gear ratio:
|
|
Optional. Sets whether the motor’s spin should be reversed.
|
# Construct a Motor object named motor_1 in Port 1 on
# the IQ (2nd gen) Brain which has the reverse flag set to True
motor_1 = Motor(Ports.PORT1, 1.0, True)
# Spin the motor forward for some time
motor_1.spin(FORWARD)
wait(1, SECONDS)
motor_1.stop()
Motor Group#
MotorGroup
creates a motor group.
Usage:
MotorGroup(motors)
Parameter |
Description |
---|---|
|
The names of previously created |
# Construct a motor group with 2 motors
motor_group_1_motor_a = Motor(Ports.PORT1, False)
motor_group_1_motor_b = Motor(Ports.PORT6, True)
motor_group_1 = MotorGroup(motor_group_1_motor_a, motor_group_1_motor_b)
# Spin the motor forward, then stop
motor_group_1.spin(FORWARD)
wait(1, SECONDS)
motor_group_1.stop()