# Overview (/integration/overview)



Getting LVGL [#getting-lvgl]

Clone or Download [#clone-or-download]

If you would like to integrate LVGL yourself you can get it from GitHub: [https://github.com/lvgl/lvgl](https://github.com/lvgl/lvgl).

You can clone it or [Download](https://github.com/lvgl/lvgl/archive/refs/heads/master.zip)
the latest version as a ZIP.

If you download LVGL yourself you need to save it into your project folder so that it can be compiled with the
rest of your source code.

Frameworks and Package Registries [#frameworks-and-package-registries]

LVGL is also available in various frameworks and registries where most of the integration work is already done:

* [Arduino library](/integration/frameworks/arduino)
* [PlatformIO package](https://registry.platformio.org/libraries/lvgl/lvgl)
* [Zephyr library](/integration/rtos/zephyr)
* [ESP-IDF (ESP32) component](https://components.espressif.com/components/lvgl/lvgl)
* [NXP MCUXpresso component](https://www.nxp.com/design/software/embedded-software/lvgl-open-source-graphics-library:LITTLEVGL-OPEN-SOURCE-GRAPHICS-LIBRARY)
* [NuttX library](/integration/rtos/nuttx)
* [RT-Thread RTOS](/integration/rtos/rt-thread)
* CMSIS-Pack
* [RIOT OS package](https://doc.riot-os.org/group__pkg__lvgl.html#details)

Folder Structure [#folder-structure]

The graphics library itself is the `lvgl` directory. It contains several
directories, but to use LVGL, you only need the `.c` and `.h` files under
the `src` directory, plus `lvgl/lvgl.h`, and `lvgl/lv_version.h`.

The `lvgl` directory also contains an `examples` and a `demos`
directory. If your project needs examples and/or demos, add these
directories to your project and enable them in `lv_conf.h` or `Kconfig`
(`LV_BUILD_DEMOS` and `LV_BUILD_EXAMPLES`).

Public API [#public-api]

LVGL's public API is located under `include/lvgl`.
The canonical way to integrate LVGL is to add an include path pointing at
`lvgl/include`. You can then include the full public API with:

```c title=" " lineNumbers=1
#include <lvgl/lvgl.h>
```

If setting up `lvgl/include` as an include path isn't an option for your
project, LVGL's root directory also contains a header file that
includes the full public API, so `#include <lvgl/lvgl.h>` works there
too. Both paths are fully supported.

Every function of the public API validates its arguments at runtime. If a call
passes an invalid argument, LVGL logs a warning and the function returns without
doing anything instead of running into undefined behavior. This is enabled by
default (<ApiLink name="LV_USE_CHECK_ARG" />) and its behaviour can be configured.
See [Argument Checking](/debugging/argument_checking).

Configuration [#configuration]

LVGL has many compile-time settings: color depth, which Widgets are built, GPU
and rendering backends, third-party libraries, OS support, and more. They can be
set in three ways that can be mixed:

1. **`lv_conf.h`**: a header where `#define`s are adjusted (the default).
2. **Kconfig**: when LVGL is part of a Kconfig-based build, or built standalone with CMake.
3. **Compiler defines**: values passed on the command line (e.g. `-DLV_COLOR_FORMAT_DEFAULT=LV_COLOR_FORMAT_XRGB8888`).

When setting up a project for the first time, copy `lvgl/lv_conf_template.h` to
`lv_conf.h` next to the `lvgl` folder, change the first `#if 0` to `1` to enable
the file's content, and set <ApiLink name="LV_COLOR_FORMAT_DEFAULT" /> to match
your display panel. Adjust the other options as needed, every option is documented
by a comment in the file.

For the full details see [Configuring LVGL](/integration/configuration).

Connecting to Hardware [#connecting-to-hardware]

Several frameworks integrate LVGL deeply, and all the drivers are already in place.
This is the case in [Zephyr](/integration/rtos/zephyr), [ESP-IDF](/integration/chip_vendors/espressif),
[NuttX](/integration/rtos/nuttx), [RT-Thread](/integration/rtos/rt-thread), [NXP](/integration/chip_vendors/nxp),
[Renesas FSP](/integration/chip_vendors/renesas), etc.

LVGL also comes with many built-in display and input device drivers for on-chip
[LCD peripheries](/integration/chip_vendors), [Embedded Linux](/integration/embedded_linux),
[external display controllers](/integration/external_display_controllers), and many more.
These drivers do the heavy lifting for the drivers and also serve as references
for custom drivers.

If the existing support in frameworks or the drivers is not enough, setting up
everything from scratch is also simple. The process can be read in the following.

Initialization [#initialization]

1. Include `lvgl/lvgl.h`
2. Initialize your hardware (clock, peripherals, etc.)
3. Call <ApiLink name="lv_init" display="lv_init()" /> to initialize LVGL

Tick Interface [#tick-interface]

Set the tick for LVGL by calling <ApiLink name="lv_tick_inc" display="lv_tick_inc(x)" /> in a timer interrupt every
`x` milliseconds, or set a callback that returns the milliseconds elapsed
since startup with <ApiLink name="lv_tick_set_cb" display="lv_tick_set_cb(my_cb)" />. Many platforms have built-in
functions that can be used as they are. For example:

* SDL:  `lv_tick_set_cb(SDL_GetTicks);`
* Arduino:  `lv_tick_set_cb(my_tick_get_cb);`, where `my_tick_get_cb` is:
  `static uint32_t my_tick_get_cb(void) { return millis(); }`
* FreeRTOS:  `lv_tick_set_cb(xTaskGetTickCount);`
* STM32:  `lv_tick_set_cb(HAL_GetTick);`
* ESP32:  `lv_tick_set_cb(my_tick_get_cb);`, where `my_tick_get_cb` is a
  wrapper for `esp_timer_get_time() / 1000;`

Displays and Input Devices [#displays-and-input-devices]

Create a **Display** (<ApiLink name="lv_display_t" display="lv_display" />), set the buffers, and the flush callback.
In practice, this means implementing a single function that can show the rendered
image on the screen. It is called a `flush` callback. To learn more about
buffering options, see implementation examples and learn more about all the
features in [Display (lv\_display)](/main-modules/display).

Add **Input devices** if needed (touchpad, external buttons, keyboard, etc.) by
creating <ApiLink name="lv_indev_t" display="lv_indev" />s. To do so, a single `read` callback needs to be implemented
which returns the state of the given input device. Read more about the input device
types, their features, and check the examples at [Input devices (lv\_indev)](/main-modules/indev).

Timer Handler [#timer-handler]

All the main tasks of LVGL are implemented as software timers handled by LVGL.
There are timers for:

* rendering
* input device reading
* animation updates
* timers occasionally used by widgets
* user-created timers
* etc.

See the [Timer (lv\_timer)](/main-modules/timer) section to learn more about timers.

To process the timers of LVGL, you need to call <ApiLink name="lv_timer_handler" />
periodically in one of the following ways:

* in the `while(1)` loop of the `main()` function, or
* in an OS task periodically. (See [Operating Systems and Threads](/integration/overview).)

In the simplest case, it can be done like this:

```c title=" " lineNumbers=1
while(1) {
  lv_timer_handler(); /*Might return immediately or execute some timers*/
  lv_sleep_ms(5);
}
```

If `LV_USE_OS` is set, <ApiLink name="lv_sleep_ms" /> will be the sleep function
provided by the operating system, otherwise it will fall back to a blocking delay.
Of course, you can use any custom delay, wait, or sleep functions instead.

Sleep Management [#sleep-management]

To better control the delay/sleep time, <ApiLink name="lv_timer_handler" />
returns the remaining time until the next timer:

```c title=" " lineNumbers=1
while(1) {
  uint32_t time_till_next = lv_timer_handler();

  /*If there is nothing to do now, check again a little bit later.*/
  if(time_till_next == LV_NO_TIMER_READY) {
     time_till_next = LV_DEF_REFR_PERIOD; /*33 ms by default in lv_conf.h*/
  }
  lv_sleep_ms(time_till_next); /*Sleep the thread*/
}
```

<ApiLink name="lv_timer_handler" /> will return <ApiLink name="LV_NO_TIMER_READY" /> (`UINT32_MAX`)
if there are no running timers. This can happen if there is nothing to redraw, there are
no indevs or they are disabled with <ApiLink name="lv_indev_enable" />, there are no running
animations, and no user-created timers.

When <ApiLink name="LV_NO_TIMER_READY" /> is returned, special handling is needed to make
LVGL run again later:

* don’t sleep forever, just for a shorter time to check again a little bit later, or
* wait for an event that you will trigger when LVGL needs to run again, or
* sleep the CPU (not just the thread)

Also check the [Operating System Support](/integration/overview) section of the documentation to learn more
about the considerations when using LVGL in an operating system.

Sleep Management [#sleep-management-1]

The MCU can go to sleep when no user input has been received for a certain period.
In this case, the main `while(1)` could look like this:

```c title=" " lineNumbers=1
while(1) {
    /* Normal operation (no sleep) if < 5 sec inactivity */
    if(lv_display_get_inactive_time(lv_display_get_default()) < 5000) {
        lv_timer_handler();
    }
    /* Sleep after 5 sec inactivity */
    else {
       my_device_sleep(); /* Sleep the device, execution stops here */
    }
    lv_sleep_ms(5);
}
```

In addition to <ApiLink name="lv_display_get_inactive_time" />, you can check
<ApiLink name="lv_anim_count_running" /> to see if all animations have finished.

Operating Systems and Threads [#operating-systems-and-threads]

LVGL is **not thread-safe**.

That is, while LVGL is executing a function, you cannot call another
LVGL function from another thread. This includes calls
to <ApiLink name="lv_timer_handler" />.

Typically, this means for example, if you want to set a label's text using
<ApiLink name="lv_label_set_text" /> in one thread while in another thread
<ApiLink name="lv_timer_handler" /> is running, the same widget
can be accessed concurrently, causing issues. The same applies to creating
and deleting widgets in different threads.

Solution [#solution]

The solution is simple: before calling LVGL functions, take a mutex and
release the mutex after the functions.

LVGL has some helper functions to make it even simpler. If <ApiLink name="LV_USE_OS" />
is set to something other than `LV_OS_NONE` in `lv_conf.h`, you can use
<ApiLink name="lv_lock" /> and <ApiLink name="lv_unlock" />. <ApiLink name="lv_timer_handler" />
calls these internally. Here is an example:

```c title=" " lineNumbers=1
void main_ui_thread(void)
{
    while(1) {
        lv_timer_handler(); /* lv_lock/lv_unlock is called internally */
        lv_sleep_ms(5);
    }
}

void other_thread(void)
{
    lv_lock();
    lv_obj_t * label = lv_label_create(lv_screen_active());
    lv_unlock();

    int cnt = 0;
    while(1) {
        lv_lock();
        lv_label_set_text_fmt(label, "%d", cnt++);
        /*Call more functions if needed*/
        lv_unlock();
        lv_sleep_ms(2000);
    }
}
```

Exceptions [#exceptions]

There are some exceptions when no locking/protecting is needed.

[event callbacks](/common-widget-features/events), [timer callbacks](/main-modules/timer),
[animation callbacks](/main-modules/animation), and callbacks passed to LVGL functions
in general are called sequentially from <ApiLink name="lv_timer_handler" />, therefore
no special consideration is required as they are already protected in
<ApiLink name="lv_timer_handler" />.

Also, <ApiLink name="lv_tick_inc" /> and <ApiLink name="lv_display_flush_ready" /> are implemented
in a special way; therefore, they can be called from any thread without issues.

Compiling LVGL [#compiling-lvgl]

In general, it's trivial to build LVGL: just compile it as you would compile
the other source files of your project.

LVGL has built-in support for

* [make](/integration/building/make)
* [CMake](/integration/building/cmake)
* and Managed builds: when the IDE just globs all the files from the `lvgl` folder

Operating System Support [#operating-system-support]

LVGL is **not thread-safe**.

That means it is the programmer's responsibility to see that no LVGL function is
called while another LVGL call is in progress in another thread.  This includes calls
to <ApiLink name="lv_timer_handler" />.

Assuming the above is the case, it is safe to call LVGL functions in

* [event callbacks](/common-widget-features/events), and in
* [timer callbacks](/main-modules/timer)

because the thread that drives both of these is the thread that calls
<ApiLink name="lv_timer_handler" />.

**Reason:**

LVGL manages many complex data structures, and those structures are "system
resources" that must be protected from being "seen" by other threads in an
inconsistent state.  A high percentage LVGL functions (functions that start with
`lv_`) either read from or change those data structures.  Those that change them
place the data in an inconsistent state during call execution (because such changes are
multi-step sequences), but return them to a consistent state before those functions
return.  For this reason, execution of each LVGL function must be allowed to complete
before any other LVGL function is started.

**Exceptions to the Above:**

These two LVGL functions may be called from any thread:

* <ApiLink name="lv_tick_inc" /> (if writing to a `uint32_t` is atomic on your
  platform; see [Tick Interface](/integration/overview) for more information) and
* <ApiLink name="lv_display_flush_ready" /> ([Flush Callback](/main-modules/display/setup) for more information)

Use of MUTEXes requires:

1. acquiring the MUTEX (locking it) before each LVGL call (or group of calls), and
2. releasing the MUTEX (unlocking it) afterwards.

If your OS is integrated with LVGL (the macro <ApiLink name="LV_USE_OS" /> has a value
other than `LV_OS_NONE` in `lv_conf.h`) you can use <ApiLink name="lv_lock" /> and
<ApiLink name="lv_unlock" /> to perform #1 and #2.

When this is the case, <ApiLink name="lv_timer_handler" /> calls <ApiLink name="lv_lock" />
and <ApiLink name="lv_unlock" /> internally, so you do not have to bracket your
calls to <ApiLink name="lv_timer_handler" /> with them.

If your OS is NOT integrated with LVGL, then these calls either return
immediately with no effect, or are optimized away by the linker.

This pseudocode illustrates the concept of using a MUTEX:

```c title=" " lineNumbers=1
void lvgl_thread(void)
{
    while(1) {
        uint32_t time_till_next;
        time_till_next = lv_timer_handler(); /* lv_lock/lv_unlock is called internally */
        if(time_till_next == LV_NO_TIMER_READY) time_till_next = LV_DEF_REFR_PERIOD; /*try again soon because the other thread can make the timer ready*/
        thread_sleep(time_till_next); /* sleep for a while */
    }
}

void other_thread(void)
{
    /* You must always hold (lock) the MUTEX while calling LVGL functions. */
    lv_lock();
    lv_obj_t *img = lv_image_create(lv_screen_active());
    lv_unlock();

    while(1) {
        lv_lock();
        /* Change to next image. */
        lv_image_set_src(img, next_image);
        lv_unlock();
        thread_sleep(2000);
    }
}
```

Multiple Instances [#multiple-instances]

It is possible to run multiple, independent instances of LVGL in the same firmware.
To enable its multi-instance feature, set <ApiLink name="LV_GLOBAL_CUSTOM" /> in `lv_conf.h`
and provide a custom function to <ApiLink name="lv_global_default" /> using `__thread` or
`pthread_key_t`. This allows running multiple LVGL instances by storing LVGL's
global variables in TLS (Thread-Local Storage).

For example:

```c title=" " lineNumbers=1
lv_global_t * lv_global_default(void)
{
    static __thread lv_global_t lv_global;
    return &lv_global;
}
```