Arduino library · Input

ESP Rotary: an example that runs

Yes. You can use the ESP Rotary 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 ranged counter on a rotary encoder with ESP Rotary", runs on the Arduino Uno R3.

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

What ESP Rotary does

A rotary encoder polled from loop(), with bounds, an increment, a speedup mode and left, right and changed handlers. That is what ESP Rotary, by Lennart Hennigs, covers. The sketch below uses it on the Arduino Uno: “A ranged counter on a rotary encoder with ESP Rotary”.

The interface of Lennart Hennigs's "ESP Rotary" library (2.2.x): a quadrature knob polled from loop(), with bounds, an increment, a speedup mode and handlers for each kind of turn.

Use the rotary part (a KY-040): one detent is a whole cycle of the two signals, four steps, so give it 4 steps per click. With DT on pin1 and CLK on pin2, clockwise is "right" and counts up, as on the bench.

The calls follow release 2.2.1 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 nameESP Rotary
AuthorLennart Hennigs
Include#include <ESPRotary.h>
Boardsevery board Mokxi compiles for
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 every board Mokxi compiles for.

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

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

What to know in the simulator: A reading that skipped a state is not counted, where upstream guesses a double step.

The calls you will use

In the order a sketch meets them.

ESPRotary r

Makes r, the ESPRotary object the calls below are made on.

r.getPosition()

Returns the position as a whole number.

r.getDirection()

Returns the direction as a rotary_direction.

r.begin(ROTARY_PIN1, ROTARY_PIN2, CLICKS_PER_STEP, MIN_POS, MAX_POS, START_POS, INCREMENT)

Starts it up. Call it once in setup().

r.setChangedHandler(rotate)

Sets the changed handler to the value you pass in.

r.setLeftRotationHandler(showDirection)

Sets the left rotation handler to the value you pass in.

r.setRightRotationHandler(showDirection)

Sets the right rotation handler to the value you pass in.

r.setLowerOverflowHandler(lower)

Sets the lower overflow handler to the value you pass in.

r.setUpperOverflowHandler(upper)

Sets the upper overflow handler to the value you pass in.

Example: A ranged counter on a rotary encoder with ESP Rotary

On the Arduino Uno R3. It runs in the browser exactly as printed.

sketch.ino · Arduino Uno R3
#include "ESPRotary.h"

#define ROTARY_PIN1 3  // DT
#define ROTARY_PIN2 2  // CLK: clockwise is right

#define CLICKS_PER_STEP 4   // a KY-040 detent is four steps
#define MIN_POS 0
#define MAX_POS 10
#define START_POS 5
#define INCREMENT 2

ESPRotary r;

void rotate(ESPRotary &r) {
  Serial.print("position: ");
  Serial.println(r.getPosition());
}

void upper(ESPRotary &) { Serial.println("upper bound hit"); }
void lower(ESPRotary &) { Serial.println("lower bound hit"); }

void showDirection(ESPRotary &r) {
  Serial.println(r.directionToString(r.getDirection()));
}

void setup() {
  Serial.begin(115200);
  r.begin(ROTARY_PIN1, ROTARY_PIN2, CLICKS_PER_STEP, MIN_POS, MAX_POS, START_POS, INCREMENT);
  r.setChangedHandler(rotate);
  r.setLeftRotationHandler(showDirection);
  r.setRightRotationHandler(showDirection);
  r.setLowerOverflowHandler(lower);
  r.setUpperOverflowHandler(upper);

  Serial.println("Ranged Counter");
  Serial.print("Current position: ");
  Serial.println(r.getPosition());
}

void loop() {
  r.loop();
}

Wiring

  • Arduino Uno R3 2 to Rotary encoder, KY-040 CLK
  • Arduino Uno R3 3 to Rotary encoder, KY-040 DT
  • Arduino Uno R3 5V to Rotary encoder, KY-040 VCC
  • Arduino Uno R3 GND to Rotary encoder, KY-040 GND

Open it in the editor, wired and ready to run

Try ESP Rotary without installing anything

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