Labs / LVGL / 02 LVGL Basic Knowledge and Concepts

VII. Extensibility and Customization Capabilities: GUI Extension Interfaces

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

Contents

VII. Extensibility and Customization Capabilities: GUI Extension Interfaces

It provides resource loading and custom development capabilities to meet the personalized needs of business scenarios.

7.1 File System

The file system module of LVGL is a hardware-independent abstraction layer, whose core purpose is to mask the underlying differences between various storage media (such as SD cards, SPI Flash, local disks) and file systems (such as FATFS, POSIX-compliant file systems), so as to provide a unified file operation interface for upper-layer applications (such as image loading, file reading and writing).

7.1.1 Core Design Concept

0
VII. Extensibility and Customization Capabilities: GUI Extension Interfaces

7.1.2 Ready-made Drivers (Out Of The Box)

LVGL comes with built-in drivers adapted for mainstream file systems and platforms, eliminating the need to manually implement core callbacks, which can be directly reused:

7.1.3 Add Custom File System Driver

If the built-in driver cannot meet the requirements (e. g. the SPI Flash file system adapted to the MPY platform), you need to manually register a custom driver, and the core process is as follows:

7.1.3.1 Driver Structure Initialization

You need to first create a driver struct (which shall be allocated globally or statically to avoid invalidation caused by the destruction of local variables) and complete the basic initialization:

7.1.3.2 Bind Core Callback Function

The core capabilities of the driver are implemented by callback functions, which are divided into file operations and directory operations two categories, and can be bound as needed:

Callback typeCore callbacksFunction description
Basic ready checkready_cbTells LVGL whether the storage device for this driver is ready (e.g., whether an SD card is inserted)
Core file operationsopen_cbOpen file: takes the "path with the driver letter removed" + "open mode (read / write)" and returns a file object pointer (used by subsequent operations)
close_cbClose file: releases the resources acquired when the file was opened
read_cbRead file: reads a specified number of bytes from an opened file
write_cbWrite file: writes a specified number of bytes to an opened file
seek_cbMove file pointer: adjusts the file read/write position
tell_cbGet file pointer position: returns the offset of the current read/write pointer in the file
Directory operationsdir_open_cbOpen directory: prepares to iterate over directory contents
dir_read_cbRead directory: reads file / subdirectory names in the directory in a loop (a "/" prefix is recommended to mark directories)
dir_close_cbClose directory: releases the resources used for directory iteration
7.1.3.3 Register the driver

After completing the structure configuration and callback binding, register the driver with the LVGL kernel, after which you can access this file system via the drive letter.

7.1.4 Core Logic of Callback Function

All callback designs are centered around the "file object", with the core rules as follows:

7.1.5 Core Usage Logic of the File System

7.1.5.1 File Operation Process (Read/Write)

Regardless of the underlying storage type, the upper-layer operation process remains unified:

7.1.5.2 Directory Operation Procedure

Process for traversing directory contents:

7.1.5.3 Core Modes / Result Codes

7.1.6 Key Requirements for Image Controls to Use the File System

To make the LVGL image widget load images from files (instead of variables compiled into the program), the following 4 callbacks must be implemented, and none of them can be missing:

7.2 Custom Extensions

Version Record

Version Number

Modifier

Time

Content

v1.0

Li Zisheng

2026/03/18

Initialize the document.