smartdrive#

Introduction#

The smartdrive class controls how a robot drives and turns using motors, wheels, and a sensor. A smartdrive can use an Inertial Sensor or Gyro Sensor to track heading and rotation.

A smartdrive uses the sensor to help the robot move and turn precisely. At the start of each project, the drivetrain calibrates the sensor automatically. Keep the robot still for about 2 seconds during calibration, so the robot can move and turn correctly.

The smartdrive class is based on the drivetrain class. It can use the same drive and turn functions as drivetrain, and it also adds sensor-based functions like turnToHeading and turnToRotation.

Class Constructors#

1 — Creates a smartdrive using existing motor_group objects for the left (&l) and right (&r) sides, along with an Inertial Sensor or Gyro Sensor.
smartdrive(
    motor_group     &l,
    motor_group     &r,
    inertial        &g,
    double          wheelTravel = 320,
    double          trackWidth  = 320,
    double          wheelBase   = 130,
    distanceUnits   unit = mm,
    double          externalGearRatio = 1.0 );

2 — Creates a smartdrive using existing motor objects for the left (&l) and right (&r) sides, along with an Inertial Sensor or Gyro Sensor.
smartdrive(
    motor           &l,
    motor           &r,
    inertial        &g,
    double          wheelTravel = 320,
    double          trackWidth  = 320,
    double          wheelBase   = 130,
    distanceUnits   unit = mm,
    double          externalGearRatio = 1.0 );

Class Destructor#

Destroys the smartdrive object and releases associated resources.

~smartdrive();

Parameters#

The sensor parameter can be an inertial or gyro object.

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.
`&g`	`guido`	A reference to an existing `gyro` or `inertial` instance.
`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#

/* 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 inertial instance
inertial myInertial = inertial(PORT3);

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

Member Functions#

The smartdrive class includes the following member functions:

Actions — Turn the robot using heading or rotation.

turnToHeading — Turns the robot to face a specific heading from -359 to 359 degrees. The robot will turn the shortest direction to reach the target heading.
turnToRotation — Turns the robot to a specific rotation.
calibrateDrivetrain — Calibrates the drivetrain’s configured Inertial Sensor or Gyro Sensor.

Settings — Adjust heading and rotation values.

setHeading — Changes the robot’s current heading to a new heading.
setRotation — Changes the robot’s current rotation to a new rotation.

Values — Check heading and rotation.

heading — Returns the robot’s current heading from 0 to 359 degrees.
rotation — Returns the robot’s current rotation.

A smartdrive can also use the inherited member functions from drivetrain, such as drive, driveFor, turn, turnFor, stop, isDone, and isMoving.

Before calling any smartdrive member functions, a smartdrive 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 inertial instance
inertial myInertial = inertial(PORT3);

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

turnToHeading#

A heading is the direction the robot is facing, measured in degrees. turnToHeading turns the robot to face a specific heading from -359 to 359 degrees. The robot will turn the shortest direction to reach the target heading.

The robot’s starting heading is 0 degrees.

The project will wait until the robot is done turning before the next line of code runs.

Available Functions

1 — Turns the drivetrain to the specified heading using the currently configured turn velocity.
bool turnToHeading(
    double        angle,
    rotationUnits units,
    bool          waitForCompletion = true );

2 — Turns the drivetrain to the specified heading at the specified velocity.
bool turnToHeading(
    double        angle,
    rotationUnits units,
    double        velocity,
    velocityUnits units_v,
    bool          waitForCompletion = true );

Parameters

Parameter	Type	Description
`angle`	`double`	The direction the robot should face, in degrees. This can be from -359 to 359 when using `deg` or `degrees`.
`units`	`rotationUnits`	The rotation 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 heading, as a Boolean value.

true — The robot reached the target heading.
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 turnToHeading is in progress will interrupt the current movement.
Because turnToHeading is target-based (uses an angle parameter), functions such as isDone and isMoving work with turnToHeading.

Examples

// Face the new 0 degrees
myDrivetrain.setHeading(90, degrees);
myDrivetrain.turnToHeading(0, degrees);

turnToRotation#

turnToRotation turns the robot to a specific rotation.

Rotation is how much the robot has turned, measured in degrees or revolutions. At the beginning of a project, the rotation value is set to 0 degrees. Rotation can also be set using the setRotation function.

Rotation values are absolute. This means the direction of the turn depends on the robot’s current rotation. Turning right increases the rotation, and turning left decreases the rotation.

For example, if the robot starts at 0 degrees and you turn to a rotation of 720 degrees, it will turn right twice. If you then turn to a rotation of 360 degrees, it will turn left once, because 360 is less than 720.

The project will wait until the robot is done turning before the next line of code runs.

Available Functions

1 — Turns the drivetrain to the specified rotation using the currently configured turn velocity.
bool turnToRotation(
    double        angle,
    rotationUnits units,
    bool          waitForCompletion = true );

2 — Turns the drivetrain to the specified rotation at the specified velocity.
bool turnToRotation(
    double        angle,
    rotationUnits units,
    double        velocity,
    velocityUnits units_v,
    bool          waitForCompletion = true );

Parameters

Parameter	Type	Description
`angle`	`double`	The rotation value that the robot will turn to.
`units`	`rotationUnits`	The rotation 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 rotation, as a Boolean value.

true — The robot reached the target rotation.
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 turnToRotation is in progress will interrupt the current movement.
Because turnToRotation is target-based (uses an angle parameter), functions such as isDone and isMoving work with turnToRotation.

Examples

// Spin counterclockwise for 2 turns, then face forward
myDrivetrain.setRotation(720, degrees);
myDrivetrain.turnToRotation(0, degrees);

calibrateDrivetrain#

calibrateDrivetrain calibrates the Inertial Sensor or Gyro Sensor configured with the smartdrive.

Calibration helps the sensor measure movement correctly. Keep the robot still for about 2 seconds during calibration. If the robot moves during calibration, the sensor may not measure movement correctly.

The project will wait until calibration is done before the next line of code runs.

calibrateDrivetrain is generated automatically by VEXcode when a drivetrain is configured with an Inertial Sensor or Gyro Sensor. It is provided as part of the project source and is not part of the VEX EXP C++ API.

Available Functions

void calibrateDrivetrain();

Parameters

This function does not accept any parameters.

Return Values

This function does not return a value.

Notes

The robot calibrates automatically at the start of each project.
Keep the robot still for about 2 seconds during calibration.

Function Implementation

The following is the auto-generated implementation of calibrateDrivetrain created by VEXcode:

bool vexcode_initial_drivetrain_calibration_completed = false;
void calibrateDrivetrain() {
  wait(200, msec);
  Brain.Screen.print("Calibrating");
  Brain.Screen.newLine();
  Brain.Screen.print("Inertial");
  DrivetrainInertial.calibrate();
  while (DrivetrainInertial.isCalibrating()) {
    wait(25, msec);
  }
  vexcode_initial_drivetrain_calibration_completed = true;
  // Clears the screen and returns the cursor to row 1, column 1.
  Brain.Screen.clearScreen();
  Brain.Screen.setCursor(1, 1);
}

setHeading#

A heading is the direction the robot is facing, measured in degrees. setHeading changes the robot’s current heading to a new heading value.

For example, if the robot has turned to face right, setting the heading to 0 degrees makes that right-facing position the new 0 degrees. Then the robot can turn to other positions based on that new heading.

Available Functions

void  setHeading(
  double value,
  rotationUnits units);

Parameters

Parameter	Type	Description
`value`	`double`	The heading value to set for the robot. This can be from -359 to 359 when using `deg` or `degrees`.
`units`	`rotationUnits`	The heading unit: `deg` (degrees), `rev` (revolutions), or `raw` (raw units). One revolution is equal to 360 degrees.

Return Values

This function does not return a value.

Examples

// Face the new 0 degrees
myDrivetrain.setHeading(90, degrees);
myDrivetrain.turnToHeading(0, degrees);

setRotation#

Rotation is how much the robot has turned, measured in degrees or revolutions. At the beginning of a project, the rotation value is set to 0 degrees. setRotation changes the robot’s current rotation to a new value.

For example, if the robot has made two full turns to the right, its rotation value will be 720 degrees. Setting the rotation to 0 degrees will reset that rotation from 720 to 0 degrees. Then the robot can turn to rotations based on that new value.

Available Functions

void  setRotation(
  double value,
  rotationUnits units);

Parameters

Parameter	Type	Description
`value`	`double`	The rotation value to set for the robot.
`units`	`rotationUnits`	The rotation unit: `deg` (degrees), `rev` (revolutions), or `raw` (raw units). One revolution is equal to 360 degrees.

Return Values

This function does not return a value.

Examples

// Spin counterclockwise for 2 turns, then face forward
myDrivetrain.setRotation(720, degrees);
myDrivetrain.turnToRotation(0, degrees);

heading#

A heading is the direction the robot is facing, measured in degrees. heading returns the robot’s current heading from 0 to 359 degrees.

The robot’s starting heading is 0 degrees.

Available Functions

double heading( rotationUnits units = rotationUnits::deg );

Parameters

Parameter	Type	Description
`units`	`rotationUnits`	Optional. The unit to return heading in: `degrees`, `deg` (default), `rev`, or `raw`. One revolution is equal to 360 degrees.

Return Values

Returns the robot’s current heading as a double in the selected unit.

Examples

// Show heading before and after turning
Brain.Screen.print("Before: %f", myDrivetrain.heading(degrees));
myDrivetrain.turnFor(right, 90, degrees);
wait(1, seconds);
Brain.Screen.newLine();
Brain.Screen.print("After: %f", myDrivetrain.heading(degrees));
myDrivetrain.stop();

rotation#

Rotation is how much the robot has turned, measured in degrees or revolutions. At the beginning of a project, the rotation value is set to 0 degrees. rotation returns the robot’s current rotation.

Turning right increases the rotation, and turning left decreases the rotation. For example, making two full turns to the right will return a rotation of 720 degrees.

Available Functions

double rotation( rotationUnits units = rotationUnits::deg );

Parameters

Parameter	Type	Description
`units`	`rotationUnits`	Optional. The unit to return heading in: `degrees`, `deg` (default), `rev`, or `raw`. One revolution is equal to 360 degrees.

Return Values

Returns the robot’s current rotation as a double in the selected unit.

Examples

// Show rotation before and after turning
Brain.Screen.print("Before: %f", myDrivetrain.rotation(degrees));
myDrivetrain.turnFor(right, 90, degrees);
wait(1, seconds);
Brain.Screen.newLine();
Brain.Screen.print("After: %f", myDrivetrain.rotation(degrees));
myDrivetrain.stop();