STMicroelectronics UM3236 LVGL Libraries for LCD Displays User Manual

UM3236 LVGL Libraries for LCD Displays
User Manual

Introduction

In the modern context of the automotive industry, it is common to develop more and more complex GUIs even for small LCD displays. To meet this need, a new component, AEK-LCD-LVGL, has been created and added to the AutoDevKit ecosystem.
This new component imports the LVGL graphics library, and it is used with the AEK-LCD-DT028V1 component to develop complex GUIs faster.
The LVGL (light and versatile graphics library) is a free, open-source graphics library, written in C language, providing tools to create GUIs with easy-to-use graphics, nice visual effects, and low memory occupation.
LVGL is very powerful as it contains predefined elements, such as buttons, charts, lists, sliders, and images. Creating graphics with animations, anti- aliasing, opacity, and smooth scrolling is simplified with LVGL. The library is compatible with many types of input devices, such as touchpads, mouses, keyboards, and encoders. The aim of this user manual is to show how to create an LCD GUI easily, using AutoDevKit.
Note: For more details about LVGL, refer to the official documentation. The source code is available for download from GitHub.
AEK-LVGL architecture The above image shows the LVGL software architecture integrated into AutoDevKit.
The software architecture is characterized by:

• An LVGL library: it implements advanced graphical functions based on the AEK-LCD-DT028V1 basic graphic library:
  – aek_ili9341_drawPixel: it prints pixels on the AEK-LCD-DT028V1 LCD;
  – aek_lcd_get_touchFeedback:it it detects touch on the AEK-LCD-DT028V1 LCD touch screen;
  – aek_lcd_read_touchPos: it gets the coordinates of the touched point;
  – aek_lcd_set_touch Feedback: it flags that the touch action is completed.

• A basic graphic library: it implements basic graphic functions and calls low-level driver primitives.

• A low-level driver: it implements MCU peripherals. In this case, the SPI protocol is used.

• An AEK-LCD-DT028V1: LCD evaluation board.

LVGL basics

The LVGL library interacts with the AEK-LCD-DT028V1 component through two drivers Disprove and IndevDriver, as shown in the image below. The Disprove is in charge of preparing the buffer image and passing it to the lower layer to display it on the LCD. It uses the following lv_disp_drv_t typed structure:

• draw_buf: it points to a memory buffer structure in which the LVGL draws.

•  hirers: horizontal resolution of the display in pixels.

• Verres: vertical resolution of the display in pixels.

• flush_cb: it points to the function used to print the memory buffer to the LCD display.

•  monitor_cb: it monitors the number of pixels and the time required to display data.
  On the other side, IndevDriver retrieves the LCD touch information coming from the lower layer. It uses the following lv_indev_drv_t typed structure:
  type: this field contains the type of the input device. Predefined available macros include:
  – LV_INDEV_TYPE_POINTER (used in our case)
  – LV_INDEV_TYPE_KEYPAD
  – LV_INDEV_TYPE_ENCODER
  – LV_INDEV_TYPE_BUTTON
  redact: it points to the function used to retrieve touch information.
  flush_cb and redact: are called periodically based, respectively, on the user- defined screen refresh period and touch refresh input. The LVGL library manages refresh times through an internal clock. Two basic LVGL functions are used for time management:

• lv_tick_inc(uint32_t x): the aim of this function is to synchronize the LVGL time with the physical time of the MCU. The tick update has to be set between 1 to 10 milliseconds according to LVGL specification. In
  our case, we set it to 5 milliseconds.

• lv_timer_handler (void): it updates the internal LVGL objects based on the elapsed time. The physical time is monitored through the programmable interrupt timer (PIT) peripheral of the MCU.

Interface between LVGL and the AEK-LCD-DT028V1 component

The interface between AEK-LCD-LVGL and the AEK-LCD-DT028V1 component is implemented by a file named lcd_lvgl.c located under the “aek_lcd_lvgl_component_rla” folder. This file contains functions to:

• initialize the LVGL library,
• manage LVGL internal timer,
• interface the LVGL library with the basic graphic library implemented by the AEK-LCD-DT028V1 component.

The five key functions are explained in the following paragraphs.
3.1 Display Init
The aek_lcd_lvgl_display_init function initialize the two LVGL key structures, Disprove and IndevDriver.
3.1.1 Disprove
The key goal of the Disprove structure is to hold the drawing buffer for the LVGL. The Disprove draw_buf field points at the memory buffer structure able to contain up to two different memory buffers. The draw_buf field is initialized with the lv_disp_draw_buf_init() function.In the above code, the DISP_HOR_RES and DISP_VER_RES parameters represent the LCD dimension.
Note:
The buffer size must be customized according to the system available memory. The official LVGL guide recommends choosing the size of the drawing buffers of at least 1/10 of the screen size. If a second optional buffer is used, LVGL can tap into one buffer while the data of the other buffer is sent to be displayed in background.The other parameters of the structure are the screen dimensions, the two functions, flush and monitor_cb, that we will analyze later. Once filled, the structure has to be registered with the dedicated lv_disp_drv_register() function to set an active display.
3.1.2 IndevDriver
The IndevDriver is initialized as follows:The key defined fields are the type of device used and the function to manage it. Also in this case, the initialized structure needs to be registered to make the device become active.
3.2 Flush
The flush function uses the AEK-LCD-DT028V1 component basic graphic library to draw, on the LCD, the image present in the memory buffer initialized according to the previous paragraph.The flush function skeleton has been provided by the LVGL function and customized for the LCD screen driver in use (i.e., aek_ili9341_drawPixel – pixel drawing). The input parameters are:

• dry: the pointer to the Disprove
• area: buffer that contains the specific area that needs to be updated
• color: buffer that contains the colors to be printed.

3.3 monitor_cb
The monitor_cb function is defined in the official LVGL guide and does not require customizations. 3.4 my_input_read
The my_input_read function is in charge of managing the input coming from the LCD screen at high level.
The function skeleton is defined by the LVGL library. The input parameters are:

• drv: pointer to the initialized input driver
• data: contains the pixel-converted x,y coordinate of touched points The image below shows the implementation of the my_input_read function:

3.5 Refresh screen
The aek_lcd_lvgl_refresh_screen function updates the LVGL internal timers.
Note: This function has to be correctly placed in the application code to fulfill the LVGL time constraints.

AutoDevKit ecosystem

The application development that uses the AEK-LCD-LVGL takes full advantage of the AutoDevKit ecosystem, whose basic components are:

• AutoDevKit Studio IDE installable from www.st.com/autodevkitsw
• SPC5-UDESTK debugging software for Windows or Opened debugger
•  AEK-LCD-LVGL drive

4.1AutoDevKit Studio
AutoDevKit Studio (STSW-AUTODEVKIT) is an integrated development environment (IDE) based on Eclipse designed to assist the development of embedded applications based on SPC5 Power Architecture 32-bit microcontrollers.
The package includes an application wizard to initiate projects with all the relevant components and key elements required to generate the final application source code. AutoDevKit Studio also features:

• the possibility of integrating other software products from the standard Eclipse marketplace
• free license GCC GNU C Compiler component
• support for industry-standard compilers
• support for multi-core microcontrollers
•  PinMap editor to facilitate MCU pin configuration
•  integrated hardware and software components, component compatibility checking, and MCU and peripheral configuration tools
• the possibility of creating new system solutions from existing ones by adding or removing compatible function boards
• new code can be generated immediately for any compatible MCU
•  high-level application APIs to control each functional component, including the ones for the AEK-LCDLVGL component.

For more informationq refer to UM2623 (in particular, Section 6 and Section 7) or watch the video tutorials.
4.2 AEK_LCD_LVGL component
The AEK-LVGL drivers are provided with the STSW-AUTODEVKIT (from version 2.0.0 on) installation to facilitate the programming phase.
Update your AutoDevKit installation to get the latest version. Once properly installed, select the component named AEK_LVGL Component RLA.
4.2.1 AEK_LCD_LVGL component configuration
To configure the component, follow the procedure below.
Step 1. Set the Refr_Period time. This is the refresh screen period (the recommended value is 30).
Step 2. Set the Read_Period time. This the minimum time between two following touch detections (the recommended value is 30).
Step 3. Tick the Draw Complex box to enable advanced widget like shadows, gradients, rounded corners, circles, arcs, skew lines, and image transformations.
Step 4. Select the fonts that you want to use. Consider that each font requires extra flash memory for the generated application code.

How to create an AutoDevKit project with the AEK-LCD-LVGL component based

on SPC58EC

The steps are:
Step 1. Create a new AutoDevKit Studio application for the SPC58EC series microcontroller and add the following components:
– SPC58ECxx Init Package Component RLA
– SPC58ECxx Low Level Drivers Component RLA
Note:
Add these components at the beginning, otherwise the remaining components are not visible.
Step 2. Add the following additional components:
Step 2a. AutoDevKit Init Package Component
Step 2b. SPC58ECxx Platform Component RLA
Step 2c. AEK-LCD-DT028V1 Component RLA (see UM2939 for configuration)
Step 2d. AEK-LCD-LVGL Component RLAStep 3. Click the [Allocation] button in the AEK-LCD-LVGL configuration window. This operation delegates the AEK-LCD-LVGL configuration to AutoDevKit.
Step 4. The allocation has enabled the PIT timer peripheral. You can verify it in the Low-Level Driver component.Step 5. Generate and build the application using the appropriate icons in AutoDevKit Studio. The project folder  s then populated with new files, including main.c. The component folder is populated then with AEKLCD-DT028V1 and
AEK-LCD-LVGL drivers.
Step 6. Open the manic file and include AEK-LCD-DT028V1.h and AEK_LCD_LVGL.h files.Step 7. In the manic file, after the irqIsrEnable() function, insert the following mandatory functions:Step 8. In the main.c, copy and paste an example from the LVGL library taken from the official guide and insert it in the main().Step 9. Save, generate, and compile the application.
Step 10. Open the board view editor provided by AutoDevKit This provides a graphical point-to-point guide on how to wire the boards.
Step 11. Connect the AEK-LCD-DT028V1 to a USB port on your PC using a mini-USB to USB cable.
Step 12. Launch SPC5-UDESTK-SW and open the debug’s file in the AEK-LCD-LVGL– Application /UDE folder.
Step 13. Run and debug your code.

Available demos for AEK-LVGL

There are several demos provided with the AEK-LCD-LVGL component:

• SPC582Bxx_RLA AEK_LCD_LVGL Test Application
• SPC58ECxx_RLA AEK-LCD_LVGL Test Application
• dual screen AVAS demo – SPC58ECxx_RLA_MainEcuForIntegratAVASControl – Test Application

Note: More demos might become available with new AutoDevKit releases.

Advanced application example – dual screen AVAS demo

An advanced application has been implemented using LVGL. This application draws a car gauge for engine rpms in a display and manages the related gauge animations.
The implemented AVAS application is based on the AEK-AUD-C1D9031 board and simulates the car engine sound at low speeds to warn pedestrians of an electric vehicle approaching.
In the demo, we simulate the acceleration and deceleration (i.e., an increase/decrease of rpms) of a car engine and its volume through a control panel implemented on the LCD screen of the AEK-LCD- DT028V1.We have extended the demo by adding a second AEK-LCD-DT028V1 LCD and using the LVGL library to create a speedometer to gauge the engine rpm values.
7.1 LVGL widgets used
To develop the dual screen AVAS demo, we have used the following LVGL widgets:

• An image used as a tachometer background
• An arc used as a tachometer indicator
• An animation that updates the arc value according to the engine rpm

7.1.1 An LVGL image widget
To use an image with the LVGL library, convert it into a C array by using a free online converter. Note:
When converting the image remember to tick the box of the Big-Endian format.
In the dual screen AVAS demo, the C array representing the tachometer image has been named Gauge. The image widget has been customized as follows: Where:

• lv_img_declare: is used to declare an image called Gauge.
• lv_img_create: is used to create an image object and attach it to the current screen.
•  lv_img_set_src: this is the image obtained from the LVGL converter previously shown (it is recommended to use the jpg format).
• lv_obj_align: is used to align the image to the center with a given offset.
• lv_obj_set_size: is used to set the image size.

Note:
For more details about how to manage an image with the LVGL library, refer to the official documentation.
7.1.2 An LVGL arc widget
A multicolored arc has been created to show the engine instantaneous rpms. The multicolored arc consists of two contiguous colors, red and blue, respectively.The following code shows how to create an arc: Where:

• lv_arc_create: creates an arc object.
• lv_arc_set_rotation: sets the arc rotation.
•  lv_arc_set_bg_angles: sets the maximum and minimum arc value in degrees.
• lv_arc_set_value: sets the arc initial value at zero.
•  lv_obj_set_size: sets the arc dimensions.
• lv_obj_remove_style: removes the arc final pointer.
• lv_obj_clear_flag: sets the arc as not clickable.
• lv_obj_align: aligns the arc to the center with a specified offset.

7.1.3 Widget associated animation
A specific arc animation function is created and passed to the LVGL engine to display rpm changes. The function code is the following: Where:

• arc: is the pointer to the current arc widget
•  delay: is the delay time before the animation starts
• start: is the initial arc position
•  end: is the final arc position
• speed: is the animation speed in unit/secs.

Note: For more details about the used animation functions, refer to LVGL documentation. Considering that the complete arc consists of two contiguous arches, we had to manage the animation function properly. For this purpose, let us analyze two different scenarios:

1. Case: the animation involves one arc In this simple case, we assign a single animation to the arc.
2. Case: the animation involves two arches In this case, the animation of the second arc starts at the end of the animation of the first one.

A specific LVGL function (lv_anim_speed_to_time) computes the animation time. This execution time is used to compute the delay of the second arc animation. 7.2 Dual core implementation
In the dual screen AVAS demo, display and audio playback tasks are concurrently executed in a real-time embedded system. To overcome a possible loss of system responsiveness, we have decided to use two different cores: one dedicated to the display and one to the audio playback.
The AEK-MCU-C4MLIT1 board hosts an SPC58EC80E5 microcontroller with a dual core processor, the best fit for the above described case.
In detail:

• Core 2: It is the first to start, it initializes the library and then execute the application code.
• Core 0: It calls the aek_lcd_lvgl_refresh_screen() function within the main loop, in order to update continuously the display and read the touch input.

The PIT functions and the aek_lcd_lvgl_refresh_screen() must be placed in the same core.
Revision history
Table 1. Document revision history

IMPORTANT NOTICE – READ CAREFULLY
STMicroelectronics NV and its subsidiaries (“ST”) reserve the right to make changes, corrections, enhancements, modifications, and improvements to ST products and/or to this document at any time without notice. Purchasers should obtain the latest relevant information on ST products before placing orders. ST products are sold pursuant to ST’s terms and conditions of sale in place at the time of order acknowledgment. Purchasers are solely responsible for the choice, selection, and use of ST products and ST assumes no liability for application assistance or the design of purchasers’ products.
No license, express or implied, to any intellectual property right is granted by ST herein.
Resale of ST products with provisions different from the information set forth herein shall void any warranty granted by ST for such product.
ST and the ST logo are trademarks of ST. For additional information about ST trademarks, refer to www.st.com/trademarks. All other product or service names are the property of their respective owners.
Information in this document supersedes and replaces information previously supplied in any prior versions of this document. © 2023 STMicroelectronics – All rights reserved

UM3236 – Rev 1 – October 2023
For further information contact your local STMicroelectronics sales of

References

• STSW-AUTODEVKIT - AutoDevKit Studio for 32-bit power architecture MCUs - STMicroelectronics
• Welcome to the documentation of LVGL! — LVGL documentation
• Core widgets — LVGL documentation
• Welcome to the documentation of LVGL! — LVGL documentation
• GitHub - lvgl/lvgl: Embedded graphics library to create beautiful UIs for any MCU, MPU and display type. It's boosted by a professional yet affordable drag and drop UI editor, called SquareLine Studio.
• Online image converter - BMP, JPG or PNG to C array or binary | LVGL
• AEK-AUD-C1D9031 - AVAS solution based on SPC582B60E1 Chorus family MCU and FDA903D Class D audio amplifier - STMicroelectronics
• AutoDevKit - fast prototyping for automotive engineers - STMicroelectronics
• STSW-AUTODEVKIT - AutoDevKit Studio for 32-bit power architecture MCUs - STMicroelectronics

Read User Manual Online (PDF format)

Download This Manual (PDF format)

Download this manual  >>