Drivetrain

Drivetrain directions

Most common robot configuration is direct motor driven wheels strapped to its chassis. Even it looks simple enough, there are different configurations and algorithms for improved agility and control response.
Drivetrain. object allows to define robot wheel base and control its movement with a few simple lines of code. This includes drive forward / backward, turn left / right and drive to side (mecanum).

Drivetrain types

Steer drive	Tank drive	Mecanum drive

Standard car wheel base with Ackermann steering.	Vehicle with track drive (or simple wheels). Steers by changing speed of left and right side. Also called Arcade drive.	Drivetrain with 4 Mecanum wheels (with 45° rollers). Allows omnidirectional movement.
Move directions: • Drive forward / backward • Steer left / right	Move directions: • Drive forward / backward • Turn left / right • Spin (in place) left / right	Move directions: • Drive forward / backward • Turn left / right • Spin (in place) left / right • Drive to side left / right

Code snippets

Steer driveTank driveMecanum drive

void setup() {
  // Setup Steer drive
  Drivetrain.setWheelLeft(DC.A); // Left wheel
  Drivetrain.setWheelRight(DC.B); // Right wheel
  Drivetrain.setDriveSteer(); // Select "Steer" drivetrain
  // Steering wheels connected to Servo port A
  Servo.A.setInvert(true); // Invert servo spin direction
  Servo.A.setTrim(-38, -7, 18); // Trim servo to correct steer angles
}
void loop() {
  // Drive forward at 50% power and turn left 40%
  Drivetrain.driveTurn(50, -40);
  // Drivetrain.brake(); // Brake wheels
}

void setup() {
  // Setup Tank drive
  Drivetrain.setWheelLeft(DC.A); // Left wheel
  Drivetrain.setWheelRight(DC.B); // Right wheel
  Drivetrain.setDriveTank(); // Select "Tank" drivetrain
}
void loop() {
  // Drive backward at 40% power with 30% turn right
  Drivetrain.driveTurn(-40);
  // Drivetrain.brake(); // Brake wheels
}

void setup() {
  // Setup Mecanum drive
  Drivetrain.setWheelLeftFront(DC.A); // Left front wheel
  Drivetrain.setWheelRightFront(DC.B); // Right front wheel
  Drivetrain.setWheelLeftRear(DC.C); // Left rear wheel
  Drivetrain.setWheelRightRear(DC.D); // Right rear wheel
  Drivetrain.setDriveMecanum(); // Select "Mecanum" drivetrain
  DC.setAutobrake(true); // Brake all motors if power set to 0
}
void loop() {
  // Move diagonally to 45 degrees with 80% power and 30% turning left
  Drivetrain.driveTurnDirection(80, -30, 45);
}

Initial setup

Drivetrain algorithm requires knowledge of robot chassis configuration. This is depended on where motors are placed, which port is connected and spin direction when power is applied.
Recommended to use Initial_setup.ino example to correctly assign each wheel.

//      ___
// A |-|   |-| B
//     |   |
// C |-|___|-| D
//
void setup() {
  // Set left front wheel to port DC A
  Drivetrain.setWheelLeftFront(DC.A);
  // Set right front wheel to port DC B
  // Also invert motor spin direction
  Drivetrain.setWheelRightFront(DC.B, true);
  // Set rear wheels
  Drivetrain.setWheelLeftRear(DC.C); // Left rear wheel
  Drivetrain.setWheelRightRear(DC.D); // Right rear wheel
  // Select algorithm logic to drive configured wheels
  Drivetrain.setDriveTank();
}
void loop() {
  // Spin motors using selected drive algorithm
  Drivetrain.drive(100);
}

Additional features

Drivetrain module only implements wheel configuration and movement algorithms. For an additional control features check DC and Servo sections.

DC.setAccelerationTime(time) - control robot acceleration speed.
DC.setDecelerationTime(time) - control robot deceleration speed.
DC.setAutobrake(true) - brake motors to prevent wheel free spin.
DC.setRange(min, max) - limit motor power.
Servo.setTrim(min, min, max) - set servo motor motion limits.
Servo.setSpeedRPM(rpm) - set servo motor motion limits.
Servo.run(sequence) - move servo in predefined pattern.

Functions

Configure wheels

Each "setWheel" function contains additional invert parameter to flip motor spin direction.
Example: Drivetrain.setWheelLeftFront(DC.A, true).
(a shortcut for using motor.setInvert(true)).

Drivetrain.setWheelLeft(`motor`) ¶

Drivetrain.setWheelLeftFront(`motor`) ¶

Drivetrain.setWheelLeftRear(motor) ¶: Select robot left side wheel. Available configurations:
1. Single wheel on left side setWheelLeft().
2. Front and Rear wheels on left side setWheelLeftFront(), setWheelLeftRear().
Parameter:
motor - RoboBoard port [DC.A,DC.B,DC.C,DC.D].
invert - (optional) flip motor spin direction yes / no [true:false].

Drivetrain.setWheelRight(`motor`) ¶

Drivetrain.setWheelRightFront(`motor`) ¶

Drivetrain.setWheelRightRear(motor) ¶: Select robot right side wheel. Available configurations:
1. Single wheel on right side setWheelRight().
2. Front and Rear wheels on right side setWheelRightFront(), setWheelRightRear().
Parameter:
motor - RoboBoard port [DC.A,DC.B,DC.C,DC.D].
invert - (optional) flip motor spin direction yes / no [true:false].

`motor` Drivetrain.getWheelLeftFront() ¶

`motor` Drivetrain.getWheelLeftRear() ¶

`motor` Drivetrain.getWheelRightFront() ¶

motor Drivetrain.getWheelRightRear() ¶: Get motor interface of configured wheel.
If not configured - returns dummy object (doing nothing).
Returns:
motor - MotorInterface object.

Configure drivetrain

Select drive algorithm. Specifies how robot wheels should behave.

Drivetrain.setDriveTank() ¶

Drivetrain.setDriveMecanum() ¶

Drivetrain.setDriveSteer(servo) ¶: Select drive algorithm.
Parameter:
servo - (optional) Servo object. By default Servo.A is used.
Drivetrain.setMaxSpeed(power) ¶: Set limit for maximum robot speed. Will divide value passed to drive() function.
Parameter:
power - max percentage of speed [0:100]%. Default: 100
number Drivetrain.getMaxSpeed() ¶: Get configured limit for maximum robot speed.
Parameter:
number - max percentage of speed [0:100]%.

Move robot

Drivetrain directions

Instruct robot to move in specified direction. It calculates trajectory depending on selected drivetrain algorithm and parameter percentage. Available parameters:

"drive" - drive forward or backward
"turn" - turn robot to left or right
"direction" - drive to angle in 360 degrees (mecanum drive only)
"brake" - stop with braking
"handbrake" - slow down robot. Same effect as pressing gas and brake pedals at the same time

Drivetrain.brake() ¶

Drivetrain.brake(power) ¶: Stop driving with wheel braking.
Electric brake only. Does not hold wheel in place.
Parameter:
power - amount of brake power [0:100]%.

Drivetrain.handbrake() ¶

Drivetrain.handbrake(power) ¶: Reduce driving speed by adding resistance. If brake power is greater than speed - electric brake is engaged. Need to call handbrake(0) to release the brake.
Electric brake only. Does not hold wheel in place.
Parameter:
power - amount of brake power [0:100]%.
Drivetrain.coast() ¶: Stop driving with free wheel spin (no power, no brake).
Drivetrain.drive(driveSpeed) ¶: Start driving forward or backward at percentage of speed.
Parameter:
driveSpeed - [-100:100]%. -(backward), +(forward)
Drivetrain.turn(turnSpeed) ¶: Start turning left or right at percentage of speed.
In Steer drive this will turn servo motor A and controls rear wheels differential speed.
Parameter:
turnSpeed - [-100:100]%. -(left), +(right).
Drivetrain.driveTurn(driveSpeed, turnSpeed) ¶: Start driving forward or backward with turning left or right at the same time. Move trajectory is combined by drive and turn speeds.
Parameter:
driveSpeed - [-100:100]%. -(backward), +(forward)
turnSpeed - [-100:100]%. -(left), +(right)
Drivetrain.driveDirection(driveSpeed, driveAngle) ¶: Start driving to specified degree of angle with percentage of speed.
May be used with combination of joystick magnitude and angle.
Mecanum drivetrain only.
Parameter:
driveSpeed - [-100:100]%. -(backward), +(forward)
driveAngle - [0:359]°. 0(forward), 90(right), 180(backward), 270(left)
Drivetrain.driveTurnDirection(driveSpeed, turnSpeed, driveAngle) ¶: Start driving to specified degree of angle with percentage of speed and turning.
Mecanum drivetrain only.
Parameter:
driveSpeed - [-100:100]%. -(backward), +(forward)
turnSpeed - [-100:100]%. -(left), +(right)
driveAngle - [0:359]°. 0(forward), 90(right), 180(backward), 270(left)
Drivetrain.spinLeftRight(left, right) ¶: Start spinning left and right wheels at different speed and directions.
Mainly used with Tank drivetrain for individual track control.
Parameter:
left - left wheels speed [-100:100]%. -(backward), +(forward)
right - right wheels speed [-100:100]%. -(backward), +(forward)
Drivetrain.spinWheels(LF, RF, LR, RR) ¶: Start spinning each configured wheel individually.
Parameter:
LF RF LR RR - wheel speed [-100:100]%. -(backward), +(forward)
power Drivetrain.getBrake() ¶: Returns: power - amount of brake applied [0:100]%.
speed Drivetrain.getDrive() ¶: Returns: speed - drive speed [-100:100]%. -(backward), +(forward)
speed Drivetrain.getTurn() ¶: Returns: speed - turn speed [-100:100]%. -(left), +(right)
angle Drivetrain.getDirection() ¶: Mecanum drivetrain only.
Returns: angle - drive direction [0:359]°. 0(forward), 90(right), 180(backward), 270(left)
state Drivetrain.isMoving() ¶: Check if robot is currently moving (power is applied).
Returns:
state - true if robot is moving. false not moving.

Joystick input

Helper functions to convert joystick / gamepad input to values suitable for motor control. Takes care of value range and smooth control input.

int button = Joystick::getTrigger(gamepad.button.r1);
int turn = Joystick::getAxis(3, gamepad.stick.rx);
int angle = Joystick::getAngle(gamepad.stick.lx, gamepad.stick.ly);
int magnitude = Joystick::getMagnitude(gamepad.stick.lx, gamepad.stick.ly);

Drivetrain.driveTurnDirection(magnitude, turn, angle);

`power` Joystick::getTrigger(`input`) ¶

power Joystick::getTrigger(exp, input) ¶: Get amount of trigger button is pressed.
Parameter:
input - raw joystick button input [0:255].
exp - exponent value to increase precision at low speed [1:4]. Default: 2.
Returns:
power - amount of button pressed [0:100]%.

`position` Joystick::getAxis(`input`) ¶

position Joystick::getAxis(exp, input) ¶: Get joystick axis position.
Parameter:
input - raw joystick axis input [-127:128].
exp - exponent value to increase precision at low speed [1:4]. Default: 2.
Returns:
position - axis position [-100:100]%. 0 - center.

`angle` Joystick::getAngle(`x`, `y`) ¶

angle Joystick::getAngle(exp, x, y) ¶: Get joystick angle (degree) from center.
Parameter:
x - raw joystick X axis input [-127:128].
y - raw joystick Y axis input [-127:128].
exp - exponent value to increase precision at low speed [1:4]. Default: 2.
Returns:
angle - joystick lean angle [0:359]°. 0 - pointing up.

`power` Joystick::getMagnitude(`x`, `y`) ¶

power Joystick::getMagnitude(exp, x, y) ¶: Get joystick amount pushed from center to side.
Parameter:
x - raw joystick X axis input [-127:128].
y - raw joystick Y axis input [-127:128].
exp - exponent value to increase precision at low speed [1:4]. Default: 2.
Returns:
power - joystick lean amount [0:100]%.

Default configuration values

Joystick::range ¶: Raw joystick input range. Default: 127.
Joystick::exponent ¶: Standard input exponent value [1:4]. Default: 2. input^exponent
Joystick::deadzone ¶: Joystick deadzone [0:100]%. Default: 0.
Note: disabled by default as exponent feature discards small values when stick is stationary.

Drivetrain

Drivetrain types

Code snippets

Initial setup

Additional features

Functions

Configure wheels

Drivetrain.setWheelLeft(motor) ¶

Drivetrain.setWheelLeftFront(motor) ¶

Drivetrain.setWheelLeftRear(motor) ¶

Drivetrain.setWheelRight(motor) ¶

Drivetrain.setWheelRightFront(motor) ¶

Drivetrain.setWheelRightRear(motor) ¶

motor Drivetrain.getWheelLeftFront() ¶

motor Drivetrain.getWheelLeftRear() ¶

motor Drivetrain.getWheelRightFront() ¶

motor Drivetrain.getWheelRightRear() ¶

Configure drivetrain

Drivetrain.setDriveTank() ¶

Drivetrain.setDriveMecanum() ¶

Drivetrain.setDriveSteer(servo) ¶

Drivetrain.setMaxSpeed(power) ¶

number Drivetrain.getMaxSpeed() ¶

Move robot

Drivetrain.brake() ¶

Drivetrain.brake(power) ¶

Drivetrain.handbrake() ¶

Drivetrain.handbrake(power) ¶

Drivetrain.coast() ¶

Drivetrain.drive(driveSpeed) ¶

Drivetrain.turn(turnSpeed) ¶

Drivetrain.driveTurn(driveSpeed, turnSpeed) ¶

Drivetrain.driveDirection(driveSpeed, driveAngle) ¶

Drivetrain.driveTurnDirection(driveSpeed, turnSpeed, driveAngle) ¶

Drivetrain.spinLeftRight(left, right) ¶

Drivetrain.spinWheels(LF, RF, LR, RR) ¶

power Drivetrain.getBrake() ¶

speed Drivetrain.getDrive() ¶

speed Drivetrain.getTurn() ¶

angle Drivetrain.getDirection() ¶

state Drivetrain.isMoving() ¶

Joystick input

power Joystick::getTrigger(input) ¶

power Joystick::getTrigger(exp, input) ¶

position Joystick::getAxis(input) ¶

position Joystick::getAxis(exp, input) ¶

angle Joystick::getAngle(x, y) ¶

angle Joystick::getAngle(exp, x, y) ¶

power Joystick::getMagnitude(x, y) ¶

power Joystick::getMagnitude(exp, x, y) ¶

Joystick::range ¶

Joystick::exponent ¶

Joystick::deadzone ¶

Drivetrain.setWheelLeft(`motor`) ¶

Drivetrain.setWheelLeftFront(`motor`) ¶

Drivetrain.setWheelLeftRear(`motor`) ¶

Drivetrain.setWheelRight(`motor`) ¶

Drivetrain.setWheelRightFront(`motor`) ¶

Drivetrain.setWheelRightRear(`motor`) ¶

`motor` Drivetrain.getWheelLeftFront() ¶

`motor` Drivetrain.getWheelLeftRear() ¶

`motor` Drivetrain.getWheelRightFront() ¶

`motor` Drivetrain.getWheelRightRear() ¶

Drivetrain.setDriveSteer(`servo`) ¶

Drivetrain.setMaxSpeed(`power`) ¶

`number` Drivetrain.getMaxSpeed() ¶

Drivetrain.brake(`power`) ¶

Drivetrain.handbrake(`power`) ¶

Drivetrain.drive(`driveSpeed`) ¶

Drivetrain.turn(`turnSpeed`) ¶

Drivetrain.driveTurn(`driveSpeed`, `turnSpeed`) ¶

Drivetrain.driveDirection(`driveSpeed`, `driveAngle`) ¶

Drivetrain.driveTurnDirection(`driveSpeed`, `turnSpeed`, `driveAngle`) ¶

Drivetrain.spinLeftRight(`left`, `right`) ¶

Drivetrain.spinWheels(`LF`, `RF`, `LR`, `RR`) ¶

`power` Drivetrain.getBrake() ¶

`speed` Drivetrain.getDrive() ¶

`speed` Drivetrain.getTurn() ¶

`angle` Drivetrain.getDirection() ¶

`state` Drivetrain.isMoving() ¶

`power` Joystick::getTrigger(`input`) ¶

`power` Joystick::getTrigger(`exp`, `input`) ¶

`position` Joystick::getAxis(`input`) ¶

`position` Joystick::getAxis(`exp`, `input`) ¶

`angle` Joystick::getAngle(`x`, `y`) ¶

`angle` Joystick::getAngle(`exp`, `x`, `y`) ¶

`power` Joystick::getMagnitude(`x`, `y`) ¶

`power` Joystick::getMagnitude(`exp`, `x`, `y`) ¶