[中文]

Connecting LVGL to Your Hardware

Initializing LVGL

After you have:

• acquired LVGL,

• added the appropriate LVGL files to your project, and

• created a lv_conf.h file for your project,

you will need to complete a few more steps to get your project up and running with LVGL.

1. Initialize LVGL once early during system execution by calling lv_init(). This needs to be done before making any other LVGL calls.

2. Initialize your drivers.

3. Connect the Tick Interface.

4. Connect the Display Interface.

5. Connect the Input-Device Interface.

6. Drive LVGL time-related tasks by calling lv_timer_handler() every few milliseconds to manage LVGL timers. See Timer Handler for different ways to do this.

7. Optionally set a theme with lv_display_set_theme().

8. Thereafter #include "lvgl/lvgl.h" in source files wherever you need to use LVGL functions.

Tick Interface

LVGL needs awareness of what time it is (i.e. elapsed time in milliseconds) for all of its tasks for which time is a factor: refreshing displays, reading user input, firing events, animations, etc.

There are two ways to provide this information to LVGL:

1. Supply LVGL with a callback function to retrieve elapsed system milliseconds by calling lv_tick_set_cb(my_get_milliseconds_function). my_get_milliseconds_function() needs to return the number of milliseconds elapsed since system start up. 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;

2. Call lv_tick_inc(x) periodically, where x is the elapsed milliseconds since the last call. If lv_tick_inc() is called from an ISR, it should be from either a high priority interrupt or an interrupt that cannot be missed when the system is under high load.

   Note

   lv_tick_inc() is only one of two LVGL functions that may be called from an interrupt. See the Threading Considerations section to learn more.

The ticks (milliseconds) should be independent from any other activities of the MCU.

For example this works, but LVGL's timing will be incorrect as the execution time of lv_timer_handler() is not considered:

// Bad idea
lv_timer_handler();
lv_tick_inc(5);
my_delay_ms(5);

Display Interface

LVGL needs to be supplied with knowledge about each display panel you want it to use. Specificially:

• its pixel format and size (Creating a Display),

• where to render pixels for it (Draw Buffer(s)), and

• how to send those rendered pixels to it (Flush Callback).

See the respective links for how to supply LVGL with this knowledge.

Input-Device Interface

LVGL needs to know how to get input from all user-input devices that will be used in your project. LVGL supports a wide variety of user-input devices:

• touch-screens,

• touch-pads,

• mice,

• crowns,

• encoders,

• keypads,

• keyboards,

• etc.

See Creating an Input Device to see how to do this.

API

lv_tick.h