Tuning Guide

Figuring out the right ARMS configuration for your robot is not always easy. On this page are guides on some of the more complicated parts of this process. It is recommended to follow these guides in order.

Odometry Setup

TPI: While this will require further tuning later, we can calculate TPI initially as TICKS_PER_REVOLUTION / WHEEL_CIRCUMFERENCE. TICKS_PER_REVOLUTION is 360 for motors and ADI encoders and is 36000 for rotation sensors. WHEEL_CIRCUMFERENCE is pi times the diameter of your tracking wheel, if using tracking wheels, or of your drivetrain wheel if otherwise.

MIDDLE_TPI: If using middle tracking wheel, follow same procedure as for TPI.

TRACK_WIDTH: If using left and right tracking wheels, this is the distance between the left and right tracking wheel. If using no tracking wheels, this is the distance between the left and right drivetrain wheels. If using a single parallel tracking wheel, see Using a Single Parallel Tracking Wheel.

MIDDLE_DISTANCE: If using a middle tracking wheel, this is the distance from the tracking wheel to the center of rotation of the drivetrain. If the middle tracking wheel is in front of the center of rotation, MIDDLE_DISTANCE has to be negative. If it is behind the center of rotation, it can stay positive.

Legal Sensor Configurations

In order for odometry to work properly, you must have one of the following sensor setups:

• No Sensors (using motor encoders)
• IMU
• Left and Right Tracking Wheels
• IMU + Left and Right Tracking Wheels
• IMU + Parallel Tracking Wheel

A middle tracking wheel may be added to any of the above setups.

Using a Single Parallel Tracking Wheel

Some special tricks are required to use a single parallel tracking wheel with ARMS:

• Set both the left and right encoder ports to the parallel tracking wheel's encoder port
• Set the TRACK_WIDTH to twice the distance from the parallel tracking wheel to the center of the drivetrain. If the parallel tracking wheel is on the left side of the drivetrain, the TRACK_WIDTH has to be negative. If it is on the right side, it can stay positive.

Odometry Tuning

LLEMU Setup

While odometry information is accessible through the PROS terminal by setting ODOM_DEBUG to 1, it may be preferable to display information on the brain using LLEMU while tuning. Here is some code that will do that:

void initialize() {
  arms::init();
  // initialize LLEMU after ARMS so that it doesn't get covered by the ARMS auton selector
  pros::lcd::initialize();
}
 
void opcontrol() {
  while (true) {
    // insert other opcontrol code here
    pros::lcd::set_text(0, "X: " + std::to_string(arms::odom::getPosition().x));
    pros::lcd::set_text(1, "Y: " + std::to_string(arms::odom::getPosition().y));
    pros::lcd::set_text(2, "H: " + std::to_string(arms::odom::getHeading()));
    pros::lcd::set_text(3, "Left: " + std::to_string(arms::odom::getLeftEncoder()));
    pros::lcd::set_text(4, "Right: " + std::to_string(arms::odom::getRightEncoder()));
    pros::lcd::set_text(5, "Middle: " + std::to_string(arms::odom::getMiddleEncoder()));
    pros::delay(10);
  }
}

Checking Encoders

Before we even start looking at odometry data, we should make sure all of our encoders are configured correctly.

• The left and right encoder values should increase when moving the robot forwards, and decrease when moving backwards.
• When turning the robot counterclockwise, the left and middle encoder values should decrease and the right encoder value should increase.

Note: these are the steps for checking that a 3 tracking wheel setup is working correctly. You should modify the procedure according to your specific odometry setup.

General Tuning Notes

• Due to sensor noise and other random factors, the distance reported by odometry may be slightly lower on some runs and slightly higher on other runs. To account for this, you may want to run the tuning procedure several times and use the average of the results instead of changing the constants after every run.
• Due to the relative nature of odometry, small errors will build up over time. Thus, when tuning, it is good to tune over large distances and turns so that errors are more noticeable. Additionally, if using tracking wheels, make sure there is nothing mechanically that could impede the rotation of the tracking wheels.

Tuning TPI

1. Move robot forwards a known number of inches.
2. Record the robot's X position from odom.
3. Set the new TPI as OLD_TPI * ODOM_X / FORWARD_DISTANCE.
4. Reupload code with new TPI.
5. Repeat until the X position from odom matches the distance pushed.

To tune MIDDLE_TPI, follow the same procedure as stated above, except move the robot sideways to the left instead of forwards, and record the robot's Y position instead of its X position.

Tuning Track Width

Note: this is the track with tuning procedure for using motor encoders or left and right tracking wheels. If you have an IMU, disable it while tuning this part. For tuning track width for a single parallel tracking wheel, follow a similar procedure as Tuning Middle Distance , but using the X position from odom rather than the Y position.

1. Turn robot counterclockwise a known number of degrees.
2. Record the robot's heading from odom.
3. Set the new TRACK_WIDTH as OLD_TRACK_WIDTH * ODOM_HEADING / TURN_DEGREES.
4. Reupload code with new TRACK_WIDTH.
5. Repeat until the heading from odom matches the degrees turned.

Tuning Middle Distance

1. Turn robot 90 degrees counterclockwise.
2. Record the robot's Y position and heading from odom.
3. Set the new MIDDLE_DISTANCE as OLD_MIDDLE_DISTANCE + (ODOM_Y / (ODOM_HEADING * PI / 180)). (ODOM_HEADING * PI / 180 is the heading of the robot in radians)
4. Reupload code with new MIDDLE_DISTANCE.
5. Repeat until the robot's Y position after the turn is close to zero.

PID Tuning

General PID Tuning Principles

For drivetrain PID, PD control is generally fine, with a little bit of I if necessary.

1. Increase kP until the robot oscillates around the target.
2. Increase kD until the robot no longer overshoots the target.
3. If the robot is still a little bit off from the target, increase kI until this no longer happens.

Angular PID Tuning

When tuning angular PID, it helps to first tune in ASYNC mode to remove interference from the settler.

// insert this code snippet into your opcontrol
if (master.get_digital_new_press(DIGITAL_A)) {
  arms::odom::reset({0, 0}, 0);
  arms::chassis::turn(90, arms::ASYNC);
  pros::delay(3000);
}

Once the angular PID looks good in ASYNC mode, remove the ASYNC flag and the delay and check if it's still fine.

Linear PID Tuning

Follow a similar procedure as for Angular PID Tuning.

// insert this code snippet into your opcontrol
if (master.get_digital_new_press(DIGITAL_A)) {
  arms::odom::reset({0, 0}, 0);
  arms::chassis::move(24, arms::ASYNC);
  pros::delay(5000);
}

Boomerang Tuning

// insert this code snippet into your opcontrol
if (master.get_digital_new_press(DIGITAL_A)) {
  arms::odom::reset({0, 0}, 0);
  arms::chassis::move({24, 24, 90});
}

Increase TRACKING_KP if the robot doesn't reach the target point and decrease it if the robot starts oscillating too much.

Increase LEAD_PCT to make boomerang more aggressive and decrease it to make boomerang less aggressive.