smartdrive#

To make smartdrive commands appear in VEXcode V5, a Drivetrain with a gyro must be configured.

For information about configuring a SmartDrive with the Devices Window in VEXcode V5, refer to these articles:

For more information on how Drivetrains work, read Creating a V5 Drivetrain.

Initializing the smartdrive Class #

A Smart Drivetrain is created by using the following constructor:

The smartdrive constructor creates a smartdrive object. This object can do everything a drivetrain can do but has additional methods that include use of an Inertial Sensor or Gyro in order to make more accurate turns.

Parameter	Description
`lm`	The name of the Left `Motor` or `Motor Group`.
`rm`	The name of the Right `Motor` or `Motor Group`.
`guido`	The name of the device you are using to detect the angle or heading of the robot. This can be the any `Inertial Sensor`, or `Gyro Sensor`.
`wheelTravel`	The circumference of the driven wheels. The default is 300 mm.
`trackWidth`	The track width of the Smart Drivetrain. The default is 320 mm.
`wheelBase`	The wheel base of the Smart Drivetrain. The default is 320 mm.
`units`	A valid `distanceUnit` for the units that wheelTravel, trackWidth and wheelBase are specified in. The default is `MM`.
`externalGearRatio`	The gear ratio used to compensate drive distances if gearing is used.

Motors and/or Motor Groups must be created first before they can be used to create an object with the smartdrive Class constructor.

// Create the Motors.
motor left_motor = motor(PORT1,false);
motor right_motor = motor(PORT2, true);
// Create the Inertial Sensor
inertial Inertial = inertial(PORT3);
// Construct a 2-Motor Smart Drivetrain "Smartdrive" with the
// smartdrive class.
smartdrive Smartdrive = smartdrive(left_motor, right_motor, Inertial, 259.34, 320, 40, mm, 1);

If making a 4-Motor Smart Drivetrain, you need to create the Motors separately before grouping them into a Motor Group.

// Create the left Motors and group them under the
// motor_group "leftMotors".
motor leftMotorA = motor(PORT1, false);
motor leftMotorB = motor(PORT2, false);
motor_group leftMotors = motor_group(leftMotorA, leftMotorB);
// Create the right Motors and group them under the
// MotorGroup "rightMotors".
motor rightMotorA = motor(Ports.PORT3, true);
motor rightMotorB = motor(Ports.PORT4, true);
motor_group rightMotors = motor_group(rightMotorA, rightMotorB);
// Create the Inertial Sensor
inertial Inertial = inertial(PORT5);
// Construct a 4-Motor smartdrive "Smartdrive" with the
// smartdrive class.
smartdrive Smartdrive = smartdrive(leftMotors, rightMotors, Inertial, 259.34, 320, 40, mm, 1);

This Smartdrive object will be used in all subsequent examples throughout this API documentation when referring to smartdrive class methods.

To create an object without Inertial Sensor or Gyro Sensor functionality, instead create an object using the drivetrain Class constructor.

Class Methods #

drive()#

This is a non-waiting method and allows the next method to run without delay.

This method is called in the following ways:

The drive(directionType dir) method is used to drive the smartdrive in the specified direction forever at the default velocity as specified by the setDriveVelocity() method, until another Smart Drivetrain movement method is used, or the project is stopped.

Parameters	Description
`dir`	A valid `directionType`.

Returns: None.

// Drive the smartdrive forward.
Smartdrive.drive(forward);

The drive(directionType dir, double velocity, velocityUnits units) method is used to drive the Smart Drivetrain in the specified direction forever at a specified velocity, until another Smart Drivetrain movement method is used, or the project is stopped.

Parameters	Description
`dir`	A valid `directionType`.
`velocity`	The velocity at which the smartdrive will move.
`units`	A valid `velocityUnit`.

Returns: None.

// Drive the smartdrive forward at 100 rpm.
Smartdrive.drive(forward, 100, rpm);

driveFor()#

This can be a waiting or non-waiting method depending on if the wait parameter is used.

This method is called in the following ways:

The driveFor(double distance, distanceUnits units, bool waitForCompletion) method is used to drive the Smart Drivetrain for a specified distance at the default velocity.

Parameters	Description
`distance`	The distance for the smartdrive to move.
`units`	A valid `distanceUnit`. The default is `inches`.
`waitForCompletion`	Determines whether the command will block subsequent commands (`wait=true`) or allow immediate execution (`wait=false`). If unspecified, the default for the `wait` parameter is `wait=true`.

Returns: A boolean value representing whether the smartdrive has reached the target distance.

// Drive the Smart Drivetrain for 10 inches.
Smartdrive.driveFor(10, inches);

The driveFor(directionType dir, double distance, distanceUnits units, bool waitForCompletion) method is used to drive the Smart Drivetrain in a specified direction for a specified distance at the default velocity.

Parameters	Description
`dir`	A valid `directionType`.
`distance`	The distance for the Smart Drivetrain to move.
`units`	A valid `distanceUnit`. The default is `inches`.
`waitForCompletion`	Determines whether the command will block subsequent commands (`wait=true`) or allow immediate execution (`wait=false`). If unspecified, the default for the `wait` parameter is `wait=true`.

Returns: A boolean value representing whether the Smart Drivetrain has reached the target distance.

// Drive the Smart Drivetrain forward for 10 inches.
Smartdrive.driveFor(forward, 10, inches);

The driveFor(double distance, distanceUnits units, double velocity, velocityUnits units_v, bool waitForCompletion) method is used to drive the Smart Drivetrain for a specified distance at the default velocity.

Parameters	Description
`distance`	The distance for the Smart Drivetrain to move.
`units`	A valid `distanceUnit`. The default is `inches`.
`velocity`	The velocity the Smart Drivetrain will move with. The default velocity set by the `setDriveVelocity()` method will be used if not provided.
`units_v`	A valid `velocityUnit`. The default is `rpm`.
`waitForCompletion`	Determines whether the command will block subsequent commands (`wait=true`) or allow immediate execution (`wait=false`). If unspecified, the default for the `wait` parameter is `wait=true`.

Returns: A boolean value representing whether the Smart Drivetrain has reached the target distance.

// Drive the Smart Drivetrain for 10 inches at 100 rpm.
Smartdrive.driveFor(10, inches, 100, rpm);

The driveFor(directionType dir, double distance, distanceUnits units, double velocity, velocityUnits units_v, bool waitForCompletion) method is used to drive the Smart Drivetrain for a specified distance at the default velocity.

Parameters	Description
`dir`	A valid `directionType`.
`distance`	The distance for the Smart Drivetrain to move.
`units`	A valid `distanceUnit`. The default is `inches`.
`velocity`	The velocity the Smart Drivetrain will move with. The default velocity set by the `setDriveVelocity()` method will be used if not provided.
`units_v`	A valid `velocityUnit`. The default is `rpm`.
`waitForCompletion`	Determines whether the command will block subsequent commands (`wait=true`) or allow immediate execution (`wait=false`). If unspecified, the default for the `wait` parameter is `wait=true`.

Returns: A boolean value representing whether the Smart Drivetrain has reached the target distance.

// Drive the Smart Drivetrain forward for 10 inches at 100 rpm.
Smartdrive.driveFor(forward, 10, inches, 100, rpm);

turn()#

This is a non-waiting method and allows the next method to run without delay.

This method is called in the following ways:

The turn(turnType dir) method is used to turn the robot in a specified direction at the default velocity as specified by the setTurnVelocity() method, until another Smart Drivetrain movement method is used, or the project is stopped.

Parameters	Description
`dir`	A valid `directionType`.

Returns: None.

// Turn the Smart Drivetrain right.
Smartdrive.turn(right);

The turn(turnType dir, double velocity, velocityUnits units) method is used to turn the robot in a specified direction at a specified velocity, until another Smart Drivetrain movement method is used, or the project is stopped.

Parameters	Description
`dir`	A valid `directionType`.
`velocity`	The velocity at which the Smart Drivetrain will turn. The default velocity set by The `Smartdrive.setTurnVelocity()` method will be used if not provided.
`units`	A valid `velocityUnit`. The default is `rpm`.

Returns: None.

// Turn the Smart Drivetrain right at 100 rpm.
Smartdrive.turn(right, 100, rpm);

turnFor()#

This can be a waiting or non-waiting method depending on if the wait parameter is used.

The turnFor() method in the smartdrive class works differently than in the drivetrain class because the Inertial Sensor or Gyro Sensor, instead of the internal motor encoders, are utilized to make more accurate turns.

This method is called in the following ways:

The turnFor(double angle, rotationUnits units, bool waitForCompletion) method is used to turn the Smart Drivetrain for a specific angle at the default velocity as specified by the setTurnVelocity() method.

Parameters	Description
`angle`	The angle for the Smart Drivetrain to turn.
`units`	A valid `rotationUnit`. The default is `degrees`.
`waitForCompletion`	Determines whether the command will block subsequent commands (`wait=true`) or allow immediate execution (`wait=false`). If unspecified, the default for the `wait` parameter is `wait=true`.

Returns: A boolean value representing whether the Smart Drivetrain has turned to the target angle.

// Turn the Smart Drivetrain for 90 degrees.
Smartdrive.turnFor(90, degrees);

The turnFor(turnType dir, double angle, rotationUnits units, bool waitForCompletion) method is used to turn the Smart Drivetrain for a specific angle at the default velocity as specified by the setTurnVelocity() method.

Parameters	Description
`dir`	A valid `directionType`.
`angle`	The angle for the Smart Drivetrain to turn.
`units`	A valid `rotationUnit`. The default is `degrees`.
`waitForCompletion`	Determines whether the command will block subsequent commands (`wait=true`) or allow immediate execution (`wait=false`). If unspecified, the default for the `wait` parameter is `wait=true`.

Returns: A boolean value representing whether the Smart Drivetrain has turned to the target angle.

// Turn the Smart Drivetrain right for 90 degrees.
Smartdrive.turnFor(right, 90, degrees);

The turnFor(double angle, rotationUnits units, double velocity, velocityUnits units_v, bool waitForCompletion) method is used to turn the Smart Drivetrain for a specific angle at a specified velocity.

Parameters	Description
`angle`	The angle for the Smart Drivetrain to turn.
`units`	A valid `rotationUnit`. The default is `degrees`.
`velocity`	The velocity at which the Smart Drivetrain will turn. The default velocity set by The `setTurnVelocity()` method will be used if not provided.
`units_v`	A valid `velocityUnit`. The default is `rpm`.
`waitForCompletion`	Determines whether the command will block subsequent commands (`wait=true`) or allow immediate execution (`wait=false`). If unspecified, the default for the `wait` parameter is `wait=true`.

Returns: A boolean value representing whether the Smart Drivetrain has turned to the target angle.

// Turn the Smart Drivetrain for 90 degrees at 100 rpm.
Smartdrive.turnFor(90, degrees, 100, rpm);

The turnFor(turnType dir, double angle, rotationUnits units, double velocity, velocityUnits units_v, bool waitForCompletion) method is used to turn the Smart Drivetrain for a specific angle at a specified velocity.

Parameters	Description
`dir`	A valid `directionType`.
`angle`	The angle for the Smart Drivetrain to turn.
`units`	A valid `rotationUnit`. The default is `degrees`.
`velocity`	The velocity at which the Smart Drivetrain will turn. The default velocity set by The `setTurnVelocity()` method will be used if not provided.
`units_v`	A valid `velocityUnit`. The default is `rpm`.
`waitForCompletion`	Determines whether the command will block subsequent commands (`wait=true`) or allow immediate execution (`wait=false`). If unspecified, the default for the `wait` parameter is `wait=true`.

Returns: A boolean value representing whether the Smart Drivetrain has turned to the target angle.

// Turn the Smart Drivetrain right for 90 degrees at 100 rpm.
Smartdrive.turnFor(right, 90, degrees, 100, rpm);

turnToHeading()#

This can be a waiting or non-waiting method depending on if the wait parameter is used.

This method is called in the following ways:

The turnToHeading(double angle, rotationUnits units, bool waitForCompletion) method turns the Smart Drivetrain to a specific heading.

Parameters	Description
`angle`	The heading angle to turn to.
`units`	A valid `rotationUnit`.
`waitForCompletion`	Determines whether the command will block subsequent commands (`wait=true`) or allow immediate execution (`wait=false`). If unspecified, the default for the `wait` parameter is `wait=true`.

Returns: A boolean value that signifies when the Smart Drivetrain has reached the target turn value.

// Turn to heading 180 degrees.
Smartdrive.turnToHeading(180, degrees);

The turnToHeading(double angle, rotationUnits units, double velocity, velocityUnits units_v, bool waitForCompletion) method turns the Smart Drivetrain to a specific heading.

Parameters	Description
`angle`	The heading angle to turn to.
`units`	A valid `rotationUnit`.
`velocity`	Spin the motors of the Smart Drivetrain using this velocity.
`units_v`	A valid `velocityUnit`.
`waitForCompletion`	Determines whether the command will block subsequent commands (`wait=true`) or allow immediate execution (`wait=false`). If unspecified, the default for the `wait` parameter is `wait=true`.

Returns: A boolean value that signifies when the Smart Drivetrain has reached the target turn value.

// Turn to heading 180 degrees at 100 rpm.
Smartdrive.turnToHeading(180, degrees, 100, rpm);

turnToRotation()#

This can be a waiting or non-waiting method depending on if the wait parameter is used.

This method is called in the following ways:

The turnToRotation(double angle, rotationUnits units, bool waitForCompletion) method turns the Smart Drivetrain to a specific rotation.

Parameters	Description
`angle`	The rotation angle to turn to.
`units`	A valid `rotationUnit`.
`waitForCompletion`	Determines whether the command will block subsequent commands (`wait=true`) or allow immediate execution (`wait=false`). If unspecified, the default for the `wait` parameter is `wait=true`.

Returns: A boolean value that signifies when the Smart Drivetrain has reached the target turn value.

// Turn to rotation 180 degrees.
Smartdrive.turnToRotation(180, degrees);

The turnToRotation(double angle, rotationUnits units, double velocity, velocityUnits units_v, bool waitForCompletion) method turns the Smart Drivetrain to a specific rotation.

Parameters	Description
`angle`	The rotation angle to turn to.
`units`	A valid `rotationUnit`.
`velocity`	Spin the motors of the Smart Drivetrain using this velocity.
`units_v`	A valid `velocityUnit`.
`waitForCompletion`	Determines whether the command will block subsequent commands (`wait=true`) or allow immediate execution (`wait=false`). If unspecified, the default for the `wait` parameter is `wait=true`.

Returns: A boolean value that signifies when the Smart Drivetrain has reached the target turn value.

// Turn to rotation 180 degrees at 100 rpm.
Smartdrive.turnToRotation(180, degrees, 100, rpm);

stop()#

This is a non-waiting command and allows the next command to run without delay.

This method is called in the following ways:

The stop() command is used to stop the Smart Drivetrain, setting the Smart Drivetrain to 0 velocity and configuring the current stopping mode. The default Brake Type is coast, unless previously changed using the setStopping() command.

Returns: None.

// Spin Smartdrive for 2.5 seconds.
Smartdrive.spin(forward);

wait(2.5 seconds);

// Stop Smartdrive.
Smartdrive.stop();

The stop(brakeType mode) command is used to stop the Smart Drivetrain using a specific Brake Type.

Parameters	Description
`mode`	A valid `brakeType`.

Returns: None.

// Spin Smartdrive for 2.5 seconds.
Smartdrive.spin(forward);

wait(2.5 seconds);

// Stop Smartdrive using the hold Brake Type.
Smartdrive.stop(hold);

isSpinning()#

The isSpinning() command returns if any Smart Drivetrain motor is on and rotating to a specific target.

Returns: true if any Smart Drivetrain motor is on and rotating to a target. false if it they done rotating to a target.

isDone()#

The isDone() command returns if all Smart Drivetrain motors are done rotating to a specific target.

Returns: true if the all Smart Drivetrain motors are done rotating to a target. false if any Smart Drivetrain motor is on and rotating to a target.

isTurning()#

The isTurning() method returns if a turnToHeading(), turnToRotation(), or turnFor() method is currently running.

Returns: true if the a turnToHeading(), turnToRotation(), or turnFor() method is currently running. false if one is not.

setDriveVelocity()#

The setDriveVelocity(double velocity, velocityUnits units) method is used to set the default velocity for the Smartdrive. This velocity setting affects all subsequent drive method unless a specific velocity is provided in those method.

Parameters	Description
`velocity`	The new velocity to set as default for the Smartdrive.
`units`	A valid `velocityUnit` or `percent`. The default is `rpm`.

Returns: None.

// Set the Smart Drivetrain to drive at a velocity of 200 rpm.
Smartdrive.setDriveVelocity(200, rpm);

setTurnVelocity()#

The setTurnVelocity(double velocity, velocityUnits units) method is used to set the default velocity for turning maneuvers in the Smartdrive. This setting specifies the speed at which the Smart Drivetrain will execute turning method unless overridden by a specific velocity in those method.

Parameters	Description
`velocity`	The new velocity to set as default for turning maneuvers.
`units`	A valid `velocityUnit` or `percent`. The default is `rpm`.

Returns: None.

// Set the Smart Drivetrain to turn at a velocity of 200 RPM.
Smartdrive.setTurnVelocity(200, rpm);

setStopping()#

The setStopping(mode) method is used to set the stopping mode for all motors on the Smartdrive. This setting determines the behavior of the motors when they receive a stop method or when the velocity is set to zero.

Parameters	Description
`mode`	A valid `brakeType`.

Returns: None.

// Set the stopping mode to BRAKE.
Smartdrive.setStopping(brake);

setGearRatio()#

The setGearRatio(mode) method is used to set the gear ratio for all motors on the Smartdrive.

Parameters	Description
`mode`	A valid `gearSetting`.

Returns: None.

setTurnThreshold()#

The setTurnThreshold(double t) method sets the turn threshold for the Smartdrive. The threshold value is used to determine that turns are complete. If this is too large, then turns will not be accurate. If too small, then turns may not complete.

Parameters	Description
`t`	The new turn threshold in `degrees`. The default for a Smart Drivetrain is 1 degree.

Returns: None.

setTurnConstant()#

The setTurnConstant(double kp) method sets the turn constant for the Smartdrive. The Smart Drivetrain uses a simple P controller when doing turns. This constant, generally known as kp, is the gain used in the equation that turns angular error into motor velocity.

Parameters	Description
`kp`	The new turn constant in the range 0.1 - 4.0. The default is 1.0.

Returns: None.

setTurnDirectionReverse()#

The setTurnDirectionReverse(bool value) method sets the expected turn direction for positive heading.

Parameters	Description
`value`	A boolean value to set the direction the motors spins to reversed or not.

| value | A boolean value to set the reversed flag to true or false. |

Returns: None.

setHeading()#

The setHeading(double value, rotationUnits units) method sets the heading for the Smart Drivetrain Inertial Sensor or Gyro Sensor.

Parameters	Description
`value`	The new value to use for heading.
`units`	A valid `rotationUnit`.

Returns: None.

// set the value of heading to 180 degrees.
Smartdrive.setHeading(180, degrees);

setRotation()#

The setRotation() method sets the rotation for the Smart Drivetrain Inertial Sensor or Gyro Sensor.

Parameters	Description
`value`	The new value to use for rotation.
`units`	A valid `rotationUnit`.

Returns: None.

// Set the value of rotation to 180 degrees.
Smartdrive.setRotation(180, degrees);

setTimeout()#

The Smartdrive.setTimeout(int32_t time, timeUnits units) method is used to set the timeout value for all motors on the Smartdrive. This setting determines how long the Smart Drivetrain will attempt to execute driveFor or turnFor method before timing out if the motors have not completed their movements.

Parameters	Description
`timeout`	The timeout duration to set as default for Smart Drivetrain operations.
`units`	A valid `timeUnit` type. The default is `msec`.

Returns: None.

// Set the timeout for the Smart Drivetrain to 10 seconds.
Smartdrive.setTimeout(10, seconds);

heading()#

The heading(rotationUnits units) method returns the current heading of the Smartdrive.

Parameters	Description
`units`	A valid `rotationUnit` type. The default is `degrees`.

Returns: A double representing the current heading of the Smart Drivetrain in the specified units.

// Get the current heading for the Smartdrive.
double value = Smartdrive.heading();

rotation()#

The rotation(rotationUnits units) method returns the current rotation of the Smartdrive.

Parameters	Description
`units`	A valid `rotationUnit`. The default is `degrees`.

Returns: A double representing the current rotation of the Smart Drivetrain in the specified units.

// Get the current rotation for the Smartdrive.
double value = Smartdrive.rotation();

velocity()#

The velocity(velocityUnits units) method returns the average velocity of the Smart Drivetrain.

Parameters	Description
`units`	A valid `velocityUnit` or `percent`. The default is `rpm`.

Returns: A double representing the Smart Drivetrain velocity in the specified units.

current()#

The current() method returns the average current of the Smart Drivetrain.

Parameters	Description
`units`	The only valid units for current are `amp` or `percent`.

Returns: A double representing the Smart Drivetrain current in the specified units.

voltage()#

The voltage(voltageUnits units) method returns the average velocity of the Smart Drivetrain.

Parameters	Description
`units`	A valid `voltageUnit`. The default is `volt`.

Returns: A double representing the Smart Drivetrain voltage in the specified units.

power()#

The power(powerUnits units) method returns the average power of the Smart Drivetrain .

Parameters	Description
`units`	The only valid unit for power is `watt`.

Returns: A double representing the Smart Drivetrain power in the specified units.

torque()#

The torque() method returns the average torque of the Smart Drivetrain.

Parameters	Description
`units`	A valid `torqueUnit`. The default is `Nm`.

Returns: A double representing the Smart Drivetrain torque in the specified units.

efficiency()#

The efficiency() method returns the average efficiency of the Smart Drivetrain.

Parameters	Description
`units`	The only valid unit for efficiency is `percent`.

Returns: A double representing the Smart Drivetrain efficiency in the provided units.

temperature()#

The temperature() method returns the average temperature of the Smart Drivetrain.

Parameters	Description
`units`	The only valid unit for temperature is `percent`.

Returns: A double representing the Smart Drivetrain temperature in the provided units.