Arduino library · Input

ESP32RotaryEncoder: an example that runs

Yes. You can use the ESP32RotaryEncoder library online in Mokxi with nothing to install, and the sketch runs in your browser against the simulated part (Rotary encoder, KY-040). The example below, "A wrapping value and a button on an ESP32-C3", runs on the ESP32-C3-DevKitM-1.

Built in on Mokxi: #include <ESP32RotaryEncoder.h> and it builds, with nothing to install. Free, and no account needed.

What ESP32RotaryEncoder does

A rotary encoder and its button on an ESP32, counted from pin interrupts, with bounds, wrap-around and onTurned() and onPressed() callbacks. That is what ESP32RotaryEncoder, by Matthew Clark, covers. The sketch below uses it on the ESP32-C3-DevKitM-1: “A wrapping value and a button on an ESP32-C3”.

The interface of Matthew Clark's "ESP32RotaryEncoder" library (MaffooClock, 1.2.x): a rotary encoder and its button on an ESP32, counted from pin interrupts, with bounds and callbacks.

Use the rotary part (a KY-040): CLK on pin A and DT on pin B turn clockwise up. The module has pull-ups on CLK and DT but none on SW, so EncoderType::SW_FLOAT (or FLOATING) is the right one when the button is used.

The calls follow release 1.2.0 of the library, so a sketch written here builds on a real board too. The example is the one Mokxi's own tests build and run, so what is printed here is what runs.

Library Manager nameESP32RotaryEncoder
AuthorMatthew Clark
Include#include <ESP32RotaryEncoder.h>
BoardsESP32-C3, ESP32-C6, Seeed XIAO ESP32-C3, ESP32-C3 SuperMini, Seeed XIAO ESP32-C6, ESP32 DevKit, ESP32-DevKitC V4, LOLIN32 Lite, Wemos D1 R32, Cheap Yellow Display, TTGO T-Display, ESP32-S3-DevKitC-1, Seeed XIAO ESP32-S3, Arduino Nano ESP32
In the simulatorSimulated: it runs against the part the way it does on the bench.
Parts it drivesRotary encoder, KY-040

Install it

It builds on ESP32-C3, ESP32-C6, Seeed XIAO ESP32-C3, ESP32-C3 SuperMini, Seeed XIAO ESP32-C6, ESP32 DevKit, ESP32-DevKitC V4, LOLIN32 Lite, Wemos D1 R32, Cheap Yellow Display, TTGO T-Display, ESP32-S3-DevKitC-1, Seeed XIAO ESP32-S3, Arduino Nano ESP32.

In Mokxi it is built in: #include <ESP32RotaryEncoder.h> and the sketch compiles, with no download, no zip and no Library Manager.

On a real board, install "ESP32RotaryEncoder" by Matthew Clark from the Arduino IDE’s Library Manager (Sketch, Include Library, Manage Libraries), or add ESP32RotaryEncoder to lib_deps in PlatformIO. Mokxi follows the calls of release 1.2.0, so a sketch written here builds there too.

What to know in the simulator: Its class is called RotaryEncoder, as is RotaryEncoder.h’s: a sketch includes one header or the other.

The calls you will use

In the order a sketch meets them.

RotaryEncoder rotaryEncoder(DI_ENCODER_A, DI_ENCODER_B, DI_ENCODER_SW)

Makes rotaryEncoder, the RotaryEncoder object the calls below are made on.

rotaryEncoder.setEncoderType(EncoderType::SW_FLOAT)

Sets the encoder type to the value you pass in.

rotaryEncoder.setBoundaries(1, 10, true)

Sets the boundaries to the value you pass in. Arguments: min value, max value, circle values.

rotaryEncoder.begin()

Starts it up. Call it once in setup(). Arguments: use timer.

Example: A wrapping value and a button on an ESP32-C3

On the ESP32-C3-DevKitM-1. It runs in the browser exactly as printed.

sketch.ino · ESP32-C3-DevKitM-1
#include <ESP32RotaryEncoder.h>

const uint8_t DI_ENCODER_A = 2;   // CLK
const uint8_t DI_ENCODER_B = 3;   // DT
const int8_t DI_ENCODER_SW = 4;

RotaryEncoder rotaryEncoder(DI_ENCODER_A, DI_ENCODER_B, DI_ENCODER_SW);

void knobCallback(long value) {
  Serial.printf("Value: %ld\n", value);
}

void buttonCallback(unsigned long duration) {
  Serial.printf("boop! button was down for %lu ms\n", duration);
}

void setup() {
  Serial.begin(115200);

  // The KY-040 has pull-ups on A and B but not on its switch.
  rotaryEncoder.setEncoderType(EncoderType::SW_FLOAT);

  // 1 to 10, wrapping round past either end.
  rotaryEncoder.setBoundaries(1, 10, true);
  rotaryEncoder.onTurned(&knobCallback);
  rotaryEncoder.onPressed(&buttonCallback);
  rotaryEncoder.begin();
  Serial.println("ready");
}

void loop() {
  // The library's own timer calls the callbacks.
}

Wiring

  • ESP32-C3-DevKitM-1 2 to Rotary encoder, KY-040 CLK
  • ESP32-C3-DevKitM-1 3 to Rotary encoder, KY-040 DT
  • ESP32-C3-DevKitM-1 4 to Rotary encoder, KY-040 SW
  • ESP32-C3-DevKitM-1 3V3 to Rotary encoder, KY-040 VCC
  • ESP32-C3-DevKitM-1 GND to Rotary encoder, KY-040 GND

Open it in the editor, wired and ready to run

Try ESP32RotaryEncoder without installing anything

Open the example, change the sketch, and keep your version in a free account.