RotaryEncoderPCNT

Cross-platform PCNT hardware abstraction

#include <RotaryEncoderPCNT.h>

Public Member Functions

 RotaryEncoderPCNT (int a, int b, int start_pos, uint16_t glitch_ns)
 
 RotaryEncoderPCNT (int a, int b, int start_pos)
 
 RotaryEncoderPCNT (int a, int b)
 
 RotaryEncoderPCNT ()
 
 ~RotaryEncoderPCNT ()
 
void init ()
 
void deinit ()
 
int position ()
 
void setPosition (int pos)
 
void zero ()
 

Public Attributes

uint8_t pin_a = 255
 
uint8_t pin_b = 255
 
uint16_t glitch_time = 1000
 

Detailed Description

Cross-Platform Rotary Encoder PCNT Driver

Provides unified interface for ESP32 PCNT peripheral across different ESP-IDF versions. Handles quadrature encoder signal processing with hardware acceleration and noise filtering.

Design Principles:

  • Single interface for multiple ESP-IDF API versions
  • Hardware acceleration for minimal CPU overhead
  • Configurable filtering for noise immunity
  • Position offset support for application flexibility
  • Automatic resource cleanup in destructor

Threading Considerations:

  • PCNT hardware is inherently thread-safe
  • position() calls are atomic hardware reads
  • Multiple instances can use different PCNT units
  • No shared state between encoder instances

Constructor & Destructor Documentation

◆ RotaryEncoderPCNT() [1/4]

RotaryEncoderPCNT::RotaryEncoderPCNT ( int  a,
int  b,
int  start_pos,
uint16_t  glitch_ns 
)
inline

Full parameter constructor Creates encoder instance with complete configuration

Parameters
aGPIO pin number for encoder signal A (CLK)
bGPIO pin number for encoder signal B (DT)
start_posInitial position offset value
glitch_nsGlitch filter time in nanoseconds (noise immunity)

◆ RotaryEncoderPCNT() [2/4]

RotaryEncoderPCNT::RotaryEncoderPCNT ( int  a,
int  b,
int  start_pos 
)
inline

Constructor with starting position Uses default glitch filter setting

Parameters
aGPIO pin number for encoder signal A (CLK)
bGPIO pin number for encoder signal B (DT)
start_posInitial position offset value

◆ RotaryEncoderPCNT() [3/4]

RotaryEncoderPCNT::RotaryEncoderPCNT ( int  a,
int  b 
)
inline

Basic constructor with pin assignment Uses default starting position and glitch filter

Parameters
aGPIO pin number for encoder signal A (CLK)
bGPIO pin number for encoder signal B (DT)

◆ RotaryEncoderPCNT() [4/4]

RotaryEncoderPCNT::RotaryEncoderPCNT ( )
inline

Default constructor Requires manual pin assignment before init()

◆ ~RotaryEncoderPCNT()

RotaryEncoderPCNT::~RotaryEncoderPCNT ( )
inline

Destructor with automatic cleanup Ensures proper PCNT hardware deinitialization

Member Function Documentation

◆ deinit()

void RotaryEncoderPCNT::deinit ( )

Deinitialize PCNT hardware and free resources Stops counter operation and releases PCNT peripheral

Cleanup Operations:

  • Stop PCNT counter operation
  • Disable PCNT unit and channels
  • Free allocated handles (ESP-IDF 5.x)
  • Reset internal state variables
Note
Safe to call multiple times
Automatic cleanup in destructor

◆ init()

void RotaryEncoderPCNT::init ( )

Initialize PCNT hardware for quadrature encoder processing Configures GPIO pins, PCNT channels, and glitch filtering

Configuration Steps:

  1. Set GPIO pins as inputs with pull-up resistors
  2. Configure PCNT channels for quadrature decoding
  3. Set up glitch filter for noise immunity
  4. Initialize counter and start operation

Platform Handling:

  • ESP-IDF 4.4: Uses legacy pcnt_config_t structure
  • ESP-IDF 5.x: Uses new pcnt_unit_config_t structure
  • Automatic API selection based on compile-time detection
Note
Must be called before position reading operations
Not thread-safe during initialization - call from single thread

CloudMouse SDK - Cross-Platform Rotary Encoder PCNT Implementation

Implementation of ESP32 PCNT hardware abstraction with automatic ESP-IDF version detection and API compatibility handling for rotary encoder quadrature processing.

◆ position()

int RotaryEncoderPCNT::position ( )

Read current encoder position with offset applied Returns hardware counter value plus configured offset

Returns
Current position as signed integer Positive values = clockwise from zero Negative values = counter-clockwise from zero Range: -32768 to +32767 (with offset)

Technical Notes:

  • Hardware atomic read operation
  • Includes configured position offset
  • Error handling returns last valid value (ESP-IDF 4.4)
  • Thread-safe for concurrent access

◆ setPosition()

void RotaryEncoderPCNT::setPosition ( int  pos)

Set encoder position with counter reset Updates offset and clears hardware counter to establish new zero point

Parameters
posNew position value to set as current

Operations:

  1. Update internal offset to target position
  2. Clear hardware counter to zero
  3. Subsequent reads return: hardware_count + new_offset

Use Cases:

  • Establish application-specific zero points
  • Reset position after reaching limits
  • Synchronize with external position references

◆ zero()

void RotaryEncoderPCNT::zero ( )

Reset encoder to default starting position Convenience method equivalent to setPosition(START_POS_DEFAULT)

Resets both hardware counter and offset to initial state

Member Data Documentation

◆ glitch_time

uint16_t RotaryEncoderPCNT::glitch_time = 1000

◆ pin_a

uint8_t RotaryEncoderPCNT::pin_a = 255

◆ pin_b

uint8_t RotaryEncoderPCNT::pin_b = 255