Vex v5 Motor API
This document goes over some of the smart motor commands in the v5 system.
Configuration
Inversion
In addition to inverting the motor by using the robot configuration, the following command can also be used to invert/uninvert the motor in code. For reference, by default, forward (or positive signal) relates to a counter-clockwise rotation when looking at the motor output shaft.
motorName.setReversed(value);
// sets the motor to be reversed
// in this case a positive or forward signal will now be clockwise rotation
motorName.setReversed(true);
Velocity
This command will set the default velocity of the v5 motor. This does not make the motor spin. This speed is used for commands that do not specify a speed to use. If your rotation commands does provide a speed, then that speed will be used but only for that command. See Movement Commands for rotation commands.
motorName.setVelocity(velocity, velocityUnits);
// all motor rotation commands after this line will use a default 80 percent speed
// this setting is overridden for a command, if the rotation command used specifies a speed
motorName.setVelocity(80, velocityUnits::pct);
Stopping Mode
This command will allow you to set the stopping mode of the motor to one of the three options. Stopping mode affects what happens to the motor after a rotation command is completed and the motor needs to stop. Coast will allow to motor to spin under inertia after the signal is turned off, brake will apply a sort of brake to the motor and reduce the effects of that inertia. Hold is like brake but tries to hold position.
motorName.setStopping( brakeType);
// set this motor to hold its position when stopping
motorName.setStopping(brakeType::hold);
Timeout
This command will stop the motor after the the timeout is finished, even if the motor has not reached the target position.
// after 5 secends the motor will stop even it it hasn't reached position
motorName.setTimeout(5, timeUnits::sec);
Movement Commands
Spin
There are 2 spin commands, and these are the simplest way to spin a motor.
Direction only
This command will spin the motor in the specified direction, at the default velocity.
motorName.spin( directionType);
// spin the motor in the reverse direction
// reverse is either colockwise or counter-clockwise rotation of the motor (see motor setup)
motorName.spin(directionType::rev);
Direction with Velocity
This command will spin the motor in the specified direction, at the specified velocity.
motorName.spin(directionType, velocity, velocityUnits);
// spin the motor forward, at 61.0 percent of max speed
// forward is either colockwise or counter-clockwise rotation of the motor (see motor setup)
motorName.spin(directionType::fwd, 61.0, velocityUnits::pct);
Relative Motion
There are 4 commands that achieve motion relative to the current state of the robot. The starting point of these commands is the end point of the last issued command. Look at Absolute Motion for absolute motion commands.
Time
This command will spin the motor for a relative target time, at the default velocity.
// spin the moror for 5 seconds
motorName.rotateFor(5, timeUnits::sec);
Time with Velocity
This command will spin the motor for a relative target time, at the specified velocity.
motorName.rotateFor(time, timeUnits, velocity, velocityUnits);
// spin the motor for 500 milliseconds at a speed of 9.8 revolutions per minute
motorName.rotateFor(500, timeUnits::msec, 9.8, velocityUnits::rpm);
Rotations
This command will spin the motor for relative target rotations, at the default velocity.
motorName.rotateFor(rotation, rotationUnits, waitForCompletion);
// spin the motor 360 degrees of the motor (aka 1 revolution)
// do not wait for the rotation to finish and move to next command
motorName.rotateFor(360, rotationUnits::deg, false);
Rotations with Velocity
This command will spin the motor for relative target rotations, at the specified velocity.
motorName.rotateFor(rotation, rotationUnits, velocity, velocityUnits waitForCompletion);
// spin the motor for 1500 encoder counts at a speed of 90 degrees per second (quarter motor rotation per second)
// by omitting the waitForCompletion, the value defaults true
// therefore the program will wait for the command to finish before executing the next command
motorName.rotateFor(1500, rotationUnits::raw, 90, velocityUnits::dps);
Absolute Motion
There are 2 commands that use absolute position of the encoder, meaning that subsequent uses will not start where the other command ended. If the motor is already at the position then it will not spin.
In other words these commands are relative to the zero position of the encoder. Using the relative motion commands (see Relative Motion) and resetting the encoder to zero after each command would in essence be the same as using absolute methods.
Absolute Rotations
This command will spin the motor to the target rotations, at the default velocity.
motorName.rotateTo(rotation, rotationUnits, waitForCompletion);
// spin the motor to 720 degrees of the motor (aka 2 revolutions)
// if the motor position was already at 720 degrees, then no rotation would occur
// do not wait for the rotation to finish and move to next command
motorName.rotateTo(360, rotationUnits::deg, false);
Absolute Rotations with Velocity
This command will spin the motor to the target rotations, at the specified velocity.
motorName.rotateTo(rotation, rotationUnits, velocity, velocityUnits waitForCompletion);
// spin the motor to 1500 encoder counts at a speed of 90 degrees per second (quarter motor rotation per second)
// if the motor position was already at 1500 counts, then no rotation would occur
// by omitting the waitForCompletion, the value defaults true
// therefore the program will wait for the command to finish before executing the next command
motorName.rotateTo(1500, rotationUnits::raw, 90, velocityUnits::dps);
Motor Monitoring
These commands will allow for you to retrieve useful infomration about your motor programmatically, which can then allow your programs to make decisions and take actions based on the information collected.
Activity
Spinning
Returns true if the motor is spinning at the time the command is executed, or false otherwise.
motorName.isSpinning();
// here we check if the motor is spinning, then stop it
// because the status of the motor can change anytime, it is not wise to store this value in a variable
if(motorName.isSpinning()) {
motorName.stop();
}
Completed
Returns true if the motor is done spinning to/for a target at the time the command is executed, or false otherwise.
motorName.isDone();
// here we check if the motor is done spinning, then start it
// because the status of the motor can change anytime, it is not wise to store this value in a variable
if(motorName.isDone()) {
motorName.spin(directionType::fwd);
}