Configuration

lv_conf.h

Creating lv_conf.h

When setting up your 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 the LV_COLOR_DEPTH define to align with the color depth used by your display panel. See comments in lv_conf.h for details.

The layout of the files should look like this:

lvgl/
lv_conf.h
other files and folders in your project

Alternatively, lv_conf.h can be copied to another place but then you should add the LV_CONF_INCLUDE_SIMPLE define to your compiler options (e.g. -DLV_CONF_INCLUDE_SIMPLE for GCC compiler) and set the include path manually (e.g. -I../include/gui). In this case LVGL will attempt to include lv_conf.h simply with #include "lv_conf.h".

You can even use a different name for lv_conf.h. The custom path can be set via the LV_CONF_PATH define. For example -DLV_CONF_PATH="/home/joe/my_project/my_custom_conf.h". If this define is set LV_CONF_SKIP is assumed to be 0. Please notice, when defining the LV_CONF_PATH, you need to make sure it is defined as a string, otherwise a build error will be raised.

If LV_CONF_SKIP is defined, LVGL will not try to include lv_conf.h. Instead you can pass the config defines using build options. For example "-DLV_COLOR_DEPTH=32 -DLV_USE_BUTTON=1". Unset options will get a default value which is the same as the content of lv_conf_template.h.

LVGL also can be used via Kconfig and menuconfig. You can use lv_conf.h together with Kconfig as well, but keep in mind that the values from lv_conf.h or build settings (-D...) override the values set in Kconfig. To ignore the configs from lv_conf.h simply remove its content, or define LV_CONF_SKIP.

Configuration Settings

Once the lv_conf.h file is in place, you can modify this header to configure LVGL's behavior, disable unused modules and features, adjust the size of buffers, etc.

The comments in lv_conf.h explain the meaning of each setting. Be sure to at least set LV_COLOR_DEPTH according to your display's color depth. Note that the examples and demos explicitly need to be enabled in lv_conf.h if you need them.

TODO: Add all things related to lv_conf.h file and its contents.

Multiple Instances of LVGL

It is possible to run multiple, independent instances of LVGL. To enable its multi-instance feature, set LV_GLOBAL_CUSTOM in lv_conf.h and provide a custom function to lv_global_default() using __thread or pthread_key_t. It will allow running multiple LVGL instances by storing LVGL's global variables in TLS (Thread-Local Storage).

For example:

lv_global_t * lv_global_default(void)
{
    static __thread lv_global_t lv_global;
    return &lv_global;
}

Kconfig

TODO: Add how to use LVGL with Kconfig.