ESP32Encoder Library

ESP32Encoder is a library that leverages the ESP32 Pulse Counter (PCNT) hardware peripheral to track quadrature encoders.

Key characteristics:

• Low CPU Overhead: Instead of generating an interrupt for every pulse, the library uses the hardware's interrupt mechanism which only triggers when the 16-bit counter buffer overflows. This results in a very small interrupt footprint.
• Hardware Limits: The number of supported encoders depends on the specific ESP32 chip being used:
  • ESP32 and ESP32C2: Supports up to 8 simultaneous encoders.
  • ESP32S3: Supports only 2 hardware-accelerated encoders (due to having only 2 PCNT modules).
  • ESP32C3: Does not support hardware-accelerated encoders as it lacks the PCNT hardware.

The library supports three different modes for reading incremental encoders:

1. Full Quadrature: Performs a count increment on all 4 edges of the signals.
2. Half Quadrature: Performs counts on the rising and falling edges of a single channel.
3. Single Edge Count: Counts only the rising edge of the A channel.

You can specify whether to use weak internal pull-up or pull-down resistors using the useInternalWeakPullResistors configuration option.

Available enum types:

• UP: Enables internal pull-up resistors.
• DOWN: Enables internal pull-down resistors.
• NONE: Disables internal resistors.

Switch-style encoder modules (like the KY-040) often exhibit significant electrical bouncing that exceeds the standard PCNT hardware debouncing limits.

To mitigate this, you should:

1. Add electrical debouncing (capacitors) in the range of 0.1 - 2 µF per encoder line to ground.
2. Call setFilter() with a value of 1023 immediately after attaching the encoder to enable the maximum hardware debouncing capability.

// Example pattern for switch-style encoders
encoder.setFilter(1023);

The following static members allow you to configure the behavior of all ESP32Encoder instances:

• useInternalWeakPullResistors (puType): Sets whether to use internal pull-up (puType::up), pull-down (puType::down), or no pull resistors (puType::none).
• isrServiceCpuCore (uint32_t): Sets the CPU core on which the ISR service runs. Use 0xffffffff for the default core.

// Example: Use internal pull-ups and assign ISR to core 1
ESP32Encoder::useInternalWeakPullResistors = puType::up;
ESP32Encoder::isrServiceCpuCore = 1;

The InterruptEncoder class provides a way to read quadrature encoders using interrupts instead of the ESP32 hardware PCNT peripheral. This is useful for encoders where hardware peripheral limitations or pin availability are concerns.

To use it, instantiate the class and call attach(aPinNum, bPinNum) to specify the pins used for the encoder phases. You can then retrieve the current position using read().

InterruptEncoder encoder;

void setup() {
  // Attach encoder to pins 18 and 19
  encoder.attach(18, 19);
}

void loop() {
  // Read the current count
  int64_t currentCount = encoder.read();
}

Use the following methods to attach physical GPIO pins to the encoder instance. The choice of method determines the resolution and edge detection mode of the PCNT peripheral:

• attachFullQuad(int aPinNumber, int bPinNumber): Full quadrature mode (4x encoding).
• attachHalfQuad(int aPinNumber, int bPinNumber): Half quadrature mode (2x encoding).
• attachSingleEdge(int aPinNumber, int bPinNumber): Single edge mode (1x encoding).

ESP32Encoder encoder;
encoder.attachFullQuad(18, 19); // Attach pins 18 and 19 in full quadrature mode

The ESP32Encoder class provides several methods to interact with the current pulse count:

• getCount(): Returns the current encoder count as an int64_t.
• clearCount(): Returns the current count and resets it to 0.
• pauseCount(): Pauses the counting mechanism and returns the current count.
• resumeCount(): Resumes counting.
• setCount(int64_t value): Manually sets the encoder count to a specific value.
• setFilter(uint16_t value): Sets a digital filter value to mitigate noise on the input pins.

int64_t current_pos = encoder.getCount();
encoder.setCount(0); // Reset position

To stop using the attached pins and release the PCNT unit, call detach(). Note that detatch() is a deprecated alias for detach().

encoder.detach();

The InterruptEncoder class exposes the following public members:

Methods

• void attach(int aPinNum, int bPinNum): Configures the encoder with the specified pins for phase A and phase B.
• int64_t read(): Returns the current encoder count.

Public Members

• int apin: The pin number assigned to phase A.
• int bpin: The pin number assigned to phase B.
• volatile bool aState: The current state of phase A.
• volatile bool bState: The current state of phase B.
• volatile int64_t count: The current accumulated encoder count.
• volatile int64_t microsLastA: Timestamp (in microseconds) of the last transition on phase A.
• volatile int64_t microsTimeBetweenTicks: The time elapsed between the last two ticks in microseconds.