How to port lvgl-micropython to new MCU platforms and adapt to different hardware?

[leezisheng]

Hi LVGL MicroPython maintainers,
First of all, thank you for developing this excellent project that makes LVGL GUI available for MicroPython-based embedded development!
I am currently working on porting the lvgl-micropython project to different MCU platforms (including domestic Chinese MCUs, new Raspberry Pi Pico series variants, and other third-party embedded boards), and I would like to ask for guidance on the porting process:

1. What are the core source files / modules that must be modified or implemented when porting lvgl-micropython to a new MCU?
2. What are the key hardware adaptation points (such as SPI/QSPI bus configuration, display driver integration, touch controller support, pin mapping, timer setup, and memory allocation) that need to be addressed for a new MCU?
3. Is there an official porting guide, documentation, or reference example for adding support for a new MCU in the lvgl-micropython project?
4. Are there any common pitfalls, best practices, or checklists to follow during the porting process to avoid common issues like MemoryError, display glitches, touch coordinate misalignment, or firmware build failures?

[kdschlosser]

The main goal of this project was to overcome several issues that are seen in the official LVGL to MicroPython Binding. Those issues were inconsistent API between drivers and the inability to easily upgrade MicroPython because of how woven into MicroPython the binding was. This made the binding very clunky to us and the binding was limited to only working with SPI displays.

What I did with this binding is I separated the driver code for the displays. They are split into 2 piece, one being being the display IC driver code which is written in Python and the second part is the "bus" driver which is the type of connection made to the display. There are many display IC's made that support more than one connection type so instead of having to maintain multiple sets of driver code for each display connection type by separating them only 1 display driver needs to be maintained and separately you have the different connection type drivers that need to be maintained. The display drivers have little to no knowledge of the type of bus being used. the same commands are typically sent to the display so the display drivers no mater the type of bus being used will work for the connection types supported by that display IC.

This type of a framework is what makes it easier to expand the binding to work on different MCU's. The only thing that needs to be done for different MCU's is the bus drivers need to be written. I am not familiar with the SDK's for other MCU's so writing the drivers for those MCU's is not something I have done. I have been hoping that others would help out with doing this but to date it has not been done.

There is no official documentation on doing this. It's actually fairly straight forward to do... If you look in the ext_mod/lcd_bus folder you will see the bus driver code for the Espressif line of MCU's. The same thing needs to be done for other MCU's...

The types of busses that should be provided are..

SPI
Dual SPI (2 lanes)
Quad SPI (4 lanes)
I8080 8 lanes
I8080 16 lanes
RGB 8 lanes
RGB 16 lanes
RGB 24 lanes
I2C
LED Strip (spi and others)
MIPI DSI 2 lane
MIPI DSI 4 lane

if the MCU supports using DMA transfers then that should be available to use for each of the drivers mentioned above.
If the MCU has multiple CPU cores and there would be a benefit to using more than one core then that should be done as well. The RGB driver for the ESP32 uses 2 cores because there is no hardware rotation using the RGB driver and the display also needs to be sent full frame buffers due to the display not having internal memory to store the data once it is sent to the display IC. In order to keep the rendering times down we don't want to have to handle keeping the buffers in sync and have to render the entire displays worth of data when only small areas have changed we can work around this limitation by using a second core to handle the copying of buffer data and handling the rotation so it doesn't have to be done on the same core that LVGL is running on. The code that copies the buffer data is able to be written so it will handle the positioning and rotation of a smaller buffer while it gets copied to a larger buffer in order to use partial buffers with LVGL.

The bus drivers MUST be written so they are run time drivers. All of the bus drivers should be available to use t any point in time that MicroPython is running on the MCU. The drivers need to be written with next to no wasted resources. The memory footprint needs to be as low as possible and the compile size needs to be as small as possible. We don't want any wasted resources due to the constraints of the MCU. Clean efficient code needs to be written and the use of compile time macros must not be used to make choices as to what bus gets compiled for use by the user UNLESS it is because a specific bus type is not available for use on a specific model of MCU

[kdschlosser]

All of the touch drivers are written in Python and they use common bus types found in MicroPython. The code will more than likely need to be modified in order to support working properly with the binding. In order to modify the code for a core MicroPython file for a specific port you will need to create a new folder in the micropy_updates folder. That folder needs to be the same name used in libs/micropython/ports for the MCU you are porting. Keep the directory structure the same from there out to where the file is you want to modify. Copy the original file into that new folder and make your modifications to that file.

SPI needs to be able to support having more than one device connected to the bus. the CS line needs to be managed by the driver. the user should not have to manage this wire. The SPI bus should be able to be shared with a display and or an SDCard reader. This is not possible with the current MicroPython design. The SD Card driver will more than likely also have to be updated.

You may have to update the build system in order to get it to compile for your MCU. For the most part it should work without needing any modifications doesn't matter if CMake or Makefile is being used. You simply need to alter the Makefile for a specific port in the ext_mod/lcd_bus/{port} directory to add additional files that need to be compiled. Te build system will copy files found in the micropy_updates folder to the matching path for the port. If you need to only make 1 or 2 changes to a file you can do it from the build script instead of having to copy the entire file into that micropy_updates folder. This is OK to do so long as you use the built in 'read_file' and 'write_file' functions in the build system. Those functions track changes that are made and will undo those changes when the build completes or if a build failure occurs. Look at the code in builder/esp32.py to see how it is being done.