Lesson3 Use SquareLine Studio and LVGL libraries to create a UI interface to light the lights¶
Welcome to the third lesson of learning. I believe that after completing the last two lessons, everyone has gained a deeper understanding of our product. Next, I will lead you to the second application case of the Advance series products - Display the interface by calling LVGL technology and control the on - off state of the small light bulb.
1. Using previous preparations¶
Connect the Crowpanel-Advance-HMI-AI-Display to the computer with a Type-C cable.
Connect the light bulb at the UART1-OUT interface.
This is the diagram for connecting the bulb of the 3.5-inch V1.0 version.
This is the diagram for connecting the bulb of the 3.5-inch V1.2 / V1.3 / v1.4 version.
Observing the schematic diagram of this size, it is known that the pin for UART1 to control the light bulb to turn on and off is 18
So in the code, set pin 18 as the output mode.
2. Introduce LVGL¶
LVGL (LittlevGL) is an open-source, lightweight, high-performance embedded graphics library designed specifically for devices with limited resources. It supports multi platform porting, provides rich controls, animations, touch support, and highly customizable styles, suitable for fields such as smart homes, industrial equipment, medical instruments, etc. LVGL is centered around modular design and can run on bare metal or operating systems, accelerating GUI development through powerful community support and tools such as SquareLine Studio.
SquareLine Studio is a next-generation user interface (UI) solution for individuals and professionals, allowing users to quickly and easily design and develop aesthetically pleasing UI for embedded devices. This software provides integrated design, prototyping, and development capabilities, supporting the export of platform independent C or MicroPython code for LVGL (Lightweight Graphics Library), which can be compiled and run on any vendor's device.
3. Install SquareLine Studio¶
3.1 Installation Guide¶
Enter the https://squareline.io/ to download the SquareLine installation file.
Download the version 1.4.0
Double-click the setup.exe file.
Click install.
Wait for installation.
Installation finish.
There is a 30-day trial period for the first time you use it. Please follow the prompts to register an account. You will continue to use it when you log in to your account next time.
3.2 Software Function Introduction¶
Open the software
The historical project page: open the project built earlier.
Create a project page: choose different platforms according to different hardware of the project.
When select the Arduino framwork, there's only one option "Arduino with TFT_eSPI". By choosing this, the squareline studio will generate a template code suitable for the TFT_eSPI library. However, squareline studio not only supports the TFT_eSPI library, it supports a variety of libraries to suit different hardware and application needs. For example, Adafruit_GFX library, LovyanGFX etc.
After using SLS to generate UI code, we then use different graphics libraries according to different hardware and modify the corresponding code to display the content you design.
Example page. This page has several official examples for reference.
The project settings bar is used to make basic settings for the project, including property settings such as project name, screen size, display angle, etc.
Note：Please select the corresponding resolution and color depth according to the screen specifications.
①Toolbar, including File, Export, and Help. Basic file operation bar, create or open files, export UI files and other operations. Click help and there are related introductory documents.
②Screen bar, the project screen will be listed here.
③Widget area, all widgets are here and can be selected and used according to project needs.
④Hierarchy area, it will show every widget used in each screen.
⑤This area shows the actual display effect, you can adjust the widgets or screen here.
⑥Material column, the added materials are displayed here.
⑦Setting bar, where you can make basic settings for each part, including the basic attributes and trigger operations of the part.
⑧Theme bar, different themes can be set.
4. Use SquareLine Studio to create UI control interfaces¶
4.1 Create a new SquareLine Studio project.¶
Firstly, open the SquareLine Studio software and create a case study
Choose the correct resolution based on the different sizes you are using
Here, I take a 2.8-inch screen as an example. After determining the resolution, I fill it in.
If you are using the 3.5-inch version of the product, you will need to set the display resolution to 480 x 320, according to the size comparison chart shown above.
Please note that this project uses the LVGL 8.3.11 version. Make sure to configure the correct LVGL version to ensure compatibility with the provided code and examples.
After selecting the parameters, click Create
Open the photo of the desk lamp we provided and add it in. (Of course, you can also choose the image you want to use)
The images can be found at the following location:
Just use the pictures here.
The lamp-svg image size is available for both 2.4-inch and 2.8-inch screens.
The table_lamp image sizes are available for 3.5-inch, 4.3-inch, 5.0-inch, and 7-inch screens.
After adding it, drag and drop the image in.
The task we need to complete is to turn on and off the lights by clicking on the buttons on the graphical interface. So we need to design two buttons
From the left sidebar, select Button and drag it into the interface.
You can adjust the border of the button with the mouse, which can adjust the size of the button, and you can also drag and drop the button to adjust its position.
Then, by selecting Background, choose the background color of the Button.
We have made the button patterns, and now we need to add labels to the button patterns in order to distinguish their functions.
Drag and drop from the left sidebar, select Label, and drag into the interface.
Modify the text content of the label
And modify the font size and text color of the text
The Button and Label have been designed. Click on the Hierarchy in the right-hand column and drag the Label onto the Button line to merge them into one.
At this point, if you drag the buttons again, you will find that they are dragged together
Next, we will copy a completed button, right-click, and paste it in.
Click the second button ON to change the text content to Off. Used to achieve the effect of turning off lights.
4.2 Add functions to the buttons to enable them to turn on and off lights¶
Select 'event' to add in the right sidebar.
Select 'released' as the triggering condition and 'Call function' as the action.
After selecting, click ADD.
And add a function name to the CALL Function. (Customization is sufficient)
Similarly, add an event to the Off button. The operation process is the same as above.
After adding, run
4.3 UI interface design completed, exporting UI files for easy use in subsequent code¶
Click on Project Setting
Set export path.
Complete the setup and export file.
Next, open the project folder provided for this course using VS Code. Then, copy the .h and .c files generated by LVGL into the corresponding ui folder of the project. You can download the complete project code from the link provided below.
5. Explanation of the code project¶
This project is developed and run on ESP-IDF version 5.5.4.
First, you need to specify the version of the arduino-esp32 component in the idf_component.yml file under the main folder. In this project, version 3.3.10 is used to ensure compatibility with ESP-IDF 5.5.4. After the configuration is completed, the ESP-IDF build system will automatically download and integrate the specified Arduino framework version during the first compilation.
This setup allows the project to combine the ESP-IDF development environment with the Arduino programming interface, enabling the use of Arduino-style APIs within an ESP-IDF-based project.
This section imports the required libraries for the entire screen GUI project. Arduino.h provides basic IO, serial port, delay and other low-level interfaces; LovyanGFX_Driver.h is a high-performance LCD screen driver library, responsible for screen refresh, backlight, and touch reading; Wire.h and SPI.h respectively provide I2C and SPI hardware bus drivers, SPI is used for screen data transmission, and I2C is used for communication with the GT911 touch chip; lvgl.h is the core header file of the LVGL graphics library, providing a complete set of APIs for controls, canvases, and input devices; ui.h is the interface initialization code automatically generated by the LVGL editor; touch.h encapsulates the underlying initialization functions of the GT911 touch chip, fully supporting the three core functions of screen display, touch collection, and graphical interface.
This section creates a global LovyanGFX screen driver object named "gfx". The global scope ensures that the refresh callback, touch reading functions, and setup initialization functions can directly call the screen operation interface. If it is created locally, the callback functions will not be able to access the screen hardware. By uniformly managing all hardware attributes such as screen memory, pins, brightness, and rotation, a unified management of the screen hardware is achieved.
This section defines the horizontal and vertical pixel resolutions of the screen as 320×480, and simultaneously creates a double-row drawing buffer for LVGL; draw_buf is the LVGL canvas cache management structure, and buf_1 and buf_2 are two pieces of memory used as local refresh buffers for the screen. Each buffer has a width equal to the full screen width and 20 rows of height. The double buffering mechanism is adopted to reduce screen tearing and improve the smoothness of refresh. The "static" modifier makes the buffer memory permanently reside in the static storage area, avoiding occupying stack space and preventing overflow.
This section is the standard screen refresh callback of LVGL. After LVGL completes rendering, it will automatically call this function to push the cached pixels to the physical screen. First, calculate the width and height of the area to be refreshed. Lock the SPI bus through LovyanGFX, specify the screen refresh coordinate window, and batch push RGB565 pixel data. Release the bus after the transmission is completed. Finally, call lv_disp_flush_ready to notify LVGL that the current area has been refreshed and the next frame can be rendered. This is the data interaction bridge between LVGL and the underlying screen driver.
This section defines the global touch coordinate storage variables touchX and touchY, and implements the LVGL touch input callback; by default, the touch state is marked as released. It calls the built-in touch reading interface of LovyanGFX to obtain the coordinates, detects when the touch is pressed and modifies the state to pressed, and assigns the XY coordinates to the LVGL input structure; at the same time, it prints the real-time touch coordinates via the serial port for convenient debugging. LVGL will repeatedly call this callback to obtain touch information, and the interaction controls such as buttons and sliders will respond to the operations.
This section is the initialization process that is executed only once upon powering on the Arduino. It sequentially completes the setup of the entire hardware and graphic system:
- Initialize the serial port with a baud rate of 115200, wait for the serial monitor to open and then print the boot log;
- Configure GPIO18 as an output pin reserved for hardware control, GPIO38 as the backlight control pin. When powered on, pull it low to turn off the backlight;
- Start the LovyanGFX screen hardware, set the screen rotation to 0 and the brightness to 128, and after completing the screen initialization, pull up pin 38 to light up the backlight;
- Initialize the I2C bus and bind the SDA/SCL pins of the GT911 touch control chip, print the I2C startup log;
- Initialize the LVGL kernel, bind the double-line drawing buffer;
- Register the display driver, associate the screen resolution, refresh callback and cache;
- Register the pointer-based touch input device, bind the touch reading callback, and print the touch device handle;
- Specify the I2C address of the GT911 touch control chip as 0x14, call the underlying function to initialize the touch IC;
- Load the LVGL visual interface ui_init, print the log of system initialization completion, and all hardware and graphic environment are ready.
This section constitutes the main body of the program's permanent loop. The core continuously calls the lv_timer_handler function to execute internal tasks of LVGL, including interface animations, control events, touch detection, automatic screen refreshing, etc. These are the necessary calls for the normal operation of LVGL; in combination with a 5-millisecond slight delay to release MCU resources, it reduces CPU usage without any additional business logic, merely maintaining the normal operation of the graphical interface.
Finally, if you want to control the LED connected to the UART1-OUT interface by tapping the On and Off buttons on the screen, you need to implement the callback functions defined in SquareLine Studio inside the ui_events.c file located in the ui folder under the lib directory.
6. Compile and flash the code¶
Click the link below and you can access the code for this lesson.
Select the code folder for this lesson, right-click on it, and then choose to open it with VS Code.
Note:
Remember to prepare the hardware environment as per the first point of this course.
Then, following Step 5 “Run the program” from Lesson 1, upload and execute the code in the correct sequence.
Please proceed in the following order: 1 → 2 → 3 → 4 → 5 → 6 → 10
After completing Step 10, you will be able to see your LVGL interface displayed on the screen. In addition, tapping On will turn on the LED, while tapping Off will turn it off.
