Motor and Motor Group#

Introduction#

The motor class provides control of a VEX V5 Smart Motor, including motion control, velocity control, position tracking, torque reporting, and configuration.

The motor_group class allows multiple VEX V5 Smart Motors to be controlled together as a single unit. A motor_group applies the same motion commands, velocity settings, stopping behavior, and torque limits to all motors within the group, simplifying programming when multiple motors must operate in sync.

Motor#

Class Constructors#

1 — Creates a motor object for the V5 Smart Motor connected to the specified Smart Port.
The motor automatically uses the detected internal gearSetting.
motor( 
  int32_t index );

2 — Creates a motor object on the specified Smart Port and optionally reverses its direction.
The motor automatically uses the detected internal gearSetting.
motor(
 int32_t index,
 bool    reverse );

3 — Creates a motor object on the specified Smart Port with the specified gearSetting.
motor(
 int32_t     index,
 gearSetting gears );

4 — Creates a motor object on the specified Smart Port with the specified gearSetting and optional reversed direction.
motor(
 int32_t     index,
 gearSetting gears,
 bool        reverse );

Class Destructor#

Destroys the motor object and releases associated resources.

~motor();

Parameters#

Parameter	Type	Description
`index`	`int32_t`	The Smart Port that the motor is connected to, written as `PORTx`, where `x` is the port number (for example, `PORT1`).
`reverse`	`bool`	Sets the positive direction of motor rotation: `false` (default) — Clockwise rotation is treated as forward (positive direction). `true` — Counterclockwise rotation is treated as forward (positive direction).
`gears`	`gearSetting`	Specifies the internal gear cartridge ratio. `ratio36_1` — The red 36:1 gear cartridge `ratio18_1` — The green 18:1 gear cartridge `ratio6_1` — The blue 6:1 gear cartridge

Parameter

Type

Description

index

int32_t

The Smart Port that the motor is connected to, written as PORTx, where x is the port number (for example, PORT1).

reverse

bool

Sets the positive direction of motor rotation:

false (default) — Clockwise rotation is treated as forward (positive direction).
true — Counterclockwise rotation is treated as forward (positive direction).

gears

gearSetting

Specifies the internal gear cartridge ratio.

ratio36_1 — The red 36:1 gear cartridge
ratio18_1 — The green 18:1 gear cartridge
ratio6_1 — The blue 6:1 gear cartridge

Notes#

Gear setting should match the physical cartridge installed in the motor.

Example#

// Create the motor instance in Smart Port 1
motor LeftMotor = motor(PORT1);

// Creates the motor instance with different settings
motor RightMotor = motor(
  PORT2,      // Smart Port 2
  ratio18_1,  // Gear setting is 18
  true);

Motor Group#

Class Constructors#

motor_group( motor &m1, Args&... m2 );

Class Destructor#

Destroys the motor_group object and releases associated resources.

~motor_group();

Parameters#

Parameter	Type	Description
`m1`	`motor &`	The first motor added to the group.
`m2`	`motor &`	Additional motors added to the group. The maximum is four motors to one motor group.

Example#

// Create individual motor instances
motor LeftMotor  = motor(PORT1);
motor RightMotor = motor(PORT2);

// Create a motor group with both motors
motor_group DriveMotors = motor_group(LeftMotor, RightMotor);

Member Functions#

The motor and motor_group classes includes the following member functions:

spin — Spins the motor or motor group in a specified direction.
spinFor — Spins the motor or motor group for a specified amount of rotation or time.
spinToPosition — Spins the motor or motor group to a specified absolute position.
stop — Stops the motor or motor group using a selected braking mode.
setPosition — Sets the motor or motor group’s current encoder position.
setVelocity — Sets the default velocity for a motor or motor group.
setStopping — Sets how a motor or motor group behaves when it stops.
setMaxTorque — Sets the maximum torque that a motor or motor group can spin at.
setTimeout — Sets a time limit for how long a motor or motor group command will wait to reach its target.
isDone — Returns a Boolean indication whether a motor or motor group is currently not spinning.
isSpinning — Returns a Boolean indicating whether a motor or motor group is currently spinning.
position — Returns the current position of a motor or motor group.
velocity — Returns the current velocity of a motor or motor group.
current — Returns the motor or motor group’s (or motor or motor group group’s) electrical current draw.
power — Returns the electrical power supplied to the motor or motor group.
torque — Returns the motor or motor group’s (or motor or motor group group’s) current torque value.
efficiency — Returns the efficiency of the motor or motor group.
temperature — Returns the temperature of the motor or motor group.
voltage — Returns the electrical voltage supplied to the motor or motor group.
direction — Returns the direction that the motor or motor group is spinning.
installed — Returns whether the motor or motor group is detected on the specified Smart Port.
count — Returns the number of motors in the motor group.

Before calling any motor or motor_group member functions, an instance must be created, as shown below:

/* This constructor is required when using VS Code.
Motor and Motor Group configuration is generated automatically
in VEXcode using the Device Menu. Replace the values
as needed. */

// Create the motor instance in Smart Port 1
motor Motor1 = motor(PORT1);

spin#

Spins the motor or motor group in the specified direction indefinitely.

Available Functions

1 — Spins the motor or motor group using the currently configured motor velocity.
void spin(
 directionType dir );

2 — Spins the motor or motor group at the specified velocity.
void spin(
 directionType dir,
 double        velocity,
 velocityUnits units );

3 — Spins the motor or motor group using the specified voltage.
void spin(
 directionType dir,
 double        voltage,
 voltageUnits  units );

Parameters

Parameter	Type	Description
`dir`	`directionType`	The direction in which the motor or motor group spins: `forward` `reverse`
`velocity`	`double`	The velocity value applied to the motor or motor group.
`units`	`velocityUnits`	The unit used to represent velocity: `percent` / `pct` — percent `rpm` — rotations per minute `dps` — degrees per second
`voltage`	`double`	The voltage value applied to the motor or motor group.
`units`	`voltageUnits`	The unit used to represent voltage: `volt` — volts `voltageUnits::mV` — millivolts

Return Values

This function does not return a value.

Notes

This function is non-waiting and the project will continue executing immediately after the call.
The motor or motor group will continue spinning until stop is called or another movement function is executed.
Functions such as isDone and isSpinning are not applicable to spin, since it does not use target-based movement (doesn’t have a rotation or time parameter).

Examples

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

spinFor#

Spins a motor or motor group for a set amount in a specified direction.

Available Functions

1 — Spins for a target rotation at the velocity provided in the function call.
bool spinFor(
 double        rotation,
 rotationUnits units,
 double        velocity,
 velocityUnits units_v,
 bool          waitForCompletion = true );

2 — Accepts a direction parameter and spins for a target rotation at the velocity provided in the function call.
bool spinFor(
 directionType dir,
 double        rotation,
 rotationUnits units,
 double        velocity,
 velocityUnits units_v,
 bool          waitForCompletion = true );

3 — Spins for a target rotation using the currently configured motor velocity.
bool spinFor(
 double        rotation,
 rotationUnits units,
 bool          waitForCompletion = true );

4 — Accepts a direction parameter and spins for a target rotation using the currently configured motor velocity.
bool spinFor(
 directionType dir,
 double        rotation,
 rotationUnits units,
 bool          waitForCompletion = true );

5 — Spins for a target time at the velocity provided in the function call.
bool spinFor(
 double        time,
 timeUnits     units,
 double        velocity,
 velocityUnits units_v );

6 — Accepts a direction parameter and spins for a target time at the velocity provided in the function call.
bool spinFor(
 directionType dir,
 double        time,
 timeUnits     units,
 double        velocity,
 velocityUnits units_v );

7 — Spins for a target time using the currently configured motor velocity.
bool spinFor(
 double    time,
 timeUnits units );

8 — Accepts a direction parameter and spins for a target time using the currently configured motor velocity.
bool spinFor(
 directionType dir,
 double        time,
 timeUnits     units );

Parameters

Parameter	Type	Description
`dir`	`directionType`	The direction in which the motor or motor group spins: `forward` `reverse`
`rotation`	`double`	The target rotation amount.
`units`	`rotationUnits`	The unit used to represent `rotation`: `deg` / `degrees` — degrees `turns` / `rev` — revolutions
`time`	`double`	The amount of time that the motor or motor group will spin for.
`units`	`timeUnits`	The unit used to represent `time`: `seconds` / `sec` — seconds `msec` — milliseconds
`velocity`	`double`	The velocity value applied to the motor or motor group.
`units_v`	`velocityUnits`	The unit used to represent `velocity`: `percent` / `pct` — percent `rpm` — rotations per minute `dps` — degrees per second
`waitForCompletion`	`bool`	`true` (default) — The project waits until the movement completes before executing the next line of code. `false` — The movement starts and the project continues immediately.

Return Values

Returns a Boolean indicating whether the motor or motor group was able to reach the target value.

true — The motor or motor group reached the target value.
false — The motor or motor group was not able to reach the target value or waitForCompletion is set to false.

Notes

Executing another motor movement function (such as spin or stop) while spinFor is in progress will interrupt the current movement.
Because spinFor is target-based (uses a rotation or time parameter), functions such as isDone and isSpinning work with spinFor.

Examples

// Spin 1 turn fast, then 1 turn slow
Motor1.spinFor(forward, 1, turns, true);
Motor1.spinFor(reverse, 1, turns, 20, velocityUnits::pct, true);

spinToPosition#

Spins the motor or motor group to a specified position.

Available Functions

1 — Spins to an absolute target rotation at the velocity provided in the function call.
bool spinToPosition(
 double        rotation,
 rotationUnits units,
 double        velocity,
 velocityUnits units_v,
 bool          waitForCompletion = true );

2 — Spins to an absolute target rotation using the currently configured motor velocity.
bool spinToPosition(
 double        rotation,
 rotationUnits units,
 bool          waitForCompletion = true );

Parameters

Parameter	Type	Description
`rotation`	`double`	The absolute target rotation value.
`units`	`rotationUnits`	The unit used to represent `rotation`: `deg` / `degrees` — degrees `turns` / `rev` — revolutions
`velocity`	`double`	The velocity value applied to the motor or motor group.
`units_v`	`velocityUnits`	The unit used to represent `velocity`: `pct` — percent `rpm` — rotations per minute `dps` — degrees per second
`waitForCompletion`	`bool`	`true` (default) — The project waits until the motor or motor group reaches the target position. `false` — The movement starts and the project continues immediately.

Return Values

Returns a Boolean indicating whether the call was successful.

true — The motor or motor group begins the requested target-based movement.
false — The call fails (for example, due to a parameter error) or waitForCompletion is set to false.

Notes

Executing another motor movement function (such as spin or spinFor) while spinToPosition is in progress will interrupt the current movement.
Because spinToPosition is target-based (uses a rotation parameter), functions such as isDone and isSpinning work with spinToPosition.

Examples

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

stop#

Stops the motor or motor group from spinning.

Available Functions

1 — Stops the motor or motor group using the currently configured brake mode.
void stop();

2 — Stops the motor or motor group using the brake mode provided in the function call.
void stop( 
  brakeType mode );

Parameters

Parameter	Type	Description
`mode`	`brakeType`	The brake mode used when stopping the motor or motor group: `coast` — Motor or motor group coasts to a stop `brake` — Motor or motor group stops quickly using braking `hold` — Motor or motor group actively holds its position

Parameter

Type

Description

mode

brakeType

The brake mode used when stopping the motor or motor group:

coast — Motor or motor group coasts to a stop
brake — Motor or motor group stops quickly using braking
hold — Motor or motor group actively holds its position

Return Values

This function does not return a value.

Notes

Calling stop immediately stops any current motor movement.
If no brake mode is specified, the motor or motor group uses the currently configured brake mode.
stop interrupts any active target-based movement (such as spinFor or spinToPosition).

Examples

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

setPosition#

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

Available Functions

void setPosition(
    double        value,
    rotationUnits units );

Parameters

Parameter	Type	Description
`value`	`double`	The position value to assign to the motor’s or motor group’s encoder(s).
`units`	`rotationUnits`	The unit used to represent `value`: `deg` / `degrees` — degrees `turns` / `rev` — revolutions

Parameter

Type

Description

value

double

The position value to assign to the motor’s or motor group’s encoder(s).

units

rotationUnits

The unit used to represent value:

deg / degrees — degrees
turns / rev — revolutions

Return Values

This function does not return a value.

Notes

After calling setPosition, subsequent calls to spinToPosition will use the updated position as the reference.

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.

Available Functions

void setVelocity(
    double        velocity,
    velocityUnits units );

Parameters

Parameter	Type	Description
`velocity`	`double`	The velocity value to apply to the motor.
`units`	`velocityUnits`	The unit used to represent `velocity`: `percent` / `pct` — percent `rpm` — rotations per minute `dps` — degrees per second

Parameter

Type

Description

velocity

double

The velocity value to apply to the motor.

units

velocityUnits

The unit used to represent velocity:

percent / pct — percent
rpm — rotations per minute
dps — degrees per second

Return Values

This function does not return a value.

Notes

Any subsequent motor movement function (such as spin, spinFor, or spinToPosition) that does not explicitly specify a velocity will use this value.

Examples

// 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);

setStopping#

Sets how a motor or motor group behaves when it stops.

Available Functions

void setStopping( 
  brakeType mode );

Parameters

Parameter	Type	Description
`mode`	`brakeType`	The stopping mode applied when `stop` is called: `coast` — Motor(s) coasts to a stop `brake` — Motor(s) stops quickly using braking `hold` — Motor(s) actively holds its position

Parameter

Type

Description

mode

brakeType

The stopping mode applied when stop is called:

coast — Motor(s) coasts to a stop
brake — Motor(s) stops quickly using braking
hold — Motor(s) actively holds its position

Return Values

This function does not return a value.

Notes

Any subsequent call to stop without a specified brake mode will use this value.

setMaxTorque#

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

Available Functions

1 — Sets the maximum torque as a percentage of the motor’s or motor group’s rated torque.
void setMaxTorque(
 double       value,
 percentUnits units );

2 — Sets the maximum torque using physical torque units.
void setMaxTorque(
 double      value,
 torqueUnits units );

3 — Sets the maximum torque by limiting motor current.
void setMaxTorque(
 double       value,
 currentUnits units );

Parameters

Parameter	Type	Description
`value`	`double`	The maximum torque value to set.
`units`	`percentUnits`	Specifies torque as a percentage: `percent` / `pct` — percent
`units`	`torqueUnits`	Specifies torque in physical units such as: `Nm` — Newton-meters `InLb` — inch-pounds
`units`	`currentUnits`	Specifies torque by limiting motor current: `amp`

Return Values

This function does not return a value.

Notes

When using currentUnits, torque is limited by restricting the motor’s or motor group’s current draw.

setTimeout#

Sets a time limit for how long a motor command 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 command.

Available Functions

void setTimeout(
    int32_t   time,
    timeUnits units );

Parameters

Parameter	Type	Description
`time`	`int32_t`	The maximum amount of time the motor or motor group is allowed to attempt reaching a target position.
`units`	`timeUnits`	The unit used to represent `time`: `msec` — milliseconds `seconds` / `sec` — seconds

Parameter

Type

Description

time

int32_t

The maximum amount of time the motor or motor group is allowed to attempt reaching a target position.

units

timeUnits

The unit used to represent time:

msec — milliseconds
seconds / sec — seconds

Notes

The motor’s or motor group’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.
If the motor or motor group does not reach its target position before the timeout expires, it will stop automatically.
The timeout applies to functions that have a target value such as spinFor and spinToPosition.

Examples

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

isDone#

Returns a Boolean indication whether a motor or motor group is currently not spinning.

Available Functions

bool isDone();

Parameters

This function does not accept any parameters.

Return Values

Returns a Boolean indicating whether a target-based motor movement has completed:

true — The motor or motor group has finished its target-based movement.
false — The motor or motor group is still attempting to reach its target.

Notes

isDone only applies to target-based movement functions such as spinFor and spinToPosition.
It does not apply to continuous movement functions such as spin.

Examples

// Spin forward until the motor is done spinning
Motor1.spinFor(forward, 200, degrees, false);
while (true) {
  if (Motor1.isDone()) {
    Drivetrain.stop();
  } else {
    Drivetrain.drive(forward);
  }
}

isSpinning#

Returns a Boolean indicating whether a motor or motor group is currently spinning.

Available Functions

bool isSpinning();

Parameters

This function does not accept any parameters.

Return Values

Returns a Boolean indicating whether the motor or motor group is currently spinning:

true — The motor or motor group is actively spinning.
false — The motor or motor group is not spinning.

Notes

It works with both continuous movement functions (such as spin) and target-based functions (such as spinFor and spinToPosition).
This function reports motor activity, not whether a target has been reached. To check if a target-based movement has completed, use isDone.

Examples

// Spin forward until the motor is done spinning
Motor1.spinFor(forward, 200, degrees, false);
while (true) {
  if (Motor1.isSpinning()) {
    Drivetrain.drive(forward);
  } else {
    Drivetrain.stop();
  }
}

position#

Returns the current position of a motor or motor group.

Available Functions

double position( 
  rotationUnits units );

Parameters

Parameter	Type	Description
`units`	`rotationUnits`	The unit used to represent the motor or motor group position: `deg` / `degrees` — degrees `turns` / `rev` — revolutions

Parameter

Type

Description

units

rotationUnits

The unit used to represent the motor or motor group position:

deg / degrees — degrees
turns / rev — revolutions

Return Values

Returns a double representing the current encoder position of the motor or motor group in the specified units.

Notes

Calling setPosition changes the reference point for this value.
The returned value reflects the current encoder reading and does not indicate whether the motor or motor group is actively moving.
When called on a motor_group, this function returns the position of the first motor in the group.

Examples

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

velocity#

Returns the current velocity of a motor or motor group.

Available Functions

double velocity(
    velocityUnits units );

Parameters

Parameter	Type	Description
`units`	`velocityUnits`	The unit used to represent velocity: `percent` / `pct` — percent `rpm` — rotations per minute `dps` — degrees per second

Parameter

Type

Description

units

velocityUnits

The unit used to represent velocity:

percent / pct — percent
rpm — rotations per minute
dps — degrees per second

Return Values

Returns a double representing the motor’s or motor group’s current velocity in the specified units.

Notes

When called on a motor_group, this function returns the velocity of the first motor in the group.

current#

Returns the current of a motor or motor group.

Available Functions

1 — Returns the motor’s or motor group’s electrical current in amps.
double current( 
  currentUnits units = amp );

2 — Returns the motor’s or motor group’s electrical current as a percentage of maximum rated current.
double current( 
  percentUnits units );

Parameters

Parameter	Type	Description
`units`	`currentUnits`	The unit used to represent current: `amp` (default) — amperes
`units`	`percentUnits`	Represents the current as percentage of the motor’s maximum rated current: `percent` / `pct` — percent

Parameter

Type

Description

units

currentUnits

The unit used to represent current:

amp (default) — amperes

units

percentUnits

Represents the current as percentage of the motor’s maximum rated current:

percent / pct

Return Values

Returns a double representing the motor’s or motor group’s electrical current in the specified units.

Notes

When called on a motor_group, this function returns the sum electrical current for all motors in the group.

power#

Returns the electrical power supplied to the motor or motor group.

Available Functions

double power( 
  powerUnits units = watt );

Parameters

Parameter	Type	Description
`units`	`powerUnits`	The unit used to represent the motor power: `watt` (default) — watts

Parameter

Type

Description

units

powerUnits

The unit used to represent the motor power:

watt (default) — watts

Return Values

Returns a double representing the motor’s or motor group’s electrical power in watts.

Notes

When called on a motor_group, this function returns the electrical power of the first motor in the group.

torque#

Returns the mechanical output torque of the motor or motor group.

Available Functions

double torque( 
  torqueUnits units = Nm );

Parameters

Parameter	Type	Description
`units`	`torqueUnits`	The unit used to represent the motor torque: `Nm` (default) — Newton-meters `InLb` — inch-pounds

Parameter

Type

Description

units

torqueUnits

The unit used to represent the motor torque:

Nm (default) — Newton-meters
InLb — inch-pounds

Return Values

Returns a double representing the motor’s or motor group’s mechanical output torque in the specified units.

Notes

When called on a motor_group, this function returns the mechanical output torque of the first motor in the group.

efficiency#

Returns the efficiency of the motor or motor group.

Available Functions

double efficiency( 
  percentUnits units = percent );

Parameter	Type	Description
`units`	`percentUnits`	The unit used to represent motor efficiency: `percent` / `percentUnits::pct` (default) — percent

Parameter

Type

Description

units

percentUnits

The unit used to represent motor efficiency:

percent / percentUnits::pct (default) — percent

Return Values

Returns a double representing the motor’s or motor group’s efficiency as a percentage.

Notes

When called on a motor_group, this function returns the efficiency of the first motor in the group.

temperature#

Returns the temperature of the motor or motor group.

Available Functions

1 — Returns motor or motor group temperature as a percentage of maximum operating temperature.
double temperature( 
  percentUnits units = percent );

2 — Returns motor or motor group temperature in physical temperature units.
double temperature( 
  temperatureUnits units );

Parameters

Parameter	Type	Description
`units`	`percentUnits`	The unit used to represent motor or motor group temperature as a percentage: `percent` / `percentUnits::pct` (default) — percent
`units`	`temperatureUnits`	The unit used to represent motor or motor group temperature in degrees: `celsius` — degrees Celsius `fahrenheit` — degrees Fahrenheit

Parameter

Type

Description

units

percentUnits

The unit used to represent motor or motor group temperature as a percentage:

percent / percentUnits::pct (default) — percent

units

temperatureUnits

The unit used to represent motor or motor group temperature in degrees:

celsius — degrees Celsius
fahrenheit — degrees Fahrenheit

Return Values

Returns a double representing the motor’s or motor group’s temperature in the specified units.

Notes

The operating temperature range for the motor is approximately 20°C (68°F) to 70°C (158°F).
When called on a motor_group, this function returns the temperature of the first motor in the group.

voltage#

Returns the electrical voltage supplied to the motor or motor group.

Available Functions

double voltage( 
  voltageUnits units = volt );

Parameters

Parameter	Type	Description
`units`	`voltageUnits`	The unit to represent the voltage: `volt` (default) `voltageUnits::mV` — millivolts

Parameter

Type

Description

units

voltageUnits

The unit to represent the voltage:

volt (default)
voltageUnits::mV — millivolts

Return Values

Returns a double representing the motor’s or motor group’s electrical voltage in the specified units.

Notes

When called on a motor_group, this function returns the electrical voltage of the first motor in the group.

direction#

Returns the direction that the motor or motor group is currently spinning.

Available Functions

directionType direction();

Parameters

This function does not take any parameters.

Return Values

Returns a directionType indicating the motor’s or motor group’s current direction:

forward — The motor or motor group is spinning forward / in a positive direction.
reverse — The motor is spinning or motor group in reverse / in a negative direction.

installed#

Returns whether the motor or motor group is connected to the V5 Brain.

Available Functions

bool installed();

Parameters

This function does not take any parameters.

Return Values

Returns a bool indicating if the motor or motor group is connected.

true — The motor or motor group is connected.
false — The motor or motor group is not connected.

count#

Returns the number of motors currently included in the motor group.

Available Functions

int32_t count();

Parameters

This function does not take any parameters.

Return Values

Returns an int32_t representing the total number of motors in the motor group.