Drivetrain#

Introduction#

The drivetrain class provides control over a drivetrain using separate left and right motors or motor groups.

Derived Classes#

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

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

Class Constructors#

drivetrain(
    motor_group      &l,
    motor_group      &r,
    double           wheelTravel = 320,
    double           trackWidth = 320,
    double           wheelBase = 130,
    distanceUnits    unit = mm,
    double           externalGearRatio = 1.0
    );
 This constructor constructs a drivetrain using references to existing motor_group instances 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
    );
 This constructor constructs a drivetrain using references to existing motor instances for the left (&l) and right (&r) sides.

Class Destructor#

Destroys the drivetrain object and releases associated resources.

virtual ~drivetrain();

参数#

Parameter

Type

Description

&l / &r

motor_group / motor

References to existing motor or motor_group instances. Both parameters must be of the same type: either two motor_group instances or two motor instances.
The &l parameter refers to the left motor or motor group, and &r refers to the right motor or motor group.

wheelTravel

double

The wheel’s circumference. Default is 320, expressed in millimeters by default or in the units specified by the unit parameter.

trackWidth

double

The distance between the left and right wheels. Default is 320, expressed in millimeters by default or in the units specified by the unit parameter.

wheelBase

double

The width of the wheel base. Default is 130, expressed in millimeters by default or in the units specified by the unit parameter.

unit

distanceUnits

Units for the wheelTravel, trackWidth, and wheelBase parameters:

  • mm (default) — millimeters
  • inches

externalGearRatio

double

The gear ration compensation factor. Default is 1.0.

例子#

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

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

Member Functions#

The drivetrain class includes the following member functions:

  • drive — Drives the robot continuously forward or in reverse using the current drive velocity.

  • driveFor — Drives the robot forward or in reverse for a set distance.

  • turn — Rotates the robot continuously left or right using the current turn velocity.

  • turnFor — Rotates the robot left or right for a specified angle.

  • stop — Stops the drivetrain using the configured stopping mode.

  • setDriveVelocity — Sets the default drive velocity used by drive methods.

  • setTurnVelocity — Sets the default turn velocity used by turn methods.

  • setStopping — Sets how the drivetrain behaves when it stops.

  • setTimeout — Sets how long drive and turn methods try to reach their target before timing out.

  • isDone — Returns whether a drivetrain is not currently moving.

  • isMoving — Returns whether a drivetrain is currently moving.

  • velocity — Returns the drivetrain’s current velocity.

  • current — Returns the drivetrain’s current draw.

  • power — Returns the drivetrain’s power usage.

  • torque — Returns the drivetrain’s torque.

  • efficiency — Returns the drivetrain’s efficiency.

  • temperature — Returns the drivetrain motors’ temperature.

  • voltage — Returns the voltage currently applied to the drivetrain.

Before calling any drivetrain member functions, a drivetrain instance 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 instances
motor leftMotor = motor(PORT1, false);
motor rightMotor = motor(PORT9, true);

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

drive#

Moves the drivetrain in a specified direction continuously.

Available Functions
1 
void 	drive( 
  directionType dir  );
2 
void 	drive( 
  directionType  dir, 
  double         velocity, 
  velocityUnits  units  );
  • Uses the velocity provided in the function call
Parameters

Parameter

Type

Description

dir

directionType

The direction in which the robot drives:

  • forward
  • reverse

velocity

double

The velocity at which the drivetrain will move as a double. If the velocity is not specified or previously set, the default velocity is 50%.

units

velocityUnits

The unit to represent the velocity:

  • velocityUnits::pct — percent
  • rpm — rotations per minute
  • 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#

Moves the drivetrain in a specified direction for a specified distance in the specified units.

Available Functions
1 
virtual bool driveFor(
  directionType   dir,
  double          distance,
  distanceUnits   units,
  bool            waitForCompletion = true
);
2 
virtual bool driveFor(
  double          distance,
  distanceUnits   units,
  bool            waitForCompletion = true
);
3 
virtual bool driveFor(
  double          distance,
  distanceUnits   units,
  double          velocity,
  velocityUnits   units_v,
  bool            waitForCompletion = true
);
  • Uses the velocity provided in the function call
4 
virtual bool driveFor(
  directionType   dir,
  distanceUnits   units,
  double          velocity,
  velocityUnits   units_v,
  bool            waitForCompletion = true
);
  • Accepts a direction parameter
  • Uses the velocity provided in the function call

Parameters

Parameter

Type

Description

dir

directionType

The direction in which the robot drives:

  • forward
  • reverse

distance

double

The distance the drivetrain will move.

units

distanceUnits

The units representing the distance:

  • mm — millimeters
  • inches — inches
  • cm — centimeters

velocity

double

The velocity at which the drivetrain will move as a double. If the velocity is not specified or previously set, the default velocity is 50%.

units_v

velocityUnits

The unit to represent the velocity:

  • velocityUnits::pct — percent
  • rpm — rotations per minute
  • dps — degrees per second

waitForCompletion

bool

Optional.

  • true (default) — The project waits until the function finishes before executing the next line of code.
  • false — The project starts the action and moves on to the next line of code right away, without waiting for the function to finish.
Return Values

Returns a Boolean indicating whether the drivetrain reached the target distance parameter value:

  • true — The drivetrain successfully reaches the target distance parameter value.
  • false — The drivetrain does not complete the movement or if the waitForCompletion parameter is 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#

Rotates the drivetrain in a specified direction continuously.

Available Functions
1 
void  turn( 
  turnType dir 
);
2 
void  turn( 
  turnType dir, 
  double velocity, 
  velocityUnits units 
);
  • Uses the velocity provided in the function call
Parameters

Parameter

Type

Description

dir

turnType

The direction in which the robot turns:

  • left
  • right

velocity

double

The velocity at which the drivetrain will turn as a double. If the velocity is not specified or previously set, the default velocity is 50%.

units

velocityUnits

The unit to represent the velocity:

  • velocityUnits::pct — percent
  • rpm — rotations per minute
  • dps — degrees per second
Return Value 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#

Rotates the drivetrain in a specified direction for a specified angle in the specified units.

Available Functions
1 
virtual bool turnFor( 
  double angle, 
  rotationUnits units, 
  bool waitForCompletion=true 
);
2 
virtual bool 	turnFor( 
  turnType dir, 
  double angle, 
  rotationUnits units, 
  bool waitForCompletion=true 
);
3 
virtual bool 	turnFor( 
  double angle, 
  rotationUnits units, 
  double velocity, 
  velocityUnits units_v, 
  bool waitForCompletion=true 
);
  • Uses the velocity provided in the function call
4 
virtual bool 	turnFor( 
  turnType dir, 
  double angle, 
  rotationUnits units, 
  double velocity, 
  velocityUnits units_v, 
  bool waitForCompletion=true 
);
  • Accepts a direction parameter
  • Uses the velocity provided in the function call
Parameters

Parameter

Type

Description

dir

turnType

The direction in which the robot turns:

  • left
  • right

angle

double

The angle the drivetrain will turn.

units

rotationUnits

The units representing the angle:

  • deg — degrees
  • rev — revolutions
  • raw — raw units

velocity

double

The velocity at which the drivetrain will turn as a double. If the velocity is not specified or previously set, the default velocity is 50%.

units_v

velocityUnits

The unit to represent the velocity:

  • velocityUnits::pct — percent
  • rpm — rotations per minute
  • dps — degrees per second

waitForCompletion

bool

Optional.

  • true (default) — The project waits until the function finishes before executing the next line of code.
  • false — The project starts the action and moves on to the next line of code right away, without waiting for the function to finish.
Return Values

Returns a Boolean indicating whether the drivetrain reached the target angle parameter value:

  • true — The drivetrain successfully reaches the target angle parameter value.
  • false — The drivetrain does not complete the movement or if the waitForCompletion parameter is 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#

Stops the drivetrain.

Available Functions
1 
void  stop();
  • Stops the drivetrain using the currently configured stop mode
2 
void  stop( 
  brakeType mode );
  • Stops the drivetrain using a specific brake type[]
Parameters

Parameter

Type

Description

mode

brakeType

The brake type to use when stopping the drivetrain:

  • brake — Stops immediately.
  • coast — Slows gradually to a stop.
  • hold — Stops and resists movement using motor feedback.
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);

setDriveVelocity#

Sets the default drive velocity for the drivetrain.

Available Functions 
void  setDriveVelocity( 
  double velocity, 
  velocityUnits units );
Parameters

Parameter

Type

Description

velocity

double

The velocity at which the drivetrain will move.

units

velocityUnits

The unit to represent the velocity:

  • velocityUnits::pct — percent
  • rpm — rotations per minute
  • 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#

Sets the default turn velocity for the drivetrain.

Available Functions 
void  setTurnVelocity( 
  double velocity, 
  velocityUnits units 
);
Parameters

Parameter

Type

Description

velocity

double

The velocity at which the drivetrain will turn.

units

velocityUnits

The units representing the velocity:

  • rpm — rotations per minute
  • dps — degrees per second
  • percent / pct — percent
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#

Sets the default stopping mode for the drivetrain.

Available Functions 
void setStopping( brakeType mode );
Parameters

Parameter

Type

Description

mode

brakeType

The brake type to use when stopping the drivetrain:

  • brake — Stops immediately.
  • coast — Slows gradually to a stop.
  • hold — Stops and resists movement using motor feedback.
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#

Sets a time limit for how long the drivetrain will attempt to reach a target distance or angle. If the drivetrain cannot complete the movement within the set time, it will stop automatically and continue with the next function.

Available Functions 
void  setTimeout( 
  int32_t time, 
  timeUnits units );
Parameters

Parameter

Type

Description

time

int32_t

The maximum number of seconds a drivetrain function will run before stopping and moving to the next function.

units

timeUnits

The unit that represents the time:

  • sec — seconds
  • 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);

isDone#

Returns a Boolean indicating whether no target-based drivetrain movement (such as driveFor or turnFor) is currently in progress.

Available Functions 
bool isDone( void );
Parameters

This function does not accept any parameters.

Return Values

Returns a Boolean indicating whether the drivetrain is not moving:

  • true — The drivetrain is not moving.
  • false — The drivetrain is 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#

Returns a Boolean indicating whether the drivetrain is currently executing a target-based movement (such as driveFor or turnFor).

Available Functions 
virtual bool isMoving( void );
Parameters

This function does not accept any parameters.

Return Values

Returns a Boolean indicating whether the drivetrain is moving:

  • true — The drivetrain is moving.
  • false — The drivetrain 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#

Returns the velocity of the drivetrain.

Available Functions 
double velocity( velocityUnits units );
Parameters

Parameter

Type

Description

units

velocityUnits

The units that represent the velocity:

  • rpm — rotations per minute
  • dps — degrees per second
  • percent / pct — percent
Return Values

Returns a double indicating the velocity of the drivetrain in the units specified by the units parameter.

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#

Returns the amount of electrical current the drivetrain is using.

Available Functions
1 
double current( 
  currentUnits units = currentUnits::amp 
);
 Accept a currentUnits parameter
2 
double current( 
  percentUnits units 
);
 Accept a percentUnits parameter
Parameters

Parameter

Type

Description

units

currentUnits

The units that represent the current:

  • amp — amps

units

percentUnits

The units that represent the current:

  • percent / pct — percent
Return Values

Returns a double indicating the amount of electrical current the drivetrain is using in the units specified by the units parameter.

power#

Returns the drivetrain’s power consumption.

Available Functions 
double  power( powerUnits units = powerUnits::watt );
Parameters

Parameter

Type

Description

units

powerUnits

Optional. The units that represent the power:

  • watt (default) — watts
Return Values

Returns a double representing the drivetrain’s power consumption in watts.

torque#

Returns the torque produced by the drivetrain.

Available Functions 
double torque( torqueUnits units = torqueUnits::nm );
Parameters

Parameter

Type

Description

units

torqueUnits

Optional. The units representing the torque:

  • Nm (default) — newton meters
  • InLb — inch pounds
Return Values

Returns a double indicating the torque produced by the drivetrain in the units specified by the units parameter.

efficiency#

Returns the efficiency of the drivetrain.

Available Functions 
double efficiency( percentUnits units = percentUnits::pct );
Parameters

Parameter

Type

Description

units

percentUnits

Optional. The units that represent the efficiency:

  • percent / pct — percent
Return Values

Returns a double representing the drivetrain’s efficiency as a percentage.

temperature#

Returns the average temperature of the motors used by the drivetrain.

Available Functions 
double temperature( percentUnits units );
Parameters

Parameter

Type

Description

units

percentUnits

The units that represent the temperature:

  • percent / pct — percent
Return Values

Returns a double indicating the average temperature of the motors used by the drivetrain as a percentage.

Notes

  • A returned value of 50% indicates that the average motor temperature is approximately 45°C (113°F).

  • The typical operating temperature range for drivetrain motors is approximately 20°C (68°F) to 70°C (158°F).

voltage#

Returns the electrical voltage of the drivetrain.

Available Functions 
double  voltage( voltageUnits units = voltageUnits::volt );
Parameters

Parameter

Type

Description

units

voltageUnits

Optional. The units that represent the voltage:

  • volt (default) — volts
  • mV — millivolts
Return Values

Returns a double indicating the voltage of the drivetrain in the units specified by the units parameter.

On this page