Using a rotary encoder in MicroPython with an ESP32

Handling a rotary encoder: the KY-040

This tutorial will explore using a KY-040 rotary encoder module in a DIY project. A rotary encoder is an excellent device for creating a user interface that allows you to choose a menu, increase or decrease a variable, etc. This feature is commonly found in many DIY kits.

Wiring the KY-040 rotary encoder to the ESP32

This rotary encoder has 2 signals - CLK and DT - to determine position. Additionally, the SW pin is connected to the integrated push-button switch.

Warning

If you’re new to using rotary encoders, you’ll need to add pull-up resistors to the 3 logic pins. This is the same as when using a primary push-button circuit and is necessary for distinguishing between logic levels.

Here is a suggestion to connect to the uPesy ESP32 Wroom DevKit board:

Rotary Encoder	ESP32
CLK	GPIO22
DT	GPIO23
SW	Not used here
+	3V3
GND	GND

The scheme to be done is as follows:

Note

It would help if you supplied the encoder with 3.3V to have 3.3V logic levels (ESP32 friendly).

And here is an example of breadboard mounting:

Get the angular position of the KY-040 rotary encoder

Incremental encoders are helpful because they provide information on how many increments are made rather than the angle in degrees. To determine the angle, this information needs to be interpreted by a program. This allows us to determine the increment’s value without knowing the exact angle.

Finding an efficient way to count the steps of an encoder is a critical task. A straightforward approach would be to continuously check if logical signals are being received from the encoder, but this method has its limitations; if the encoder is rotated rapidly, there is a risk that some steps may be missed. Thus, it is ideal to have a reliable method that accurately counts all the steps without blocking the program.

An efficient solution is to incorporate hardware interrupts that respond to logic-level changes. This method allows the CPU to remain uninvolved, meaning the code is not blocked.

I recommend utilizing the microPython library micropython-rotary for asynchronously reading the increments of a rotary encoder. This library consists of two files that must be moved to your board, like any other microPython library. This process can be quickly completed within the Thonny IDE.

• `rotary.py <https://github.com/miketeachman/micropython-rotary/blob/master/rotary.py>`__

• `rotary_irq_esp.py <https://github.com/miketeachman/micropython-rotary/blob/master/rotary_irq_esp.py>`__

Here is a basic script that allows you to test the library and validate the electrical setup:

import time
from rotary_irq_esp import RotaryIRQ

r = RotaryIRQ(
    pin_num_clk=22,
    pin_num_dt=23,
    reverse=True,
    incr=1,
    range_mode=RotaryIRQ.RANGE_UNBOUNDED,
    pull_up=True,
    half_step=False,
)

val_old = r.value()
while True:
    val_new = r.value()

    if val_old != val_new:
        val_old = val_new
        print("step =", val_new)

    time.sleep_ms(50)

Creating an object of type RotaryIRQ lets you set a variety of options. Please visit the library presentation page for complete details. RotaryIRQ will take care of the work in the background, and the value can be accessed using the r.value() function.

In this example, the encoder has no upper limit on the amount it can increment. The variable will increment without bounds until it is full. However, you can set a limit for the increment, for example, -20 to +20 , by altering the range_mode parameter.