how do encoders work on an ftc robot

An encoder is a sensor that tracks the rotational angle or displacement of a mechanism around an axis . FTC robots primarily use two types of encoders:

Relative (incremental) encoders track how far a shaft has rotated since it started tracking (such as at robot power-on), meaning they lose position information when powered off .
Absolute encoders report the exact angle of the shaft relative to a fixed "zero" position .

Relative encoders in FTC use a two-wire "quadrature" protocol to transmit position data . This format uses two signal wires, A and B, which generate square waves 90 degrees apart as the shaft rotates . The direction of rotation determines whether wire A leads wire B or vice versa . The Control or Expansion Hub combines these waves using an XOR operation to produce an output wave, where each rising and falling action represents one "tick" or "count" .

Most FTC-legal motors have built-in relative quadrature encoders, though external encoders (like the REV Through Bore Encoder) can also be plugged into the JST-PH encoder ports on a REV Hub . Ports 0 and 3 on the Expansion Hub use hardware-based Quadrature Encoder Interfaces (QEI) and are highly accurate at high speeds . Ports 1 and 2 are decoded in software using General-Purpose Timers (GPTs) and can lose counts or "lose steps" when paired with high Counts Per Revolution (CPR) encoders spinning quickly . If using a 5V Modern Robotics-compatible encoder, a REV Logic Level Converter is required to connect it to the Hub .

In the FTC SDK, encoders are accessed through the DcMotor object associated with the physical port . Programmers call the getCurrentPosition() method to retrieve the current position as an integer of "counts" or "ticks" . Because relative encoders do not automatically reset to zero when an OpMode starts, programmers must use STOP_AND_RESET_ENCODER to reset the count to zero .

Was this right?

Sources16

Encoders

Game Manual 0·CC BY-NC 4.0

Very commonly in FTC®, you want to know where something is. Whether that is how many times your drivetrain wheel has rotated, what angle your arm is at, or how far your string slides have gone, rotational encoders can help you. In FTC, an encoder refers to any sensor that tracks the rotational angle of a mechanism.

There are two types of encoders commonly used in FTC, relative and absolute encoders. Relative encoders are the ones covered here as they are the more common type.

Open Game Manual 0

Motor Modes and Encoders > Using Encoders

FTC Docs·BSD 3-Clause

Encoders are the devices that track how much a motor shaft has rotated, which the vast majority of motors used in FIRST Tech Challenge have built-in. The encoders on the motors can help track a motor, but they can also be used to help synchronize and control motors via "Motor Modes" built into the Control and Expansion Hub firmware. Did you know that most programmers use these motor modes incorrectly? More on these "Motor Modes" and the correct way to use them can be found on the REV Robotics Encoder documentation (https://docs.revrobotics.com/duo-control/programming/using-encoder-feedback).

Open FTC Docs

Reading and Writing to Hardware > Examples of Using Common Hardware Components > DC Motor > Encoders

Game Manual 0·CC BY-NC 4.0

Term: Encoder — An encoder refers to a device that tracks (generally) rotational movement around an axis.

There are both absolute and relative encoders. An absolute encoder will report at exactly what angle the shaft is compared to its absolute "zero". A relative encoder will report how far the shaft has rotated since it started tracking (for example, when autonomous starts). Relative encoders will have a quadrature output, whereas absolute encoders generally have analog or i2c outputs.

Encoders are used to help find the position of where the robot, or one of its mechanisms, is.

While all FTC legal motors contain built in relative quadrature encoders, they must be wired separately and are not required for use. External encoders may be used and plugged into an encoder port so long as they use the quadrature communication protocol.

Accessing encoders requires calling one method on the DcMotor object, getCurrentPosition(), which returns the current position of the encoder plugged into the port. This number may be arbitrary at the beginning of an opmode, and is not reset to 0 unless STOP_AND_RESET_ENCODERS is used or power is cycled to the expansion hub.

Important: There is no real standardized terminology when dealing with quadrature encoders. The SDK uses "CPR" or Counts Per Revolution by default,. You may also see some datasheets list "PPR" or Pulses per Revolution. One pulse can be equivalent to anywhere from 1 to 4 SDK "counts". Be careful when reading datasheets!

Warning: Encoders with high numbers of Counts per Revolution, such as the REV Through Bore Encoder, can lose steps if plugged into ports 1 or 2. In addition, calls to getVelocity() on a DcMotorEx object may overflow with high counts per revolution encoders, due to the returned number only being a 16 bit signed integer.

Open Game Manual 0

Encoders > What Are Encoders? > Relative Encoders

Game Manual 0·CC BY-NC 4.0

Ranging from the built in encoder in every FTC legal motor to common external encoders like the REV Through Bore encoder, these encoders track the relative position of the shaft or mechanism they are attached to. What this means is that the position output is relative to the initial position at robot power on, meaning position information is lost between power cycles.

Tip: Relative encoders don't reset to zero at the beginning of OpModes! You can use STOP_AND_RESET_ENCODERS to ensure that your encoders are always at zero at the beginning of an OpMode (see below).

All relative encoders in FTC use the "quadrature" protocol to send position information to the expansion hub. As a result, relative encoders must be plugged into the encoder ports located near the motor ports in order to function.

Open Game Manual 0

Encoders > Terminology

Game Manual 0·CC BY-NC 4.0

Count: A "count" (sometimes referred to as a "tick") refers to one increment of the encoder's position. Relative encoders report their position as a number equal to the number of "ticks" or "counts" the encoder has moved from its starting angle.

Counts Per Revolution: The number of "counts" that an encoder reports after it has gone exactly one revolution. This value is commonly used to convert encoder "counts" into degrees or revolutions.

Warning: Quadrature terminology can get very confusing! Some encoders may report "pulses per revolution." One pulse can either equal 1 or 4 counts. Other encoders may report "cycles per revolution", which confusingly have the same acronym as counts per revolution. The best way to check is to plug the encoder into the REV Hub and turn it 1 full revolution, then check what it reports.

Open Game Manual 0

Encoders > Programming Encoders > Reading Encoders

Game Manual 0·CC BY-NC 4.0

In FTC software, quadrature encoders and motors are accessed with the same motor object. What this means is that we can access an encoder's position like so:

Java

int position = motor.getCurrentPosition();

While convenient if one uses the built-in motor encoder, this can easily become confusing if using external encoders. To use external encoders, you must use the motor object associated with the port. For example, if there is a motor in port 1 named "Arm Motor" and an external encoder plugged into encoder port 1, you must do the following to get the encoder's position:

Java

DcMotor motor = hardwareMap.dcMotor.get("Arm Motor");
double position = motor.getCurrentPosition();

Great! We now have the relative position of our encoder, reported in the number of "counts" it is from what it considers to be zero. However, it is often convenient to have the encoder start at zero at the beginning of the OpMode. While it technically does not change anything, it can help with debugging and simplify future code. To do this, we can add a call to reset the encoders before we read them.

Java

DcMotor motor = hardwareMap.dcMotor.get("Arm Motor");
motor.setMode(DcMotor.RunMode.STOP_AND_RESET_ENCODER); // Reset the motor encoder
motor.setMode(DcMotor.RunMode.RUN_WITHOUT_ENCODER); // Turn the motor back on when we are done
int position = motor.getCurrentPosition();

As a note, RUN_WITHOUT_ENCODER does not disable the encoder. It instead tells the SDK not to use the motor encoder for built-in velocity control. We will go over what this means in a later section, but for now, know that it turns the motor back on so we can use it after the encoder is reset.

Now we have our position (in counts) relative to the starting angle of the encoder. We can make a quick program to see this in action. Here, we use a motor encoder plugged into a port named "Arm Motor" in the hardware configuration.

Java

Open Game Manual 0

Encoders > Programming Encoders > Running Motors With Encoders

Game Manual 0·CC BY-NC 4.0

We've learned how to read encoder values, but how do you set where you want to go and tell the motor to go there?

Earlier, we learned about the RUN_WITHOUT_ENCODER mode for the motor. We can use another motor mode, RUN_TO_POSITION, to tell the motor to run to a specific position in ticks, like so:

Java

DcMotor motor = hardwareMap.dcmotor.get("Arm Motor");
motor.setMode(DcMotor.RunMode.RUN_TO_POSITION); // Tells the motor to run to the specific position

Tip: You can find out more about run modes at the official REV Robotics Documentation page (https://docs.revrobotics.com/duo-control/programming/using-encoder-feedback)

However, before we tell the motor to go to a position, we have to tell the motor what position to run to. Note that this value must be an integer. Let's amend the above code to do that.

Warning: Setting the motor to RUN_TO_POSITION mode before setting a target position will throw an error. Be careful not to do that!

Java

DcMotor motor = hardwareMap.dcmotor.get("Arm Motor");
int desiredPosition = 1000; // The position (in ticks) that you want the motor to move to
motor.setTargetPosition(desiredPosition); // Tells the motor that the position it should go to is desiredPosition
motor.setMode(DcMotor.RunMode.RUN_TO_POSITION);

This code tells the motor to move to 1000 ticks, using a PID loop to control the motor's position. You can read more about PID loops here. (https://gm0.org/en/latest/docs/software/concepts/control-loops.html#pid)

We can cap the speed that the motor runs at using the following code:

Java

DcMotor motor = hardwareMap.dcmotor.get("Arm Motor");
int desiredPosition = 1000; // The position (in ticks) that you want the motor to move to
motor.setTargetPosition(desiredPosition); // Tells the motor that the position it should go to is desiredPosition
motor.setMode(DcMotor.RunMode.RUN_TO_POSITION);
motor.setPower(0.5); // Sets the maximum power that the motor can go at

Now, let's use this information to control an arm in an OpMode.

Java

Open Game Manual 0

Encoders > Programming Encoders > Reading Encoders

Game Manual 0·CC BY-NC 4.0

Tip: You can calculate a motor's Counts Per Revolution by taking the base motor's Counts Per Revolution and multiplying it by the gearbox ratio. Be careful to use the actual gearbox ratio when doing this! For example, a 5:1 Ultraplanetary motor would have a count per revolution of 28 * (5.23) = 146.44 because the base motor has 28 Counts Per Revolution and the 5:1 gearbox actually has a 5.23:1 gear ratio. Remember, when using two gearboxes on top of each other, you multiply the gear ratios together.

In the following example, we divide the encoder position by its counts per revolution to obtain the number of revolutions the encoder has rotated. You have to replace [Your Counts Per Revolution Here] with the counts per revolution of your motor, found on its product page or calculated using the above tip.

Java

double CPR = [Your Counts Per Revolution Here];

int position = motor.getCurrentPosition();
double revolutions = position/CPR;

There is one more number we can get: the angle of the shaft. Calculating this number is very simple. We can multiply the number of rotations by 360 (since there are 360 degrees in one revolution). You might notice that this number can go above 360 as the shaft rotates multiple times. As such, we introduce angleNormalized, which will always be between 0 and 360.

Java

double CPR = [Your Counts Per Revolution Here];

int position = motor.getCurrentPosition();
double revolutions = position/CPR;

double angle = revolutions * 360;
double angleNormalized = angle % 360;

Putting it all together, we get the following testing program.

Java

Open Game Manual 0

Driving Example

FTC Docs·BSD 3-Clause

Here is the Java code (method only) for converting an inches of driving target into an encoder counts target. The conversion depends on the drive motors’ counts-per-rotation (CPR), and the diameter of the drive wheels. This example assumes 1:1 gear ratio between the motor and wheel.

This method takes three inputs from the Blocks user, and returns one output (of type int or integer) to the regular Block that calls the myBlock.

Tip: constant named PI, from the inherited class Math. This holds the fixed numeric value 3.14159….

Here is an example of typical usage.

Tip: command. This converts or casts the countsToDrive variable of type double to type int, to be compatible with the required return type. Learn more about type casting here (https://www.w3schools.com/java/java_type_casting.asp) or here (https://www.geeksforgeeks.org/type-conversion-java-examples/).

As programmer, you could modify this example in many ways, such as: - handle a gear ratio between the drive motors and wheels - the second and third parameters could be ‘hard-coded’ into the myBlock, if they will never change - those 2 variables could be initialized in a non-myBlock method and used by multiple myBlock methods in that same Java class

Open FTC Docs

Encoders > Programming Encoders > Tracking Wheels and Spools

Game Manual 0·CC BY-NC 4.0

Up to this point, we have mostly been working with motors rotating something. However, many mechanisms in FTC are linear, and it can be desirable to measure these in a linear unit as well. Fortunately, this is very straightforward. All we need to know is the diameter of the object we are measuring.

Be careful when selecting your diameter. For wheels, it is the outer diameter of the wheel, but for spools, it is the inner diameter of the spool, where the string rests. For chain and belts, it is the "pitch diameter" of the sprocket or pulley.

From here, we can calculate the circumference (the length of the arc of the circle, or the distance the wheel/spool will travel in one rotation)

Java

double diameter = 1.0; // Replace with your wheel/spool's diameter
double circumference = Math.PI * diameter;

double distance = circumference * revolutions;

Note: Units are very important when dealing with FTC programming, so make sure they are always consistent! Whatever units you use for the diameter are the units for your calculated distance. So if you measure your diameter in inches, the reported distance will also be in inches.

Putting this all together with our previous testing program, we get

Java

package org.firstinspires.ftc.teamcode;

import com.qualcomm.robotcore.eventloop.opmode.LinearOpMode;
import com.qualcomm.robotcore.eventloop.opmode.TeleOp;
import com.qualcomm.robotcore.hardware.DcMotor;
@TeleOp
public class SpoolEncoderOpmode extends LinearOpMode {
   @Override
   public void runOpMode() throws InterruptedException {
      // Find a motor in the hardware map named "Arm Motor"
      DcMotor motor = hardwareMap.dcMotor.get("Arm Motor");

      // Reset the motor encoder so that it reads zero ticks
      motor.setMode(DcMotor.RunMode.STOP_AND_RESET_ENCODER);

      // Turn the motor back on, required if you use STOP_AND_RESET_ENCODER
      motor.setMode(DcMotor.RunMode.RUN_WITHOUT_ENCODER);

      waitForStart();

      while (opModeIsActive()) {
            double CPR = [Your Counts Per Revolution Here];

            double diameter = 1.0; // Replace with your wheel/spool's diameter
            double circumference = Math.PI * diameter;

            // Get the current position of the motor
            int position = motor.getCurrentPosition();
            double revolutions = position/CPR;

            double angle = revolutions * 360;
            double angleNormalized = angle % 360;

            double distance = circumference * revolutions;

            //Show the position of the motor on telemetry
            telemetry.addData("Encoder Position", position);
            telemetry.addData("Encoder Revolutions", revolutions);
            telemetry.addData("Encoder Angle (Degrees)", angle);
            telemetry.addData("Encoder Angle - Normalized (Degrees)", angleNormalized);
            telemetry.addData("Linear Distance", distance);
            telemetry.update();
      }
   }
}

Open Game Manual 0

SDK Motors > General Explanation > Motor Encoder

Game Manual 0·CC BY-NC 4.0

Important: There is no real standardized terminology when dealing with quadrature encoders. Here, we use the terms "count" and "tick" to represent a single rising or falling action in the quadrature wave. You may also see some datasheets list "pulses", which can indicate anything from 1 "count" to 4 "counts". Be careful when reading datasheets!

FTC® Encoders use the two wire quadrature format for transmitting relative encoder information. In quadrature, there are two signal wires, A and B. When moving, both A and B generate square waves that are 90 degrees apart, that is one square wave starts half way through the other square wave, and ends half way through the other square wave. When traveling in one direction, the A wire square wave leads the B wire square wave, and in the other direction the B wire square wave leads the A wire square wave. The two waves are combined in XOR to produce the output wave, where each rising and falling action is one "tick", and the faster the wave the faster the encoder is moving.

The REV hub counts the pulses and calculates velocity by using a 5 value "ring buffer", which has a new value added to it every 10 ms. These 5 values are then used to calculate the current velocity.

Warning: It is recommended that quadrature encoders be hooked up to special hardware decoded ports to allow them to be read correctly. The expansion hub contains special hardware for reading quadrature encoders, but because there are only two of those controllers, two of the pins are hooked up in "software" instead (the ports are decoded in software instead of in hardware). Effectively, this means that ports 0 and 3, the two ports connected to the special quadrature ports, will always read accurately. Ports 1 and 2 are connected to the less accurate "software" ports, meaning that with high CPR encoders (encoders that produce more than 4000 counts per revolution, such as the REV Through Bore Encoder or Talon SRX Encoder) they can "lose steps" and drift.

(Figure: An example of a quadrature wave, with channel A leading channel B. Each count is a "count" or "tick")

Open Game Manual 0

Control System Electronics > Expansion Hub Internals > Ports

Game Manual 0·CC BY-NC 4.0

IMPORTANT: Only two of the encoder ports (Ports 0 and 3) can accurately track position/velocity at high speeds. There are two methods of connecting an encoder internally to the Texas Instruments microprocessor, through the Quadrature Encoder Interface (QEI) and through General-Purpose Timers (GPTs). Ports 0 and 3 use the integrated QEI and are extremely accurate at high speeds, whereas encoders using the GPTs often start to loose counts at high speeds. As a result, high Count per Revolution (CPR) encoders (those with more than around 4000 counts per revolution) expected to spin somewhat quickly (such as encoders being used in odometry pods) should NOT be used on ports 1 and 2.
Two XT30 Connectors

Care should be taken when moving around cables as these connectors have been known to fail and break off the board.
In addition, XT30s will wear and get loose with time. See XT30 Pins are Compressed - Expansion Hub Troubleshooting (https://docs.revrobotics.com/duo-control/troubleshooting-the-control-system/expansion-hub-troubleshooting#xt30-pins-are-compressed) for details on the issue and how to fix it.
USB Mini-B Connector

Uses the FTDI FT230XQ chip to bridge the internal UART to USB, allowing an Expansion Hub to connect over USB to a Control Hub, Android device, computer, or other such device. The FT230XQ is capable of USB Full Speed (12 Mbps) on the USB side and 3 MBaud on the UART side, and 5V output to charge a phone. According to REV, the 5V output is not compatible with any of the remaining Android phones still legal in FTC. This USB chip is disabled by the compute board of the Control Hub, meaning this port is not functional out-of-the-box on a Control Hub.
Internal Connector

Open Game Manual 0

Encoders > Programming Encoders > Reading Encoders

Game Manual 0·CC BY-NC 4.0

package org.firstinspires.ftc.teamcode;

import com.qualcomm.robotcore.eventloop.opmode.LinearOpMode;
import com.qualcomm.robotcore.eventloop.opmode.TeleOp;
import com.qualcomm.robotcore.hardware.DcMotor;
@TeleOp
public class EncoderOpmode extends LinearOpMode {
    @Override
    public void runOpMode() throws InterruptedException {
        // Find a motor in the hardware map named "Arm Motor"
        DcMotor motor = hardwareMap.dcMotor.get("Arm Motor");

        // Reset the motor encoder so that it reads zero ticks
        motor.setMode(DcMotor.RunMode.STOP_AND_RESET_ENCODER);

        // Turn the motor back on, required if you use STOP_AND_RESET_ENCODER
        motor.setMode(DcMotor.RunMode.RUN_WITHOUT_ENCODER);

        waitForStart();

        while (opModeIsActive()) {
            double CPR = [Your Counts Per Revolution Here];

            // Get the current position of the motor
            int position = motor.getCurrentPosition();
            double revolutions = position/CPR;

            double angle = revolutions * 360;
            double angleNormalized = angle % 360;

            // Show the position of the motor on telemetry
            telemetry.addData("Encoder Position", position);
            telemetry.addData("Encoder Revolutions", revolutions);
            telemetry.addData("Encoder Angle (Degrees)", angle);
            telemetry.addData("Encoder Angle - Normalized (Degrees)", angleNormalized);
            telemetry.update();
        }
    }
}

Open Game Manual 0

Encoders (Rotation Counters)

FTC Docs·BSD 3-Clause

REV HD Hex Motor

^^^

+++

Built-in Encoder in the REV HD Hex Motor

REV Through Bore Encoder

^^^

+++

REV Through Bore Encoder, in incremental mode.

An encoder is a device that measures the rotational displacement around an axis. Most legal FIRST Tech Challenge motors contain a built in quadrature encoder that is compatible with a REV Hub. It is also possible to use a standalone incremental encoder like a REV Through Bore Encoder (shown above). An incremental encoder works by sending out a "tick" per partial rotation of the shaft. More information on how many ticks are output per rotation can be found on the manufacturer's website. An absolute encoder is able to indicate the displacement of the shaft from its starting position and the the exact angle the shaft is currently at relative to a "zero" position.

Open FTC Docs

Dead Wheels > Encoders

Game Manual 0·CC BY-NC 4.0

A lot of the localization done in software relies on readings from encoders. encoders are sensors that track "counts" or "ticks," which are values that represent a certain amount of a rotation. Different encoders might have a different number of counts per revolution (CPR), which is also sometimes also called ticks per revolution. The greater the number of counts, the more precise the data.

Encoders are plugged into the JST-PH ports in the REV hubs. These encoders can either be built-in to the motors or external. External encoders will still need to be plugged into an encoder port but are not related to the motor in that port. Through software, we can use the motor object to determine the position of the encoder. This should be done with motors that do not use encoders. If you're using dead wheels, you will not need the drive motor encoder ports, so those are potential ports you might want to use.

If one chooses to design dead wheels, there are only two recommended encoders that one should use for FTC: REV Through-Bore Encoders and U.S. Digital S4T Encoders.

Open Game Manual 0

Troubleshooting Common Control System Issues > REV Robotics Control and Expansion Hubs > 5V Modern Robotics-Compatible Encoders

FTC Docs·BSD 3-Clause

If a team has a 12V DC motor with a 5V encoder designed to connect to a Modern Robotics DC motor controller, the team will need one REV Robotics Logic Level Converter per 5V encoder to connect the encoder to the Control or Expansion Hub.

If a team has a 5V, Modern Robotics-compatible I2C sensor, the team will need a REV Robotics Logic Level Converter plus a REV Robotics Sensor Cable Adapter to properly connect the 5V device to a Control or Expansion Hub.

Open FTC Docs