Drivetrain#

Introduction #

The Drivetrain controls a robot’s movement, allowing it to drive forward, turn, and stop with precision.

It can also function as a smart drivetrain when configured with a Gyro Sensor or a Brain Inertial Sensor.

For the examples below, the configured drivetrain will be named Drivetrain and will be used in all subsequent examples throughout this API documentation when referring to drivetrain and smartdrive class methods.

Below is a list of all methods:

Actions – Move and turn the robot.

drive – Moves the drivetrain in a specified direction indefinitely.
driveFor – Moves the drivetrain in a specified direction for a set distance.
turn – Turns the drivetrain left or right indefinitely.
turnFor – Turns the drivetrain left or right for a set distance.
turnToHeading – Turns a smart drivetrain to a specified heading.
turnToRotation – Turns a smart drivetrain to a specified rotational value.
stop – Stops a drivetrain.
calibrateDrivetrain – Calibrates the drivetrain.

Mutators – Set default movement and turn speeds.

setDriveVelocity – Sets the default moving velocity for a drivetrain.
setTurnVelocity – Sets the default turning velocity for a drivetrain.
setStopping – Sets the stopping mode for a drivetrain.
setTimeout – Sets a time limit for drivetrain functions.
setHeading – Sets the heading of a smart drivetrain.
setRotation – Sets the rotation for the smart drivetrain.
setGearRatio – Sets the gear ratio for all motors on the drivetrain.
setTurnThreshold – Sets the turn threshold for the smart drivetrain.
setTurnConstant – Sets the turn constant for the smart drivetrain.
setTurnDirectionReverse – Sets the expected turn direction for positive heading.

Getters – Return robot state and position.

isDone – Returns whether a drivetrain is not currently moving.
isMoving – Returns whether a drivetrain is currently moving.
heading – Returns the current heading of a smart drivetrain.
rotation – Returns the current rotational value of a smart drivetrain.
velocity – Returns the current velocity of a drivetrain.
current – Returns the current current of a drivetrain.
power – Returns the average power of the smart drivetrain.
torque – Returns the average torque of the drivetrain.
efficiency – Returns the average efficiency of the drivetrain.
temperature – Returns the average temperature of the drivetrain.

Constructors – Manually initialize and configure the drivetrain.

drivetrain – Creates a basic drivetrain.
smartdrive – Creates a drivetrain configured with a Gyro Sensor or Brain Inertial Sensor.

Actions #

drive #

drive moves the drivetrain in a specified direction indefinitely.

Default Usage:
Drivetrain.drive(direction);

Overload Usages:
Drivetrain.drive(direction, velocity, units);

Parámetros

Descripción

direction

The direction in which to drive:

forward
reverse

velocidad

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

unidades

The unit that represents the velocity:

velocityUnits::pct (Percent)
rpm (Rotations per minute)
dps (Degrees per second)

// Example coming soon

driveFor #

driveFor moves the drivetrain in a specified direction for a set distance.

Default Usage:
Drivetrain.driveFor(direction, distance, units, wait);

Overload Usages:
Drivetrain.driveFor(direction, distance, units, wait);
Drivetrain.driveFor(direction, distance, units, velocity, units_v, wait);
Drivetrain.driveFor(distance, units, wait);
Drivetrain.driveFor(distance, units, velocity, units_v, wait);

Parámetros	Descripción
direction	The direction in which to drive: `forward` `reverse`
distancia	The distance for the drivetrain to move as a double.
unidades	The unit that represents the distance: `mm` – Millimeters `inches` – Inches `cm` – Centimeters
wait	Optional. `true` (default) – The project waits until `driveFor` is complete 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 `driveFor` to finish.
velocidad	The velocity at which the drivetrain will move as a double. If the velocity is not specified, the default velocity is 50%.
unidades_v	The unit that represents the velocity: `velocityUnits::pct` (Percent) `rpm` (Rotations per minute) `dps` (Degrees per second)

// Example coming soon

turn #

turn turns the drivetrain left or right indefinitely.

Default Usage:
Drivetrain.turn(direction);

Overload Usages:
Drivetrain.turn(direction, velocity, units);

Parámetros

Descripción

direction

The direction in which to turn:

left
right

velocidad

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

unidades

The unit that represents the velocity:

velocityUnits::pct (Percent)
rpm (Rotations per minute)
dps (Degrees per second)

// Example coming soon

turnFor #

turnFor turns the drivetrain left or right for a set distance.

Default Usage:
Drivetrain.turnFor(direction, angle, units, wait);

Overload Usages:
Drivetrain.turnFor(direction, angle, units, velocity, units_v, wait);
Drivetrain.turnFor(angle, units, wait);
Drivetrain.turnFor(angle, units, velocity, units_v, wait);

Parámetros	Descripción
direction	The direction in which to turn: `left` `right`
ángulo	The amount of degrees the drivetrain will turn as a double.
unidades	The unit that represents the rotational value: `degrees` `turns`
velocidad	The velocity at which the drivetrain will turn as a double. If the velocity is not specified, the default velocity is 50%.
unidades_v	The unit that represents the velocity: `velocityUnits::pct` (Percent) `rpm` (Rotations per minute) `dps` (Degrees per second)
wait	Optional. `true` (default) – The project waits until `turnFor` is complete 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 `turnFor` to finish.

// Example coming soon

turnToHeading #

turnToHeading turns a smart drivetrain to a specified heading.

Note: This method will only work with a drivetrain that has been configured with a Gyro Sensor or Brain Inertial Sensor.

Default Usage:
Drivetrain.turnToHeading(angle, units, wait);

Overload Usages:
Drivetrain.turnToHeading(angle, units, velocity, units_v, wait);

Parámetros	Descripción
ángulo	The heading to turn the drivetrain to face as a float or integer.
unidades	The unit that represents the rotational value: `degrees` `turns`
velocidad	The velocity at which the motor or motor group will spin as a float or integer. If the velocity is not specified, the default velocity is 50%.
unidades_v	The unit that represents the velocity: `velocityUnits::pct` (Percent) `rpm` (Rotations per minute) `dps` (Degrees per second)
wait	Optional. `true` (default) – The project waits until `turnToHeading` is complete 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 `turnToHeading` to finish.

// Example coming soon

turnToRotation #

turnToRotation turns a smart drivetrain to a specified rotational value.

Note: This method will only work with a drivetrain that has been configured with a Gyro Sensor or Brain Inertial Sensor.

Default Usage:
Drivetrain.turnToRotation(angle, units, wait);

Overload Usages:
Drivetrain.turnToRotation(angle, units, velocity, units_v, wait);

Parámetros	Descripción
ángulo	The heading to turn the drivetrain to face as a float or integer.
unidades	The unit that represents the rotational value: `degrees` `turns`
velocidad	The velocity at which the motor or motor group will spin as a float or integer. If the velocity is not specified, the default velocity is 50%.
unidades_v	The unit that represents the velocity: `velocityUnits::pct` (Percent) `rpm` (Rotations per minute) `dps` (Degrees per second)
wait	Optional. `true` (default) – The project waits until `turnToRotation` is complete 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 `turnToRotation` to finish.

// Example coming soon

stop #

stop stops a drivetrain.

Default Usage:
Drivetrain.stop();

Overload Usages:
Drivetrain.stop(mode);

Parámetros	Descripción
modo	How the drivetrain will stop: `coast` – Slows gradually to a stop. `brake` – Stops immediately. `hold` – Stops and resists movement using motor feedback.

// Example coming soon

calibrateDrivetrain #

calibrateDrivetrain calibrates the drivetrain.

Usage:
Drivetrain.calibrateDrivetrain();

// Example coming soon

Mutators #

setDriveVelocity #

setDriveVelocity sets the default moving velocity for a drivetrain. This velocity setting will be used for subsequent calls to any drivetrain functions if a specific velocity is not provided.

Usage:
Drivetrain.setDriveVelocity(velocity, units);

Parámetros	Descripción
velocidad	The velocity at which the drivetrain will move as a double.
unidades	The unit that represents the velocity: `percent` (Percent) `rpm` (Rotations per minute) `dps` (Degrees per second)

Parámetros

Descripción

velocidad

The velocity at which the drivetrain will move as a double.

unidades

The unit that represents the velocity:

percent (Percent)
rpm (Rotations per minute)
dps (Degrees per second)

// Example coming soon

setTurnVelocity #

setTurnVelocity sets the default turning velocity for a drivetrain. This velocity setting will be used for subsequent calls to any drivetrain functions if a specific velocity is not provided.

Usage:
Drivetrain.setTurnVelocity(velocity, units);

Parámetros	Descripción
velocidad	The velocity at which the drivetrain will turn as a double.
unidades	The unit that represents the velocity: `percent` (Percent) `rpm` (Rotations per minute) `dps` (Degrees per second)

Parámetros

Descripción

velocidad

The velocity at which the drivetrain will turn as a double.

unidades

The unit that represents the velocity:

percent (Percent)
rpm (Rotations per minute)
dps (Degrees per second)

setStopping #

setStopping sets the stopping mode for a drivetrain.

Usage:
Drivetrain.setStopping(mode);

Parámetros	Descripción
modo	How the drivetrain will stop: `brake` – Stops immediately. `coast` – Slows gradually to a stop. `hold` – Stops and resists movement using motor feedback.

// Example coming soon

setTimeout #

setTimeout sets a time limit for how long a drivetrain function will wait to reach its target. If the drivetrain cannot complete the movement within the set time, it will stop automatically and continue with the next function.

Note: The drivetrain’s time limit is used to prevent drivetrain functions that do not reach their target position from stopping the execution of the rest of the project.

Usage:
Drivetrain.setTimeout(time, units);

Parámetros	Descripción
time	The maximum number of seconds a motor function will run before stopping and moving to the next function as an integer.
unidades	The unit that represents the time: `seconds` `msec` – Milliseconds

Parámetros

Descripción

time

The maximum number of seconds a motor function will run before stopping and moving to the next function as an integer.

unidades

The unit that represents the time:

seconds
msec – Milliseconds

// Example coming soon

setHeading #

setHeading sets the heading of a smart drivetrain.

Note: This method will only work with a drivetrain that has been configured with a Gyro Sensor or Brain Inertial Sensor.

Usage:
Drivetrain.setHeading(value, units);

Parámetros	Descripción
value	The new heading as a double.
unidades	The unit that represents the heading: `degrees` `turns`

Parámetros

Descripción

value

The new heading as a double.

unidades

The unit that represents the heading:

degrees
turns

// Example coming soon

setRotation #

setRotation sets the rotation for the smart drivetrain.

Note: This method will only work with a drivetrain that has been configured with a Gyro Sensor or Brain Inertial Sensor.

Usage:
Drivetrain.setRotation(value, units);

Parámetros	Descripción
value	The new rotational value as a double.
unidades	The unit that represents the heading: `degrees` `turns`

Parámetros

Descripción

value

The new rotational value as a double.

unidades

The unit that represents the heading:

degrees
turns

// Example coming soon

setGearRatio #

setGearRatio sets the gear ratio for all motors on the Drivetrain.

Usage:
Drivetrain.setGearRatio(mode);

Parámetros	Descripción
modo	Gear Ratio options: `ratio1_1` – A gear unit that is defined as 1:1 gearing. `ratio2_1` – A gear unit that is defined as 2:1 gearing. `ratio3_1` – A gear unit that is defined as 3:1 gearing.

// Example coming soon

setTurnThreshold #

setTurnThreshold 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.

Note: This method will only work with a drivetrain that has been configured with a Gyro Sensor or Brain Inertial Sensor.

Usage:
Drivetrain.setTurnThreshold(t);

Parámetros	Descripción
t	The new turn threshold in `degrees`. The default for a Smart Drivetrain is 1 degree.

// Example coming soon

setTurnConstant #

setTurnConstant 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.

Note: This method will only work with a drivetrain that has been configured with a Gyro Sensor or Brain Inertial Sensor.

Usage:
Drivetrain.setTurnConstant(kp);

Parámetros	Descripción
kp	The new turn constant in the range 0.1 - 4.0. The default is 1.0.

// Example coming soon

setTurnDirectionReverse #

setTurnDirectionReverse method sets the expected turn direction for positive heading.

Note: This method will only work with a drivetrain that has been configured with a Gyro Sensor or Brain Inertial Sensor.

Usage:
Drivetrain.setTurnDirectionReverse(value);

Parámetros	Descripción
value	A boolean value to set the reversed flag to `true` or `false`.

// Example coming soon

Getters #

isDone #

isDone returns a Boolean indicating whether a drivetrain is not currently moving.

true – The drivetrain is not moving.
false – The drivetrain is moving.

Usage:
Drivetrain.isDone()

Parámetros	Descripción
	This method has no parameters.

// Example coming soon

isMoving #

isMoving returns a Boolean indicating whether a drivetrain is currently moving.

true – The drivetrain is moving.
false – The drivetrain is not moving.

Usage:
Drivetrain.isMoving()

Parámetros	Descripción
	This method has no parameters.

// Example coming soon

heading #

heading returns the current heading of a smart drivetrain as a double.

Note: This method will only work with a drivetrain that has been configured with a Gyro Sensor or Brain Inertial Sensor.

Usage:
Drivetrain.heading(units)

Parámetros	Descripción
unidades	Optional. The unit that represents the rotational value: `degrees` (default) `turns`

Parámetros

Descripción

unidades

Optional. The unit that represents the rotational value:

degrees (default)
turns

// Example coming soon

rotation #

rotation returns the current rotational value of a smart drivetrain as a double.

Note: This method will only work with a drivetrain that has been configured with a Gyro Sensor or Brain Inertial Sensor.

Usage:
Drivetrain.rotation(units)

Parámetros	Descripción
unidades	Optional. The unit that represents the rotational value: `degrees` (default) `turns`

Parámetros

Descripción

unidades

Optional. The unit that represents the rotational value:

degrees (default)
turns

// Example coming soon

velocidad #

velocity returns the current velocity of a drivetrain as a double.

Usage:
Drivetrain.velocity(units)

Parámetros	Descripción
unidades	The unit that represents the velocity: `percent` `rpm` – Rotations per minute `dps` – Degrees per second

Parámetros

Descripción

unidades

The unit that represents the velocity:

percent
rpm – Rotations per minute
dps – Degrees per second

// Example coming soon

current #

current returns the current current of a drivetrain as a double.

Usage:
Drivetrain.current(units)

Parámetros	Descripción
unidades	Optional. The unit that represents the current: `percent` `amp` (default)

Parámetros

Descripción

unidades

Optional. The unit that represents the current:

percent
amp (default)

// Example coming soon

power #

power(units) returns the average power of the Smart Drivetrain as a double.

Note: This method will only work with a drivetrain that has been configured with a Gyro Sensor or Brain Inertial Sensor.

Usage:
Drivetrain.power(units)

Parámetros	Descripción
unidades	La única unidad válida para potencia es el “vatio”.

// Example coming soon

torque #

torque returns the average torque of the Drivetrain as a double.

Note: This method will only work with a drivetrain that has been configured with a Gyro Sensor or Brain Inertial Sensor.

Usage:
Drivetrain.torque(units)

Parámetros	Descripción
unidades	A valid torque Unit: `Nm` (default) – A torque unit that is measured in newton meters. `InLb` – A torque unit that is measured in inch pounds. .

Parámetros

Descripción

unidades

A valid torque Unit:

Nm (default) – A torque unit that is measured in newton meters.
InLb – A torque unit that is measured in inch pounds.

// Example coming soon

efficiency #

efficiency returns the average efficiency of the Drivetrain as a double.

Note: This method will only work with a drivetrain that has been configured with a Gyro Sensor or Brain Inertial Sensor.

Usage:
Drivetrain.efficiency(units)

Parámetros	Descripción
unidades	La única unidad válida para la eficiencia es el “porcentaje”.

// Example coming soon

temperature #

The temperature() method returns the average temperature of the Drivetrain as a double.

Usage:
Drivetrain.temperature(units)

Note: This method will only work with a drivetrain that has been configured with a Gyro Sensor or Brain Inertial Sensor.

Parámetros	Descripción
unidades	The only valid unit for temperature is `percent`.

// Example coming soon

Constructors #

Drivetrain #

Se crea un sistema de transmisión utilizando el siguiente constructor:

El constructor drivetrain crea un objeto drivetrain.

Usage:
drivetrain(lm, rm, wheelTravel, trackWidth, wheelBase, unit, externalGearRatio);

Parámetro	Descripción
`lm`	The name of the Left Motor or Motor Group.
`rm`	The name of the Right Motor or Motor Group.
`Rueda de viaje`	Circunferencia de las ruedas motrices. El valor predeterminado es 300 mm.
`ancho de pista`	Ancho de vía del tren motriz. El valor predeterminado es 320 mm.
`distancia entre ejes`	Distancia entre ejes del tren motriz. El valor predeterminado es 320 mm.
`unit`	Una distanceUnit válida para las unidades en las que se especifican wheelTravel, trackWidth y wheelBase. El valor predeterminado es `MM`.
`relación de transmisión externa`	La relación de transmisión utilizada para compensar las distancias de conducción si se utilizan engranajes.

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

// Create the Motors.
motor left_motor = motor(PORT1,false);
motor right_motor = motor(PORT2, true);
// Construct a 2-Motor drivetrain "Drivetrain" with the
// drivetrain class.
drivetrain Drivetrain = drivetrain(left_motor, right_motor, 259.34, 320, 40, mm, 1);

If making a 4-Motor 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(PORT3, true);
motor rightMotorB = motor(PORT4, true);
motor_group rightMotors = motor_group(rightMotorA, rightMotorB);
// Construct a 4-Motor drivetrain "Drivetrain" with the
// drivetrain class.
drivetrain Drivetrain = drivetrain(leftMotors, rightMotors, 259.34, 320, 40, mm, 1);

Este objeto “Drivetrain” se utilizará en todos los ejemplos posteriores a lo largo de esta documentación de API cuando se haga referencia a los métodos de la clase drivetrain.

Para incorporar un Sensor inercial o un Sensor giroscópico para una funcionalidad de giro mejorada en su transmisión, puede incluirlo al crear un objeto usando el constructor de clase smartdrive.

Smartdrive #

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.

Usage:
smartdrive(lm, rm, guido, wheelTravel, trackWidth, wheelBase, unit, externalGearRatio);

Parámetro	Descripción
`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 any Inertial Sensor, or Gyro Sensor.
`Rueda de viaje`	Circunferencia de las ruedas motrices. El valor predeterminado es 300 mm.
`ancho de pista`	The track width of the Smart Drivetrain. The default is 320 mm.
`distancia entre ejes`	The wheel base of the Smart Drivetrain. The default is 320 mm.
`unit`	A valid distanceUnit for the units that wheelTravel, trackWidth and wheelBase are specified in. The default is `mm`.
`relación de transmisión externa`	La relación de transmisión utilizada para compensar las distancias de conducción si se utilizan engranajes.

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(PORT3, true);
motor rightMotorB = motor(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 an Inertial Sensor or Gyro Sensor functionality, instead create an object using the drivetrain Class constructor.