micro-gui
A lightweight MicroPython GUI library for displays with framebuf drivers, supporting input via pushbuttons, encoders, or touchpads.
What is micro-gui?
micropython-micro-gui is a lightweight GUI library for MicroPython that enables interactive interfaces on displays with framebuf-based drivers. It solves the problem of adding user input to embedded displays without touchscreens by supporting pushbuttons, encoders, and other input devices, making it ideal for low-cost hardware projects.
Embedded developers and hobbyists building interactive devices with MicroPython on platforms like ESP32, Raspberry Pi Pico, or Pyboard, especially those using non-touch displays.
It offers a portable, RAM-efficient GUI with a rich widget set and flexible input options, providing a viable alternative to touch-based libraries for cost-sensitive or resource-constrained projects.
Overview
A lightweight MicroPython GUI library for display drivers based on framebuf, allows input via pushbuttons. See also micropython-touch.
Use Cases
Best For
- Building control panels for IoT devices with pushbutton or encoder input
- Creating data dashboards on small embedded displays
- Developing instrumentation interfaces with sliders, meters, and graphs
- Prototyping low-cost embedded systems with non-touch screens
- Adding GUI functionality to MicroPython projects on ESP32 or Pi Pico
- Replacing touch overlays on displays where calibration is problematic
Not Ideal For
- Applications requiring responsive touchscreen interfaces with native calibration and multi-touch support
- Projects using ePaper or Sharp displays where slow, visually intrusive refresh rates are unacceptable
- Display-only applications where absolute minimal RAM usage is critical (nano-gui is more suitable)
- Teams wanting drag-and-drop GUI builders or extensive pre-styled, icon-based themes without custom coding
Pros & Cons
Pros
Written in pure Python, it runs on a wide range of MicroPython hosts and displays with framebuf drivers, minimizing dependencies and RAM usage as highlighted in the README's performance notes.
Includes buttons, sliders, meters, graphs, and more for interactive data display and entry, with demos showing complex applications like linked sliders and dropdowns.
Supports 2-5 pushbuttons, rotary encoders, ESP32 touchpads, and custom drivers for speech or gestures, offering intuitive alternatives to touchscreens on low-cost hardware.
Uses asyncio internally for efficient event handling but exposes a conventional callback interface, simplifying development while maintaining performance on resource-constrained devices.
Cons
Requires editing a hardware_setup.py file with specific pin assignments and display driver settings, which can be error-prone and time-consuming compared to plug-and-play solutions.
Primarily designed for non-touch input; touch is restricted to ESP32 touchpads and lacks calibration for common resistive/capacitive touchscreens, as admitted in the Rationale section.
On large or multi-byte color displays, refresh delays can cause missed button presses, necessitating workarounds like overclocking or driver-specific asyncio yields, per the Performance notes.
As an actively developed project, it has introduced breaking changes (e.g., refresh control in Sept 2024), requiring code updates and careful version management.
Frequently Asked Questions
Related Projects
micropython-nano-guiA lightweight MicroPython GUI library for display drivers based on framebuf class
lvglLVGL binding for MicroPython
TFT-GUISimple GUI for Pyboard and TFT touch panel displays
micropython-core2MicroPython version for the M5Stack CORE2
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.