1
2# Arduino
3
4The [LVGL library](https://github.com/lvgl/lvgl) is directly available as Arduino libraries.
5
6Note that you need to choose a board powerful enough to run LVGL and your GUI.  See the [requirements of LVGL](https://docs.lvgl.io/master/intro/index.html#requirements).
7
8For example ESP32 is a good candidate to create UI's with LVGL.
9
10## Get the LVGL Arduino library
11
12LVGL can be installed via the Arduino IDE Library Manager or as a .ZIP library.
13
14You can [Download](https://github.com/lvgl/lvgl/archive/refs/heads/master.zip) the latest version of LVGL from GitHub and simply copy it to Arduino's library folder.
15
16## Set up drivers
17
18To get started it's recommended to use [TFT_eSPI](https://github.com/Bodmer/TFT_eSPI) library as a TFT driver to simplify testing.
19To make it work, setup `TFT_eSPI` according to your TFT display type via editing either
20- `User_Setup.h`
21- or by selecting a configuration in the `User_Setup_Select.h`
22
23Both files are located in `TFT_eSPI` library's folder.
24
25## Configure LVGL
26
27LVGL has its own configuration file called `lv_conf.h`. When LVGL is installed, follow these configuration steps:
281. Go to the directory of the installed Arduino libraries
292. Go to `lvgl` and copy `lv_conf_template.h` as `lv_conf.h` into the Arduino Libraries directory next to the `lvgl` library folder.
303. Open `lv_conf.h` and change the first `#if 0` to `#if 1` to enable the content of the file
314. Set the color depth of you display in `LV_COLOR_DEPTH`
325. Set `LV_TICK_CUSTOM 1`
33
34Finally the layout with `lv_conf.h` should look like this:
35```
36arduino
37 |-libraries
38   |-lvgl
39   |-other_lib_1
40   |-other_lib_2
41   |-lv_conf.h
42```
43
44## Initialize and run LVGL
45
46Take a look at [LVGL_Arduino.ino](https://github.com/lvgl/lvgl/blob/master/examples/arduino/LVGL_Arduino/LVGL_Arduino.ino) to see how to initialize LVGL.
47`TFT_eSPI` is used as the display driver.
48
49In the INO file you can see how to register a display and a touchpad for LVGL and call an example.
50
51## Use the examples and demos
52
53Note that, there is no dedicated INO file for every example. Instead, you can load an example by calling an `lv_example_...` function. For example `lv_example_btn_1()`.
54
55**IMPORTANT NOTE 1**
56Due to some the limitations of Arduino's build system you need to copy `lvgl/examples` to `lvgl/src/examples`. Similarly for the demos `lvgl/demos` to `lvgl/src/demos`.
57
58
59**IMPORTANT NOTE 2**
60Note that the `lv_examples` library is for LVGL v7 and you shouldn't install it for this version (since LVGL v8)
61as the examples and demos are now part of the main LVGL library.
62
63## Debugging and logging
64
65LVGL can display debug information in case of trouble.
66In the `LVGL_Arduino.ino` example there is a `my_print` method, which sends this debug information to the serial interface.
67To enable this feature you have to edit the `lv_conf.h` file and enable logging in the section `log settings`:
68
69```c
70/*Log settings*/
71#define USE_LV_LOG      1   /*Enable/disable the log module*/
72#if LV_USE_LOG
73/* How important log should be added:
74 * LV_LOG_LEVEL_TRACE       A lot of logs to give detailed information
75 * LV_LOG_LEVEL_INFO        Log important events
76 * LV_LOG_LEVEL_WARN        Log if something unwanted happened but didn't cause a problem
77 * LV_LOG_LEVEL_ERROR       Only critical issue, when the system may fail
78 * LV_LOG_LEVEL_NONE        Do not log anything
79 */
80#  define LV_LOG_LEVEL    LV_LOG_LEVEL_WARN
81```
82
83After enabling the log module and setting LV_LOG_LEVEL accordingly, the output log is sent to the `Serial` port @ 115200 bps.
84
85