Labs / LVGL / 02 LVGL Basic Knowledge and Concepts

5. Timing and Dynamic Effects: The Dynamic Engine of GUI

Author: Li Zisheng · Source: FreakStudio open documentation, v1.0 · License: CC BY 4.0

Contents

5.1 Timers

The timer system built into LVGL is a core tool for implementing "periodic tasks" and "delayed execution" in embedded UI development, especially in MPY/MicroPython scenarios. Its design adapts to the lightweight requirements of embedded systems and follows the "non-preemptive" principle, which ensures the security of LVGL API calls and eliminates concerns about UI exceptions caused by timer interrupts.

5.1.1 Core Principle of Timer

The LVGL timer is not a hardware timer, but a task scheduling tool at the software level, which relies on the lv_timer_handler () function at its core:

5. Timing and Dynamic Effects: The Dynamic Engine of GUI

Meanwhile, the LVGL timer is "non-preemptive":

5.1.2 Timer Creation

LVGL provides two creation methods to adapt to different configuration requirements:

5.1.2.1 Create with Parameters

Key parameters can be directly specified when created via the core function, and will take effect immediately after creation:

5.1.2.2 Base Creation

Create an "empty timer via lv_timer_create_basic (), then dynamically configure parameters such as callback function, period, and user data after creation. This approach is suitable for scenarios where you need to create the object first and adjust parameters later according to business logic.

5.1.3 Basic Operations of Timer (Configuration and Control)

Serial No.

Functions

Description

Scenarios / Examples

Notes

1

Ready and Reset

(Trigger and Cycle Reset)

lv_timer_ready (timer) forces the timer to execute its callback once during the next lv_timer_handler () call, ignoring the current cycle progress;lv_timer_reset (timer) resets the timer's cycle count and clears the current progress to zero.

ready is suitable for scenarios where there is no need to wait for the end of the cycle and a task needs to be triggered immediately, such as manually refreshing the UI and forcing data update;reset is suitable for resetting periodic tasks after user operations, for example, triggering a search 500ms after the input box stops receiving input, and resetting the timer when a new character is entered.

ready means "schedule the next execution immediately";reset means "restart the timer".

2

Dynamically modify timer parameters

After a timer is created, its core parameters can be modified at any time without the need to recreate the timer.

You can modify the callback function to replace the logic executed when the timer is triggered; you can also modify the period to adjust the callback execution interval, for example, changing it from 500ms to 1000ms.

The behavior of the timer will immediately take effect according to the new parameters after modification.

3

Repetition Count Control

You can use lv_timer_set_repeat_count () to limit the execution times of the timer.

Set it to a specific value (e. g. 5), which means the timer will be automatically deleted after the callback is executed 5 times; set it to -1, which means infinite loop execution. Typical scenarios include one-off delayed tasks (set to 1) and finite-loop tasks (e. g. stop after a 5-count countdown).

-1 is the default infinite loop behavior; once set to a finite number of times, it will be automatically deleted after execution is completed.

5.1.4 Start, Stop, Pause and Resume of Timers

Serial No.

Functions

API

Description

Features

Applicable Scenarios

1

Enable / Disable

lv_timer_enable(timer) / lv_timer_disable(timer)

After the timer is enabled, periodic execution resumes; after the timer is disabled, execution stops and the periodic timer is reset.

When disabled, the timing progress will be reset to zero; when re-enabled, timing will start from 0.

Suitable for long-term switching timers, such as the main function switch (which stops completely after being turned off and restarts timing after being turned on again).

2

Pause / Resume

lv_timer_pause(timer) / lv_timer_resume(timer)

Pausing the timer will stop the execution while retaining the current timing progress; after resuming, the timing will continue from the paused position.

The progress remains unchanged after pausing; after resuming, the callback will be triggered once the remaining cycle is completed.

It is applicable to temporarily suspending tasks, such as pausing the animation timer when a pop-up window blocks the view and resuming it after the window is closed.

5.1.5 Idle Time Measurement

lv_timer_get_idle () is used to obtain the idle time proportion of lv_timer_handler ():

5.1.6 Timer Handler Recovery Callback

When lv_timer_handler () is stopped (e. g., during system sleep), if you need to monitor its "wake-up timing"(i. e., when lv_timer_handler () resumes being called), you can set a resume callback:

5.1.7 Asynchronous Call

Asynchronous invocation is an extended capability of the timer system, which addresses the issue of "being unable to execute a certain operation immediately", with the core being "to defer the task to the next lv_timer_handler () invocation for execution".

5.2 Animation System (Animations)

The core of LVGL's animation system lies in automatically and periodically modifying the attribute values of target objects (such as the coordinates, dimensions, and opacity of controls). It achieves visual dynamic effects by binding an "execution callback", eliminating the need for manual loop control throughout the process, and features lightweight performance and ease of use adapted to embedded (MPY) scenarios. Following a design logic of "defining animation rules via configuration for automatic execution by the framework", it supports single-attribute animations and composite timeline animations, while allowing highly customized dynamic effect styles.

5.2.1 Core Principles of Animation

5.2.2 Creation and Configuration of Single Animation

The core of creating an animation follows the workflow of "initialization → configure rules → launch". All rules are defined via configuration items, which are divided into mandatory configurations (animation fundamentals) and optional configurations (customized animation effects).

5.2.2.1 Mandatory Configuration

This is the foundation for the animation to function, defining "what to modify, which object to modify, how long the modification lasts, and the start and end points of the modification":

5.2.2.2 Optional Configuration

These configurations enable richer animation behaviors to adapt to different UI scenarios:

5.2.2.3 Animation Startup

After completing all configurations, call the start function to trigger the animation; the framework will automatically handle numerical calculation and callback invocation without manual intervention.

5.2.3 Animation Path (Motion Effect Curve) — Controlling the Gradient Rhythm

Animation path is a function that calculates the current value based on the animation progress, which determines the "feel" of the animation effect. LVGL has multiple built-in common paths that cover most scenarios:

5.2.4 Conversion between Speed and Time

The default animation defines the total duration via "duration", but in some scenarios, "speed"(e. g. moving 20 pixels per second) is more intuitive. LVGL provides a conversion function for this:

5.2.5 Deletion of Animations

If you need to stop the animation midway, you can delete it by using the combination of "target object + execution callback"(this is the unique identifier of the animation); once deleted, the animation will stop immediately and trigger the "deletion callback"(if configured).

5.2.6 Timeline — Composite Animation Scheduling

0 700ms 1 obj1 2 3 obj2 4 5 obj3

When it is necessary to implement "dynamic effects of multiple controls and multiple attributes according to a specific timeline"(such as boot guide animations and combined pop-up dynamic effects), a single animation is difficult to manage. LVGL provides the "timeline" function, which integrates multiple animations into a whole according to the timeline:

5.2.6.1 Core Value of the Timeline
5.2.6.2 Process for Creating and Using Timelines
  1. Create a single animation: Define each sub-animation according to the configuration rules for a single animation, but do not start it;
  2. Create a timeline object: Initialize an empty timeline container;
  3. Add sub-animations to the timeline: Specify the "start time on the timeline" for each sub-animation (this time will override the sub-animation's own delay configuration);
  4. Start Timeline: Triggers the entire composite animation, and the framework will automatically execute each sub-animation according to the timeline;
5.2.6.3 Core Operations of the Timeline
OperationFunction description
Reverse playbackReverses the whole timeline (e.g., runs from the last animation back to the first);
Set progressJump directly to a specified progress on the timeline (e.g., start playing from 50% progress);
Get total durationCheck the total time of the entire timeline;
Stop timelinePause all child animations;
Delete timelineDestroy the timeline and all child animations (important: before deleting a widget that is being animated, delete the timeline first to avoid a crash);

Version Record

Version Number

Modifier

Time

Content

v1.0

Li Zisheng

2026/03/23

Initialize the document.