Displays

The displaydev product package in OmniPython provides several display driver classes. All expose a drawing surface compatible with MicroPython’s framebuf API; gallery demonstrates them.

See Architecture for how drivers connect to board_config.py.

Pick a driver

Your target

Driver class

Board config example

MicroPython MCU (SPI/I80)

BusDisplay

board_configs/busdisplay/spi/...

CPython / MicroPython Unix desktop

SDLDisplay

board_configs/sdldisplay/

Windows CPython (native Win32)

WinDisplay

board_configs/windisplay/

Windows / Chromebook (PyGame easier)

PGDisplay

board_configs/pgdisplay/

CircuitPython RGB / USB video

FBDisplay

varies

Jupyter notebook

JNDisplay

board_configs/jndisplay/

PyScript browser

PSDisplay

board_configs/psdisplay/

Install the matching board config — it constructs the driver for you.

Display classes

BusDisplay

For microcontrollers on MicroPython and CircuitPython.

  • MicroPython: uses spibus / i80bus or community C bus drivers (lvgl_micropython).

  • CircuitPython: uses Adafruit FourWire / ParallelBus — see board configs.

SDLDisplay

SDL2 desktop backend (CPython, MicroPython Unix, CircuitPython Unix). Uses an SDL texture as GRAM. It is the default on MicroPython Unix and available on CPython via board_configs/sdldisplay/.

SDL2 bindings for SDLDisplay: import usdl2 from omnipython-desktop (PyPI) or the MIP desktop board package in OmniPython (utils/usdl2.py). A native usdl2 module is used when already present in the firmware or environment. See omnipython-desktop.

WinDisplay

Native Win32 HWND backend for CPython on Windows (uwin32). Logical RGB565 GRAM, handed to StretchDIBits as a 16-bit BI_BITFIELDS DIB, so the framebuffer is presented with no colour conversion and no copy. show() skips a frame with nothing pending, and blits only the changed rows when the scale is a whole number. displaydev.auto.AutoDisplay tries it first on win32 before pygame/SDL. Explicit config: board_configs/windisplay/.

Sizes are real pixels, at any display scaling. WinDisplay makes the process per-monitor DPI aware before it measures the screen or opens a window, so on a display scaled to 150 % a 640x480 panel at scale=1 is 640x480 pixels on the glass, crisp, and the work area it fits the window into is the real one. If your program declares a DPI awareness of its own (in its manifest, or with SetProcessDpiAwarenessContext before the first display opens), yours stands.

Open it maximised and the panel is the window: WinDisplay(maximized=True) opens maximised into the work area (the screen less the taskbar), with the panel exactly the window’s client area at scale=1, no margin and no autoscale, the way an installed web app fills its window. width, height, scale, x and y are ignored; rotation still says which way up the panel is. Read the size from display.width / display.height once it is open, or call displaydev.windisplay.maximized_size() to learn it before opening anything. With the desktop board config, set OMNIPYTHON_MAXIMIZED=1 (other desktop backends ignore it). A maximised display keeps the size it opened at, so pass rotation= up front rather than rotating it later.

import os
os.environ["OMNIPYTHON_MAXIMIZED"] = "1"
import board_config

d = board_config.display_drv
print(d.width, d.height)   # e.g. 1920 1094 on a 1920x1200 screen at 150 %

Width and height must be even. DIB scanlines are DWORD-aligned, which RGB565 rows only satisfy at an even width, and rotation swaps the two. Odd dimensions raise ValueError at construction.

PGDisplay

PyGame desktop backend. displaydev.auto.AutoDisplay (used by board_configs/desktop/) selects it after WinDisplay on Windows, and first on other CPython desktops; if PyGame is not installed it falls back to SDLDisplay. Explicit config: board_configs/pgdisplay/.

FBDisplay

Works with CircuitPython framebufferio.FramebufferDisplay — dotclock (RGB), USB Video, RGB Matrix.

USB Video lets a board stream the framebuffer as a USB webcam (RP2040; host support varies).

JNDisplay

Jupyter Notebook output via an interactive ipywidgets image. Input (mouse, wheel, keyboard) is captured by JNDevices (ipyevents) and delivered as events. Config: board_configs/jndisplay/.

PSDisplay

PyScript browser canvas. Input (pointer/touch/pen, wheel, keyboard, gamepad) is captured by PSDevices and delivered as events. Config: board_configs/psdisplay/. See PSDisplay.

Display backends expose input without choosing an application coordinator. Applications using the optional appdev app can drain the backend’s events records through a HostEvents. The input source depends on what each platform exposes:

Backends

Input source

Wired via

SDLDisplay, PGDisplay, WinDisplay

System-wide OS queue drain (module get_events, also on display_drv.get_events)

appdev.App(..., host_read=display_drv.get_events)

JNDisplay, PSDisplay

Per-surface PSDevices / JNDevices, exposed as display_drv.get_events

appdev.App(..., host_read=display_drv.get_events)

With appdev, handlers see the same events objects, so application code does not need to know which backend is active. LVGL instead connects these neutral backend capabilities through its own display_driver coordinator.

Desktop (SDL2, PyGame)

SDL2 and PyGame provide a real OS event queue. The driver module drains it and converts each event to an events object:

from displaydev.sdldisplay import SDLDisplay
import appdev

display_drv = SDLDisplay(...)
app = appdev.App(
    displays=[display_drv],
    host_read=display_drv.get_events,
)

Use poll_event() only for optional manual single-event checks — not as the host_read= callback (it returns one event, not a list).

Desktop hosts (SDLDisplay, PGDisplay, WinDisplay) set display_drv.quit_chord to CTRL+Q (keys.K_q + keys.KMOD_CTRL). HostEvents matches that chord with keys.chord_matches and emits events.QUIT. Window-close still emits events.QUIT from SDL/PyGame. MCU drivers leave quit_chord as None.

Pointer coordinates use display_drv.touch_scale (see capabilities() per backend); HostEvents divides mouse events by that scale.

This captures mouse motion/buttons, the wheel, the keyboard, the window-close (QUIT) event, and joysticks/gamepads (JOYAXISMOTION, JOYBALLMOTION, JOYHATMOTION, JOYBUTTONDOWN, JOYBUTTONUP). Connect controllers before launching — hot-plugging after startup is not handled.

Browser / notebook (PyScript, Jupyter)

PSDevices (PyScript) and JNDevices (Jupyter) capture all available input on the canvas/widget and turn it into the same events objects. The display owns that drain as get_events:

from displaydev.psdisplay import PSDisplay
import appdev

display_drv = PSDisplay("display_canvas", width, height)
app = appdev.App(
    displays=[display_drv],
    host_read=display_drv.get_events,
)

Each captures:

  • Pointer — MOUSEMOTION on every move and MOUSEBUTTONDOWN / MOUSEBUTTONUP for any button. On PyScript this uses Pointer Events, so mouse, touch, and pen all work (with the touch flag set for non-mouse pointers).

  • Wheel — MOUSEWHEEL (also consumed by encoder devices).

  • Keyboard — KEYDOWN / KEYUP with SDL-style key codes, names, and modifier masks (incl. left/right modifier variants) via keys and displaydev DOM helpers.

  • Gamepad (PyScript only) — JOYAXISMOTION / JOYBUTTONDOWN / JOYBUTTONUP, polled from the Gamepad API on each read().

  • Quit — PSDisplay / JNDisplay set quit_chord to browser/TV Back (keys.K_AC_BACK). HostEvents turns that KEYDOWN into events.QUIT (same as closing an SDL window). Reassign if the host intercepts Back:

import keys

display_drv.quit_chord = (keys.K_c, keys.KMOD_CTRL)  # e.g. CTRL+C on Jupyter

Caveat: key events require the canvas/widget to be focused (click it first), and the notebook/browser front end may consume some keys (arrows, space, Ctrl/Cmd shortcuts) before they reach the helper. This makes keyboard input on these backends less reliable than on the desktop SDL/PyGame backends.

Rotation on these backends only reshapes the surface (e.g. 320×480 ↔ 480×320); it does not physically rotate, so pointer coordinates need no rotation remapping.

Canvases

Anything you can draw on implements the framebuf API:

  • The display itself

  • framebuf bytearrays

  • pygraphics.BMP565 bitmap files

  • displaybuf.DisplayBuffer (see gallery utils)

Timing

gallery does not include a task scheduler. Options:

  • asyncio — works on CPython, MicroPython, and PyScript (required there)

  • multimer — one Timer on every host; it rides the page’s loop on PyScript

Frame rate

To see how fast an app draws, switch on the display’s meter and read it:

display_drv.measure_fps(True)        # or OMNIPYTHON_FPS=1 in the environment
...
display_drv.fps()
# {"fps": 29.8, "avg_fps": 29.5, "frames": 1180, "seconds": 40.0,
#  "present_ms": 4.2, "present_ms_max": 12.0, "busy": 0.13,
#  "flushes": 0, "pixels": 0}
display_drv.fps_reset()              # start a fresh measurement
display_drv.fps_print(5)             # one line every 5 s; 0 stops it

OMNIPYTHON_FPS=1 measures any example without editing it, and OMNIPYTHON_FPS_PRINT=5 also prints a line every five seconds, for tailing a log:

fps 29.8 avg 29.5 frames 1180 present 4.2 ms (max 12.0) busy 13%

fps is the last whole second and avg_fps everything since it was switched on or reset. present_ms is the time spent inside the present call per frame, and busy is the share of wall time spent there: a slow frame rate with a high busy means the display is the bottleneck, a low one means the app is.

A frame is one show(). On a panel LVGL draws into directly, LVGL presents with flush_rect() once per dirty area, so display_driver calls frame_done() when a frame’s last area is out; those flush_rect() calls are counted as flushes and pixels, not frames.

It is off by default and costs nothing then: show and flush_rect are the class’s own methods until you switch it on, and again after measure_fps(False).

Refresh rate

To run any app at another frame rate without touching its code or its board config, set OMNIPYTHON_REFRESH_MS:

OMNIPYTHON_REFRESH_MS=16 OMNIPYTHON_FPS_PRINT=5 micropython lv_test_timer.py   # about 60 fps
OMNIPYTHON_REFRESH_MS=50 OMNIPYTHON_FPS_PRINT=5 micropython lv_test_timer.py   # about 20 fps

It replaces the display’s refresh_period_ms (33 ms, or 16 in the browser) when the driver starts. Everything that paces frames reads that one attribute: appdev.App’s refresh timer, the display’s frame clock, and display_driver’s LVGL refresh timer, so LVGL and non-LVGL apps both follow it. A board config can set it with boarddev.env_set("OMNIPYTHON_REFRESH_MS", 16) before it builds the display, on hosts where there is no environment.

Unset, zero or not a number leaves the display’s own period. An app that passes appdev.App(..., refresh_period=N) has chosen its rate in code and keeps it; refresh_period=0 still means the app presents frames itself.

Vertical scrolling

Many drivers expose ILI9341-style vertical scroll: a top fixed band (TFA), a scrollable middle (VSA), and a bottom fixed band (BFA). You define regions with set_vscroll(tfa, bfa) or vscrdef, then move content with the vscroll property (wrapper around vscsad).

The pydevices_demo example demonstrates this model, covers drawing at vscroll = 0 during redraw, and shows auto-scroll with multimer.

Related examples: scroll_touch_test.py (touch Up/Down), appdev_encoder_test.py (encoder).

Rotation

BusDisplay uses CircuitPython-style rotation degrees (0, 90, 180, 270).

Rotating swaps width and height, so read them after you set the rotation. On the desktop, OMNIPYTHON_ROTATION sets it from outside the program.

Known issues: Unix SDL rotation clears the screen; scrolling while rotated has edge cases on desktop and MCU — track work on GitHub Issues.

Write your own backend

AutoDisplay (what the desktop board config calls) looks its backend up in a small registry, backends. You can register one of your own.

# in your backend's package
import backends
backends.register("display", "hls", "castdisplay.hls_display:HlsDisplay", probe=have_ffmpeg)

# board_config.py
import backends
backends.require("display", "hls", module="castdisplay.hls_display")
display_drv = AutoDisplay(1280, 720, tv=TV)      # extra keywords go to the winner

register takes a name, a "module:Class" string (nothing is imported until the backend is tried), and an optional probe() that returns false when this machine can’t run it. require imports the module you name, which registers the backend, and raises an ImportError that names the module if it isn’t installed.

AutoDisplay tries, in order:

  1. the backend named by the OMNIPYTHON_DISPLAY environment variable, if it is set, and nothing else. The built-in names are wasm, pyscript, jupyter, android, win, pygame and sdl;

  2. the backends your config required, in the order it asked, skipping any whose probe says no;

  3. the built-in backends for this host.

A backend that isn’t built in is never picked unless a config required it or you named it, so a backend that streams to a TV never chooses itself. A backend from outside the box is called as Class(width=..., height=..., **extra), with whatever extra keywords you gave AutoDisplay. Its constructor takes width and height, optionally rotation, and whatever keywords of its own it documents. AutoDisplay passes rotation only when the caller asks for one: AutoDisplay(1280, 720, rotation=90) calls Class(width=1280, height=720, rotation=90), and AutoDisplay(1280, 720) passes no rotation. A backend without a rotation parameter works until someone asks for a rotation; then Python raises a TypeError that names the backend. scale, title, quiet and maximized are window hints for the built-in window backends and are never passed to yours, so a config that sets them still works. It can raise backends.Decline to hand the choice to the next one.

On MicroPython there is no scanning for installed backends: require is the only way in. A frozen module imports like any other, so what you freeze decides what is present and require decides what is used.

castdisplay’s Roku, HLS and Miracast displays register themselves as roku, hls and cast, so a config that requires one gets it from AutoDisplay; OMNIPYTHON_DISPLAY=hls names one for a single run. Their options go through AutoDisplay as keywords (tv= for roku and hls, sink= and kind= for cast); see the castdisplay guide.

Next

API reference

displaydev source and product docs.