# Tank Drive Model Support¶

Note

The equations used in our TankModel is derived from Noah Gleason and Eli Barnett’s motor characterization whitepaper. It is recommended that users of this model read the paper so they can more fully understand how this works.

In the interest of making progress, this API may receive backwards-incompatible changes before the start of the 2019 FRC season.

class MotorModel(motorConfig, kv, ka, vintercept)

Motor model used by the TankModel. You should not need to create this object if you’re using the TankModel class.

Arguments: motorConfig (Object) – The specification data for your motor kv (tm_kv) – Computed kv for your robot ka (tm_ka) – Computed ka for your robot vintercept (volt) – The minimum voltage required to generate enough torque to overcome steady-state friction (see the paper for more details)
MotorModel.compute(motorPct, tmDiff)
Arguments: motorPct (*) – Percentage of power for motor in range [1..-1] tmDiff (*) – Time elapsed since this function was last called
class TankModel(motorConfig, robotMass, xWheelbase, robotWidth, robotLength, lKv, lKa, lVi, rKv, rKa, rVi)

This is a model of a FRC tankdrive-style drivetrain that will provide vaguely realistic motion for the simulator.

This drivetrain model makes a number of assumptions:

• N motors per side
• Constant gearing
• Motors are geared together
• Wheels do not ‘slip’ on the ground
• Each side of the robot moves in unison

There are two ways to construct this model. You can use the theoretical model via TankModel.theory() and provide robot parameters such as gearing, total mass, etc.

Alternatively, if you measure kv, ka, and vintercept as detailed in the paper mentioned above, you can plug those values in directly instead using the TankModel constructor instead. For more information about measuring your own values, see the paper and this thread on ChiefDelphi.

Note

You can use whatever units you would like to specify the input parameter for your robot, the websim will convert them all to the correct units for computation.

Output units for velocity and acceleration are in ft/s and ft/s^2

Example usage for a 40kg robot with 2 CIM motors on each side with 6 inch wheels:

class MyUserPhysics extends UserPhysics {

createRobotModel(robotConfig) {
let math = this.Math;

let model = this.Models.TankModel.theory(
this.Models.MotorConfigs.MOTOR_CFG_CIM,
math.unit(40, 'kg'),
10.71,
2,
math.unit(2, 'ft'),
math.unit(6, 'inch')
);

return model;
}

const dataOut = halData.out;
const pwm = dataOut.pwm;

let lrMotor = pwm[1].value;
let rrMotor = pwm[2].value;

let {rcw, fwd} = this.model.getVector(lrMotor, rrMotor, dt);

let xSpeed = fwd * Math.cos(this.robot.angle);
let ySpeed = fwd * Math.sin(this.robot.angle);

this.Matter.Body.setVelocity(this.robot, { x: xSpeed, y: ySpeed });
this.Matter.Body.setAngularVelocity(this.robot, rcw);
}
}


Use the constructor if you have measured kv, ka, and Vintercept for your robot. Use the theory() function if you haven’t.

Vintercept is the minimum voltage required to generate enough torque to overcome steady-state friction (see the paper for more details).

The robot width/length is used to compute the moment of inertia of the robot. Don’t forget about bumpers!

Arguments: motorConfig (Object) – Motor specification robotMass (Quantity) – Mass of robot xWheelbase (Quantity) – Wheelbase of the robot robotWidth (Quantity) – Width of the robot robotLength (Quantity) – Length of the robot lKv (Quantity) – Left side kv lKa (Quantity) – Left side ka lVi (volt) – Left side Vintercept rKv (Quantity) – Right side kv rKa (Quantity) – Right side ka rVi (Quantity) – Right side Vintercept
TankModel.getVector(lMotor, rMotor, tmDiff)

Given motor values and the amount of time elapsed since this was last called, retrieves the velocity and anglular velocity of the robot.

To update your encoders, use the lPosition and rPosition attributes of this object.

Note

If you are using more than 2 motors, it is assumed that all motors on each side are set to the same speed. Only pass in one of the values from each side

Arguments: lMotor (Number) – Left motor value (-1 to 1); -1 is forward rMotor (Number) – Right motor value (-1 to 1); 1 is forward tmDiff (Number) – Elapsed time since last call to this function
TankModel.inertia

The model computes a moment of inertia for your robot based on the given mass and robot width/length. If you wish to use a different moment of inertia, set this property after constructing the object

Units are [mass] * [length] ** 2

TankModel.lPosition

The linear position of the left side wheel (in feet)

TankModel.lVelocity

The velocity of the left side (in ft/s)

TankModel.rPosition

The linear position of the right side wheel (in feet)

TankModel.rVelocity

The velocity of the left side (in ft/s)

TankModel.theory(motorConfig, robotMass, gearing, nmotors, xWheelbase, robotWidth, robotLength, wheelDiameter, vintercept)

Use this to create the drivetrain model when you haven’t measured kv and ka for your robot.

Computation of kv and ka are done as follows:

• $$\omega_{free}$$ is the free speed of the motor
• $$\tau_{stall}$$ is the stall torque of the motor
• $$n$$ is the number of drive motors
• $$m_{robot}$$ is the mass of the robot
• $$d_{wheels}$$ is the diameter of the robot’s wheels
• $$r_{gearing}$$ is the total gear reduction between the motors and the wheels
• $$V_{max}$$ is the nominal max voltage of the motor
\begin{align}\begin{aligned}velocity_{max} = \frac{\omega_{free} \cdot \pi \cdot d_{wheels} }{r_{gearing}}\\acceleration_{max} = \frac{2 \cdot n \cdot \tau_{stall} \cdot r_{gearing} }{d_{wheels} \cdot m_{robot}}\\k_{v} = \frac{V_{max}}{velocity_{max}}\\k_{a} = \frac{V_{max}}{acceleration_{max}}\end{aligned}\end{align}
Arguments: motorConfig (Object) – Specifications for your motor robotMass (Quantity) – Mass of the robot gearing (Number) – Gear ratio .. so for a 10.74:1 ratio, you would pass 10.74 nmotors (Number) – Number of motors per side xWheelbase (Quantity) – Wheelbase of the robot robotWidth (Quantity) – Width of the robot robotLength (Quantity) – Length of the robot wheelDiameter (Quantity) – Diameter of the wheel vintercept (Volt) – The minimum voltage required to generate enough torque to overcome steady-state friction (see the paper for more details)