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.

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);

参数

描述

direction

The direction in which to drive:

  • forward
  • reverse

速度

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

单位

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);

参数

描述

direction

The direction in which to drive:

  • forward
  • reverse

距离

The distance for the drivetrain to move as a double.

单位

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.

速度

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

单位

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);

参数

描述

direction

The direction in which to turn:

  • left
  • right

速度

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

单位

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);

参数

描述

direction

The direction in which to turn:

  • left
  • right

角度

The amount of degrees the drivetrain will turn as a double.

单位

The unit that represents the rotational value:

  • degrees
  • turns

速度

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

单位

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);

参数

描述

角度

The heading to turn the drivetrain to face as a float or integer.

单位

The unit that represents the rotational value:

  • degrees
  • turns

速度

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

单位

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);

参数

描述

角度

The heading to turn the drivetrain to face as a float or integer.

单位

The unit that represents the rotational value:

  • degrees
  • turns

速度

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

单位

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);

参数

描述

模式

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);

参数

描述

速度

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

单位

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);

参数

描述

速度

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

单位

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);

参数

描述

模式

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);

参数

描述

time

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

单位

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);

参数

描述

value

The new heading as a double.

单位

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);

参数

描述

value

The new rotational value as a double.

单位

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);

参数

描述

模式

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);

参数

描述

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);

参数

描述

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);

参数

描述

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()

参数

描述

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()

参数

描述

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)

参数

描述

单位

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)

参数

描述

单位

Optional. The unit that represents the rotational value:

  • degrees (default)
  • turns

// Example coming soon

速度#

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

Usage:
Drivetrain.velocity(units)

参数

描述

单位

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)

参数

描述

单位

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)

参数

描述

单位

功率的唯一有效单位是“瓦特”。

// 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)

参数

描述

单位

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)

参数

描述

单位

效率的唯一有效单位是“百分比”。

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

参数

描述

单位

The only valid unit for temperature is percent.

// Example coming soon

Constructors#

Drivetrain#

使用以下构造函数创建动力传动系统:

drivetrain 构造函数创建一个 drivetrain 对象。

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

范围

描述

lm

The name of the Left Motor or Motor Group.

rm

The name of the Right Motor or Motor Group.

wheelTravel

驱动轮的周长。默认值为 300 毫米。

trackWidth

传动系统的轮距。默认值为 320 毫米。

轮距

传动系统的轴距。默认值为 320 毫米。

unit

对于 wheelTravel、trackWidth 和 wheelBase 指定的单位,有效的 distanceUnit。默认值为“MM”。

externalGearRatio

如果使用齿轮传动,则使用齿轮比来补偿驱动距离。

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);

当引用传动系统类方法时,此“Drivetrain”对象将在整个 API 文档的所有后续示例中使用。

要在您的传动系统中加入 惯性传感器陀螺仪传感器 以增强转弯功能,您可以在使用 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);

范围

描述

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.

wheelTravel

驱动轮的周长。默认值为 300 毫米。

trackWidth

The track width of the Smart Drivetrain. The default is 320 mm.

轮距

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.

externalGearRatio

如果使用齿轮传动,则使用齿轮比来补偿驱动距离。

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.