micropython-rotary
A MicroPython driver for reading rotary encoders with hardware interrupt support and effective debouncing.
What is micropython-rotary?
micropython-rotary is a MicroPython library for interfacing with rotary encoders on embedded development boards. It reads encoder rotations using hardware interrupts and implements a debouncing state machine to provide accurate and reliable counts. The driver supports various range modes, configurable increments, and platform-specific optimizations for boards like ESP32, Raspberry Pi Pico, and Pyboard.
Embedded developers and hobbyists working with MicroPython on devices like ESP32, Raspberry Pi Pico, or Pyboard who need to integrate rotary encoders for input control in projects such as dials, menus, or parameter adjustment interfaces.
Developers choose this library for its robust debouncing implementation, interrupt-driven efficiency, and cross-platform support. It offers a reliable, battle-tested solution adapted from Ben Buxton's proven algorithm, reducing software glitches and ensuring accurate encoder readings in resource-constrained embedded environments.
Overview
MicroPython module to read a rotary encoder.
Use Cases
Best For
- Adding rotary encoder input to MicroPython-based embedded projects
- Building control interfaces with dials or knobs on ESP32 or Raspberry Pi Pico
- Implementing menu navigation systems in embedded devices
- Creating parameter adjustment controls for IoT devices
- Developing instrumentation panels with rotary input
- Prototyping hardware interfaces with reliable debouncing
Not Ideal For
- Projects using CircuitPython or other non-MicroPython embedded Python environments
- Applications where software polling is sufficient and interrupt overhead is undesirable
- Systems with GPIO pins that do not support interrupts or have strict boot sequence constraints
- Developers needing built-in argument validation and error handling
Pros & Cons
Pros
Uses hardware interrupts for immediate pin change processing, ensuring real-time updates without constant polling, as detailed in the 'Interrupt based' section.
Implements Ben Buxton's state machine for reliable contact noise filtering, adapted from his C++ work, ensuring accurate counts as highlighted in the acknowledgements.
Supports multiple range modes, reverse direction, half-step mode, and configurable increments via constructor parameters, allowing customization for various use cases.
Includes tailored files for ESP8266/ESP32, Pyboard, and Raspberry Pi Pico to handle hardware differences, as shown in the file installation guide.
Cons
The library does not check for configuration errors in arguments, as stated under Methods, which can lead to runtime issues if pins or values are misconfigured.
Requires copying platform-specific files separately, though mip install eases this, adding setup complexity compared to single-file or drop-in libraries.
Depends on GPIO interrupt support, and some pins have boot sequence risks, as noted in the README for ESP8266/ESP32, limiting pin choice and potential conflicts.
Frequently Asked Questions
Related Projects
encodersAssorted code ideas, unofficial MP FAQ, plus index to my other repositories.
encodermenuSimple GUI menu for micropython using a rotary encoder and basic display.
AS5600AS560 Micropython library for reading this magnetic sensor
rotary-encoderCode to drive a rotary encoder in micropython
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.