01 | WHY MOTOR ROTATION IS NOT ROBOT DISTANCE

A motor encoder measures rotation. To estimate how far the robot moves, your code needs to know how that rotation reaches the wheel and how far the wheel rolls per revolution.

Start with the verified left and right groups from 01.3 Drivetrain Groups. Then measure the geometry. Do not compensate for a wrong motor direction by changing dimensions.

02 | DIAMETER AND CIRCUMFERENCE

Diameter is the distance across the wheel through its centre. Circumference is the distance around its rolling surface, also called wheel travel for one wheel revolution.

Wheel travel = π × diameter
A nominal 4-inch wheel: 4 × 25.4 = 101.6 mm diameter
Circumference ≈ π × 101.6 = 319.19 mm

The DriveTrain wheelTravel argument takes circumference, not diameter. Passing 101.6 where 319.19 is intended produces a major distance error.

Measure the rolling surface rather than the hub. Nominal wheel sizes are a starting point; tyre wear and compression under load affect real travel. A useful check is to mark a wheel, roll it through one complete turn under normal load and measure the distance.

03 | DISTANCE TO WHEEL ROTATION

Wheel turns = desired distance ÷ circumference
For 1000 mm with 319.19 mm wheel travel:
1000 ÷ 319.19 ≈ 3.133 wheel turns
Wheel angle ≈ 3.133 × 360 = 1127.87 degrees

This assumes rolling without slip. It is a model, not a promise that the robot will land at exactly 1000 mm.

Larger wheels travel farther per turn. At the same wheel RPM they provide greater theoretical ground speed, but the force available at the tyre and the load on the drive system also change.

04 | INTERNAL CARTRIDGE VS EXTERNAL GEARING

The blue, green or red cartridge is gearing inside the motor. Match it in each Motor declaration as described in 01.2.

External gearing is between the motor output shaft and the wheel, using gears or sprockets. Do not enter the blue cartridge’s 6:1 ratio as the external ratio: it is already represented by the motor configuration.

With a direct wheel-to-motor output connection, one output turn produces one wheel turn. External gearing can reduce or increase wheel rotation relative to that output.

05 | STATE YOUR GEAR-RATIO CONVENTION

For a simple external gear pair, define a clear speed factor:

Q = wheel turns per motor-output turn
Q = driver teeth ÷ driven teeth
Motor-output turns = wheel turns ÷ Q

With 36 driving 60, one motor-output revolution gives 0.6 wheel revolutions. For the 1000 mm example, the motor output needs about 3.133 ÷ 0.6 = 5.222 turns.

For multiple stages, multiply the stage speed factors. An idler gear can change direction without changing the simple end-to-end tooth-count ratio. Verify the final mechanism direction.

Libraries and teams can describe ratios using opposite conventions. Q here is an explicitly defined learning quantity, not automatically the value to paste into the VEX externalGearRatio argument. For a geared DriveTrain, confirm the convention in your installed VEXcode Help or its generated drivetrain configuration, then verify with a measured test. The runnable example below deliberately uses direct drive, where the ratio is unambiguously 1.

06 | TRACK WIDTH AND WHEELBASE

Track width is the lateral distance between the left and right wheel contact-line centres. It is not the outside width of the chassis.

Wheelbase is the front-to-back distance between wheel axle centres. It is different from track width and is another DriveTrain constructor parameter.

A four- or six-wheel skid-steer chassis can scrub sideways during a turn. Wheel type, wheelbase, traction and loading influence the effective turning behaviour. Physical dimensions are useful starting values, but measured turning performance may require tuning.

07 | HOW TRACK WIDTH AFFECTS A TURN

In an ideal differential-drive model, an in-place turn sends each side around a circle with radius equal to half the track width. Each side travels in the opposite direction.

Side travel for a turn = π × track width × angle ÷ 360
For a 90° turn with a 300 mm track:
π × 300 × 90 ÷ 360 ≈ 235.62 mm per side

The sides travel equal magnitudes in opposite directions. A wider track requires more side travel for the same ideal turn angle.

This explains the geometry, but it is not the exact implementation of every library’s turning algorithm. Real skid-steer robots also slip and scrub. Sensor-based turning is introduced later.

08 | CLEAR PYTHON GEOMETRY CONFIGURATION

The complete user-code example below shows ports, groups and dimensions together. Keep the generated imports and Brain setup above it. If math is not already imported, add import math in your user imports.

Use this only after verifying motor directions. The example assumes blue cartridges and direct drive; change the declared ports, cartridge flags and measured dimensions to match your robot. Do not duplicate these drive devices in the Devices panel.

# =============================================================================
# TEAM [MY TEAM NAME / NUMBER]
# =============================================================================
# ROBOT CONFIGURATION
# - FOUR-motor drivetrain:
#       Left  = Ports 3 and 4
#       Right = Ports 1 and 2
# - Example: blue cartridges; verify reversal on your build.
# - Example: DIRECT drive, no external speed change.
# - All values below are examples. Measure your robot.
# Add BELOW # Begin project code. Do not duplicate Devices entries.

# =============================================================================
# FOUR-MOTOR DRIVETRAIN
# =============================================================================
left_motor_1 = Motor(Ports.PORT3, GearSetting.RATIO_6_1, False)
left_motor_2 = Motor(Ports.PORT4, GearSetting.RATIO_6_1, False)
right_motor_1 = Motor(Ports.PORT1, GearSetting.RATIO_6_1, True)
right_motor_2 = Motor(Ports.PORT2, GearSetting.RATIO_6_1, True)

left_drive = MotorGroup(left_motor_1, left_motor_2)
right_drive = MotorGroup(right_motor_1, right_motor_2)

# =============================================================================
# MEASURED GEOMETRY: MILLIMETRES
# =============================================================================
WHEEL_DIAMETER_MM = 101.6
WHEEL_TRAVEL_MM = math.pi * WHEEL_DIAMETER_MM
TRACK_WIDTH_MM = 300
WHEEL_BASE_MM = 250
EXTERNAL_GEAR_RATIO = 1.0  # Direct drive ONLY in this example

drivetrain = DriveTrain(
    left_drive, right_drive,
    WHEEL_TRAVEL_MM, TRACK_WIDTH_MM, WHEEL_BASE_MM,
    MM, EXTERNAL_GEAR_RATIO
)

# =============================================================================
# TEST SETTINGS AND MAIN
# =============================================================================
TEST_DISTANCE_MM = 300
TEST_SPEED_PERCENT = 15

def main():
    drivetrain.set_drive_velocity(TEST_SPEED_PERCENT, PERCENT)
    drivetrain.set_stopping(BRAKE)
    drivetrain.set_timeout(5, SECONDS)
    drivetrain.drive_for(FORWARD, TEST_DISTANCE_MM, MM)
    drivetrain.stop()

main()

DriveTrain adds distance-based movement to the left/right interface. Its constructor order is left side, right side, wheel circumference, track width, wheelbase, distance unit and external ratio.

The five-second timeout bounds how long this test tries to complete; reaching the timeout does not prove that the target distance was reached. The code uses motor encoders rather than an inertial sensor.

09 | TEST BEFORE CHANGING THE MODEL

1. First verify supported-wheel direction and stopping behaviour.
2. For distance measurements, use a clear floor area with adequate run-out space.
3. Mark a consistent chassis reference point at the start.
4. Run the short distance test, then measure the same point’s displacement.
5. Repeat three times at the same speed and load.
6. Record commanded distance, measured distance and whether the robot drifted.

If error is inconsistent, investigate slip, drag, loose hardware and battery/load changes. If it is consistent, recheck units, circumference and external gearing before applying calibration.

10 | CALIBRATE ONE VARIABLE AT A TIME

For the direct-drive encoder model, if repeated tests travel too far, the configured wheel travel may be too small. A proportional starting correction is:

New wheel travel = old wheel travel × measured distance ÷ commanded distance
Example: old = 319.19 mm, commanded = 500 mm, measured = 525 mm
New estimate = 319.19 × 525 ÷ 500 ≈ 335.15 mm

This is an effective calibration value, not necessarily the literal measured tyre circumference. Use it only after eliminating a gearing or unit mistake. Validate at another distance rather than trusting one result.

Keep original measurements and tuned values labelled separately. Do not adjust wheel travel and external ratio together to hide the same error, and do not tune distance using a robot that is slipping badly.

CHALLENGES | MEASURE, PREDICT AND VERIFY

1. Measure: record wheel diameter, rolled wheel travel, track width and wheelbase in millimetres.
2. Map the gearing: identify every external driver and driven gear or sprocket. State your ratio convention.
3. Predict: calculate wheel turns for 500 mm and 1000 mm of travel.
4. Configure: write TEAM, ROBOT CONFIGURATION and MEASURED GEOMETRY comment sections using your real hardware.
5. Test: complete three short measured trials and record the results.
6. Investigate: explain whether any error is consistent or variable before changing a value.
7. Validate: repeat at another distance after a justified correction.

OFFICIAL REFERENCE

VEX V5 Python DriveTrain and SmartDrive reference

Use the Help for your installed VEXcode version when configuring a geared drivetrain. This is an independent learning resource; VEX and VEXcode are trademarks of their respective owners.