Encoder Library

Encoder provides 4X counting mode and highly optimized code (explained below) when running on Teensy or Arduino boards. Chipkit boards have limited support.

Update: TLB has posted code to use Teensy 3.1's hardware quadrature encoders.

Hardware Requirements

Encoders have 2 signals, which must be connected to 2 pins. There are three options.

1. Best Performance: Both signals connect to interrupt pins.
2. Good Performance: First signal connects to an interrupt pin, second to a non-interrupt pin.
3. Low Performance: Both signals connect to non-interrupt pins, details below.

Low cost encoders only connect their pins to ground. Encoder will activate the on-chip pullup resistors. If you connect lengthy wires, adding 1K pullup resistors may provide a better signal.

Basic Usage

Create an Encoder object, using 2 pins. You may create mulitple Encoder objects, where each uses its own 2 pins. The first pin should be capable of interrupts. If both pins have interrupt capability, both will be used for best performance. Encoder will also work in low performance polling mode if neither pin has interrupts.

Returns the accumulated position. This number can be positive or negative.

Set the accumulated position to a new number.

Understanding Quadrature Encoded Signals

The Encoder library monitors the 2 pins and updates a count of the relative change in position. The library updates its count at each change, which is often called 4X counting, since 4 counts are available for each physical mark or hole in the encoder hardware.

Example Program

/* Encoder Library - TwoKnobs Example
 * https://www.pjrc.com/teensy/td_libs_Encoder.html
 *
 * This example code is in the public domain.
 */

#include <Encoder.h>

// Change these pin numbers to the pins connected to your encoder.
//   Best Performance: both pins have interrupt capability
//   Good Performance: only the first pin has interrupt capability
//   Low Performance:  neither pin has interrupt capability
Encoder knobLeft(5, 6);
Encoder knobRight(7, 8);
//   avoid using pins with LEDs attached

void setup() {
  Serial.begin(9600);
  Serial.println("TwoKnobs Encoder Test:");
}

long positionLeft  = -999;
long positionRight = -999;

void loop() {
  long newLeft, newRight;
  newLeft = knobLeft.read();
  newRight = knobRight.read();
  if (newLeft != positionLeft || newRight != positionRight) {
    Serial.print("Left = ");
    Serial.print(newLeft);
    Serial.print(", Right = ");
    Serial.print(newRight);
    Serial.println();
    positionLeft = newLeft;
    positionRight = newRight;
  }
  // if a character is sent from the serial monitor,
  // reset both back to zero.
  if (Serial.available()) {
    Serial.read();
    Serial.println("Reset both knobs to zero");
    knobLeft.write(0);
    knobRight.write(0);
  }
}

Interrupt Latency Requirements

SoftwareSerial and NewSoftSerial are very likely to cause problems.

Optimized Interrupt Option

// This optional setting causes Encoder to use more optimized code,
// It must be defined before Encoder.h is included.
#define ENCODER_OPTIMIZE_INTERRUPTS
#include <Encoder.h>

Encoder will directly define interrupts the minimum overhead. The downside is a conflict if any other code in your sketch or any libraries you use require attachInterrupt().

Maximum Speed and CPU Usage

Emulating Quadrature Encoded Signals

                        +5V
                         |        Quadrature Encoder Signal Emulator
 Clock                   |
 Input o----*--------------------------      ---------------------------o Output1
            |            |14           |    |
            |     _______|_______      |    |     _______________ 
            |    |    CD4013     |     |    |    |    CD4013     |
            |  5 |               | 1   |    |  9 |               | 13
        ---------|  D         Q  |-----|----*----|  D         Q  |------o Output2
       |    |    |               |     |         |               |
       |    |  3 |               |     |      11 |               |
       |     ----|> Clk          |      ---------|> Clk          |
       |         |               |               |               |
       |       6 |               |             8 |               |
       |     ----|  S            |           ----|  S            |
       |    |    |               |          |    |               |
       |    |  4 |            _  | 2        | 10 |            _  | 12
       |    *----|  R         Q  |---       *----|  R         Q  |----
       |    |    |               |          |    |               |    |
       |    |    |_______________|          |    |_______________|    |
       |    |            |                  |                         |
       |    |            | 7                |                         |
       |    |            |                  |                         |
        --------------------------------------------------------------
            |            |                  |
            |            |                  |
          -----        -----              -----
           ---          ---                ---
            -            -                  -

Measuring Maximum Interrupt Rates

SpeedTest: 147 mV (close to zero CPU remaining) at 127 kHz interrupt rate.

If using a mechanical system where you reach a speed limit imposed by your motors or other hardware, the amount this voltage has decreased, compared to the baseline, should give you a good approximation of the portion of available CPU time Encoder is consuming at your maximum speed.

Low Performance Polling Mode

With Arduino Uno, Duemilanove or Mega, Serial.print() can cause trouble. Arduino 1.0 provides transmit buffering, which works much better than Arduino 0023 and earlier. With either, a high speed baud rate should be used, and minimizing the amount of data transmitted helps.

As of January 2012, Chipkit does not support attachInterrupt's CHANGE mode so low performance polling mode is always used. Chipkit's Serial.print() lacks transmit buffering (same issue as Arduino Uno on pre-1.0 Arduino). Chipkit does not support the pullup resistors, so you must provide real resistors on both signals. The Chipkit developers have been contacted regarding these issues. Hopefully future versions of MPIDE will fix these problems.

Other Encoder Pages

This Arduino Playground page has the most info and example code.

More links:

https://arduino.cc/playground/Main/RotaryEncoderAcceleration
https://www.circuitsathome.com/mcu/reading-rotary-encoder-on-arduino
https://www.marginallyclever.com/2011/03/using-a-rotary-encoder-with-arduino/
https://hacks.ayars.org/2009/12/using-quadrature-encoder-rotary-switch.html
https://www.helicron.net/avr/quadrature/