Build CircuitPython firmware with LVGL

ports/circuitpython in omnipython-lvgl is a user C module for CircuitPython. CircuitPython 11 builds user C modules the way MicroPython does, so you hand that directory to any port’s make as USER_C_MODULES and nothing in the CircuitPython tree is patched.

Get the sources

Pick a release tag from the CircuitPython releases, and fetch its submodules:

git clone --branch 11.0.0-alpha.1 https://github.com/adafruit/circuitpython.git circuitpython
cd circuitpython
make fetch-all-submodules
cd ..
git clone --recurse-submodules --shallow-submodules https://github.com/PyDevices/omnipython-lvgl.git

The port reads the generated binding, lv_conf.h and lvgl/ from the same checkout, two directories up from itself, so there is nothing to generate or fetch. A clone without the lvgl submodule stops the build at once and names the command that fetches it.

Install the toolchain

Install CircuitPython’s build tools and cross-compilers before building. This repository doesn’t do it for you: follow CircuitPython’s BUILDING.md and Adafruit’s Building CircuitPython guide. For an Arm board you need gcc-arm-none-eabi; check arm-none-eabi-gcc --version after installing.

Create a Python venv for CircuitPython’s requirements-dev.txt, which provides minify_html and related tools (if minify_html fails to install, you may need Rust):

python3 -m venv .venv
.venv/bin/pip install -r circuitpython/requirements-dev.txt
export PATH="$(pwd)/.venv/bin:$PATH"

Build for the unix port or a board

make -C circuitpython/ports/unix VARIANT=coverage \
    USER_C_MODULES=/path/to/omnipython-lvgl/ports/circuitpython
make -C circuitpython/ports/raspberrypi BOARD=<board> CIRCUITPY_GIFIO=0 \
    USER_C_MODULES=/path/to/omnipython-lvgl/ports/circuitpython

Add FROZEN_MANIFEST=/path/to/omnipython-lvgl/ports/circuitpython/manifest.py to freeze the fs_driver helper as well.

CIRCUITPY_GIFIO=0 is for boards: LVGL links its own AnimatedGIF decoder, which collides with gifio’s. The build stops with a message if you forget it.

LVGL adds about 1 MB to the firmware, more than most boards’ default firmware region holds, so a board with a small app partition needs a bigger one. LVGL’s qstrs also need CircuitPython’s four-byte qstr offsets (MICROPY_QSTR_OFFSET_BYTES), which micropython.mk sets on ports that have them. For a worked example with a partition table, see Flash LVGL CircuitPython on a Qualia.

Build with other PyDevices modules

omnipython-builds’ build.py fetches CircuitPython, passes the modules you name to its make as USER_C_MODULES:

./build.py --interpreter circuitpython --port unix --modules lvgl,pygraphics

lvgl is this port: build.py fetches omnipython-lvgl at the commit omnipython-builds pins, or uses an omnipython-lvgl checkout beside it. To build another checkout, name its port by path instead (--modules /path/to/omnipython-lvgl/ports/circuitpython,pygraphics). The binary lands in builds/circuitpython/unix/coverage/.

For a board, name CircuitPython’s port and board, and put CIRCUITPY_GIFIO=0 at the end:

./build.py --interpreter circuitpython --port espressif \
    --board <board> --modules lvgl CIRCUITPY_GIFIO=0

Check the build

Run the smoke test from your omnipython-lvgl checkout with the interpreter you built (build-coverage/micropython for the unix make line above):

./circuitpython/ports/unix/build-coverage/micropython ./omnipython-lvgl/tools/test_lvgl_smoke.py
All LVGL smoke tests passed.

Driving the screen

CircuitPython has no machine.Timer, so the application pumps LVGL: app.run() or your own asyncio loop. With omnipython, display_driver does the wiring. Put omnipython on the board as source (--no-mpy), with your board_config:

import display_driver  # noqa: F401 - initializes display and input
import lvgl as lv
from display_driver import app

scr = lv.screen_active()
label = lv.label(scr)
label.set_text("Hello CircuitPython LVGL!")
label.center()

app.run()

display_driver wants a board_config unless your code has already created an appdev.App. To skip omnipython, give LVGL a buffer and a flush callback as the first program does.

JPEG images need CIRCUITPY_JPEGIO on: Show JPEG images.