1. Overview

This application note explains how to run the LVGL GUI in uClinux running on the i.MX RT devices. LVGL is a popular open-source embedded graphics library for creating UIs on MCU and MPU targets. Refer to https://lvgl.io/ for detailed information on LVGL.

The Emcraft BSP includes a port and integration of the LVGL GUI, specifically for the i.MX RT devices running uClinux. The LVGL GUI support is integrated on top of the Linux framebuffer device driver (for the display) and touch screen devices driver, providing seamless integration with the Linux display and /dev/input input devices frameworks.

The standard Emcraft distribution includes the LVGL library sources and pre-built demo binaries for each supported board. The build configuration files and application source code required to compile LVGL from source are provided separately as a paid add-on patch (see Section 4).

2. Understanding Implementation

2.1. Understanding Integration and Build Framework

The standard Emcraft uCLinux distribution includes LVGL sources and pre-built demo binaries in the A2F directory:

• A2F/lvgl - source code of the LVGL library (clone of https://github.com/lvgl/lvgl / tag v8.3.6)

• A2F/lv_drivers - source code of the LVGL drivers (clone of https://github.com/lvgl/lv_drivers / tag v8.3.0)

Pre-built binaries are provided in A2F/lvgl_bins/<board>/ for each supported board. Each directory contains liblvgl.so (the LVGL shared library) and a set of pre-built demo applications:

• A2F/lvgl_bins/IMXRT105X_NXPEVK/ - NXP IMXRT1050-EVK. Demos: benchmark, ebike, music, stress, widgets.

• A2F/lvgl_bins/IMXRT106X_NXPEVK/ - NXP IMXRT1060-EVK. Demos: benchmark, ebike, music, stress, widgets.

• A2F/lvgl_bins/IMXRT117X_NXPEVK/ - NXP IMXRT1170-EVK. Demos: benchmark, music, stress, widgets.

• A2F/lvgl_bins/MAAXBOARD_RT/ - Avnet MaaXBoard-RT. Demos: benchmark, music, stress, widgets.

The pre-built binaries are used by default when building the projects/rootfs/ project — the Makefile in projects/rootfs/lvgl copies them into the root filesystem as liblvgl.so and the following demo applications: benchmark_gui_demo, music_gui_demo, stress_gui_demo, widgets_gui_demo. For IMXRT1050-EVK and IMXRT1060-EVK boards, ebike_gui_demo is additionally included.

The core of the LVGL is built as a shared library and is available on the target board as /usr/lib/liblvgl.so. All LVGL demos are built as separate Linux applications linked with the liblvgl.so library.

To rebuild the LVGL library and demos from source (e.g. to port to a new display or input device), the LVGL add-on patch must be applied (see Section 4). The patch installs the following files into projects/rootfs/lvgl:

• <board>/lv_drv_conf.h - per-board configuration for the Linux framebuffer and touchscreen

• <board>/lv_conf.h - per-board configuration for various LVGL options

• main.c - C source file containing a typical main() for an LVGL application

• Updated Makefile with rules to compile LVGL and demos from source

Once the patch is applied, custom changes to lv_drv_conf.h and lv_conf.h can be made to match a specific I/O configuration, and then run make in the projects/rootfs/lvgl directory to rebuild the library and applications.

2.2. Implementing I/O interactions

The ebike demo described below is available only in 480x272 resolution, so it is applicable to IMXRT1050-EVK and IMXRT1060-EVK boards, but not to the IMXRT1170-EVK (720x1280) or MaaXBoard-RT (800x480). A port to the respective display resolution is required to run the demo on those targets.

In addition to the 4 standard LVGL demos, Emcraft provides one more to demonstrate interactions of the GUI with various IO interfaces. The GUI is based on the Futuristic Ebike example from the SquareLine Studio (https://squareline.io/).

Open

The original Futuristic Ebike project was modified by Emcraft in the SquareLine Studio to assign a pin_clicked C-function callback to the virtual keyboard button click events in the Group Pin component. The UI was then exported to the projects/rootfs/lvgl/ebike_ui directory. The pin_clicked callback was implemented in projects/rootfs/lvgl/ebike_ui/ui_event.c so that when the user enters a 4-digit PIN-code and presses the V button on the virtual keyboard, the PIN-code is printed out to the Linux shell terminal from which the application is being run.

There is a separate thread implemented by Emcraft in the projects/rootfs/lvgl/main.c to monitor the state of the USER button (the SW8 button on the back side of the NXP IMXRT1050-EVK board). If the USER button is pressed the application assumes that the bike accelerates, and if the button is released the bike slows down. A dedicated LVGL timer was implemented to update the Speed, Trip, Odometer and other on-screen labels depending on the current button state. The user can see that the bike speed is increasing if the USER button is kept pressed, and decreasing if one releases the button.

The integration and build provisions for ebike_gui_demo are similar to the ones for the 4 standard LVGL demos described above. Once the demo is built, it is available on the target from the Emcraft standard rootfs project.

2.3. Understanding Interface to Linux I/O Frameworks

The LVGL implementation in the Emcraft BSP is configured to use the standard Linux framebuffer and input frameworks to support graphics output and touch input on the LCD panel.

Support for the framebuffer is provided by the mxs-lcdif driver (drivers/video/fbdev/mxsfb.c). On the IMXRT1050-EVK and IMXRT1060-EVK boards, the LCDIF controller drives the LCD panel directly. On the IMXRT1170-EVK and MaaXBoard-RT boards, the LCDIF output goes through a MIPI DSI bridge (drivers/video/fbdev/mxc/mipi_dsi_northwest.c) to reach the LCD panel. In all cases, access to the display graphics is available via the /dev/fb0 device node. Support for the touch screen is provided via the /dev/input/event0 device node.

The following table summarizes the display and touch screen configurations for each supported board:

Both the Linux framebuffer and the LVGL internal rendering buffers are allocated in the external SDRAM. This supports a 25 FPS, as measured with standard LVGL demos.

2.4. Display Connection on MaaXBoard-RT

The IMXRT1050-EVK, IMXRT1060-EVK, and IMXRT1170-EVK boards use the standard NXP-recommended LCD panels. The MaaXBoard-RT board uses a Raspberry Pi 7" Touchscreen display, which is not a standard display for this board and requires two FPC/FFC adapter boards (30-pin 0.5 mm/1 mm to 2.54 mm) to connect the MaaXBoard-RT MIPI DSI connector to the RPi display connector:

Open

The following table describes the adapter wiring between the MaaXBoard-RT MIPI DSI connector and the Raspberry Pi display connector:

3. Running LVGL Demos

3.1. Running Standard LVGL Demos

Step through the following procedure to run the standard LVGL demos:

1. From the Linux shell, perform the following command to power on the LCD backlight:

   / # echo 0 > /sys/class/backlight/backlight/bl_power

2. From the Linux shell, type the benchmark_gui_demo command to run the benchmark demo:

   / # benchmark_gui_demo

    

   Open

   

   Type Ctrl-C to finish the demo:

   / # benchmark_gui_demo ^C / #

3. Type the music_gui_demo command to run the music demo. Click the widgets icons on the touch panel to navigate the demo:

   / # music_gui_demo

    

   Open

   

   Type Ctrl-C to finish the demo:

   / # music_gui_demo ^C / #

4. Type the stress_gui_demo command to run the stress demo:

   / # stress_gui_demo

    

   Open

   

   Type Ctrl-C to finish the demo:

   / # stress_gui_demo ^C / #

5. Type the widgets_gui_demo command to run the widgets demo. Click the widgets icons on the touch panel to navigate the demo:

   / # widgets_gui_demo

    

   Open

   

   Type Ctrl-C to finish the demo:

   / # widgets_gui_demo ^C / #

3.2. Running Emcraft Ebike Demo

The ebike demo is not available on the IMXRT1170-EVK (720x1280) or MaaXBoard-RT (800x480) boards. A port to the respective display resolution is required.

Step through the following procedure to run the Emcraft Ebike demo.

1. From the Linux shell, type the ebike_gui_demo command to run the ebike demo:

   / # ebike_gui_demo

2. Click the padlock icon in the bottom right corner of the screen to switch to the Unlock Your Bike group.

   Open

   

    

3. Click any 4 digits and then v. Make sure the correct PIN-code is printed out to the Linux shell terminal:

   / # ebike_gui_demo entered pin: 4 7 1 2

4. Click the bike icon to switch back to the Driving Information group.

5. Press and hold the SW8 button which resides on the opposite side of the IMXRT1050-EVK board to LCD. Make sure that the Speed, Trip, Odometer and other values are increasing on the corresponding widgets on the LCD. If release the SW8 button the Speed reading is decreasing:

   Open

   

4. Building LVGL

4.1. Secure Download Area

Emcraft supports the LVGL port to the i.MX RT as a paid add-on. Once you have purchased the add-on from Emcraft, you can obtain the LVGL patch from the secure download area. All pages are protected — contact Emcraft for login credentials.

4.1.1. i.MX RT1170-EVK / MaaXBoard-RT

• Release 3.3.2 (current): https://www.emcraft.com/imxrtaddon/imxrt1170-3.3.2/lvgl

• Release 3.3.1: https://www.emcraft.com/imxrtaddon/imxrt1170/lvgl

4.1.2. i.MX RT1060-EVK

• Release 3.2.0 (current): https://www.emcraft.com/imxrtaddon/imxrt1060-3.2.0/lvgl

• Release 3.1.0: https://www.emcraft.com/imxrtaddon/imxrt1060-3.1.0/lvgl

4.1.3. i.MX RT1050-EVK

• Release 3.2.0 (current): https://www.emcraft.com/imxrtaddon/imxrt1050-3.2.0/lvgl

• Release 3.1.0: https://www.emcraft.com/imxrtaddon/imxrt1050-3.1.0/lvgl

• Release 3.0.4: https://www.emcraft.com/imxrtaddon/imxrt1050/lvgl

4.2. Building LVGL

Step through the following procedure to apply the LVGL add-on and build the LVGL binaries from source:

1. From the top of the Linux installation on the development host, go to the projects directory

2. Apply the patch:

   $ patch -p1 < ../../projects-lvgl-gui.patch

   Note: The patch switches the build from using pre-built binaries to compiling the LVGL library and demo applications from source. After applying the patch, make will build liblvgl.so and all demos from the LVGL sources in A2F/lvgl using the per-board configuration headers installed by the patch.

3. Build the rootfs project:

   $ cd rootfs/ $ make

The built LVGL binaries will be included in the bootable target image. They can be run on the target as described in the previous sections.