Motor

Introduction

The VEX IQ (2nd Gen) Motion category offers methods for interacting with motors and motor groups.

For the examples below, the configured motor will be named Motor1, and the configured motor group will be named MotorGroup1. They will be used in all subsequent examples throughout this API documentation when referring to motor and motor_group class methods.

Below is a list of all methods:

Actions – Control the movements of motors.

• spin – Spins a motor or motor group in a specified direction indefinitely.

• spinFor – Spins a motor or motor group for a specified distance.

• spinToPosition – Spins a motor to an absolute position.

• stop – Stops a motor or motor group with configurable behavior.

Mutators – Change the motor’s different attributes.

• setVelocity – Sets the default velocity for the motor or motor group.

• setMaxTorque – Sets the maximum torque for a motor or motor group.

• setPosition – Sets the motor or motor group’s position to a specific value.

• setStopping – Sets the stop behavior (brake, coast, or hold).

• setTimeout – Limits how long a motor function waits before giving up if movement is blocked.

• setReversed – Sets only a motor to have its direction be reversed.

• resetPosition – Sets only a motor’s position to 0.

Getters – Return data from the motors.

• isDone – Returns whether a motor or motor group is currently not spinning.

• isSpinning – 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.

Constructors – Manually initialize and configure motors and motor groups.

• motor – Creates a motor.

• motor_group – Creates a motor group.

Actions

spin

spin spins a motor or motor group in the specified direction indefinitely.

Default Usage:
Motor1.spin(direction);

Overload Usages:
Motor1.spin(direction, velocity, velocityUnits);
Motor1.spin(direction, voltage, voltageUnits);

Parameters	Description
direction	The direction in which to spin the motor or motor group: forward reverse
velocity	The velocity that the motor or motor group will spin at as a double.
velocityUnits	The unit that will represent the velocity: percent dps – degrees per second rpm – rotations per minute
voltage	The voltage that the motor will spin with.
voltageUnits	The unit that will represent the voltage: voltageUnits::volt – volts voltageUnits::mV – millivolts

int main() {
  // Initializing Robot Configuration. DO NOT REMOVE!
  vexcodeInit();

  // Spin forward, then stop
  Motor1.spin(forward);
  wait(1, seconds);
  Motor1.stop();
}

spinFor

spinFor spins a Motor or Motor Group for a set amount in a specified direction.

Default Usage:
Motor1.spinFor(direction, rotation, units, wait);

Overload Usages:
Motor1.spinFor(rotation, units, velocity, units_v, wait);
Motor1.spinFor(direction, rotation, units, velocity, units_v, wait);
Motor1.spinFor(rotation, units, wait);
Motor1.spinFor(time, units_t, velocity, units_v);
Motor1.spinFor(direction, time, units_t, velocity, units_v);
Motor1.spinFor(time, units_t);
Motor1.spinFor(direction, time, units_t);

Parameters	Description
direction	The direction in which to spin the motor or motor group: forward reverse
rotation	How far the motor will rotate.
units	The unit that will represent the rotation: degrees turns
wait	Optional. true (default) – The robot waits until spinFor is complete before executing the next line of code. false – The robot starts the action and moves on to the next line of code right away, without waiting for spinFor to finish.
velocity	The velocity that the motor or motor group will spin at as a double.
units_v	The unit that will represent the velocity: dps – degrees per second rpm – rotations per minute velocityUnits::pct – percent
time	The amount of time the motor will spin for. wait cannot be used when using the time parameter.
units_t	The unit that represents the time: seconds msec – milliseconds

int main() {
  // Initializing Robot Configuration. DO NOT REMOVE!
  vexcodeInit();

  // Spin 1 turn fast, then 1 turn slow
  Motor1.spinFor(forward, 1, turns, true);
  Motor1.spinFor(reverse, 1, turns, 20, percent, true);
}

spinToPosition

spinToPosition spins the motor or motor group to a specified position.

Default Usage:
Motor1.spinToPosition(position, units, wait);

Overload Usages:
Motor1.spinToPosition(position, positionUnits, velocity, velocityUnits, wait);

Parameters	Description
position	The position that the motor or motor group will spin to.
units	The unit that will represent the position: degrees turns
wait	Optional. true (default) – The robot waits until spinToPosition is complete before executing the next line of code. false – The robot starts the action and moves on to the next line of code right away, without waiting for spinToPosition to finish.
velocity	The velocity that the motor or motor group will spin at as a double.
velocityUnits	The unit that will represent the velocity: dps – degrees per second rpm – rotations per minute velocityUnits::pct – percent

int main() {
  // Initializing Robot Configuration. DO NOT REMOVE!
  vexcodeInit();

  // Spin forward, then go to 90°
  Motor1.spin(forward);
  wait(1, seconds);
  Motor1.spinToPosition(90, degrees);
}

stop

stop stops the motor or motor group from spinning.

Default Usage:
Motor1.stop();

Overload Usages:
Motor1.stop(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.

int main() {
  // Initializing Robot Configuration. DO NOT REMOVE!
  vexcodeInit();

  // Spin and coast to a stop
  Motor1.setVelocity(100, percent);
  Motor1.spin(forward);
  wait(1, seconds);
  Motor1.stop(coast);
}

Mutators

setVelocity

setVelocity 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:
Motor1.setVelocity(velocity, units);

Parameters	Description
velocity	The velocity the motor or motor group will spin at as a double.
units	The unit that represents the velocity: percent rpm – rotations per minute dps – degrees per second.

int main() {
  // Initializing Robot Configuration. DO NOT REMOVE!
  vexcodeInit();

  // Try default, then slow, then fast
  Motor1.spinFor(forward, 180, degrees);
  wait(1, seconds);
  Motor1.setVelocity(20, percent);
  Motor1.spinFor(reverse, 180, degrees);
  wait(1, seconds);
  Motor1.setVelocity(100, percent);
  Motor1.spinFor(forward, 180, degrees);
}

setMaxTorque

setMaxTorque sets the maximum torque that a motor or motor group can spin at.

Usage:
Motor1.setMaxTorque(value, units);

Parameters	Description
value	The maximum torque the motor or motor group can spin at.
units	The unit that represents the torque: percent Nm – Newton meters. InLb – inch pounds. amp – amps.

setPosition

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

Usage:
Motor1.setPosition(position, units);

Parameters	Description
position	The position that the specified motor or motor group will spin to.
units	The unit that will represent the rotation: degrees turns

int main() {
  // Initializing Robot Configuration. DO NOT REMOVE!
  vexcodeInit();

  // Set a new zero, then go to 0°
  Motor1.setPosition(180, degrees);
  Motor1.spinToPosition(0, degrees);
}

setStopping

setStopping sets how a motor or motor group behaves when it stops.

Usage:
Motor1.setStopping(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.

setTimeout

setTimeout sets a time limit for how long a motor command will wait to reach its target. If the robot cannot complete the movement within the set time, it will stop automatically and continue with the next command.

Note: The motor’s time limit is used to prevent motor commands that do not reach their target position from stopping the execution of other commands in the stack.

Usage:
Motor1.setTimeout(time, units);

Parameters	Description
time	The maximum number of seconds a motor command will run before stopping and moving to the next command.
units	The unit that represents the timeout: seconds msec – milliseconds

int main() {
  // Initializing Robot Configuration. DO NOT REMOVE!
  vexcodeInit();

  // Stop a long move after 0.5 seconds
  Motor1.setTimeout(0.5, seconds);
  Motor1.spinFor(forward, 2, turns);
  Motor1.spinToPosition(0, degrees);
}

setReversed

setReversed sets the motor to be reversed. This method works the same as setting the reverse parameter to true when constructing a motor.

Usage:
Motor1.setReversed(reversed);

Parameters	Description
reversed	A Boolean representing whether or not the motor is reversed: true – Reverse the motor direction. false – Return to the motor’s default configuration.

resetPosition

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

Usage:
Motor1.resetPosition();

Parameters	Description
	This method has no parameters.

int main() {
  // Initializing Robot Configuration. DO NOT REMOVE!
  vexcodeInit();

  // Spin to 360°, then reset the encoder
  Motor1.spinToPosition(360, degrees);
  Motor1.resetPosition();

  // Now spin to 90° from this new zero point
  Motor1.spinToPosition(90, degrees);
}

Getters

isDone

isDone returns a Boolean indicating whether a motor or motor group is not currently spinning.

• 1 – The motor or motor group is done spinning.

• 0 – The motor or motor group is still spinning.

Usage:
Motor1.isDone()

Parameters	Description
	This method has no parameters.

isSpinning

isSpinning returns a Boolean indicating whether a motor or motor group is currently spinning.

• 1 – The motor or motor group is spinning.

• 0 – The motor or motor group is not spinning.

Usage:
Motor1.isSpinning()

Parameters	Description
	This method has no parameters.

position

position returns the current position of a motor or motor group as a double.

Usage:
Motor1.position(units)

Parameters	Description
units	The unit that will represent the position: degrees turns

int main() {
  // Initializing Robot Configuration. DO NOT REMOVE!
  vexcodeInit();

  // Spin, then show the final position
  Motor1.spin(forward);
  wait(1, seconds);
  Motor1.stop();
  Brain.Screen.print("Pos: %f", Motor1.position(degrees));
}

velocity

velocity returns the current velocity of a motor or motor group as a double.

Usage:
Motor1.velocity(units)

Parameters	Description
units	The unit that will represent the velocity: percent rpm – rotations per minute dps – degrees per second

current

current returns the current of a motor or motor group as a double.

Usage:
Motor1.current(units)

Parameters	Description
units	The unit that represents the current: amp – amps. percent

direction

direction returns the current direction a motor or motor group is spinning in:

• forward

• reverse

Usage:
Motor1.direction()

Parameters	Description
	This method has no parameters.

power

power returns the current power of the motor.

Usage:
Motor1.power(units)

Parameters	Description
units	The unit that represents the power: watt

torque

torque returns the current torque of the motor.

Usage:
Motor1.torque(units)

Parameters	Description
units	The unit that represents the torque: Nm – Newton meters. InLb – inch pounds. amp – amps.

efficiency

efficiency returns the efficiency of the motor as a percent.

Usage:
Motor1.efficiency()

Parameters	Description
	This method has no parameters.

temperature

temperature returns the current temperature of the motor as a percent.

Usage:
Motor1.temperature(units)

Parameters	Description
units	The unit that represents the temperature: celsius fahrenheit

count

count returns the number of motors in a motor group as an integer. This method will not work with individual Motors.

Usage:
MotorGroup1.count()

Parameters	Description
	This method has no parameters.

Constructors

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

motor

motor creates an object of the motor Class in the specified port.

Default Usage:
motor Motor1 = motor(port);

Overload Usages:
motor Motor1 = motor(port, reverse); motor Motor1 = motor(port, gearRatio); motor Motor1 = motor(port, gearRatio, reverse);

Parameters	Description
port	Which Smart Port that the Motor is connected to as PORT followed by the port number, ranging from 1 to 12.
reverse	A Boolean indicating whether or not the Motor’s directions are configured in reverse: true – The Motor is reversed. false – The Motor is not reversed.
gearRatio	The gear ratio of the Motor as a double.

int main() {
  // Initializing Robot Configuration. DO NOT REMOVE!
  vexcodeInit();

  // Make a reversed motor on Port 1
  motor Motor1 = motor(PORT1, true);
}

motor_group

motor_group creates an object of the motor_group Class in the specified port. A motor_group is a collection of individual motor objects.

Usage:
motor_group MotorGroup1 = motor_group(motor1, motor2);

Parameters	Description
motor	The configured motor to add to the motor_group. Up to 12 motor objects can be added to the group.

int main() {
  // Initializing Robot Configuration. DO NOT REMOVE!
  vexcodeInit();

  // Create two motors
  motor motorA = motor(PORT1, false);
  motor motorB = motor(PORT6, true);

  // Create a motor group with those motors
  motor_group MotorGroup1 = motor_group(motorA, motorB);
}