Drivetrain#

Introduction#

The drivetrain class controls how a robot drives and turns. A drivetrain is made of motors and wheels that work together to move the robot.

A drivetrain does not use an Inertial Sensor or Gyro Sensor for heading-based or rotation-based turns. It can drive forward or reverse and turn left or right, but it cannot turn to a specific heading or rotation. For heading-based and rotation-based turns, use the smartdrive class.

Derived Classes#

The drivetrain class serves as a base class for the following derived classes:

smartdrive — This class adds Inertial Sensor or Gyro Sensor support to enable heading-based and rotation-based turns.

Class Constructors#

1 — Creates a drivetrain using existing motor_group objects for the left (&l) and right (&r) sides.

drivetrain(
    motor_group      &l,
    motor_group      &r,
    double           wheelTravel = 320,
    double           trackWidth = 320,
    double           wheelBase = 130,
    distanceUnits    unit = mm,
    double           externalGearRatio = 1.0 );

2 — Creates a drivetrain using existing motor objects for the left (&l) and right (&r) sides.

drivetrain(
    motor            &l,
    motor            &r,
    double           wheelTravel = 320,
    double           trackWidth = 320,
    double           wheelBase = 130,
    distanceUnits    unit = mm,
    double           externalGearRatio = 1.0 );

Class Destructor#

Destroys the drivetrain object and releases associated resources.

virtual ~drivetrain();

Parameters#

Parameter	Type	Description
`&l` / `&r`	`motor_group` / `motor`	The left and right motors or motor groups. Both parameters must use the same type: either two `motor_group` objects or two `motor` objects.
`wheelTravel`	`double`	The circumference of the drivetrain wheels. The default is `320`.
`trackWidth`	`double`	The distance between the left and right wheels. The default is `320`.
`wheelBase`	`double`	The distance between the front and back wheels. The default is `130`.
`unit`	`distanceUnits`	The unit for `wheelTravel`, `trackWidth`, and `wheelBase`: `mm` (millimeters, default) or `inches`.
`externalGearRatio`	`double`	The gear ratio used to adjust drive distances if gears are used. The default is `1.0`.

Example#

// Create the left and right motor objects
motor leftMotor = motor(PORT1, false);
motor rightMotor = motor(PORT9, true);

// Create the drivetrain object
drivetrain myDrivetrain = drivetrain(
    leftMotor,  // left motor object
    rightMotor, // right motor object
    259.34,     // wheelTravel
    320,        // trackWidth
    40,         // wheelBase
    mm,         // unit
    1.0 );      // externalGearRatio

Member Functions#

There are many ways to code the drivetrain. Below is a list of all drivetrain member functions:

Actions — Move and turn the robot.

drive — Moves the robot forward or reverse forever.
driveFor — Moves the robot forward or reverse for a specific distance.
turn — Turns the robot left or right forever.
turnFor — Turns the robot left or right for a specific number of degrees.
stop — Stops the robot’s movement.

Mutators — Adjust drivetrain settings.

setDriveVelocity — Tells the robot how fast to drive.
setTurnVelocity — Tells the robot how fast to turn.
setStopping — Tells how the robot will stop moving: by braking, coasting, or holding.
setTimeout — Sets how many seconds the robot will try to finish a movement.

Getters — Check movement status.

isDone — Returns whether the robot is finished moving, as a Boolean value.
isMoving — Returns whether the robot is moving, as a Boolean value.
velocity — Returns how fast the robot is driving.
current — Returns how much electrical current the drivetrain is using.
power — Returns how quickly the drivetrain is using energy.
torque — Returns how much torque the drivetrain is using.
efficiency — Returns how efficiently the drivetrain is using power.
temperature — Returns how warm the drivetrain is.
voltage — Returns the electrical voltage supplied to the drivetrain.

Before calling any drivetrain member functions, a drivetrain object must be created, as shown below:

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

// Create the left and right motor objects
motor leftMotor = motor(PORT1, false);
motor rightMotor = motor(PORT9, true);

// Create the drivetrain object
drivetrain myDrivetrain = drivetrain(
    leftMotor,  // left motor object
    rightMotor, // right motor object
    259.34,     // wheelTravel
    320,        // trackWidth
    40,         // wheelBase
    mm,         // unit
    1.0 );      // externalGearRatio

Actions#

drive#

drive moves the robot forward or reverse forever. The robot will continue to move until it is given another action, like turning or stopping. For RPM or DPS, the limit is changed by the gear ratio of the drivetrain.

Available Functions

1 — Drives using the currently configured drive velocity.
void drive(
    directionType dir );

2 — Drives at the specified velocity.

void drive(
    directionType dir,
    double        velocity,
    velocityUnits units );

Parameters

Parameter	Type	Description
`dir`	`directionType`	The direction the robot moves: `forward` or `reverse`.
`velocity`	`double`	The velocity to drive with from 0% to 100% when using `velocityUnits::pct`, from 0 to 600 rpm when using `rpm`, or from 0 to 3600 degrees per second when using `dps`. If no velocity is provided, the robot drives at the current drive velocity.
`units`	`velocityUnits`	The velocity unit: `velocityUnits::pct` (percent), `rpm` (rotations per minute), or `dps` (degrees per second).

Return Values

This function does not return a value.

Notes

drive is non-waiting; the project will continue executing the next line of code immediately after the call.
The drivetrain will continue moving until stop is called or another drivetrain movement function (such as driveFor or turn) is executed.
Functions such as isDone and isMoving are not applicable to drive, since it does not use target-based movement (doesn’t have a distance parameter).

Examples

// Drive forward and back
myDrivetrain.drive(forward);
wait(2, seconds);
myDrivetrain.drive(reverse, 25, rpm);
wait(2, seconds);
myDrivetrain.stop();

driveFor#

driveFor moves the robot forward or reverse for a specific distance. The project will wait until the robot is done moving before the next line of code runs by default. For RPM or DPS, the limit is changed by the gear ratio of the drivetrain.

Available Functions

1 — Drives in the specified direction for a distance using the currently configured drive velocity.
bool driveFor(
    directionType dir,
    double        distance,
    distanceUnits units,
    bool          waitForCompletion = true );

2 — Drives in a direction dependent on the distance using the currently configured drive velocity.
bool driveFor(
    double        distance,
    distanceUnits units,
    bool          waitForCompletion = true );

3 — Drives in a direction dependent on the distance at the specified velocity.
bool driveFor(
    double        distance,
    distanceUnits units,
    double        velocity,
    velocityUnits units_v,
    bool          waitForCompletion = true );

4 — Drives in the specified direction for a distance at the specified velocity.

bool driveFor(
    directionType dir,
    double        distance,
    distanceUnits units,
    double        velocity,
    velocityUnits units_v,
    bool          waitForCompletion = true );

Parameters

Parameter	Type	Description
`dir`	`directionType`	The direction the robot moves: `forward` or `reverse`.
`distance`	`double`	The distance the robot drives.
`units`	`distanceUnits`	The distance unit: `mm` (millimeters), `inches`, or `cm` (centimeters).
`velocity`	`double`	The velocity to drive with from 0% to 100% when using `velocityUnits::pct`, from 0 to 600 rpm when using `rpm`, or from 0 to 3600 degrees per second when using `dps`. If no velocity is provided, the robot drives at the current drive velocity.
`units_v`	`velocityUnits`	The velocity unit: `velocityUnits::pct` (percent), `rpm` (rotations per minute), or `dps` (degrees per second).
`waitForCompletion`	`bool`	`true` (default) makes the project wait until the robot is done moving before the next line of code runs. `false` makes the next line of code run right away.

Return Values

Returns whether the robot reached the target distance, as a Boolean value.

true — The robot reached the target distance.
false — The robot did not finish the movement, or the function returned before the movement completed because waitForCompletion was set to false.

Notes

Executing another drivetrain movement function (such as drive or turnFor) while driveFor is in progress will interrupt the current movement.
Because driveFor is target-based (uses a distance parameter), functions such as isDone and isMoving work with driveFor.

Examples

// Drive 200 mm, then back 200 mm
myDrivetrain.driveFor(forward, 200, mm);
myDrivetrain.driveFor(reverse, 200, mm);

turn#

turn turns the robot left or right forever. The robot will continue to turn until it is given another action, like driving or stopping. For RPM or DPS, the limit is changed by the gear ratio of the drivetrain.

Available Functions

1 — Turns using the currently configured turn velocity.
void turn(
    turnType dir );

2 — Turns at the specified velocity.

void turn(
    turnType     dir,
    double       velocity,
    velocityUnits units );

Parameters

Parameter	Type	Description
`dir`	`turnType`	The direction the robot turns: `left` or `right`.
`velocity`	`double`	The velocity to turn with from 0% to 100% when using `velocityUnits::pct`, from 0 to 600 rpm when using `rpm`, or from 0 to 3600 degrees per second when using `dps`. If no velocity is provided, the robot turns at the current turn velocity.
`units`	`velocityUnits`	The velocity unit: `velocityUnits::pct` (percent), `rpm` (rotations per minute), or `dps` (degrees per second).

Return Values This function does not return a value. Notes

turn is non-waiting; the project will continue executing the next line of code immediately after the call.
The drivetrain will continue turning until stop is called or another drivetrain movement function (such as turnFor or drive) is executed.
Functions such as isDone and isMoving are not applicable to turn, since it does not use target-based movement (doesn’t have an angle parameter).

Examples

// Turn right, then left, then stop
myDrivetrain.turn(right);
wait(2, seconds);
myDrivetrain.turn(left);
wait(2, seconds);
myDrivetrain.stop();

turnFor#

turnFor turns the robot left or right for a specific number of degrees. The turn is relative to the current position of the robot. The project will wait until the robot is done turning before the next line of code runs by default. For RPM or DPS, the limit is changed by the gear ratio of the drivetrain.

Available Functions

1 — Turns for the specified angle using the currently configured turn velocity.
bool turnFor(
    double        angle,
    rotationUnits units,
    bool          waitForCompletion = true );

2 — Turns in the specified direction for an angle using the currently configured turn velocity.
bool turnFor(
    turnType      dir,
    double        angle,
    rotationUnits units,
    bool          waitForCompletion = true );

3 — Turns for the specified angle at the specified velocity.

bool turnFor(
    double        angle,
    rotationUnits units,
    double        velocity,
    velocityUnits units_v,
    bool          waitForCompletion = true );

4 — Turns in the specified direction for an angle at the specified velocity.

bool turnFor(
    turnType      dir,
    double        angle,
    rotationUnits units,
    double        velocity,
    velocityUnits units_v,
    bool          waitForCompletion = true );

Parameters

Parameter	Type	Description
`dir`	`turnType`	The direction the robot turns: `left` or `right`.
`angle`	`double`	The angle the robot turns.
`units`	`rotationUnits`	The turn unit: `deg` (degrees), `rev` (revolutions), or `raw` (raw units). One revolution is equal to 360 degrees.
`velocity`	`double`	The velocity to turn with from 0% to 100% when using `velocityUnits::pct`, from 0 to 600 rpm when using `rpm`, or from 0 to 3600 degrees per second when using `dps`. If no velocity is provided, the robot turns at the current turn velocity.
`units_v`	`velocityUnits`	The velocity unit: `velocityUnits::pct` (percent), `rpm` (rotations per minute), or `dps` (degrees per second).
`waitForCompletion`	`bool`	`true` (default) makes the project wait until the robot is done turning before the next line of code runs. `false` makes the next line of code run right away.

Return Values

Returns whether the robot reached the target angle, as a Boolean value.

true — The robot reached the target angle.
false — The robot did not finish the turn, or the function returned before the turn completed because waitForCompletion was set to false.

Notes

Executing another drivetrain movement function (such as turn or drive) while turnFor is in progress will interrupt the current movement.
Because turnFor is target-based (uses an angle parameter), functions such as isDone and isMoving work with turnFor.

Examples

// Turn right then left
myDrivetrain.turnFor(right, 90, degrees);
wait(1, seconds);
myDrivetrain.turnFor(left, 90, degrees);

stop#

stop stops the robot’s movement. If a stopping mode is provided, it controls how the robot stops for this function call.

Available Functions

1 — Stops the drivetrain using the currently configured stopping mode.
void stop();

2 — Stops the drivetrain using the specified brake mode.
void stop(
    brakeType mode );

Parameters

Parameter	Type	Description
`mode`	`brakeType`	How the robot will stop: `brake` — Stops immediately. `coast` — Slows to a stop. `hold` — Stops immediately and holds the wheels’ position.

Parameter

Type

Description

mode

brakeType

How the robot will stop:

brake — Stops immediately.
coast — Slows to a stop.
hold — Stops immediately and holds the wheels’ position.

Return Values

This function does not return a value.

Examples

// Drive forward, then coast to a stop
myDrivetrain.setDriveVelocity(100, percent);
myDrivetrain.drive(forward);
wait(2, seconds);
myDrivetrain.stop(coast);

Mutators#

setDriveVelocity#

setDriveVelocity tells the robot how fast to drive. A higher percentage makes the robot drive faster and a lower percentage makes the robot drive slower. For RPM or DPS, the limit is changed by the gear ratio of the drivetrain.

Every project begins with the robot driving at 50% velocity by default.

Note: A higher velocity makes the robot drive faster, but it may be less precise. A lower velocity makes the robot drive slower, but it can be more precise.

Available Functions

void  setDriveVelocity(
  double velocity,
  velocityUnits units );

Parameters

Parameter	Type	Description
`velocity`	`double`	The velocity to drive with from 0% to 100% when using `velocityUnits::pct`, from 0 to 600 rpm when using `rpm`, or from 0 to 3600 degrees per second when using `dps`.
`units`	`velocityUnits`	The velocity unit: `velocityUnits::pct` (percent), `rpm` (rotations per minute), or `dps` (degrees per second).

Return Values

This function does not return a value.

Notes

The drive velocity applies to all subsequent drivetrain movement functions (such as drive and driveFor) unless a specific velocity is provided in the function call.

Examples

// Drive forward, then coast to a stop
myDrivetrain.setDriveVelocity(100, percent);
myDrivetrain.drive(forward);
wait(2, seconds);
myDrivetrain.stop(coast);

setTurnVelocity#

setTurnVelocity tells the robot how fast to turn. A higher percentage makes the robot turn faster and a lower percentage makes the robot turn slower. For RPM or DPS, the limit is changed by the gear ratio of the drivetrain.

Every project begins with the robot turning at 50% velocity by default.

Note: A higher velocity makes the robot turn faster, but it may be less precise. A lower velocity makes the robot turn slower, but it can be more precise.

Available Functions

void  setTurnVelocity(
  double velocity,
  velocityUnits units );

Parameters

Parameter	Type	Description
`velocity`	`double`	The velocity to turn with from 0% to 100% when using `velocityUnits::pct`, from 0 to 600 rpm when using `rpm`, or from 0 to 3600 degrees per second when using `dps`.
`units`	`velocityUnits`	The velocity unit: `percent` or `pct` (percent), `rpm` (rotations per minute), or `dps` (degrees per second).

Return Values

This function does not return a value.

Notes

The turn velocity applies to all subsequent drivetrain turning functions (such as turn and turnFor) unless a specific velocity is provided in the function call.

Examples

// Try default, slow, then fast
myDrivetrain.turnFor(right, 360, degrees);
wait(1, seconds);
myDrivetrain.setTurnVelocity(20, percent);
myDrivetrain.turnFor(right, 360, degrees);
wait(1, seconds);
myDrivetrain.setTurnVelocity(100, percent);
myDrivetrain.turnFor(right, 360, degrees);

setStopping#

setStopping sets how the robot will stop moving: by braking, coasting, or holding.

Available Functions

void setStopping(
  brakeType mode );

Parameters

Parameter	Type	Description
`mode`	`brakeType`	How the robot will stop: `brake` — Stops immediately. `coast` — Slows to a stop. `hold` — Stops immediately and holds the wheels’ position.

Parameter

Type

Description

mode

brakeType

How the robot will stop:

brake — Stops immediately.
coast — Slows to a stop.
hold — Stops immediately and holds the wheels’ position.

Return Values

This function does not return a value.

Notes

The stopping mode applies to all subsequent stop calls unless a specific stopping mode is provided in the function call.

setTimeout#

setTimeout sets how many seconds the robot will try to finish a movement. If the robot cannot finish in that time, it will stop trying and move on to the next line of code. This keeps the robot from getting stuck on a movement.

Available Functions

void  setTimeout(
  int32_t time,
  timeUnits units );

Parameters

Parameter	Type	Description
`time`	`int32_t`	The amount of time the robot can try to finish a movement. This should be a positive whole number.
`units`	`timeUnits`	The unit of time: `sec` (seconds) or `msec` (milliseconds).

Return Values

This function does not return a value.

Notes

The timeout only applies to target-based drivetrain movement functions (such as driveFor and turnFor).

Examples

// Start turning if driving takes too long
myDrivetrain.setTimeout(1, seconds);
myDrivetrain.driveFor(forward, 25, inches);
myDrivetrain.turnFor(right, 90, degrees);

Getters#

isDone#

isDone returns whether the robot is finished moving, as a Boolean value. This can be used to control the timing of other behaviors based on the robot’s movement.

Available Functions

bool isDone( void );

Parameters

This function does not accept any parameters.

Return Values

true — The robot is finished moving.
false — The robot is still moving.

Notes

isDone is compatible with target-based drivetrain movements (functions that move to a target, such as driveFor and turnFor).
isDone is not compatible with functions such as drive and turn, since they do not use target-based movement.

isMoving#

isMoving returns whether the robot is moving, as a Boolean value. This can be used to control the timing of other behaviors based on the robot’s movement.

Available Functions

virtual bool isMoving( void );

Parameters

This function does not accept any parameters.

Return Values

true — The robot is moving.
false — The robot is not moving.

Notes

isMoving is compatible with target-based drivetrain movements (functions that move to a target, such as driveFor and turnFor).
isMoving is not compatible with functions such as drive and turn, since they do not use target-based movement.

velocity#

velocity returns how fast the robot is driving.

A positive value means the robot is driving forward. A negative value means the robot is driving in reverse.

Available Functions

double velocity(
  velocityUnits units );

Parameters

Parameter	Type	Description
`units`	`velocityUnits`	The velocity unit: `percent` or `pct` (percent), `rpm` (rotations per minute), or `dps` (degrees per second).

Return Values

Returns the drivetrain velocity as a double in the selected unit.

Examples

// Show velocity before and during motion
Brain.Screen.print("Resting: %f", myDrivetrain.velocity(percent));
myDrivetrain.drive(forward, 100, velocityUnits::pct);
wait(1, seconds);
Brain.Screen.newLine();
Brain.Screen.print("Moving: %f", myDrivetrain.velocity(percent));
myDrivetrain.stop();

current#

current returns how much electrical current the drivetrain is using. Current is the amount of electricity flowing through the drivetrain. It can be returned in amps (amperes) or as a percentage, depending on the unit.

A higher current value means the drivetrain is using more electrical current. This can happen when the robot is pushing against an object or trying to move when it is stuck.

This can be used to check if the drivetrain is struggling during a movement. If current stays high, the drivetrain may get warmer or use power less efficiently.

Available Functions

1 — Returns the drivetrain’s electrical current in amperes.
double current(
    currentUnits units = currentUnits::amp );

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

Parameters

Parameter	Type	Description
`units`	`currentUnits`	The unit to return current in: `amp` (amps, default).
`units`	`percentUnits`	The unit to return current in: `percent` or `pct`.

Return Values

Returns the drivetrain current as a double in the selected unit.

power#

power returns how much power the drivetrain is using, measured in watts. Power shows how quickly the drivetrain is using energy.

A higher power value means the drivetrain is using energy faster. This can happen when the robot is pushing against an object or trying to move when it is stuck.

This can be used to compare movements or check if the drivetrain is struggling. If power stays high, the drivetrain may get warmer or use energy less efficiently.

Available Functions

double power(
  powerUnits units = powerUnits::watt );

Parameters

Parameter	Type	Description
`units`	`powerUnits`	The power unit: `watt` (watts, default).

Return Values

Returns drivetrain power as a double in watts.

torque#

Torque shows how hard the drivetrain can push or pull while the wheels spin.

torque returns how much torque the drivetrain is using, measured in Newton-meters (Nm) or inch-pounds (InLb).

A higher torque value means the drivetrain is pushing or pulling harder. This can happen when the robot is pushing against an object or trying to move when it is stuck.

This can be used to check if the drivetrain is struggling or to compare how much push different movements need.

Available Functions

double torque(
  torqueUnits units = torqueUnits::nm );

Parameters

Parameter	Type	Description
`units`	`torqueUnits`	The unit to return torque in: `Nm` (newton meters, default) or `InLb` (inch pounds).

Return Values

Returns drivetrain torque as a double in the selected unit.

efficiency#

efficiency returns how efficiently the drivetrain is using power, as a percentage from 0% to 100%.

Efficiency shows how much of the drivetrain’s power is being used for movement. A higher efficiency value means more of the drivetrain’s power is being used to move. A lower efficiency value can happen when the drivetrain is working hard but not moving much, like when the robot is stuck or pushing against an object.

This can be used to compare movements or check if the drivetrain is wasting power instead of using it for movement.

Available Functions

double efficiency(
  percentUnits units = percentUnits::pct );

Parameters

Parameter	Type	Description
`units`	`percentUnits`	The unit to return efficiency in: `percent` or `pct` (default).

Return Values

Returns drivetrain efficiency as a double in the selected unit.

temperature#

temperature returns the average temperature of the drivetrain as a percentage from 0% to 100%.

Temperature shows how warm the drivetrain motors are. A higher temperature means the motors are getting warmer while they work. The motors should stay below 55°C to keep working at full performance.

If the motors get too hot, they will lower their maximum current to protect themselves. At 70°C, the motors will stop running until they cool down.

This can be used to check if the drivetrain is getting too hot during repeated movements, long runs, or when it is pushing against an object.

Available Functions

double temperature(
  percentUnits units );

Parameters

Parameter	Type	Description
`units`	`percentUnits`	The unit to return temperature in: `percent` or `pct`.

Return Values

Returns the average drivetrain temperature as a double in the selected unit.

Notes

A returned value of 50% indicates that the average motor temperature is approximately 45°C (113°F).
The typical operating temperature range for the drivetrain is approximately 20°C (68°F) to 70°C (158°F).

voltage#

voltage returns the electrical voltage supplied to the drivetrain.

Voltage is the electrical pressure supplied to the drivetrain motors. This can be used with current and power values to understand how the drivetrain is using electrical energy.

Available Functions

double  voltage(
  voltageUnits units = voltageUnits::volt );

Parameters

Parameter	Type	Description
`units`	`voltageUnits`	The unit to return voltage in: `volt` (volts, default) or `voltageUnits::mV` (millivolts).

Return Values

Returns drivetrain voltage as a double in the selected unit.