Migrating v8.3.10 LVGL based project to v9.2.1
The following document describes the migration process of a GUI Guider project based on the older LVGL library 8.3.10, to the newer LVGL library 9.2.1 that is supported on GUI Guider v1.9.0+. We will take the CoffeePourAnimation example project as a basis to illustrate this process.
For demonstrative purposes, we will create the project on GUI Guider 1.8.0, which was the last GUI Guider version that only supported LVGL 8.3.10, and migrate it to GUI Guider 1.10.0, currently the latest version of GUI Guider, that supports LVGL 9.2.1.
In this case, we will use a MIMXRT1060-EVKC with a RK043FN66HS-CTG display.
With the project created, the very first thing we have to make sure to do is generate the GUI C code using the ‘Generate Code’ button:
Note that the project created will be based on the SDK version 2.16.000:
This SDK version is what contains the LVGL libraries, which are v8.3.10. If we want to upgrade the LVGL libraries to the latest v9.2.1, we need to update the SDK as well. But simply importing the project to a newer GUI Guider version will not update the SDK. This will just update the project file, without changing any of the underlying software package.
In order to make sure both the SDK and the LVGL libraries get updated, we will use MCUXpresso IDE. Here, we can create a new base project that uses the SDK version 25.06.00 and replace only the GUI with the one of the older projects. This will ensure we have a v9.2.1 LVGL based project, with the GUI from the previous project.
Why use specifically v25.06.00 of the SDK? Because this is the version of SDK that the latest GUI Guider (v1.10.0) uses to create projects based on LVGL v9.2.1.
In order to do this, first import the LVGL example for the board we are using (in this case, the MIMXRT1060-EVKC). This new project will be used to ensure the newest LVGL library is in place:
Make sure to import the example project named: "lvgl_guider".
The resulting project will be created, along with the following folders and files. The actual GUI, is stored on the “custom” and “generated” folders, so these are the folders that have to be replaced to bring the old GUI on the new project:
In order to replace them, navigate to both the original GUI Guider project folder, as well as the MCUXpresso lvgl_guider example project folder. Delete the ‘custom’ and ‘generated’ folders from the lvgl_guider example, and drag-and-drop these same folders from the GUI Guider project into the MCUXpresso example project:
After doing this, the new ‘generated’ and ‘custom’ folders will not be detected as source folders for the project, since they were copied from an external project. In order to add them as source folders, navigate to Project Properties > C/C++ General > Paths and Symbols, click on ‘Add Folder…’ and select both ‘custom’ and ‘generated’ folders before clicking OK:
After following either of these two processes, the old GUI Guider project will have been updated to the new SDK, which also has the new LVGL 9.2.1 libraries. That said, due to major changes on the APIs of LVGL v8 and v9, building the project will most likely result in compilation errors. Most changes of the LVGL libraries are addressed on the official LVGL documentation, specifically the following migration guide from v8 to v9: Changelog — LVGL documentation
The following section will describe the process to address the specific changes from the CoffeePourAnimation example project from LVGL v8.3.10 to v9.2.1.
Adjusting for 9.2.1 LVGL library changes:
First of all, if after compiling the project, the following error shows up:
fatal error: gui_guider.h: No such file or directory
It means that the code generated by GUI Guider was not done correctly. If that is the case, one must repeat the whole process described earlier, making sure to click on the “Generate Code” in C, as mentioned previously.
Specifically for this example CoffeePourAnimation GUI, we get an error stating:
fatal error: extra/widgets/animimg/lv_animimg.h: No such file or directory
This is because the path to the “lv_animimg.h” header file was changed on LVGL v9. In fact, that LVGL file was also renamed to “lv_animimage.h”. Therefore, we have to change the following line in “gui_guider.h”.
From:
#include "extra/widgets/animimg/lv_animimg.h"
To:
#include "src/widgets/animimage/lv_animimage.h"
The next error that shows up is one that is present for all of the image files:
fatal error: lvgl/lvgl.h: No such file or directory
This is because previously, on LVGL v8, the include path was set to the parent directory of the “lvgl.h” file (meaning that the inclusion of this header file had to be “lvgl/lvgl.h”). This is no longer the case, so we can define the following macro in order to fix the inclusion issue and simplify it to: #include “lvgl.h”.
The macro to be defined is LV_LVGL_H_INCLUDE_SIMPLE.
In project properties, under C/C++ Build > Settings > Tool Settings > MCU C Compiler> Preprocessor, click on the “Add…” button, and add that macro:
After completing this, the next errors that are shown after a compilation are all related to the images of the GUI. There were several format changes on the image headers from LVGL v8 to v9. This means that the “.c” array files that were generated on GUI Guider will no longer be compatible with the new LVGL libraries. Because of this, the images have to be re-converted for LVGL v9.2.1. This can be achieved by using the official LVGL image converter tool, either online here: Image Converter — LVGL, or via a python script found here: lvgl/scripts/LVGLImage.py at master · lvgl/lvgl · GitHub.
All of the images used on the GUI should be located under the “import” folder of the main project’s folder location.
Once all of the images from the project have been converted to the LVGL v9 format, simply replace the .c array files located under the project folder > generated > images, with the newly generated ones:
Although several changes were made to the API of the LVGL library between v8.x and v9.x, LVGL comes with an API map file, that maps new API functions to older ones for retroactive compatibility. As stated on the aforementioned Changelog — LVGL documentation, for example, “lv_disp_... is renamed to lv_display_...”, and the “lv_api_map_v8.h” file addresses this change, so that the old v8 function calls that our GUI uses, will still work on the new v9 LVGL:
That said, there might be some exceptions that fly under the radar. In the specific case that we are looking at, it happens on the following line under the “events_init.c” file:
lv_animimg_del(guider_ui.coffeePour_animimg_coffee);
In this case, the API map file does not currently contain an alias for the new function call of LVGL v9, therefore we have to adjust it manually. This might happen on other functions for specific GUIs being imported. Thankfully MCUXpresso does provide suggestions that might point to the right function to replace them with:
Also, the next change is necessary on the “events_init.c” file, which instead of doing a direct call to “animimg1->dsc”, we do it through the following call.
From:
const void **coffee_imgs = animimg1->dsc;
To:
const void **coffee_imgs = lv_animimg_get_src(guider_ui.coffeePour_animimg_coffee);
Finally, the lv_line_set_points() was changed from using the following arguments on v8:
void lv_line_set_points(lv_obj_t *obj, const lv_point_t points[], uint16_t point_num)
To these arguments on v9:
void lv_line_set_points(lv_obj_t *obj, const lv_point_precise_t points[], uint32_t point_num)
Therefore, the following change has to be made on “setup_scr_coffeePour.c”.
From:
static lv_point_t coffeePour_line_right[] = {{0, 0},{0, 180},{0, 90},{120, 90},};
static lv_point_t coffeePour_line_left[] = {{120, 0},{120, 180},{120, 90},{0, 90},};
To:
static lv_point_precise_t coffeePour_line_right[] = {{0, 0},{0, 180},{0, 90},{120, 90},};
static lv_point_precise_t coffeePour_line_left[] = {{120, 0},{120, 180},{120, 90},{0, 90},};
With these changes, the CoffePourAnimation GUI Guider project has been migrated from using LVGL v8.3.10 to v9.2.1.
Happy migrating!
View full article
