1=======
2Arduino
3=======
4
5The `LVGL library <https://github.com/lvgl/lvgl>`__ is directly available as Arduino libraries.
6
7Note that you need to choose a board powerful enough to run LVGL and
8your GUI. See the :ref:`requirements of LVGL <requirements>`.
9
10For example ESP32 is a good candidate to create UI's with LVGL.
11
12If you are using the Arduino GIGA Display Shield (docs `here <https://docs.arduino.cc/hardware/giga-display-shield>`__), use the `Arduino_H7_Video <https://github.com/arduino/ArduinoCore-mbed/tree/main/libraries/Arduino_H7_Video>`__ library, included in the Arduino Mbed OS board package (`here <https://github.com/arduino/ArduinoCore-mbed>`__), which provides built-in LVGL compatibility.
13
14Get the LVGL Arduino library
15----------------------------
16
17LVGL can be installed via the Arduino IDE Library Manager or as a .ZIP library.
18
19You can `Download <https://github.com/lvgl/lvgl/archive/refs/heads/master.zip>`__
20the latest version of LVGL from GitHub and simply copy it to Arduino's
21library folder.
22
23Set up drivers
24--------------
25
26To get started it's recommended to use `TFT_eSPI <https://github.com/Bodmer/TFT_eSPI>`__ library as a TFT
27driver to simplify testing. To make it work, setup ``TFT_eSPI``
28according to your TFT display type via editing either:
29
30- ``User_Setup.h``
31- or by selecting a configuration in the ``User_Setup_Select.h``
32
33Both files are located in ``TFT_eSPI`` library's folder.
34
35
36Configure LVGL
37--------------
38
39LVGL has its own configuration file called ``lv_conf.h``. When LVGL is
40installed, follow these configuration steps:
41
421. Go to the directory of the installed Arduino libraries
432. Go to ``lvgl`` and copy ``lv_conf_template.h`` as ``lv_conf.h`` into the Arduino Libraries directory next to the ``lvgl`` library folder.
443. Open ``lv_conf.h`` and change the first ``#if 0`` to ``#if 1`` to enable the content of the file
454. Set the color depth of you display in :c:macro:`LV_COLOR_DEPTH`
46
47Finally the layout with ``lv_conf.h`` should look like this:
48
49::
50
51   arduino
52    |-libraries
53      |-lvgl
54      |-other_lib_1
55      |-other_lib_2
56      |-lv_conf.h
57
58
59Initialize and run LVGL
60-----------------------
61
62Take a look at `LVGL_Arduino.ino <https://github.com/lvgl/lvgl/blob/master/examples/arduino/LVGL_Arduino/LVGL_Arduino.ino>`__
63to see how to initialize LVGL. ``TFT_eSPI`` is used as the display driver.
64
65In the INO file you can see how to register a display and a touchpad for
66LVGL and call an example.
67
68
69Use the examples and demos
70--------------------------
71
72Note that, there is no dedicated INO file for every example. Instead,
73you can load an example by calling an ``lv_example_...`` function. For
74example :cpp:func:`lv_example_btn_1`.
75
76:important: Due to some the limitations of Arduino's build system you
77            need to copy ``lvgl/examples`` to ``lvgl/src/examples``. Similarly for
78            the demos ``lvgl/demos`` to ``lvgl/src/demos``.
79
80
81Debugging and logging
82---------------------
83
84LVGL can display debug information in case of trouble. In the
85``LVGL_Arduino.ino`` example there is a ``my_print`` method, which sends
86this debug information to the serial interface. To enable this feature
87you have to edit the ``lv_conf.h`` file and enable logging in the
88section ``log settings``:
89
90.. code-block:: c
91
92   /* Log settings */
93   #define USE_LV_LOG      1   /* Enable/disable the log module */
94   #if LV_USE_LOG
95   /* How important log should be added:
96    * LV_LOG_LEVEL_TRACE       A lot of logs to give detailed information
97    * LV_LOG_LEVEL_INFO        Log important events
98    * LV_LOG_LEVEL_WARN        Log if something unwanted happened but didn't cause a problem
99    * LV_LOG_LEVEL_ERROR       Only critical issue, when the system may fail
100    * LV_LOG_LEVEL_NONE        Do not log anything
101    */
102   #  define LV_LOG_LEVEL    LV_LOG_LEVEL_WARN
103
104After enabling the log module and setting :c:macro:`LV_LOG_LEVEL` accordingly, the
105output log is sent to the ``Serial`` port @ 115200 bps.
106