Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: 'Creating GUIs with LVGL (V7)'
description: 'In this tutorial you will learn to use LVGL (Light and Versatile Graphics Library) to create a simple graphical user interface that consists of a label that updates itself.'
description: 'In this tutorial you will learn to use LVGL (Light and Versatile Graphics Library) to create a simple graphical user interface that consists of a label which updates itself.'
coverImage: assets/por_ard_lvgl_cover.svg
difficulty: intermediate
tags:
Expand All @@ -23,7 +23,7 @@ software:
---

## Overview
In this tutorial you will learn to use [LVGL](https://lvgl.io/) to create a simple graphical user interface that consists of a text label that updates itself.
In this tutorial you will learn to use [LVGL](https://lvgl.io/) to create a simple graphical user interface that consists of a text label which updates itself.

## Goals

Expand All @@ -42,19 +42,19 @@ In this tutorial you will learn to use [LVGL](https://lvgl.io/) to create a simp

## The Light and Versatile Graphics Library

Graphical User interfaces are necessary for visualizing information and interacting with certain aspects of an application. The Light and Versatile Graphics Library, also known as [LVGL](https://lvgl.io/), is an open-sourced library used to create graphical user-interfaces for microcontrollers and high-end processors. The light weight embedded library provides all the necessary widgets and user interface elements that will allow you to easily create user interfaces for displays and touch screens.
Graphical User interfaces are needed for visualizing information and interacting with certain aspects of an application. The Light and Versatile Graphics Library, also known as [LVGL](https://lvgl.io/), is an open-sourced library used to create graphical user-interfaces for microcontrollers and high-end processors. The light weight embedded library provides all the necessary widgets and user interface elements that will allow you to easily create user interfaces for displays and touch screens.

## Instructions

### Building a Simple GUI

This tutorial will guide you through building a basic user interface using the LVGL Library which you can download using the Arduino Library Manager. The setup for this tutorial requires you to first to upload the finished sketch file to the Portenta board. You will then connect the board to a USB-hub in order to connect it to an external monitor. Once the hub is powered externally, a graphical user interface with a label will be displayed on the screen.
This tutorial will guide you through building a basic user interface using the LVGL Library, which you can download using the Arduino Library Manager. The setup for this tutorial requires you to first upload the finished sketch file to the Portenta board. You will then connect the board to a USB-hub in order to connect it to an external monitor as well. Once the hub is powered externally, a graphical user interface with a label will be displayed on the screen.

![Overview of how to connect the Portenta to the peripherals.](assets/por_ard_lvgl_tutorial_steps.svg)

### 1. The Basic Setup

Begin by plugging your Portenta board into the computer using a USB-C cable and open the Arduino IDE or the Arduino Pro IDE. If this is your first time running Arduino sketch files on the board, we suggest you check out how to [set up the Portenta H7 for Arduino](setting-up-portenta) before you proceed.
Begin by plugging your Portenta board into the computer using a USB-C cable and open the Arduino IDE. If this is your first time running Arduino sketch files on the board, we suggest you check out how to [set up the Portenta H7 for Arduino](setting-up-portenta) before you proceed.

![The Portenta H7 can be connected to the computer using an appropriate USB-C cable](assets/por_ard_lvgl_basic_setup.svg)

Expand All @@ -64,7 +64,7 @@ Next, select 'Portenta' in the **Tools > Board** menu before installing [lvgl](h

![Library Manager showing the installed lvgl library.](assets/por_ard_lvgl_select_library.png)

***The sketches that we show are using the version 7.11.0, if you have the version 8 or greater you will need to make changes on the code, check LVGL API docs to see the update changes: <https://docs.lvgl.io/master/>.***
***The sketches that we show are using the version 7.11.0. If you have the version 8 or greater you will need to make changes on the code, check LVGL API docs to see the update changes: <https://docs.lvgl.io/master/>.***

### 3. Adding a Label Widget

Expand Down Expand Up @@ -104,25 +104,25 @@ This sketch creates a label that will be displayed in the center of the connecte

### 4. Connect an External Monitor

Compile and upload the sketch to your Portenta H7. At this point your board becomes the host. Unplug the board from your computer and connect it to the USB-hub along with a monitor that is connected to the HDMI port. Power up your hub by connecting it to an external power source and the monitor will display a label saying `Counter`.
Compile and upload the sketch to your Portenta H7. At this point your board becomes the host. Unplug the board from your computer and connect it to the USB-hub along with a monitor, which is connected to the HDMI port. Power up your hub by connecting it to an external power source and the monitor will display a label saying `Counter`.

![Connecting the USB peripherals and the display to Portenta.](assets/por_ard_lvgl_connect_monitor.svg)

***If you aren't familiar how the USB host works, we recommend you to have a look at the [USB Host tutorial](https://docs.arduino.cc/tutorials/portenta-h7/usb-host).***
***If you are not familiar how the USB host works, we recommend you to have a look at the [USB Host tutorial](https://docs.arduino.cc/tutorials/portenta-h7/usb-host).***

Our label object currently has LVGL's default style. If you want to customize the style you can have a look at LVGL's [documentation](https://docs.lvgl.io/latest/en/html/widgets/label.html).
Our label object currently has LVGL's default style. If you want to customize the style, you can have a look at LVGL's [documentation](https://docs.lvgl.io/latest/en/html/widgets/label.html).

### 5. Creating a Simple Counter

Let's create a counter that increases each second and update the label on the screen. To do so, we will create a label and an updating task that is going to updated the label periodically and change its value. This is possible using an LVGL concept called 'Task'.
Let's create a counter that increases each second and update the label on the screen. To do so, you have to create a label and an updating task that is going to update the label periodically and change its value. This is possible using an LVGL concept called 'Task'.

First we create a counter variable at the beginning of the program (before the `setup()` function).
First, you can create a counter variable at the beginning of the program (before the `setup()` function).

```cpp
int counter = 0;
```

Then we create the function that is going to update the value of the counter and its label. Add it to the sketch just before the `setup()` function.
Then, you can create the function that is going to update the value of the counter and its label. Add it to the sketch just before the `setup()` function.

```cpp
static void updateCounterTask(lv_task_t *task) {
Expand All @@ -137,7 +137,7 @@ static void updateCounterTask(lv_task_t *task) {
}
```

As the last line inside the `setup()` function, we create the task that calls our `updateCounterTask()` function every second (1000 milliseconds).
As the last line inside the `setup()` function, you can create the task that calls your `updateCounterTask()` function every second (1000 milliseconds).

```cpp
// Create a task to update the counter
Expand Down Expand Up @@ -204,22 +204,22 @@ void loop() {

## Conclusion

This tutorial shows how to build a simple user interface with your Portenta. Starting with a static view in the monitor and then converting it into a simple dynamic application that features an updating variable on the screen. The tutorial also shows how to use the "task" feature of LVGL to run instructions recurrently.
This tutorial shows how to build a simple user interface with your Portenta. Starting with a static view in the monitor and then converting it into a simple dynamic application that features an updating variable on the screen. The tutorial also shows how to use the "task" feature of LVGL to run instructions recurrently.

### Next Steps
Now that you know how to build a simple UI for a screen, you can try to add more labels to the screen to show various information or try out different LVGL widgets.

## Troubleshooting

### Counter Label Doesn't Update
### Counter Label Does Not Update

- Make sure that the label and task are declared on top of the sketch, outside the `setup()` and `loop()` like a normal variable.
- Check if the task has the same structure in the first declaration and the function creation.
- Look inside the `loop()` and see if `lv_task_handler()` is there.

### Sketch Upload Troubleshooting

- If you have troubles uploading the sketch, try to first set the board in bootloader mode, by clicking the reset button twice, then you should see the built-in LED pulsating.
- If you uploaded the sketch and you don't have any output in the display, make sure you have `portenta_init_video()` in the `setup()`.
- If you have troubles uploading the sketch, try to first set the board in bootloader mode, by clicking the reset button twice. Then you should see the built-in LED pulsating.
- If you uploaded the sketch and you do not have any output in the display, make sure you have `portenta_init_video()` in the `setup()`.
- Unplug and plug the HDMI cable in again.
- Reset the Portenta once it's connected to the USB-hub.
- Reset the Portenta once it is connected to the USB-hub.