Using LVGL with OmniPython
How to run LVGL on the OmniPython display, input, and timing
packages, and what display_driver.py does for you.
One binding for three interpreters
omnipython-lvgl bundles this integration for each interpreter, from one generated binding:
Port |
Interpreter |
|---|---|
MicroPython firmware |
|
CircuitPython firmware |
|
CPython ( |
All three share displaydev, neutral board capabilities, and multimer, so
the same LVGL Python code is portable across them. You can even develop it interactively in
Jupyter.
The rest of this page covers wiring LVGL up by hand, which is what you need with upstream lv_micropython rather than omnipython-lvgl.
1. Install the minimum OmniPython packages
import omip
omip.install("omnipython") # displaydev, appdev, display_driver and the rest of lib/
omip.install("github:PyDevices/omnipython/board_configs/<your_board>")
Replace <your_board> with a path from
board configs,
or follow
install workflows.
2. Build or obtain LVGL firmware
Follow upstream lv_micropython for your
board. OmniPython supplies the flush and input glue via board_config.py; LVGL
supplies the UI toolkit.
For production ESP32 projects, consider
kdschlosser’s lvgl_micropython
C drivers wired through BusDisplay.
3. Wire board_config to LVGL
Your board_config.py should expose:
display_drv— adisplaydevdriver withblit_rect, dimensions, and rotationneutral input callables where present:
host_read,touch_read,keypad_read,encoder_read,encoder_button_read
Board configs describe hardware; they do not create an application-level appdev.App.
Connect LVGL’s display flush callback to copy LVGL’s draw buffer through
display_drv.blit_rect — or use the packaged display_driver, which does it
for you.
display_driver
display_driver.py is the LVGL coordinator. It
lives in this repository’s lib/ and ships with omnipython (the mip package,
the wheel, and the frozen module in a omnipython-builds build), beside the
board_config idiom, appdev, events, keys and multimer it needs. The
sister projects carry only lvgl and fs_driver
(loading fonts at runtime).
With display_driver, LVGL input is wired automatically through its own
app (an appdev.App) and virtual touch / encoder / keypad devices.
Do not instantiate or poll
appdevin an LVGL app.lv.task_handler(), driven bydisplay_driver.event_loopplusmultimer, already drains input. Window-close (QUIT) is handled by the bridge’sHostInputpath.
Build the UI, then hand control over with app.run().
Wheel and swipe input
A mouse wheel or two-finger trackpad swipe drives the virtual encoder
device, so it adjusts whichever control the LVGL group has focused —
provided that control entered edit mode, which only happens once a click
lands on it (an LVGL core behavior: changing focus always drops edit mode,
so a handler that sets it back on must run on the FOCUSED event, not
PRESSED, which fires too early).
By default the encoder reads a single axis and never touches focus, matching
prior versions. Call display_driver.set_wheel_mapping() to change that:
import display_driver
# Horizontal sliders read best adjusted along their own axis, with the
# perpendicular swipe stepping between them:
display_driver.set_wheel_mapping(adjust_axis="h", adjust_sign=-1, navigate=True)
adjust_axis:"v"(default) or"h"— which axis adjusts the focused control’s value. Match it to the control’s orientation: horizontal sliders read best with"h"; vertical sliders and knobs,"v".adjust_sign:1(default) or-1to flip the adjust direction.navigate:False(default) orTrueto let the other axis move group focus between controls (lv.group_t.focus_next/focus_prevon the default group) — wheel-only browse-and-tweak, with no keyboard or extra indev required.navigate_sign:1(default) or-1to flip which way focus travels. Separate fromadjust_signbecause the two axes come from different sources with their own conventions — SDL and Win32 disagree about the sign of vertical scroll, so “swipe down goes to the next control” is a claim about that axis on that platform, not about the mapping as a whole.
A wheel event’s legacy integer delta and its float “precise” delta
disagree about which one is real depending on the platform’s usdl2
build — confirmed empirically to differ between a desktop MicroPython
build and a CPython one on the same machine. display_driver resolves
this per event already; if you ever read wheel deltas directly instead of
through display_driver, don’t assume either field is the trustworthy one
without checking on your own target.
One timer on every host
display_driver includes the LVGL event_loop, which runs on multimer: one
multimer.Timer runs lv.timer_handler() and re-arms itself to what LVGL
returns, so an idle screen wakes when LVGL wants it. There is no separate
async mode to choose. The same code runs on MCUs, desktop, PyScript and
Jupyter, and multimer picks how callbacks are delivered
(timers). event_loop still accepts an asynchronous argument,
but only for API parity; it is ignored.
The frame rate is the display’s: OMNIPYTHON_REFRESH_MS changes it for LVGL and
non-LVGL apps alike, and OMNIPYTHON_FPS_PRINT prints it
(displaydev).
Verifying an integration
lv_test_timer.py
is a single smoke test. Its UI reports the
autodetected interpreter, OS, display driver class, screen, timer backend, and
LVGL version, plus a seconds counter, spinning arc, frame rate, and tap button.
python examples/lv_test_timer.py kit runs a timed LVGL timer and input check,
prints a KIT_RESULT= JSON line, then quits. To drive that across every desktop
interpreter, use the harnesses documented in
pydevices-examples/tools/README.md.
See also
omnipython-lvgl — the generator and the three ports, and loading fonts at runtime