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

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:
- Simplify the compile process of LVGL + MicroPython to lower the barrier to entry.
- Unify API specifications to facilitate developers in adding new display/input device drivers.
- Supports more hardware connection topologies to adapt to different embedded Product Form.
- Performance optimization: Underlying optimizations have been implemented for scenarios such as the RGB bus, which improves the GUI rendering frame rate while reducing memory usage.
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:
- Target platforms: ESP32, STM32, RP2 (Raspberry Pi Pico), Renesas RA, nRF, i.MX RT, SAMD, etc. , with support for simulation on Unix/macOS desktops (for convenient debugging).
- Build Dependencies: Python ≥ 3.10 and a C compiler (gcc/clang/msvc) are required, and the corresponding toolchain needs to be installed for different platforms (e. g., for ESP32,
build-essential,cmake, etc.). - Note: This feature is not yet supported on Windows platforms; the macOS/Unix version needs to be run directly after being compiled locally.
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 |
WIPmeans that the content is still under development;- Compatibility solution: Unlisted ICs can be adapted via the generic
rgb_displaydriver. - SDL2: For Unix/macOS desktop only, it can simulate LCD display and input on a computer, allowing GUI code debugging without flashing to hardware.
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.
- Do not refer to the official tutorials of
- Prohibit the execution of any Git submodule initialization commands
- After cloning the repository and during the compile process, never ever run
git submodule init/updateor other submodule-related commands.
- After cloning the repository and during the compile process, never ever run
- The only way to update the version
- To upgrade to the latest
masterversion, you must delete the local old repository and re-clone it entirely;git pullupdate is not supported.
- To upgrade to the latest
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

2.2 Install Dependencies
- Python Version: All compile types must satisfy Python ≥ 3.10
- Windows system: compile is not supported on all platforms for the time being
- Comply with the core rules of the project: it is prohibited to re-clone the repository when initializing or updating submodules
We can use the following command to check the Python version:
python --version
Cross-Platform Compile Dependency Comparison Table
| Target build platform | Runtime environment | Required dependency packages | One-click install command |
|---|---|---|---|
| ESP32 | Ubuntu (Linux) | build-essential, cmake, ninja-build, python, python3-venv, libusb-1.0-0-dev | apt-get install build-essential cmake ninja-build python python3-venv libusb-1.0-0-dev |
| macOS | Xcode command line tools, cmake, ninja, python | Omitted | |
| RP2 | Ubuntu (Linux) | build-essential, cmake, ninja-build, python, gcc-arm-none-eabi, libnewlib-arm-none-eabi | apt-get install build-essential cmake ninja-build python gcc-arm-none-eabi libnewlib-arm-none-eabi |
| macOS | Xcode command line tools, make, cmake, ninja, python, arm-none-eabi-gcc | Omitted | |
| STM32 | Ubuntu (Linux) | gcc-arm-none-eabi, build-essential, ninja-build, python | apt-get install gcc-arm-none-eabi build-essential ninja-build python |
| macOS | Xcode command line tools, make, ninja, python, arm-none-eabi-gcc | Omitted | |
| Ubuntu local machine | Ubuntu (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-dev | See the long command below |
| macOS local machine | macOS | Xcode command line tools, libffi, ninja, make, SDL2 | Omitted |
| All platforms | Windows | Not supported yet | - |
2.2.1 One-click dependency installation command by environment
Ubuntu (Linux) environment:
- ESP32 compile dependencies:
sudo apt-get update
sudo apt-get install build-essential cmake ninja-build python python3-venv libusb-1.0-0-dev -y- RP2 compile dependencies
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- STM32 compile dependencies
sudo apt-get update
sudo apt-get install gcc-arm-none-eabi build-essential ninja-build python -y- Ubuntu Native Compile Dependencies
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 -y2.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
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

The verification dependencies are as follows:
# Verify the cross-compiler
arm-none-eabi-gcc --version
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 snippet | Purpose | Required? |
|---|---|---|
| python3 make.py | Start the build script (fixed, do not change) | ✅ Required |
| Target chip | Which microcontroller you are building firmware for | ✅ Required |
| Clean option | Delete the leftover files from the last build | ❌ Optional |
| Board model | The specific model of your microcontroller | ❌ Advanced, optional |
| Hardware drivers | Display / 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:
| Platform | Description |
|---|---|
| esp32 | Espressif ESP32 series MCU |
| macOS | Runs on macOS after building; note: it must be built and run on the same computer |
| stm32 | ST Microprocessors series MCU |
| unix | Runs on Unix after building; note: it must be built and run on the same computer |
| rp2 | Raspberry Pi Pico 2 MCU |
| renesas-ra | Renesas RA series MCU |
| nrf | Nordic Semiconductor MCU |
| mimxrt | NXP i.MX RT series MCU |
| samd | Microchip 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
clean: Completely delete the compile cache folder and clear the residual files from the last compile.
When the following situations arise, you may choose the following options:
- compile error, compile failure
- Switched the development board model and recompiled
- Want a brand new and clean compile environment
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:
- For microcontrollers, use
BOARD= model numberto specify the board - For the PC version, use
VARIANT= typeto specify the compile mode
The list of optional development boards is as follows:
| Platform | Item |
|---|---|
| esp32 | ARDUINO_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 | |
| stm32 | ADAFRUIT_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 | |
| rp2 | ADAFRUIT_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-ra | ARDUINO_PORTENTA_C33 |
| EK_RA4M1 | |
| EK_RA4W1 | |
| EK_RA6M1 | |
| EK_RA6M2 | |
| RA4M1_CLICKER | |
| VK_RA6M5 | |
| nrf | ACTINIUS_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 | |
| mimxrt | ADAFRUIT_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/

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:
DISPLAY= xxx: Specify the screen driverINDEV= xxx: Specify the touch/input driver
Supports configuration of multiple screens and multiple input devices:
DISPLAYScreen Driver Configuration:- Fill in the built-in driver model: The driver file is located in the project directory
api_drivers/common_api_drivers/display - Enter custom path: the full path of the screen driver folder you created
- Fill in the built-in driver model: The driver file is located in the project directory
INDEVInput Device Driver Configuration:- Fill in the built-in driver model: The driver file is located in the project directory
api_drivers/common_api_drivers/display - Enter custom path: the full path of the screen driver folder you created
- Fill in the built-in driver model: The driver file is located in the project directory
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 format | Official English description | Beginner-friendly translation & usage |
|---|---|---|
| BAUD=number | Speed 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 name | Serial 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 |
| deploy | Automatically 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-resize | Disable automatic partition size adjustment | Advanced: prevents the system from automatically modifying the firmware partitions; beginners can ignore |
| --partition-size=size | Manually set the application partition size | Advanced: for OTA remote updates only; beginners ignore |
| --optimize-size | Prioritize compressing firmware size | ✅ Reduce firmware size Function: generates a smaller firmware when the chip's storage space is insufficient |
| --debug | Enable ESP-IDF debug logging | Advanced: for finding bugs; beginners do not need to enable |
| --ccache | Speed up building | Advanced: 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.) |
| --ota | Enable the remote firmware update feature | Advanced: enable when doing wireless OTA updates; beginners do not need it |
| --dual-core-threads | Enable 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=number | Set the thread stack size | Advanced: used when running multithreaded code; beginners ignore |
| CONFIG_*=value | Modify the low-level ESP-IDF configuration | Advanced: official kernel parameter changes; beginners should not touch these at all |
| --uart-repl-bitrate=baud rate | Set the serial debug communication speed | Advanced: raises the serial speed when transferring large files; beginners ignore |
| --enable-uart-repl=y/n | Enable / disable the serial debug feature | Advanced: 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 |
| 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 |
| ✅ 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 |
| 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 format | Beginner's note |
|---|---|
| --custom-board-path=path | Fill in the path of the custom board configuration file |
| --toml=configuration file path | Use 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_micropythonPure Minimal Compile (for first compile use):
python3 make.py esp32 BOARD=ESP32_GENERIC_S3
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/libThen recompile:
python3 make.py esp32 clean BOARD=ESP32_GENERIC_S3
2.3.2.1.3 Common Issue: SSL Verification Failure in Git
If the compile fails due to network issues:

You can choose to disable Git's SSL verification:
git config --global http.sslVerify false
git config --global http.postBuffer 5242880002.3.2.1.4 FAQ: Submodule Pull Failure

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 --recursiveThe 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
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
Then execute:
python3 make.py esp32 clean BOARD=ESP32_GENERIC_S3 BOARD_VARIANT=SPIRAM_OCT DISPLAY=st7789 INDEV=gt911
When the result is displayed as follows, it indicates a successful compile:


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

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=cst816sIf 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
When the following is output, it indicates a successful compile:

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:
- Meaning: The application partition (the area that stores the MicroPython firmware and user code) is almost full, with only
2048 bytesof remaining space (0% available). - Impact:
- The current firmware can be flashed and operate normally.
- If you want to add new features, drivers or user code later, the compile will fail directly due to insufficient space.
The occupancy of each partition can be seen from the logs:
| Partition | Flash offset | Size | Free space |
|---|---|---|---|
| bootloader | 0x000000 | 19232 B | 13536 B |
| Partition table | 0x008000 | 3072 B | 1024 B |
| Application firmware | 0x010000 | 2770944 B | 2048 B |
| Total | 2836480 B (about 2.7MB) | ||

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
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_PICO22.3.3.2.1 Common Issue: Git SSL Verification Failed
If the compile fails due to network issues:

You can choose to disable Git's SSL verification:
git config --global http.sslVerify false
git config --global http.postBuffer 5242880002.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


2.3.3.2.3 FAQ: Script not found during compile gen/

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


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
cd lvgl_micropython_rp2fix
python3 make.py rp2 BOARD=RPI_PICO2
If the compile fails due to network issues:

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_rp2fixDisable Git SSL verification:
cd lvgl_micropython_rp2fix
git config --global http.sslVerify false
git config --global http.postBuffer 524288000Execute the compile command:
cd lvgl_micropython_rp2fix
python3 make.py rp2 BOARD=RPI_PICO2
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:


The following output indicates that everything is working properly:

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

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:


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=gt911Recompile:
python3 make.py rp2 clean BOARD=RPI_PICO2 DISPLAY=st7789 INDEV=gt911
If the following is output, the compile is successful:

We can see the compiled firmware in the build folder:

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\
2.3.4 Compile using ESP32-WROOM as an example (ST7789+ GT911)

Open the terminal and navigate to the project root directory (you must be under the lvgl_micropython folder)
cd ~/lvgl_micropythonThe 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=gt911If 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


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:
| Partition | Size before adjustment | Size after adjustment | Change |
|---|---|---|---|
| factory (app) | 2408K | 2660K | Increased by 252K |
| vfs (file system) | 1624K | 1372K | Decreased 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.

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
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
Run the following command in the activated virtual environment:
pip install esptool

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*
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
Execute the command to test communication to verify the ESP32 connection (read the chip ID):
esptool --port /dev/ttyACM0 --chip esp32s3 chip-id
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.binNote:
--erase-all: It is recommended to add this parameter during a fresh flashing process, as it will completely erase the Flash before writing data.- After the burning is complete, press the RESET key on the development board to restart, and the firmware will run automatically!

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

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
Run the command to list all serial ports:
mpremote connect list
Run the command (replace it with your serial port):
mpremote connect /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)
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
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
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
Run the following command in the activated virtual environment:
pip install esptool

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*
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
Run the command to test communication to verify the ESP32 connection (read the chip ID):
esptool --port /dev/ttyACM0 --chip esp32s3 chip-id
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.binNote:
--erase-all: It is recommended to add this parameter during a fresh flashing process, as it will completely erase the Flash before writing data.- After the burning is complete, press the RESET key on the development board to restart, and the firmware will run automatically!

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

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
Run the command to list all serial ports:
mpremote connect list
Run the command (replace it with your serial port):
mpremote connect /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)
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 
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!!!!
- ❌ Prohibit setting screen rotation in advance :
set_rotation ()must be displayed + touch after initialization is completed , otherwise the coordinates are chaotic and stuck; - ❌ Do not manually call lv.init ():
st7789.ST7789 ()will automatically initialize LVGL, and manual invocation will cause a conflict. - ❌ Do not initialize the screen before framebuffer allocation: The framebuffer must be created prior to screen initialization, otherwise no buffer will be available.
Use Thonny to flash:

The display is as follows:

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:

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:

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)

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
Run the command to test communication to verify the ESP32 connection (read the chip ID):
esptool --port /dev/ttyUSB0 --chip esp32 chip-id
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
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:

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
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:

The meanings of the relevant parameters output here are as follows:
rst: 0x1 (POWERON_RESET): The reset type is power-on reset, which is a normal power-on / reset methodboot: 0x13 (SPI_FAST_FLASH_BOOT): The boot mode is SPI Flash high-speed boot, and the firmware is read normallyconfigsip: 0, SPIWP: 0xeeand subsequent driver parameters: default internal SPI configuration of the ESP32 chip, no anomaliesmode: DIO, clock div: 2: Flash communication is in standard DIO mode, and the clock division configuration is normalload: xxxandentry: xxx: The MicroPython firmware has been successfully loaded from Flash into memory, and the boot process is complete.Touch Product ID: 911: GT911 capacitive touch chip successfully identified, model fully matchedTouch Firmware Version: 0x1060: The built-in firmware version of the touch chip is normalTouch Vendor ID: 0x0: Touch chip vendor ID, no abnormalities detectedTouch resolution: width= 240, height= 320: The touch resolution perfectly matches the screen (240x320)MicroPython 78ff170de9-dirty on 2026-04-07; Generic ESP32 module with ESP32: Running a custom LVGL MicroPython firmware, compile on 2026-04-07, adapted for generic ESP32Type "help ()" for more information.: Firmware startup completed, awaiting command input- Overall status: ESP32, GT911 and firmware are all normal, and there is no any fault in the hardware
The screen displays the following:

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 esp323. 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
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". |