lv_micropython_cmod

MicroPython user C module glue for LVGL: micropython.mk, CMake usermod, GC-aware allocator, and smoke tests.

Requires a sibling clone of lv_bindings with generated/lvgl_micropython.c (run regenerate_lvmp.sh).

Documentation

See docs/.

This repo is mostly glue: it wires LVGL into MicroPython builds and exposes the runtime hooks that the firmware needs. In practice, you usually change the build glue or allocator here when the port itself changes, but you do not regenerate the bindings here. If the binding layer changed, update lv_bindings first and then rebuild this module against the new generated file.

Workspace layout

workspace/
  lv_micropython_cmod/     ← this repo
  lv_bindings/
  micropython/             ← for builds

Generate bindings

cd lv_bindings
git submodule update --init lvgl
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
./regenerate_lvmp.sh

Build (Make ports)

USER_C_MODULES is the workspace parent (directory containing this repo and any other */micropython.mk siblings):

cd micropython/ports/unix
# Prefer the cmods workspace `./build_mp.sh` (merges this manifest + upstream).
# Standalone: point FROZEN_MANIFEST at a wrapper that include()s this file and
# the port/variant manifest, or use cmods/manifest.py with FROZEN_MANIFEST_UPSTREAM set.
make USER_C_MODULES=../../.. FROZEN_MANIFEST=../../../lv_micropython_cmod/manifest.py

Override bindings location if needed:

make USER_C_MODULES=../../.. BINDINGS_DIR=/path/to/lv_bindings

Build (CMake ports)

USER_C_MODULES points at this repo (or lv_micropython_cmod/micropython.cmake). CMake does not scan the workspace for siblings:

cd micropython/ports/esp32
make BOARD=ESP32_GENERIC_S3 USER_C_MODULES=../../../lv_micropython_cmod

cd micropython/ports/rp2
make BOARD=RPI_PICO USER_C_MODULES=../../../lv_micropython_cmod

To include this module plus other usermods, pass a semicolon-separated list (no aggregator file required):

make BOARD=ESP32_GENERIC_S3 \
  USER_C_MODULES="/abs/path/to/lv_micropython_cmod;/abs/path/to/displayif"

(cmods is an optional convenience workspace with ./build_mp.sh; it is not required.)

Smoke test

./micropython/ports/unix/build-standard/micropython ./lv_micropython_cmod/tools/test_lvgl_unix.py

Prefer the unified smoke test directly: lv_bindings/tools/test_lvgl_smoke.py.

Files

Path	Role
micropython.mk	Make ports — USER_C_MODULES = workspace parent
micropython.cmake	CMake ports — USER_C_MODULES = this repo (see above)
src/lv_mem_core_micropython.c	GC-aware LVGL allocator
manifest.py	Freezes lib/display_driver.py (sync from lv_bindings)
lib/display_driver.py	Vendored pydisplay LVGL glue (import display_driver)
scripts/sync_from_lv_bindings.sh	Refresh lib/display_driver.py from lv_bindings
tools/test_lvgl_unix.py	Deprecated wrapper → lv_bindings/tools/test_lvgl_smoke.py

CircuitPython integration lives in lv_circuitpython_mod.