LVGL Animations run at Double Speed with task_handler module

[StephenDone]

Hi @kdschlosser,

Describe the bug
LVGL screen load animations run at double speed.
For example a lv.SCREEN_LOAD_ANIM.MOVE_LEFT specified with a 3000ms period, completes in just over 1500ms.

Expected behavior
LVGL animations should take close to the specified period to complete.

Test script. Substitute code for your own display initialisation before running. Note the 3000ms animation time...

# Create a simple screen with a centred, coloured label
def create_screen(name, colour):
    screen = lv.obj()

    label = lv.label(screen)
    label.set_style_text_color(colour, 0)
    label.set_style_text_font(lv.font_montserrat_16, 0)
    label.set_text(name)
    label.center()

    return screen

# Time how long it takes to load the screen using the animation
load_ticks = time.ticks_ms()
def show_anim_time():
    global load_ticks

    now_ticks = time.ticks_ms()
    anim_ticks = time.ticks_diff( now_ticks, load_ticks )
    print(f'animation took {anim_ticks} ms')
    load_ticks = now_ticks

# Called when the current screen has loaded. Loads the next screen.
def screen_loaded_cb(e, next_screen):
    show_anim_time()
    lv.screen_load_anim(next_screen, lv.SCREEN_LOAD_ANIM.MOVE_LEFT, 3000, 0, False)

display = CreateKnobTouch_Display(color_space=lv.COLOR_FORMAT.RGB565)
display.set_backlight(100)
display.set_rotation(lv.DISPLAY_ROTATION._0)

screen1 = create_screen('Screen 1', lv.color_hex(0xFF0000))
screen2 = create_screen('Screen 2', lv.color_hex(0x00FF00))

# Add callbacks to the screens for the screen loaded event
screen1.add_event_cb(lambda e: screen_loaded_cb(e, screen2), lv.EVENT.SCREEN_LOADED, None)
screen2.add_event_cb(lambda e: screen_loaded_cb(e, screen1), lv.EVENT.SCREEN_LOADED, None)

# Load the first screen
lv.screen_load(screen1)

# Start handling lvgl events
task_handler = task_handler.TaskHandler()

Test script output with standard task_handler module...

C:\repos\ftms\device_root>mpremote mount -l . run C:\repos\ftms\sd_knobtouch\mpremote\remote_path.py repl
Local directory . is mounted at /remote
sys.path=['', '/patch', '/lib', '/remote', '/remote/patch', '/remote/lib', '.frozen']
Connected to MicroPython at COM7
Use Ctrl-] or Ctrl-x to exit this shell
>
MicroPython 78ff170de9-dirty on 2026-03-30; Generic ESP32S3 module with Octal-SPIRAM with ESP32S3
Type "help()" for more information.
>>> import task_handler_test
Loading init module: _st77916_init_type3
Initializing Waveshare ESP32-S3 1.8 inch knob display - ST77916
animation took 1415 ms
>>> animation took 1590 ms
animation took 1502 ms
animation took 1542 ms
animation took 1543 ms
animation took 1503 ms
animation took 1542 ms
animation took 1543 ms
animation took 1503 ms
animation took 1542 ms
animation took 1543 ms
animation took 1503 ms
animation took 1542 ms

Cause of the problem
The TaskHandler class appears to be double counting time. I.e. Calling lv.tick_inc() with twice the total period during a given period of time...

On line 167 it is called with a number of ticks corresponding to the timer interval...

166    def _timer_cb(self, _):
167       lv.tick_inc(self.duration)  ##### <<<<<<
168        if self._running:
169            return

...the task handler is then scheduled to run. And within the task handler, lv.tick_inc(ticks_diff) is called twice more, but with a ticks_diff value.

Commenting out line 167 results in the following test script output...

C:\repos\ftms\device_root>mpremote mount -l . run C:\repos\ftms\sd_knobtouch\mpremote\remote_path.py repl
Local directory . is mounted at /remote
sys.path=['', '/patch', '/lib', '/remote', '/remote/patch', '/remote/lib', '.frozen']
Connected to MicroPython at COM7
Use Ctrl-] or Ctrl-x to exit this shell
>
MicroPython 78ff170de9-dirty on 2026-03-30; Generic ESP32S3 module with Octal-SPIRAM with ESP32S3
Type "help()" for more information.
>>> import task_handler_test
Loading init module: _st77916_init_type3
Initializing Waveshare ESP32-S3 1.8 inch knob display - ST77916
animation took 1398 ms
>>> animation took 3060 ms
animation took 3020 ms
animation took 3025 ms
animation took 3031 ms
animation took 3037 ms
animation took 3006 ms
animation took 3030 ms
animation took 2999 ms
animation took 3004 ms
animation took 3009 ms
animation took 3009 ms
animation took 3009 ms
animation took 3009 ms
animation took 3009 ms

...just a guess. But was line 167 the original code and then the more complex ticks_diff code was added, but the original was never removed?

**Exact make and model number of the MCU that you are compiling for or the firmware is running on. **

ESP32-S3 R8

MicroPython 78ff170de9-dirty on 2026-03-30; Generic ESP32S3 module with Octal-SPIRAM with ESP32S3

For ESP32 MCU's The PSRAM and FLASH SPI type, quad SPI or octal SPI.

• PSRAM: octal
• FLASH: quad

I need to know the OS and OS version of the machine that compiled the binary. If using a VM then I need to know the OS and OS version the VM is running. (WSL == VM)

• OS: Windows 11 with WSL 2 Ubuntu.

Build Command

python3 make.py esp32 --flash-size=16 
BOARD=ESP32_GENERIC_S3 
BOARD_VARIANT=SPIRAM_OCT 
DISPLAY=st77916 
INDEV=cst816s 
CONFIG_SPIRAM_XIP_FROM_PSRAM=y 
CONFIG_FREERTOS_USE_TRACE_FACILITY=y 
CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS=y 
CONFIG_FREERTOS_VTASKLIST_INCLUDE_COREID=y

[kdschlosser]

OK so what I want you to do is modify the task handler script like this...

    timestamp = time.ticks_ms()
    
    def _timer_cb(self, _):
        stop_time = time.ticks_ms()
        
        diff = time.ticks_diff(stop_time, self.timestamp)
        
        print(diff, self.duration)
        self.timestamp = stop_time
        
        lv.tick_inc(self.duration)
        if self._running:
            return

        if self._scheduled < self.max_scheduled:
            try:
                micropython.schedule(self._task_handler_ref, 0)
                self._scheduled += 1
            except:  # NOQA
                pass

If the timer is not running at the specified duration then the problem is in MicroPython and not in my code. The first timestamp will be off but after that you should see 33 33 every 33 milliseconds.

[kdschlosser]

I see where the problem is. It is in my code...

It's because I am calling lv_tick_inc in both the _timer_db function and also in the _task_handler function. The call made in the _task_handler function is going to be the most accurate because it is actually a measurement of the time that has passed.

[kdschlosser]

change the code in task_handler so it reads...

class TaskHandler(object):
    _current_instance = None

    def __init__(
        self,
        duration=33,
        timer_id=_default_timer_id,
        max_scheduled=2,
        exception_hook=_default_exception_hook
    ):
        if TaskHandler._current_instance is not None:
            self.__dict__.update(TaskHandler._current_instance.__dict__)
        else:
            if not lv.is_initialized():
                lv.init()

            TaskHandler._current_instance = self

            self._callbacks = []

            self.duration = duration
            self.exception_hook = exception_hook

            self._timer = Timer(timer_id)

            # Allocation occurs here
            self._task_handler_ref = self._task_handler
            self.max_scheduled = max_scheduled

            self._timer.init(
                mode=Timer.PERIODIC,
                period=self.duration,
                callback=self._timer_cb
            )
            self._scheduled = 0
            self._running = False

    def add_event_cb(self, callback, event, user_data=_DefaultUserData):
        for i, (cb, evt, data) in enumerate(self._callbacks):
            if cb == callback:
                evt = event
                if user_data != _DefaultUserData:
                    data = user_data

                self._callbacks[i] = (cb, evt, data)
                break
        else:
            if user_data == _DefaultUserData:
                user_data = None

            self._callbacks.append((callback, event, user_data))

    def remove_event_cb(self, callback):
        for (cb, evt, data) in self._callbacks:
            if cb == callback:
                self._callbacks.remove((cb,evt,data))
                break

    def deinit(self):
        self._timer.deinit()
        TaskHandler._current_instance = None

    def disable(self):
        self._scheduled += self.max_scheduled

    def enable(self):
        self._scheduled -= self.max_scheduled

    @classmethod
    def is_running(cls):
        return cls._current_instance is not None

    def _task_handler(self, _):
        try:
            self._scheduled -= 1

            if lv._nesting.value == 0:  # NOQA
                self._running = True

                run_update = True
                for cb, evt, data in self._callbacks:
                    if not evt & TASK_HANDLER_STARTED:
                        continue

                    try:
                        if cb(TASK_HANDLER_STARTED, data) is False:
                            run_update = False

                    except Exception as err:  # NOQA
                        if (
                            self.exception_hook and
                            self.exception_hook != _default_exception_hook
                        ):
                            self.exception_hook(err)
                        else:
                            sys.print_exception(err)  # NOQA

                if run_update:
                    lv.task_handler()

                    for cb, evt, data in self._callbacks:
                        if not evt & TASK_HANDLER_FINISHED:
                            continue

                        try:
                            cb(TASK_HANDLER_FINISHED, data)
                        except Exception as err:  # NOQA
                            if (
                                self.exception_hook and
                                self.exception_hook != _default_exception_hook
                            ):
                                self.exception_hook(err)
                            else:
                                sys.print_exception(err)  # NOQA

                self._running = False
            
        except Exception as e:
            self._running = False
            
            if self.exception_hook:
                self.exception_hook(e)

    def _timer_cb(self, _):
        
        lv.tick_inc(self.duration)
        if self._running:
            return

        if self._scheduled < self.max_scheduled:
            try:
                micropython.schedule(self._task_handler_ref, 0)
                self._scheduled += 1
            except:  # NOQA
                pass

[StephenDone]

change the code in task_handler so it reads...
...

Yes, that works fine. Very consistent values.

...
Loading init module: _st77916_init_type3
Initializing Waveshare ESP32-S3 1.8 inch knob display - ST77916
animation took 1391 ms
>>> animation took 3053 ms
animation took 3007 ms
animation took 3008 ms
animation took 3007 ms
animation took 3007 ms
animation took 3007 ms
animation took 2994 ms
animation took 2999 ms
animation took 3006 ms
...

I see where the problem is. It is in my code...

It's because I am calling lv_tick_inc in both the _timer_db function and also in the _task_handler function. The call made in the _task_handler function is going to be the most accurate because it is actually a measurement of the time that has passed.

Just out of interest, why did you decide to remove the ticks_diff based code and keep the timer interval duration based code instead?
The timer duration approach does seem to be very accurate, but like you initially commented, I thought the ticks_diff based code would be more resilient to variations in timer events.

[kdschlosser]

the reason why is because the where the tick_inc is now is being done inside of an ISR which is a hardware timer. It is going to occur every 33 milliseconds even while the display is refreshing the tick will still be incremented. So if you have some long running code in an event handler for LVGL the tick is still going to get incremented.

[StephenDone]

the reason why is because the where the tick_inc is now is being done inside of an ISR which is a hardware timer. It is going to occur every 33 milliseconds even while the display is refreshing the tick will still be incremented. So if you have some long running code in an event handler for LVGL the tick is still going to get incremented.

Understood!