Labs / LVGL

Extension: Step-by-step guide to compile lvgl-micropython firmware, even beginners can succeed on the first try

Author: Li Zisheng · Source: FreakStudio open documentation, v1.2 · License: CC BY 4.0

Contents

Repository Address: https://github.com/lvgl-micropython/lvgl_micropython

265 14 170

I. Project Overview

This is an open-source project that binds the LVGL embedded GUI library to MicroPython, which is a derivative of lv_micropython and lv_binding_micropython. Its core goal is to enable developers to develop graphical interfaces on microcontrollers using Python, while simplifying the compile process, unifying APIs, and expanding hardware support.

  • Binding can be analogized to a "language translator": LVGL is an embedded GUI framework written in C, and this project encapsulates the C-language LVGL API into Python-callable interfaces via "glue code", enabling MicroPython developers to directly manipulate all features of LVGL with Python without writing low-level C code.
  • MicroPython: A streamlined version of the Python language, designed specifically for resource-constrained Microcontroller Units (MCUs) with extremely minimal memory footprint, while retaining Python's concise and user-friendly syntax as well as hardware access capabilities.
  • LVGL: It is one of the most popular open-source GUI frameworks in the embedded field. Implemented in C99 and optimized specifically for low-resource devices, it provides a rich set of UI components such as buttons, labels, lists and animations, and supports touch interaction as well as complex interface layouts.

The objective of its project is as follows:

1.1 Key Architecture and Features

The project has refactored its dependency logic: instead of being an affiliated component of MicroPython, it now takes MicroPython as its dependency. This change greatly simplifies the adaptation work for MicroPython version upgrades — only minor modifications are required to support new versions of MicroPython, eliminating the previous hassle of frequently refactoring binding code.

The project provides make.py Python scripts to uniformly handle compile, and supports mainstream embedded platforms:

1.2 Support and Features

It supports the vast majority of mainstream LCD driver chips, including mainstream capacitive/resistive touch chips:

Category

Project

Note

Supported Display IC's

GC9A01

Supported Display IC's

HX8357B

Supported Display IC's

HX8357D

Supported Display IC's

ILI9163

Supported Display IC's

ILI9225

Supported Display IC's

ILI9341

Supported Display IC's

ILI9481

Supported Display IC's

ILI9486

Supported Display IC's

ILI9488

Supported Display IC's

LT768x

WIP

Supported Display IC's

R61581

Supported Display IC's

RA8876

WIP

Supported Display IC's

RM68120

Supported Display IC's

RM68140

Supported Display IC's

S6D02A1

Supported Display IC's

SSD1351

Supported Display IC's

SSD1963_480

Supported Display IC's

SSD1963_800

Supported Display IC's

SSD1963_800ALT

Supported Display IC's

SSD1963_800BD

Supported Display IC's

ST7701S

WIP

Supported Display IC's

ST7735B

Supported Display IC's

ST7735R_Red

Supported Display IC's

ST7735R_Green

Supported Display IC's

ST7789

Supported Display IC's

ST7796

Supported Touch IC's

CST816S

Supported Touch IC's

FT5x06

Supported Touch IC's

FT5x16

Supported Touch IC's

FT5x26

Supported Touch IC's

FT5x36

Supported Touch IC's

FT5x46

Supported Touch IC's

FT6x06

Supported Touch IC's

FT6x36

Supported Touch IC's

GT911

Supported Touch IC's

STMPE610

Supported Touch IC's

XPT2046

Special use drivers

SDL2

Only for the unix and macOS ports

II. Compile Tutorial

⚠️ Mandatory Core Notes (Must Read! Violation will directly lead to compile failure)

This is the project 's most critical rule, officially marked in all caps, and must be strictly complied with:

  • Do not use any compile information bound to the official LVGL
    • Do not refer to the official tutorials of lv_micropython / lv_binding_micropython — this project is an independent fork and is completely incompatible with them.
  • Prohibit the execution of any Git submodule initialization commands
    • After cloning the repository and during the compile process, never ever run git submodule init/update or other submodule-related commands.
  • The only way to update the version
    • To upgrade to the latest master version, you must delete the local old repository and re-clone it entirely;git pull update is not supported.

The architecture of this project has been refactored: MicroPython is a dependency of this binding, rather than the binding being a dependency of MicroPython, and the compile logic has been completely simplified.

2.1 Project Cloning

Here, use the following command to clone the project:

# 1. Clone the repository (without any submodule parameters)
git clone https://github.com/lvgl-micropython/lvgl_micropython

# 2. Enter the project root directory
cd lvgl_micropython
Extension: Step-by-step guide to compile lvgl-micropython firmware, even beginners can succeed on the first try
2.1

2.2 Install Dependencies

We can use the following command to check the Python version:

python --version
3.13.12 3.10

Cross-Platform Compile Dependency Comparison Table

Target build platformRuntime environmentRequired dependency packagesOne-click install command
ESP32Ubuntu (Linux)build-essential, cmake, ninja-build, python, python3-venv, libusb-1.0-0-devapt-get install build-essential cmake ninja-build python python3-venv libusb-1.0-0-dev
macOSXcode command line tools, cmake, ninja, pythonOmitted
RP2Ubuntu (Linux)build-essential, cmake, ninja-build, python, gcc-arm-none-eabi, libnewlib-arm-none-eabiapt-get install build-essential cmake ninja-build python gcc-arm-none-eabi libnewlib-arm-none-eabi
macOSXcode command line tools, make, cmake, ninja, python, arm-none-eabi-gccOmitted
STM32Ubuntu (Linux)gcc-arm-none-eabi, build-essential, ninja-build, pythonapt-get install gcc-arm-none-eabi build-essential ninja-build python
macOSXcode command line tools, make, ninja, python, arm-none-eabi-gccOmitted
Ubuntu local machineUbuntu (Linux)build-essential, libffi-dev, pkg-config, cmake, ninja-build, gnome-desktop-testing, libasound2-dev, libpulse-dev, libaudio-dev, libjack-dev, libsndio-dev, libx11-dev, libxext-dev, libxrandr-dev, libxcursor-dev, libxfixes-dev, libxi-dev, libxss-dev, libxkbcommon-dev, libdrm-dev, libgbm-dev, libgl1-mesa-dev, libgles2-mesa-dev, libegl1-mesa-dev, libdbus-1-dev, libibus-1.0-dev, libudev-dev, fcitx-libs-dev, libpipewire-0.3-dev, libwayland-dev, libdecor-0-devSee the long command below
macOS local machinemacOSXcode command line tools, libffi, ninja, make, SDL2Omitted
All platformsWindowsNot supported yet-

2.2.1 One-click dependency installation command by environment

Ubuntu (Linux) environment:

sudo apt-get update
sudo apt-get install build-essential cmake ninja-build python python3-venv libusb-1.0-0-dev -y
sudo apt-get update
sudo apt-get install build-essential cmake ninja-build python3 python-is-python3 gcc-arm-none-eabi libnewlib-arm-none-eabi -y
sudo apt-get update
sudo apt-get install gcc-arm-none-eabi build-essential ninja-build python -y
sudo apt-get update
sudo apt-get install build-essential libffi-dev pkg-config cmake ninja-build gnome-desktop-testing libasound2-dev libpulse-dev libaudio-dev libjack-dev libsndio-dev libx11-dev libxext-dev libxrandr-dev libxcursor-dev libxfixes-dev libxi-dev libxss-dev libxkbcommon-dev libdrm-dev libgbm-dev libgl1-mesa-dev libgles2-mesa-dev libegl1-mesa-dev libdbus-1-dev libibus-1.0-dev libudev-dev fcitx-libs-dev libpipewire-0.3-dev libwayland-dev libdecor-0-dev -y

2.2.2 Install Dependencies

2.2.2.1 Install Dependencies for ESP32

Enter the following command:

sudo apt-get update
sudo apt-get install build-essential cmake ninja-build python3 python3-venv libusb-1.0-0-dev python-is-python3 -y
ESP32 python3 libusb-1.0-0-dev python-is-python3 libusb-1.0-0-doc 2.2.2.1
2.2.2.2 Install Dependencies for Raspberry Pi Pico (RP2)

Enter the following command:

sudo apt-get update
sudo apt-get install build-essential cmake ninja-build python3 python-is-python3 gcc-arm-none-eabi libnewlib-arm-none-eabi -y
Extension: Step-by-step guide to compile lvgl-micropython firmware, even beginners can succeed on the first try
RP2 python3 python3-pip

The verification dependencies are as follows:

# Verify the cross-compiler
arm-none-eabi-gcc --version
15 13.2.rel1-2 13.2.1 2023 10 9

2.3 Compile the Firmware

2.3.1 Standard Syntax Format and Compile Options

To compile the firmware, you only need one fixed command, which consists of 4 parts in sequence, and the order must not be messed up under any circumstances:

python3 make.py {build target} {build options} {target options} {global options}

The parameters can be interpreted as follows:

python3 make.py  目标芯片  清理选项  开发板型号  硬件驱动

The parameters are explained as follows:

Command snippetPurposeRequired?
python3 make.pyStart the build script (fixed, do not change)✅ Required
Target chipWhich microcontroller you are building firmware for✅ Required
Clean optionDelete the leftover files from the last build❌ Optional
Board modelThe specific model of your microcontroller❌ Advanced, optional
Hardware driversDisplay / touch chip configuration❌ Advanced, optional
2.3.1.1 Compile Target (Build Target)

This is the command 's first parameter, which is mandatory. Its function is to inform the compiler: you need to compile the firmware for which specific microcontroller.

Optional chip list:

PlatformDescription
esp32Espressif ESP32 series MCU
macOSRuns on macOS after building; note: it must be built and run on the same computer
stm32ST Microprocessors series MCU
unixRuns on Unix after building; note: it must be built and run on the same computer
rp2Raspberry Pi Pico 2 MCU
renesas-raRenesas RA series MCU
nrfNordic Semiconductor MCU
mimxrtNXP i.MX RT series MCU
samdMicrochip Technology SAM D series MCU
2.3.1.2 compile Options (Build Options)

This is the command. The second parameter is optional! It has only one optional value: clean

When the following situations arise, you may choose the following options:

2.3.1.3 Target Options

The third parameter of the command, for advanced configuration, no need to write it for minimal compile!

Function: Select the specific development board model (for example, write BOARD= RPI_PICO for Raspberry Pi Pico, and write BOARD= RPI_PICO_W for Pico W).

Quick Summary:

The list of optional development boards is as follows:

PlatformItem
esp32ARDUINO_NANO_ESP32
ESP32_GENERIC
D2WD
OTA
SPIRAM
UNICORE
ESP32_GENERIC_C3
ESP32_GENERIC_S2
ESP32_GENERIC_S3
SPIRAM_OCT
LILYGO_TTGO_LORA32
LOLIN_C3_MINI
LOLIN_S2_MINI
LOLIN_S2_PICO
M5STACK_ATOM
OLIMEX_ESP32_POE
SIL_WESP32
UM_FEATHERS2
UM_FEATHERS2NEO
UM_FEATHERS3
UM_NANOS3
UM_PROS3
UM_TINYPICO
UM_TINYS2
UM_TINYS3
UM_TINYWATCHS3
stm32ADAFRUIT_F405_EXPRESS
ARDUINO_GIGA
ARDUINO_NICLA_VISION
ARDUINO_PORTENTA_H7
B_L072Z_LRWAN1
B_L475E_IOT01A
CERB40
ESPRUINO_PICO
GARATRONIC_NADHAT_F405
GARATRONIC_PYBSTICK26_F411
HYDRABUS
LEGO_HUB_NO6
LEGO_HUB_NO7
LIMIFROG
MIKROE_CLICKER2_STM32
MIKROE_QUAIL
NETDUINO_PLUS_2
NUCLEO_F091RC
NUCLEO_F401RE
NUCLEO_F411RE
NUCLEO_F412ZG
NUCLEO_F413ZH
NUCLEO_F429ZI
NUCLEO_F439ZI
NUCLEO_F446RE
NUCLEO_F722ZE
NUCLEO_F746ZG
NUCLEO_F756ZG
NUCLEO_F767ZI
NUCLEO_G0B1RE
NUCLEO_G474RE
NUCLEO_H563ZI
NUCLEO_H723ZG
NUCLEO_H743ZI
NUCLEO_H743ZI2
NUCLEO_L073RZ
NUCLEO_L152RE
NUCLEO_L432KC
NUCLEO_L452RE
NUCLEO_L476RG
NUCLEO_L4A6ZG
NUCLEO_WB55
NUCLEO_WL55
OLIMEX_E407
OLIMEX_H407
PYBD_SF2
PYBD_SF3
PYBD_SF6
PYBLITEV10
PYBV10
PYBV11
PYBV3
PYBV4
SPARKFUN_MICROMOD_STM32
STM32F411DISC
STM32F429DISC
STM32F439
STM32F4DISC
STM32F769DISC
STM32F7DISC
STM32H573I_DK
STM32H7B3I_DK
STM32L476DISC
STM32L496GDISC
USBDONGLE_WB55
VCC_GND_F407VE
VCC_GND_F407ZG
VCC_GND_H743VI
rp2ADAFRUIT_FEATHER_RP2040
ADAFRUIT_ITSYBITSY_RP2040
ADAFRUIT_QTPY_RP2040
ARDUINO_NANO_RP2040_CONNECT
GARATRONIC_PYBSTICK26_RP2040
NULLBITS_BIT_C_PRO
PIMORONI_PICOLIPO_16MB
PIMORONI_PICOLIPO_4MB
PIMORONI_TINY2040
POLOLU_3PI_2040_ROBOT
POLOLU_ZUMO_2040_ROBOT
RPI_PICO
RPI_PICO_W
SIL_RP2040_SHIM
SPARKFUN_PROMICRO
SPARKFUN_THINGPLUS
W5100S_EVB_PICO
W5500_EVB_PICO
WEACTSTUDIO
FLASH_2M
FLASH_4M
FLASH_8M
renesas-raARDUINO_PORTENTA_C33
EK_RA4M1
EK_RA4W1
EK_RA6M1
EK_RA6M2
RA4M1_CLICKER
VK_RA6M5
nrfACTINIUS_ICARUS
ARDUINO_NANO_33_BLE_SENSE
ARDUINO_PRIMO
BLUEIO_TAG_EVIM
DVK_BL652
EVK_NINA_B1
EVK_NINA_B3
FEATHER52
IBK_BLYST_NANO
IDK_BLYST_NANO
MICROBIT
NRF52840_MDK_USB_DONGLE
PARTICLE_XENON
PCA10000
PCA10001
PCA10028
PCA10031
PCA10040
PCA10056
PCA10059
PCA10090
SEEED_XIAO_NRF52
WT51822_S4AT
mimxrtADAFRUIT_METRO_M7

We can use the following command in the terminal to check the supported development boards:

# List all boards supported by ESP32
ls lib/micropython/ports/esp32/boards/

# List all boards supported by RP2
ls lib/micropython/ports/rp2/boards/
lvgl_micropython_rp2fix ports/rp2/boards RPI_PICO2 SPARKFUN_PRONICRO_RP2350 WS1005_EVB_PICO
lib/micropython/ports/esp32/boards ESP32_GENERIC ESP32_GENERIC_P4 ESP32_GENERIC_S2
2.3.1.4 Global Options

The last parameter of the command, a high-level configuration, which you don't need to write at all for minimal compile!

Function: Add screen and touch chip drivers, which is only used when the drivers need to be solidified into the firmware:

Supports configuration of multiple screens and multiple input devices:

2.3.1.5 Model/Variant-Specific Configuration (ESP32-Specific Instructions)

The following parameters apply to all ESP32 chips and represent the most commonly used advanced configurations; beginners only need to understand the common items marked with ✅:

Parameter formatOfficial English descriptionBeginner-friendly translation & usage
BAUD=numberSpeed for flashing the firmware; must be used with deploy✅ Flashing baud rate function:
Sets the speed for flashing firmware to the microcontroller (the larger the number, the faster)
Example: BAUD=921600
PORT=serial port nameSerial port the microcontroller is connected to; must be used together with deploy✅ Serial port function:
Specifies the ESP32 port recognized by the computer
Example: PORT=/dev/ttyUSB0
deployAutomatically flash the firmware to the microcontroller after building✅ Build + automatic flashing
Function: no need to copy the firmware manually; flash it to the chip directly after building
⚠️ Must be used with the ESP32 connected to the computer
--skip-partition-resizeDisable automatic partition size adjustmentAdvanced: prevents the system from automatically modifying the firmware partitions; beginners can ignore
--partition-size=sizeManually set the application partition sizeAdvanced: for OTA remote updates only; beginners ignore
--optimize-sizePrioritize compressing firmware size✅ Reduce firmware size
Function: generates a smaller firmware when the chip's storage space is insufficient
--debugEnable ESP-IDF debug loggingAdvanced: for finding bugs; beginners do not need to enable
--ccacheSpeed up buildingAdvanced: requires installing extra tools; beginners ignore
--flash-size=4/8/16...Set the microcontroller's Flash storage size✅ Configure flash size
Function: fill in according to your ESP32 hardware (4/8/16/32G, etc.)
--otaEnable the remote firmware update featureAdvanced: enable when doing wireless OTA updates; beginners do not need it
--dual-core-threadsEnable ESP32 dual-core operation (experimental feature)Advanced: lets both cores of the microcontroller run code at the same time; beginners use with caution
--task-stack-size=numberSet the thread stack sizeAdvanced: used when running multithreaded code; beginners ignore
CONFIG_*=valueModify the low-level ESP-IDF configurationAdvanced: official kernel parameter changes; beginners should not touch these at all
--uart-repl-bitrate=baud rateSet the serial debug communication speedAdvanced: raises the serial speed when transferring large files; beginners ignore
--enable-uart-repl=y/nEnable / disable the serial debug featureAdvanced: the serial port can be turned off when debugging over USB; beginners keep it enabled by default

There are also some parameters that can only be used by ESP32-specific model MCUs:

Category

Parameter Format

Beginners' Guide

Scope of Application / Remarks

ESP32-S3 Exclusive

--octal-flash

Enable 8-line SPI Flash

Only supported by ESP32-S3; enabled when the hardware is equipped with octal high-speed flash memory, not required for the standard version

ESP32-S2 / S3 / C3 / C6 Universal

--enable-cdc-repl=y/n

✅ USB debugging switch (supports direct USB debugging without requiring a serial port module)

Applicable to S2 / S3 / C3 / C6; not supported on older ESP32 models

--enable-jtag-repl=y/n

Advanced Debugging: JTAG hardware Debug Switch

Generally not required for beginners; only applicable to S2 / S3 / C3 / C6

Meanwhile, there are also parameters related to custom development boards, which are suitable for developers who design their own ESP32 hardware, while beginners/users of general-purpose modules don't need them at all:

Parameter formatBeginner's note
--custom-board-path=pathFill in the path of the custom board configuration file
--toml=configuration file pathUse a custom hardware configuration file in TOML format

2.3.2 Compile using ESP32_GENERIC_S3 as an example

2.3.2.1 Minimal compile
2.3.2.1.1 Initial Compile

Open the terminal and navigate to the project root directory (you must be under the lvgl_micropython folder)

cd ~/lvgl_micropython

Pure Minimal Compile (for first compile use):

python3 make.py esp32 BOARD=ESP32_GENERIC_S3
python3 esp32 ESP32_GENERIC_S3 1.27.0 v9.4.0
2.3.2.1.2 Re-compile after compile failure

If any issues arise, you need to run:

# 1. Clean the compile cache and build directory
rm -rf build lib/micropython/ports/esp32/build-ESP32_GENERIC_S3

# 2. Clean the openthread submodule that failed to download (so the script downloads it again)
rm -rf lib/esp-idf/components/openthread/lib

Then recompile:

python3 make.py esp32 clean BOARD=ESP32_GENERIC_S3
ESP32_GENERIC_S3 python3 esp32
2.3.2.1.3 Common Issue: SSL Verification Failure in Git

If the compile fails due to network issues:

esp32 s3

You can choose to disable Git's SSL verification:

git config --global http.sslVerify false
git config --global http.postBuffer 524288000
2.3.2.1.4 FAQ: Submodule Pull Failure
2.3.2.1.4

If a certain submodule fails to be pulled as prompted, you need to pull it manually, as illustrated in the figure below:

Git submodule components/mbedtls/mbedtls is out of date.
Run the following command to fix: git submodule update --init --recursive

The system explicitly informs you: The mbedtls submodule is missing/outdated, which is the root cause of the fatal error that leads to compile stuck:

CMake Error: Include directory '/.../mbedtls/include' is not a directory.

The mbedtls folder is empty! There is no include Header File directory, so CMake cannot compile.

Next, we will navigate to the corresponding directory to pull the submodule:

cd /home/leeqingshui/lvgl_micropython/lib/esp-idf
git submodule update --init components/mbedtls/mbedtls
ESP32_GENERIC_S3

Next, execute the following:

# Return to the repository root directory
cd /home/leeqingshui/lvgl_micropython

# 1. Clean the compile cache and build directory
rm -rf build lib/micropython/ports/esp32/build-ESP32_GENERIC_S3

# 2. Clean the openthread submodule that failed to download (so the script downloads it again)
rm -rf lib/esp-idf/components/openthread/lib
lib/micropython/ports/esp32/build-ESP32_GENERIC_S3 2.3.2.1.1

Then execute:

python3 make.py esp32 clean BOARD=ESP32_GENERIC_S3 BOARD_VARIANT=SPIRAM_OCT DISPLAY=st7789 INDEV=gt911
ESP32_GENERIC_S3 python3 st7796 ft6236 Python3

When the result is displayed as follows, it indicates a successful compile:

4/7 2.3.2.1.1
esp32s3.bin

We can find the compiled firmware in this folder:/home/leeqingshui/lvgl_micropython/build

lvgl_micropython_ESP32_GENERIC.bin
2.3.2.2 compile of Waveshare ESP32S3 2-inch Touch LCD Development Board

The command for the first compile operation is as follows:

python3 make.py esp32 --flash-size=16 --optimize-size --enable-cdc-repl=y BOARD=ESP32_GENERIC_S3 BOARD_VARIANT=SPIRAM_OCT DISPLAY=st7789 INDEV=cst816s

If it is a new compile after cleanup, the steps are as follows:

 python3 make.py esp32 clean --flash-size=16 --optimize-size --enable-cdc-repl=y BOARD=ESP32_GENERIC_S3 BOARD_VARIANT=SPIRAM_OCT DISPLAY=st7789 INDEV=cst816s
ESP32_S3 99 2

When the following is output, it indicates a successful compile:

2048 0 esp32s3 ESP32

You can see that the LVGL-MicroPython firmware for the ESP32-S3 + 8MB Octal PSRAM + 16MB Flash version has been fully generated and can be directly flashed to the device:

The occupancy of each partition can be seen from the logs:

PartitionFlash offsetSizeFree space
bootloader0x00000019232 B13536 B
Partition table0x0080003072 B1024 B
Application firmware0x0100002770944 B2048 B
Total2836480 B (about 2.7MB)
ESP32S3

2.3.3 Compile Using the Raspberry Pi Pico 2 as an Example

2.3.3.1 Preparation before compile

With the dependencies already installed, make sure the terminal is navigated to the project root directory: lvgl_micropython:

cd lvgl_micropython
Extension: Step-by-step guide to compile lvgl-micropython firmware, even beginners can succeed on the first try
2.3.3.2 Minimal compile

No cleanup or curing drivers required, fully supports. py format screen/touch drivers, with the smallest and most stable firmware.

Simply enter the following command:

# Standard Raspberry Pi Pico2
python3 make.py rp2 BOARD=RPI_PICO2
2.3.3.2.1 Common Issue: Git SSL Verification Failed

If the compile fails due to network issues:

2.3.3.2.1

You can choose to disable Git's SSL verification:

git config --global http.sslVerify false
git config --global http.postBuffer 524288000
2.3.3.2.2 Re-compile after compile failure

Use the following command to clear the old cache, then recompile:

cd ~/lvgl_micropython && rm -rf lib build
python3 make.py rp2 clean BOARD=RPI_PICO2
Pico2 python3 rp2 RP1_PICO 2.3.3.2.2
Pico2
adafruit/asf4 2.3.3.2.1
2.3.3.2.3 FAQ: Script not found during compile gen/
Pico2 2.3.3.2.3

At this point, if you find that the compile fails and an error is reported saying that the script cannot be found during compilation, gen/_api_gen_mpy.py, essentially the auto-generation logic related to RP2 in the project is not completed yet and the file has not been created. The original author clearly stated here that "RP2 support is still in future plans, and people who understand RP2 are needed to help write the driver".

The community has a temporary solution: https://github.com/lvgl-micropython/lvgl_micropython/issues/415

Pico2 RP2
2021 7 23 RP2 Python3

Some developers have created a rp2-fix branch in their own fork, which has got the RP2 version of the SPI screen up and running (link: https://github.com/hemonu/lvgl_micropython/tree/rp2-fix ).

2.3.3.2.4 Compile third-party developer code

The code repository is located at: https://github.com/hemonu/lvgl_micropython/tree/rp2-fix

First, clone the repository:

git clone -b rp2-fix https://github.com/hemonu/lvgl_micropython.git lvgl_micropython_rp2fix
Pico2 rp2-fix lvgl_micropython_rp2fix
cd lvgl_micropython_rp2fix
python3 make.py rp2 BOARD=RPI_PICO2
lvgl_micropython_rp2fix python3 rp2 1.27.0

If the compile fails due to network issues:

libf2fs

Use the following command to clean up the old cache, then recompile:

# First go back to the parent directory
cd ..

# Completely delete the folder that failed to download (irreversible, run after confirming)
rm -rf lvgl_micropython_rp2fix

git clone -b rp2-fix https://github.com/hemonu/lvgl_micropython.git lvgl_micropython_rp2fix

Disable Git SSL verification:

cd lvgl_micropython_rp2fix
git config --global http.sslVerify false
git config --global http.postBuffer 524288000

Execute the compile command:

cd lvgl_micropython_rp2fix
python3 make.py rp2 BOARD=RPI_PICO2
Pico2 rp2-fix lvgl_micropython_rp2fix python3 rp2 1.27.0

We need to navigate to the lvgl_micropython_rp2fix/gen directory, copy the python_api_gen_mpy.py file, and rename it to

_api_gen_mpy.py File:

lvgl_micropython_rp2fix/gen
python3 2.3.3.2.4

The following output indicates that everything is working properly:

home/leeqingshui/lvgl_micropython_rp2fix/build/lvgl_micropython_RPI_PICO.uf2 2.3.3.2.4

We can see that the firmware file is now present in the directory below:

lvgl_micropython_rp2fix/build lvgl_micropython_RPI_PICO.uf2 2.3.3.2.4

Meanwhile, the LVGL API class names, method names, parameters and return values we need are all included in the type hint file (lvgl.pyi) automatically generated by the project:

392.5KB 2024 3 26 12 05 31 13 24 CMakeFiles/Firmware.dir/home/leeqingshu/lvgl_micropython_rp2fix/lvgl/lvgl_micropython_rp2fix/lib/pico-sdk/src
lvgl_micropython_rp2fix/gen
2.3.3.3 Compile the firmware for the ST7789 screen and GT911 touch chip

We use the code developed by third-party developers here.

The code repository is located at: https://github.com/hemonu/lvgl_micropython/tree/rp2-fix

First compile:

python3 make.py rp2 BOARD=RPI_PICO2 DISPLAY=st7789 INDEV=gt911

Recompile:

python3 make.py rp2 clean BOARD=RPI_PICO2 DISPLAY=st7789 INDEV=gt911
python3 rp2 RPI_PICO2

If the following is output, the compile is successful:

Pico2 5546 901648 build-RPI_Pico2.uf2 ST7789 GT911

We can see the compiled firmware in the build folder:

Pico2 3 home/leeqingshu/lvgl_micropython_rp2fix/lib/lvgl_micropython/ports/rp2/build-RPI_PICO2/Firmware.elf

We can transfer it to the host computer via Secure Copy:

scp leeqingshui@192.168.17.130:/home/leeqingshui/lvgl_micropython_rp2fix/build/lvgl_micropy_RPI_PICO2.uf2 F:\ubuntu-vm\share\
192.168.17.130 home/leeqingshui/lvgl_micropython_rp2fix/build/lvgl_micropy_RPI_PICO2.uf2 100 1751KB 92.8MB/s 00

2.3.4 Compile using ESP32-WROOM as an example (ST7789+ GT911)

ESP32 3.2 ST7789+GT911 ST7789+TFT8472 ESP32-WROOM

Open the terminal and navigate to the project root directory (you must be under the lvgl_micropython folder)

cd ~/lvgl_micropython

The commands for the first compile are as follows:

python3 make.py esp32 --flash-size=4 --optimize-size --enable-uart-repl=y --uart-repl-bitrate=115200 BOARD=ESP32_GENERIC DISPLAY=st7789 INDEV=gt911

If you are performing a new compile after cleanup, the steps are as follows:

python3 make.py esp32 clean --flash-size=4 --optimize-size --enable-uart-repl=y --uart-repl-bitrate=115200 BOARD=ESP32_GENERIC DISPLAY=st7789 INDEV=gt911
0x2987e0 2.59MB/2715KB 0x25a000 2.35MB/2408KB
0x25a000 0x2987e0 0
ESP32 2408KB 2715KB

Here, we can see that the first compile prompts "Insufficient space in the app partition":

FAILED: esp-idf/esptool_py/CMakeFiles/app_check_size ...
Error: app partition is too small for binary micropython.bin size 0x2987e0:
- Part 'factory' 0/0 @ 0x10000 size 0x25a000 (overflow 0x3e7e0)

In the default partition table, factory (app application partition) has a size of 0x25a000 (approximately 2.35MB / 2408KB), and the micropython.bin generated after compile has a size of 0x2987e0 (approximately 2.59MB / 2715KB). The firmware size exceeds the partition capacity, resulting in a compile failure.

The reason is very simple: after the integration of LVGL and MicroPython, the firmware size is relatively large, and the partition table with the default 4MB Flash cannot allocate enough space for the app, which is a common problem in this type of compile.

***** Resizing Partition *****
***** Running build again *****

make.py after detecting insufficient partitions, automatically adjusted the partition table:

PartitionSize before adjustmentSize after adjustmentChange
factory (app)2408K2660KIncreased by 252K
vfs (file system)1624K1372KDecreased by 252K

The adjusted app partition capacity (0x298000, approx. 2.62MB) is sufficient to accommodate the firmware (0x2987e0), with only about 2KB of space remaining (the log indicates nearly full, which is a normal critical state).

The entire compile process was ultimately successful, generating a usable LVGL MicroPython firmware that can be directly flashed to an ESP32 development board for use.

lvgl_micropython_ESP32_GENERIC4.bin

2.4 Flash the Firmware and Perform Testing

2.4.1 ESP32S3 Development Board

2.4.1.1 Burn-in Test of the Minimal Compile Firmware

Open the terminal and execute the following commands in sequence:

# 1. Upgrade Pip to the latest version
python3 -m pip install --upgrade pip

# 2. Configure the Aliyun mirror for Pip (permanent, makes later tool installs faster)
mkdir -p ~/.pip
cat > ~/.pip/pip.conf << EOF
[global]
index-url = https://mirrors.aliyun.com/pypi/simple/
[install]
trusted-host = mirrors.aliyun.com
EOF
python3

Create and activate a Python virtual environment:

# 1. Create a virtual environment (named mp_env, isolates the environment to avoid conflicts)
python3 -m venv mp_env

# 2. Activate the virtual environment (the terminal prompt will start with `(mp_env)` afterward)
source mp_env/bin/activate
python3

Run the following command in the activated virtual environment:

pip install esptool
4.5/4.5MB 16.7MB/s ESP32-S3
Extension: Step-by-step guide to compile lvgl-micropython firmware, even beginners can succeed on the first try

Connect the ESP32-S3 development board to the computer via a USB cable (press and hold the BOOT button while powering on the board), then run the following commands to check the USB devices and serial port devices:

lsusb
ls /dev/ttyACM*
303a 1001 ESP32-S3

Grant serial port permissions (to avoid the "insufficient permissions" prompt during flashing):

# 1. Add the current user to the dialout group (serial port permission group)
sudo usermod -aG dialout $USER

# 2. Apply the permission temporarily (no need to log out/restart the computer)
newgrp dialout
ESP32-S3

Execute the command to test communication to verify the ESP32 connection (read the chip ID):

esptool --port /dev/ttyACM0 --chip esp32s3 chip-id
ESP32 dev/ttyACM0 esp32s3 ESP32-S3 3c 0f 02 d7 60

Replace the firmware path in the following command with your own. bin file path, then execute it:

esptool --port /dev/ttyACM0 \
  --chip esp32s3 \
  -b 460800 \
  --before default_reset \
  --after hard_reset \
  write_flash \
  --flash_mode dio \
  --flash_size 16MB \
  --flash_freq 80m \
  --erase-all \
  0x0 \
  /home/leeqingshui/lvgl_micropython/build/lvgl_micropy_ESP32_GENERIC_S3-SPIRAM_OCT-8.bin

Note:

ESP32-S3 dev/ttyACM0 ESP32S3

When the following output appears, press the RST button to restart:

ESP32-S3

Next, we need to install the mpremote tool, connect to the development board to enter the MicroPython REPL interactive mode, and verify whether the firmware is running properly:

pip install mpremote
1.27.0 4.9.4

Run the command to list all serial ports:

mpremote connect list
dev/ttyACM0 3c0f02d760bc0000 303a 4001

Run the command (replace it with your serial port):

mpremote connect /dev/ttyACM0
dev/ttyACM0

When the terminal displays the >>> prompt, it indicates that MicroPython is running properly and the firmware has been successfully flashed!

Then we execute the following two commands for verification:

import lvgl 
dir(lv)
Extension: Step-by-step guide to compile lvgl-micropython firmware, even beginners can succeed on the first try

Just run the import part in the REPL; if no error is reported, it means the operation succeeded:

import lcd_bus
import lvgl as lv
import st7789
import gt911
78ff170de9-dirty 2026 03 26 ESP32S3 st7789 gt911
2.4.1.2 Waveshare ESP32S3 2-inch Touch LCD Development Board

Open the terminal and execute the following commands in sequence:

# 1. Upgrade Pip to the latest version
python3 -m pip install --upgrade pip

# 2. Configure the Aliyun mirror for Pip (permanent, makes later tool installs faster)
mkdir -p ~/.pip
cat > ~/.pip/pip.conf << EOF
[global]
index-url = https://mirrors.aliyun.com/pypi/simple/
[install]
trusted-host = mirrors.aliyun.com
EOF
python3

Create and activate a Python virtual environment:

# 1. Create a virtual environment (named mp_env, isolates the environment to avoid conflicts)
python3 -m venv mp_env

# 2. Activate the virtual environment (the terminal prompt will start with `(mp_env)` afterward)
source mp_env/bin/activate
python3

Run the following command in the activated virtual environment:

pip install esptool
ESP32 16.7 4.5 ESP32S3
ESP32-S3

Connect the ESP32-S3 development board to the computer via a USB cable (press and hold the BOOT button while powering on the board), then run the following commands to check the USB devices and serial port devices:

lsusb
ls /dev/ttyACM*
001 009 303a 1001

Grant serial port permissions (to avoid the "insufficient permissions" prompt during flashing):

# 1. Add the current user to the dialout group (serial port permission group)
sudo usermod -aG dialout $USER

# 2. Apply the permission temporarily (no need to log out/restart the computer)
newgrp dialout
Extension: Step-by-step guide to compile lvgl-micropython firmware, even beginners can succeed on the first try

Run the command to test communication to verify the ESP32 connection (read the chip ID):

esptool --port /dev/ttyACM0 --chip esp32s3 chip-id
ESP32 dev/ttyACM0 esp32s3 ESP32-S3 QFN56 5 40MHz 3c 0f 02

Replace the firmware path in the following command with your own. bin file path, then execute it:

esptool --port /dev/ttyACM0 \
  --chip esp32s3 \
  -b 460800 \
  --before default_reset \
  --after hard_reset \
  write_flash \
  --flash_mode dio \
  --flash_size 16MB \
  --flash_freq 80m \
  --erase-all \
  0x0 \
  /home/leeqingshui/lvgl_micropython/build/lvgl_micropy_ESP32_GENERIC_S3-SPIRAM_OCT-16.bin

Note:

ESP32-S3 esp32s3

When the following output appears, press the RST button to restart the device:

ESP32-S3

Next, we need to install the mpremote tool, connect to the development board to enter the MicroPython REPL interactive mode, and verify whether the firmware is running properly:

pip install mpremote
1.27.0 4.9.4 26.0.1

Run the command to list all serial ports:

mpremote connect list
dev/ttyACM0 3c0f02d760bc0000

Run the command (replace it with your serial port):

mpremote connect /dev/ttyACM0
dev/ttyACM0

When the terminal displays the >>> prompt, it indicates that MicroPython is running properly and the firmware has been flashed successfully!

Then we execute the following two commands for verification:

import lvgl 
dir(lv)
Extension: Step-by-step guide to compile lvgl-micropython firmware, even beginners can succeed on the first try

Simply run the import section only in the REPL; if no error is thrown, it means the operation succeeded:

import lcd_bus
import lvgl as lv
import st7789
import cst816s 
78ff170de9-dirty 2026 03 27 ESP32S3 st7789 cst816s

Next, burn the following main.py file to the development board and run it:

import lcd_bus
import lvgl as lv
import st7789
import cst816s 
import time
import machine
import i2c
from micropython import const  
import task_handler

# SPI screen parameters
SPI_BUS = 2
SPI_FREQ = 40000000
LCD_SCLK = 39
LCD_MOSI = 38
LCD_MISO = 40
LCD_DC = 42
LCD_CS = 45
LCD_BL = 1

# I2C touch parameters
I2C_BUS = 0
I2C_FREQ = 400000
TP_SDA = 48
TP_SCL = 47
TP_ADDR = 0x15
TP_REGBITS = 8

# Screen resolution
TFT_HOR_RES = 320
TFT_VER_RES = 240

# Frame buffer size (fixes the REPL variable error)
BUFFER_SIZE = const(28800)

# ====================== Initialize screen hardware ======================
# Initialize the SPI bus
spi_bus = machine.SPI.Bus(host=SPI_BUS, mosi=LCD_MOSI, miso=LCD_MISO, sck=LCD_SCLK)

# Initialize the display bus
display_bus = lcd_bus.SPIBus(
    spi_bus=spi_bus,
    freq=SPI_FREQ,
    dc=LCD_DC,
    cs=LCD_CS,
)

# Allocate double frame buffers
fb1 = display_bus.allocate_framebuffer(BUFFER_SIZE, lcd_bus.MEMORY_INTERNAL | lcd_bus.MEMORY_DMA)
fb2 = display_bus.allocate_framebuffer(BUFFER_SIZE, lcd_bus.MEMORY_INTERNAL | lcd_bus.MEMORY_DMA)

# Initialize the ST7789 display
main_display = st7789.ST7789(
    data_bus=display_bus,
    frame_buffer1=fb1,
    frame_buffer2=fb2,
    display_width=TFT_VER_RES,
    display_height=TFT_HOR_RES,
    color_space=lv.COLOR_FORMAT.RGB565,
    color_byte_order=st7789.BYTE_ORDER_BGR,
    rgb565_byte_swap=True,
    backlight_pin=LCD_BL,
    backlight_on_state=st7789.STATE_PWM,
)
main_display.init()
main_display.set_power(True)
main_display.set_backlight(100)  # Turn on the backlight (100% brightness)

# ====================== Initialize touch ======================
i2c_bus = i2c.I2C.Bus(host=I2C_BUS, scl=TP_SCL, sda=TP_SDA, freq=I2C_FREQ, use_locks=False)
touch_dev = i2c.I2C.Device(bus=i2c_bus, dev_id=TP_ADDR, reg_bits=TP_REGBITS)
indev = cst816s.CST816S(touch_dev, startup_rotation=lv.DISPLAY_ROTATION._180)

# [Order fix] After touch initialization is done, set the screen rotation last (officially required)
main_display.set_rotation(lv.DISPLAY_ROTATION._90)  # Rotate 90 degrees

# ====================== LVGL UI (Label displays correctly) ======================

# Get the current screen and set a white background
scrn = lv.screen_active()
scrn.set_style_bg_color(lv.color_hex(0xFFFFFF), 0)

# Create the Label
label = lv.label(scrn)
label.set_text("FreakStudio") 
label.set_style_text_color(lv.color_black(), 0)  
label.set_pos(20, 20)

# Create the slider
slider = lv.slider(scrn)
# Set the slider size (width 300, height 25)
slider.set_size(300, 25)
# Center the slider
slider.center()

th = task_handler.TaskHandler(duration=5)

Here are a few points that require your attention!!!!

Use Thonny to flash:

ESP32 COM40

The display is as follows:

ESP32S3-2 2.4.1.2

2.4.2 Raspberry Pi Pico 2 Development Board

Press and hold the BOOT button on the Raspberry Pi Pico 2 before powering it on, then drag the compiled firmware into the virtual USB drive.

2.4.2.1 ST7789V Screen + GT911 Touch Chip

Burn the following code using Thonny:

from micropython import const
import machine
import lcd_bus
import lvgl as lv
import st7789
import time
import task_handler
import i2c
import gt911

# Screen-related configuration
WIDTH = const(240)
HEIGHT = const(320)
LCD_CS    = const(10)
LCD_DC    = const(9)
LCD_RST   = const(8)
LCD_BL    = const(11)
LCD_SCK   = const(6)
LCD_MOSI  = const(7)
LCD_FREQ  = const(40_000_000)

# GT911 touch parameters
I2C_HOST   = const(0) 
TP_RST    = const(14)   
TP_INT    = const(15)   
TP_SCL    = const(13)   
TP_SDA    = const(12)   
TP_FREQ   = const(100_000)
TP_ADDR    = 0x5D
TP_REGBITS = 16

# ====================== Initialize screen hardware ======================

# Initialize SPI and the display bus
spi_bus = machine.SPI(0, baudrate=LCD_FREQ, sck=LCD_SCK, mosi=LCD_MOSI)
display_bus = lcd_bus.SPIBus(spi_bus=spi_bus, freq=LCD_FREQ, dc=LCD_DC, cs=LCD_CS)

# Allocate double frame buffers
fb_size = WIDTH * HEIGHT * 2 // 5
fb1 = display_bus.allocate_framebuffer(fb_size, lcd_bus.MEMORY_INTERNAL | lcd_bus.MEMORY_DMA)
fb2 = display_bus.allocate_framebuffer(fb_size, lcd_bus.MEMORY_INTERNAL | lcd_bus.MEMORY_DMA)

# Initialize the ST7789 display
display = st7789.ST7789(
    data_bus=display_bus,
    display_width=WIDTH,
    display_height=HEIGHT,
    frame_buffer1=fb1,
    frame_buffer2=fb2,
    backlight_pin=machine.Pin(LCD_BL),
    backlight_on_state=st7789.STATE_PWM,
    reset_pin=machine.Pin(LCD_RST),
    reset_state=st7789.STATE_LOW,
    offset_x=0,
    offset_y=0, 
    color_space=lv.COLOR_FORMAT.RGB565,
    color_byte_order=st7789.BYTE_ORDER_RGB,
    rgb565_byte_swap=True
)

display.init()
display.set_power(True)
display.set_backlight(100)
# Turn on the backlight (100% brightness)

# ====================== Initialize touch ======================

# Initialize I2C bus
i2c_bus = i2c.I2C.Bus(host=I2C_HOST, scl=TP_SCL, sda=TP_SDA, freq=TP_FREQ, use_locks=False)
touch_dev = i2c.I2C.Device(bus=i2c_bus, dev_id=TP_ADDR, reg_bits=TP_REGBITS)
touch = gt911.GT911(device=touch_dev, reset_pin=TP_RST, interrupt_pin=TP_INT, startup_rotation=lv.DISPLAY_ROTATION._180, debug=True)

# [Order fix] After touch initialization is done, set the screen rotation last (officially required)
display.set_rotation(lv.DISPLAY_ROTATION._180)

# ====================== LVGL UI (Label displays correctly) ======================

task_handler.TaskHandler(duration=5)

# Test with a white background (easier to observe)
scrn = lv.screen_active()
scrn.set_style_bg_color(lv.color_hex(0xFFFFFF), 0)

# Create the slider widget and center it
slider = lv.slider(scrn)
slider.set_size(100, 10)
slider.center()

# Create the Label widget
label = lv.label(scrn)
label.set_text('HELLO WORLD!')
label.align(lv.ALIGN.CENTER, 0, -60)

The running results are as follows:

Pico2 ST7789V GT911 2.4.2.1

It should be noted that when using Raspberry Pi Pico 2 (RP2350) with MicroPython + LVGL + lcd_bus to drive the screen, a hard reset must be performed every time before re-running the code: the underlying hardware (DMA, SPI bus, frame buffer memory, GPIO peripherals) of the RP2350 chip on Pico 2 will not be released and reset along with program termination or soft restart; the residual hardware occupation and disordered status will directly lead to memory allocation failure and screen initialization exception, and only a full-chip hard reset can restore a clean initial hardware state.

2.4.2.1 The ST7789V screen does not have a touch chip

If you only have an ST7789V screen without a touch controller at hand, you can use the following code for flashing:

from micropython import const
import machine
import lcd_bus
import lvgl as lv
import st7789
import time
import task_handler

# Keep only the screen-related configuration
WIDTH = const(240)
HEIGHT = const(320)
LCD_CS    = const(10)
LCD_DC    = const(9)
LCD_RST   = const(8)
LCD_BL    = const(11)
LCD_SCK   = const(6)
LCD_MOSI  = const(7)
LCD_FREQ  = const(20_000_000)


# Initialize SPI
spi_bus = machine.SPI(0, baudrate=LCD_FREQ, sck=LCD_SCK, mosi=LCD_MOSI)
display_bus = lcd_bus.SPIBus(spi_bus=spi_bus, freq=LCD_FREQ, dc=LCD_DC, cs=LCD_CS)

# Initialize LVGL + screen
fb_size = WIDTH * HEIGHT * 2 // 5
fb1 = display_bus.allocate_framebuffer(fb_size, lcd_bus.MEMORY_INTERNAL | lcd_bus.MEMORY_DMA)
fb2 = display_bus.allocate_framebuffer(fb_size, lcd_bus.MEMORY_INTERNAL | lcd_bus.MEMORY_DMA)

display = st7789.ST7789(
    data_bus=display_bus,
    display_width=WIDTH,
    display_height=HEIGHT,
    frame_buffer1=fb1,
    frame_buffer2=fb2,
    backlight_pin=machine.Pin(LCD_BL),
    backlight_on_state=st7789.STATE_PWM,
    reset_pin=machine.Pin(LCD_RST),
    reset_state=st7789.STATE_LOW,
    offset_x=0,
    offset_y=0, 
    color_space=lv.COLOR_FORMAT.RGB565,
    color_byte_order=st7789.BYTE_ORDER_RGB,
    rgb565_byte_swap=True
)


display.init()
display.set_power(True)
display.set_backlight(100)

task_handler.TaskHandler(duration=5)

# Test with a white background (easier to observe)
scrn = lv.screen_active()
scrn.set_style_bg_color(lv.color_hex(0xFFFFFF), 0)

# Create the slider widget and center it
slider = lv.slider(scrn)
slider.set_size(100, 10)
slider.center()

# Create the Label widget
label = lv.label(scrn)
label.set_text('HELLO WORLD!')
label.align(lv.ALIGN.CENTER, 0, -60)

The running results are as follows:

Pico2 ST7789V 2.4.2.1

It should be noted that when using the Raspberry Pi Pico2 (RP2350) with MicroPython + LVGL + lcd_bus to drive the screen, a hard restart must be performed every time before re-running the code: the underlying hardware (DMA, SPI bus, frame buffer memory, GPIO peripherals) of the Pico2's RP2350 chip will not be released and reset with program termination or soft restart; the residual hardware occupancy and disordered status will directly lead to memory allocation failure and screen initialization exceptions, and only a full-chip hard restart can restore the clean initial hardware status.

2.4.3 ESP32-WROOM 3.2-inch Screen Development Board

For the creation of virtual environments and the esptool tool installation, you can refer to 2.4.1.1 Flashing Test for Minimal Compile Firmware. Connect the ESP32-S3 development board to your computer via a USB cable (press the BOOT button then power on the board), and run the following command to check the USB device:

lsusb
ls /dev/ttyUSB*

Why not use ls /dev/ttyACM*?

The regular ESP32-WROOM uses the CH340 USB-to-TTL module (external serial port), while the ESP32-S3 / Raspberry Pi Pico features a native USB CDC serial port, and the device naming rules for the two are completely different under Linux:

  • Native USB CDC (chip-integrated USB): The device name is /dev/ttyACM*(e. g. ttyACM0)
  • Third-party USB-to-serial chips such as CH340: the device name is /dev/ttyUSB*(for example, ttyUSB0)
ESP32-WROOM CH340 001 009 dev/ttyUSB0

Grant serial port permissions (to avoid the "insufficient permissions" prompt during flashing):

# 1. Add the current user to the dialout group (serial port permission group)
sudo usermod -aG dialout $USER

# 2. Apply the permission temporarily (no need to log out/restart the computer)
newgrp dialout
ESP32

Run the command to test communication to verify the ESP32 connection (read the chip ID):

esptool --port /dev/ttyUSB0 --chip esp32 chip-id
ESP32 dev/ttyUSB0 esp32 ESP32-DOWD-V3 v3.1

Replace the firmware path in the following command with your own. bin file path, then execute it:

esptool --port /dev/ttyUSB0 \
--chip esp32 \
-b 460800 \
--before default_reset \
--after hard_reset \
write_flash \
--flash_mode dio \
--flash_size 4MB \
--flash_freq 40m \
--erase-all \
0x0 \
/home/leeqingshui/lvgl_micropython/build/lvgl_micropy_ESP32_GENERIC-4.bin
ESP32 dev/ttyUSB0 esp32 460800 4MB 40m 80m 0x0 home/leeqingshui/lvgl_micropython/build/lvgl_micropython_ESP32_GENERIC-4.bin 2787296

After the burning is complete, press the RESET key on the development board to restart, and the firmware will run automatically!

Next, we need to install the mpremote tool, connect to the development board to enter the MicroPython REPL interactive mode, and verify whether the firmware is running properly:

ESP32-WROOM-3.2

Just run the import part in the REPL; if no error is reported, it means the operation succeeded:

import lcd_bus
import lvgl as lv
import st7789
import gt911
st7789 gt911

Next, program the main.py file below into the development board and run it:

from micropython import const
import machine
import lcd_bus
import lvgl as lv
import st7789
import time
import task_handler
import i2c
import gt911

# Screen-related configuration
SPI_HOST   = const(1) 
WIDTH = const(240)
HEIGHT = const(320)
LCD_CS    = const(15)
LCD_DC    = const(2)
# LCD_RST   = const(8)
LCD_BL    = const(27)
LCD_SCK   = const(14)
LCD_MOSI  = const(13)
LCD_MISO  = const(12)
LCD_FREQ  = const(20_000_000)

# GT911 touch parameters
I2C_HOST   = const(0) 
TP_RST    = const(25)   
TP_INT    = const(21)   
TP_SCL    = const(32)   
TP_SDA    = const(33)   
TP_FREQ   = const(100_000)
TP_ADDR    = 0x5D
TP_REGBITS = 16

# ====================== Initialize screen hardware ======================

# Initialize SPI and the display bus
spi_bus = machine.SPI.Bus(host=SPI_HOST, sck=LCD_SCK, mosi=LCD_MOSI)
display_bus = lcd_bus.SPIBus(spi_bus=spi_bus, freq=LCD_FREQ, dc=LCD_DC, cs=LCD_CS)

# Allocate double frame buffers
fb_size = WIDTH * HEIGHT * 2 // 4
fb1 = display_bus.allocate_framebuffer(fb_size, lcd_bus.MEMORY_INTERNAL | lcd_bus.MEMORY_DMA)
fb2 = display_bus.allocate_framebuffer(fb_size, lcd_bus.MEMORY_INTERNAL | lcd_bus.MEMORY_DMA)

# Initialize the ST7789 display
display = st7789.ST7789(
    data_bus=display_bus,
    display_width=WIDTH,
    display_height=HEIGHT,
    frame_buffer1=fb1,
    frame_buffer2=fb2,
    backlight_pin=machine.Pin(LCD_BL),
    backlight_on_state=st7789.STATE_PWM,
    reset_pin=None,
    reset_state=st7789.STATE_LOW,
    offset_x=0,
    offset_y=0, 
    color_space=lv.COLOR_FORMAT.RGB565,
    color_byte_order=st7789.BYTE_ORDER_BGR,
    rgb565_byte_swap=True                  
)

display.init()
display.set_power(True)
# Turn on the backlight (100% brightness)
display.set_backlight(100)

# ====================== Initialize touch ======================

# Initialize I2C bus
i2c_bus = i2c.I2C.Bus(host=I2C_HOST, scl=TP_SCL, sda=TP_SDA, freq=TP_FREQ, use_locks=False)
touch_dev = i2c.I2C.Device(bus=i2c_bus, dev_id=TP_ADDR, reg_bits=TP_REGBITS)
touch = gt911.GT911(device=touch_dev, reset_pin=TP_RST, interrupt_pin=TP_INT, startup_rotation=lv.DISPLAY_ROTATION._0, debug=True)

# [Order fix] After touch initialization is done, set the screen rotation last (officially required)
display.set_rotation(lv.DISPLAY_ROTATION._180)

# ====================== LVGL UI (Label displays correctly) ======================

# Get the current screen and set a white background
scrn = lv.screen_active()
scrn.set_style_bg_color(lv.color_hex(0xFFFFFF), 0)

# Create the Label
label = lv.label(scrn)
label.set_text("FreakStudio") 
label.set_style_text_color(lv.color_black(), 0)  
label.set_pos(20, 20)

# Create the slider
slider = lv.slider(scrn)
# Set the slider size (width 300, height 25)
slider.set_size(200, 25)
# Center the slider
slider.center()

th = task_handler.TaskHandler(duration=5)

Burn using Thonny:

Extension: Step-by-step guide to compile lvgl-micropython firmware, even beginners can succeed on the first try

The meanings of the relevant parameters output here are as follows:

The screen displays the following:

ESP32-WROOM 3.2 ESP32 GT911

Notes on Version 2.5 Update and Synchronization

If you need to sync the latest remote code, do not use git pull, you must execute the following:

# 1. Delete the old local repository (on Windows delete the folder directly; on Linux/macOS run this)
rm -rf lvgl_micropython

# 2. Clone the latest repository again
git clone https://github.com/lvgl-micropython/lvgl_micropython
cd lvgl_micropython

# 3. Rebuild
python3 make.py esp32

3. Erase the Firmware

Execute in the terminal to check the device ports:

# Most CH340/CP2102 serial chips
ls /dev/ttyUSB*

# Some ESP native USB chips (such as ESP32-S3)
ls /dev/ttyACM*

Standard erase command (replace with your port):

esptool.py --port /dev/ttyUSB0 erase_flash
ESP32 dev/ttyUSB0 ESP32-D0WD-V3 10.0

Version Record

Version Number

Modifier

Time

Content

v1.0

Li Zisheng

2026/03/24

Initialize the document.

v1.0.1

Li Zisheng

2026/03/28

Modify the title.

v1.1

Li Zisheng

2026/04/07

Added firmware compile and testing for ESP32-WROOM.

v1.2

Li Zisheng

2026/05/07

Added the tutorial section for "3. Erase Firmware".