ESP32RotaryEncoder.cpp

#include "ESP32RotaryEncoder.h"

#if defined( ESP32 )
  #define RE_ISR_ATTR IRAM_ATTR

  #ifdef ARDUINO_ISR_ATTR
    #undef ARDUINO_ISR_ATTR
    #define ARDUINO_ISR_ATTR IRAM_ATTR
  #endif

  #if defined( ESP_ARDUINO_VERSION ) && ( ESP_ARDUINO_VERSION == ESP_ARDUINO_VERSION_VAL(2,0,10) )
    /**
     * BUG ALERT!
     *
     * With Arduino-ESP32 core 2.0.10, the #include statement below fails to compile due to a bug.
     * Also see `attachInterrupts()` for the note about the `attachInterrupt()` macro in 2.x cores.
     */
    #error Please upgrade the Arduino-ESP32 core to use this library.
  #else
    #include <FunctionalInterrupt.h>
  #endif
#endif

RotaryEncoder::RotaryEncoder( uint8_t encoderPinA, uint8_t encoderPinB, int8_t buttonPin, int8_t vccPin, uint8_t encoderSteps )
  : encoderPinA{ encoderPinA },
    encoderPinB{ encoderPinB },
    buttonPin{ buttonPin },
    vccPin{ vccPin },
    encoderSteps{ encoderSteps == 0 ? RE_DEFAULT_STEPS : encoderSteps }
{
  ESP_LOGD( LOG_TAG, "Initialized: A = %u, B = %u, Button = %i, VCC = %i, Steps = %u", encoderPinA, encoderPinB, buttonPin, vccPin, this->encoderSteps );
}

RotaryEncoder::~RotaryEncoder()
{
  detachInterrupts();

  esp_timer_stop( loopTimer );
  esp_timer_delete( loopTimer );
}

void RotaryEncoder::setBoundaries( long minValue, long maxValue, bool circleValues )
{
  ESP_LOGD( LOG_TAG, "boundary minValue = %ld, maxValue = %ld, circular = %s", minValue, maxValue, ( circleValues ? "true" : "false" ) );
  if( minValue > maxValue )
    ESP_LOGW( LOG_TAG, "Minimum value (%ld) is greater than maximum value (%ld); behavior is undefined.", minValue, maxValue );

  portENTER_CRITICAL( &mux );
  this->minEncoderValue = minValue;
  this->maxEncoderValue = maxValue;
  this->circleValues = circleValues;
  portEXIT_CRITICAL( &mux );
}

void RotaryEncoder::setMinValue( long minValue )
{
  ESP_LOGD( LOG_TAG, "minValue = %ld", minValue );

  portENTER_CRITICAL( &mux );
  this->minEncoderValue = minValue;
  portEXIT_CRITICAL( &mux );
}

void RotaryEncoder::setMaxValue( long maxValue )
{
  ESP_LOGD( LOG_TAG, "maxValue = %ld", maxValue );

  portENTER_CRITICAL( &mux );
  this->maxEncoderValue = maxValue;
  portEXIT_CRITICAL( &mux );
}

void RotaryEncoder::setCircular( bool circleValues )
{
  ESP_LOGD( LOG_TAG, "Boundaries %s circular", ( circleValues ? "are" : "are not" ) );

  portENTER_CRITICAL( &mux );
  this->circleValues = circleValues;
  portEXIT_CRITICAL( &mux );
}

void RotaryEncoder::setStepValue( long stepValue )
{
  ESP_LOGD( LOG_TAG, "stepValue = %ld", stepValue );
  if( stepValue > maxEncoderValue || stepValue < minEncoderValue )
    ESP_LOGW( LOG_TAG, "Step value (%ld) is outside the bounds (%ld...%ld); behavior is undefined.", stepValue, minEncoderValue, maxEncoderValue );

  portENTER_CRITICAL( &mux );
  this->stepValue = stepValue;
  portEXIT_CRITICAL( &mux );
}

void RotaryEncoder::onTurned( EncoderCallback f )
{
  callbackEncoderChanged = f;
}

void RotaryEncoder::onPressed( ButtonCallback f )
{
  callbackButtonPressed = f;
}

void RotaryEncoder::beginLoopTimer()
{
  /**
   * We're using esp_timer.h from ESP32 SDK rather than esp32-hal-timer.h from Arduino API
   * because the `timerAttachInterrupt()` won't accept std::bind like `attachInterrupt()` in
   * FunctionalInterrupt will.  We have a static method that `timerAttachInterrupt()` will take,
   * but we'd lose instance context.  But the `esp_timer_create_args_t` will let us set a callback
   * argument, which we set to `this`, so that the static method maintains instance context.
   *
   * As of 29 September 2023, there is an open issue to allow `std::function` in esp32-hal-timer:
   * https://github.com/espressif/arduino-esp32/issues/8427
   *
   * ...for now (and maybe forever?), we'll do it this way.
   */

  esp_timer_create_args_t _timerConfig;
  _timerConfig.arg = this;
  _timerConfig.callback = reinterpret_cast<esp_timer_cb_t>( timerCallback );
  _timerConfig.dispatch_method = ESP_TIMER_TASK;
  _timerConfig.skip_unhandled_events = true;
  _timerConfig.name = "RotaryEncoder::loop_ISR";

  esp_timer_create( &_timerConfig, &loopTimer );
  esp_timer_start_periodic( loopTimer, RE_LOOP_INTERVAL );
}

void RotaryEncoder::timerCallback( void *self )
{
  RotaryEncoder *instance = (RotaryEncoder *)self;
  instance->loop();
}

void RotaryEncoder::attachInterrupts()
{
  #if defined( BOARD_HAS_PIN_REMAP ) && ( ESP_ARDUINO_VERSION < ESP_ARDUINO_VERSION_VAL(3,0,0) )
    /**
     * The io_pin_remap.h in Arduino-ESP32 cores of the 2.0.x family
     * (since 2.0.10) define an `attachInterrupt()` macro that folds-in
     * a call to `digitalPinToGPIONumber()`, but FunctionalInterrupt.cpp
     * does this too, so we actually don't need the macro at all.
     * Since 3.x the call inside the function was removed, so the wrapping
     * macro is useful again.
     */
    #undef attachInterrupt
  #endif

  attachInterrupt( encoderPinA, std::bind( &RotaryEncoder::_encoder_ISR, this ), CHANGE );
  attachInterrupt( encoderPinB, std::bind( &RotaryEncoder::_encoder_ISR, this ), CHANGE );

  if( buttonPin > RE_DEFAULT_PIN )
    attachInterrupt( buttonPin, std::bind( &RotaryEncoder::_button_ISR, this ), CHANGE );

  ESP_LOGD( LOG_TAG, "Interrupts attached" );
}

void RotaryEncoder::detachInterrupts()
{
  detachInterrupt( encoderPinA );
  detachInterrupt( encoderPinB );
  detachInterrupt( buttonPin );

  ESP_LOGD( LOG_TAG, "Interrupts detached" );
}

void RotaryEncoder::begin( bool useTimer )
{
  resetEncoderValue();

  _lastRotaryInterruptTime = 0;
  _previousAB = 3;
  _encoderPosition = 0;
  encoderChangedFlag = false;

  buttonPressedFlag = false;
  _lastButtonInterruptTime = 0;
  buttonPressedTime = 0;
  buttonPressedDuration = 0;

  pinMode( encoderPinA, encoderPinMode );
  pinMode( encoderPinB, encoderPinMode );

  if( buttonPin > RE_DEFAULT_PIN )
    pinMode( buttonPin, buttonPinMode );

  if( vccPin > RE_DEFAULT_PIN )
  {
    pinMode( vccPin, OUTPUT );
    digitalWrite( vccPin, HIGH );
  }

  delay( 20 );
  attachInterrupts();

  if( useTimer )
    beginLoopTimer();

  ESP_LOGD( LOG_TAG, "RotaryEncoder active" );
}

bool RotaryEncoder::isEnabled()
{
  return _isEnabled;
}

void RotaryEncoder::enable()
{
  if( _isEnabled.exchange(true) )
    return;

  attachInterrupts();

  ESP_LOGD( LOG_TAG, "Input enabled" );
}

void RotaryEncoder::disable()
{
  if( !_isEnabled.exchange(false) )
    return;

  detachInterrupts();

  ESP_LOGD( LOG_TAG, "Input disabled" );
}

bool RotaryEncoder::buttonPressed()
{
  if( !_isEnabled ) {
    return false;
  }

  bool wasPressed;
  unsigned long duration;

  portENTER_CRITICAL( &mux );
  wasPressed = buttonPressedFlag;
  buttonPressedFlag = false;
  duration = buttonPressedDuration;
  portEXIT_CRITICAL( &mux );

  if( wasPressed )
    ESP_LOGD( LOG_TAG, "Button pressed for %lu ms", duration );

  return wasPressed;
}

bool RotaryEncoder::encoderChanged()
{
  if( !_isEnabled ) {
    return false;
  }

  bool hasChanged;
  long value;

  portENTER_CRITICAL( &mux );
  hasChanged = encoderChangedFlag;
  encoderChangedFlag = false;
  value = currentValue;
  portEXIT_CRITICAL( &mux );

  if( hasChanged )
      ESP_LOGD( LOG_TAG, "Knob turned; value: %ld", value );

  return hasChanged;
}

long RotaryEncoder::getEncoderValue()
{
  portENTER_CRITICAL( &mux );
  long value = currentValue;
  portEXIT_CRITICAL( &mux );

  return value;
}

long RotaryEncoder::constrainValue( long value ) const
{
  if( value < minEncoderValue )
    return circleValues ? maxEncoderValue : minEncoderValue;

  else if( value > maxEncoderValue )
    return circleValues ? minEncoderValue : maxEncoderValue;

  else
    return value;
}

void RotaryEncoder::setEncoderValue( long newValue )
{
  long constrainedValue = constrainValue(newValue);
  if( constrainedValue != newValue )
    ESP_LOGD( LOG_TAG, "Encoder value '%ld' constrained to '%ld'", constrainedValue, newValue );

  long oldValue;
  portENTER_CRITICAL( &mux );
  oldValue = currentValue;
  currentValue = constrainedValue;
  portEXIT_CRITICAL( &mux );

  if( constrainedValue != oldValue )
    ESP_LOGD( LOG_TAG, "Overriding encoder value from '%ld' to '%ld'", oldValue, constrainedValue );
}

void ARDUINO_ISR_ATTR RotaryEncoder::loop()
{
  if( callbackEncoderChanged != NULL && encoderChanged() )
    callbackEncoderChanged( getEncoderValue() );

  if( callbackButtonPressed != NULL && buttonPressed() )
    callbackButtonPressed( buttonPressedDuration );
}

void ARDUINO_ISR_ATTR RotaryEncoder::_button_ISR()
{
  if ( !_isEnabled ) {
    return;
  }

  portENTER_CRITICAL_ISR( &mux );

  // Simple software de-bounce
  if( ( millis() - _lastButtonInterruptTime ) < 30 )
  {
    portEXIT_CRITICAL_ISR( &mux );
    return;
  }

  // HIGH = idle, LOW = active
  bool isPressed = !digitalRead( buttonPin );

  if( isPressed )
  {
    buttonPressedTime = millis();
  }
  else
  {
    unsigned long now = millis();
    buttonPressedDuration = now - buttonPressedTime;

    buttonPressedFlag = true;
  }

  _lastButtonInterruptTime = millis();

  portEXIT_CRITICAL_ISR( &mux );
}

void ARDUINO_ISR_ATTR RotaryEncoder::_encoder_ISR()
{
  if ( !_isEnabled ) {
    return;
  }

  portENTER_CRITICAL_ISR( &mux );

  /**
   * Almost all of this came from a blog post by Garry on GarrysBlog.com:
   * https://garrysblog.com/2021/03/20/reliably-debouncing-rotary-encoders-with-arduino-and-esp32/
   *
   * Read more about how this works here:
   * https://www.best-microcontroller-projects.com/rotary-encoder.html
   */

  bool valueChanged = false;

  _previousAB <<=2;  // Remember previous state

  if( digitalRead( encoderPinA ) ) _previousAB |= 0x02; // Add current state of pin A
  if( digitalRead( encoderPinB ) ) _previousAB |= 0x01; // Add current state of pin B

  _encoderPosition += encoderStates[( _previousAB & 0x0f )];


  /**
   * Based on how fast the encoder is being turned, we can apply an acceleration factor
   */

  unsigned long speed = micros() - _lastRotaryInterruptTime;

  long _stepValue;
  if( speed > 40000UL )                            // Greater than 40 milliseconds
    _stepValue = this->stepValue;                  // Increase/decrease by 1 x stepValue

  else if( speed > 20000UL )                       // Greater than 20 milliseconds
    _stepValue = ( this->stepValue <= 9 ) ?        // Increase/decrease by 3 x stepValue
      this->stepValue : ( this->stepValue * 3 )    // But only if stepValue > 9
    ;

  else                                             // Faster than 20 milliseconds
    _stepValue = ( this->stepValue <= 100 ) ?      // Increase/decrease by 10 x stepValue
      this->stepValue : ( this->stepValue * 10 )   // But only if stepValue > 100
    ;


  /**
   * Update counter if encoder has rotated a full detent
   * For the following comments, we'll assume it's 4 steps per detent
   * The tripping point is >= STEPS or <= -STEPS
   */

  if( _encoderPosition >= encoderSteps )        // Four steps forward
  {
    this->currentValue = constrainValue(this->currentValue + _stepValue);
    valueChanged = true;
  }
  else if( _encoderPosition <= -encoderSteps )  // Four steps backwards
  {
    this->currentValue = constrainValue(this->currentValue - _stepValue);
    valueChanged = true;
  }

  if( valueChanged )
  {
    encoderChangedFlag = true;

    // Reset our "step counter"
    _encoderPosition = 0;

    // Remember current time so we can calculate speed
    _lastRotaryInterruptTime = micros();
  }

  portEXIT_CRITICAL_ISR( &mux );
}