File system¶

LVGL has a 'File system' abstraction module that enables you to attach any type of file systems. The file system is identified by a drive letter. For example, if the SD card is associated with the letter 'S', a file can be reached like "S:path/to/file.txt".

Add a driver¶

To add a driver, lv_fs_drv_t needs to be initialized like this:

lv_fs_drv_t drv;
lv_fs_drv_init(&drv);                     /*Basic initialization*/

drv.letter = 'S';                         /*An uppercase letter to identify the drive */
drv.file_size = sizeof(my_file_object);   /*Size required to store a file object*/
drv.rddir_size = sizeof(my_dir_object);   /*Size required to store a directory object (used by dir_open/close/read)*/
drv.ready_cb = my_ready_cb;               /*Callback to tell if the drive is ready to use */
drv.open_cb = my_open_cb;                 /*Callback to open a file */
drv.close_cb = my_close_cb;               /*Callback to close a file */
drv.read_cb = my_read_cb;                 /*Callback to read a file */
drv.write_cb = my_write_cb;               /*Callback to write a file */
drv.seek_cb = my_seek_cb;                 /*Callback to seek in a file (Move cursor) */
drv.tell_cb = my_tell_cb;                 /*Callback to tell the cursor position  */
drv.trunc_cb = my_trunc_cb;               /*Callback to delete a file */
drv.size_cb = my_size_cb;                 /*Callback to tell a file's size */
drv.rename_cb = my_rename_cb;             /*Callback to rename a file */


drv.dir_open_cb = my_dir_open_cb;         /*Callback to open directory to read its content */
drv.dir_read_cb = my_dir_read_cb;         /*Callback to read a directory's content */
drv.dir_close_cb = my_dir_close_cb;       /*Callback to close a directory */

drv.free_space_cb = my_free_space_cb;     /*Callback to tell free space on the drive */

drv.user_data = my_user_data;             /*Any custom data if required*/

lv_fs_drv_register(&drv);                 /*Finally register the drive*/

Any of the callbacks can be NULL to indicate that operation is not supported.

As an example of how the callbacks are used, if you use lv_fs_open(&file, "S:/folder/file.txt", LV_FS_MODE_WR), LVGL:

Verifies that a registered drive exists with the letter 'S'.
Checks if it's open_cb is implemented (not NULL).
Calls the set open_cb with "folder/file.txt" path.

Usage example¶

The example below shows how to read from a file:

lv_fs_file_t f;
lv_fs_res_t res;
res = lv_fs_open(&f, "S:folder/file.txt", LV_FS_MODE_RD);
if(res != LV_FS_RES_OK) my_error_handling();

uint32_t read_num;
uint8_t buf[8];
res = lv_fs_read(&f, buf, 8, &read_num);
if(res != LV_FS_RES_OK || read_num != 8) my_error_handling();

lv_fs_close(&f);

The mode in lv_fs_open can be LV_FS_MODE_WR to open for write or LV_FS_MODE_RD | LV_FS_MODE_WR for both

This example shows how to read a directory's content. It's up to the driver how to mark the directories, but it can be a good practice to insert a '/' in front of the directory name.

lv_fs_dir_t dir;
lv_fs_res_t res;
res = lv_fs_dir_open(&dir, "S:/folder");
if(res != LV_FS_RES_OK) my_error_handling();

char fn[256];
while(1) {
    res = lv_fs_dir_read(&dir, fn);
    if(res != LV_FS_RES_OK) {
        my_error_handling();
        break;
    }

    /*fn is empty, if not more files to read*/
    if(strlen(fn) == 0) {
        break;
    }

    printf("%s\n", fn);
}

lv_fs_dir_close(&dir);

Use drivers for images¶

Image objects can be opened from files too (besides variables stored in the flash).

To initialize the image, the following callbacks are required:

open
close
read
seek
tell

API¶

Typedefs

typedef uint8_t lv_fs_res_t¶

typedef uint8_t lv_fs_mode_t¶

typedef struct _lv_fs_drv_t lv_fs_drv_t¶

Enums

enum [anonymous]¶

Errors in the file system module.

Values:

enumerator LV_FS_RES_OK¶

enumerator LV_FS_RES_HW_ERR¶

enumerator LV_FS_RES_FS_ERR¶

enumerator LV_FS_RES_NOT_EX¶

enumerator LV_FS_RES_FULL¶

enumerator LV_FS_RES_LOCKED¶

enumerator LV_FS_RES_DENIED¶

enumerator LV_FS_RES_BUSY¶

enumerator LV_FS_RES_TOUT¶

enumerator LV_FS_RES_NOT_IMP¶

enumerator LV_FS_RES_OUT_OF_MEM¶

enumerator LV_FS_RES_INV_PARAM¶

enumerator LV_FS_RES_UNKNOWN¶

enum [anonymous]¶

Filesystem mode.

Values:

enumerator LV_FS_MODE_WR¶

enumerator LV_FS_MODE_RD¶

Functions

void _lv_fs_init(void)¶: Initialize the File system interface

void lv_fs_drv_init(lv_fs_drv_t *drv)¶

Initialize a file system driver with default values. It is used to surly have known values in the fields ant not memory junk. After it you can set the fields.

Parameters: drv -- pointer to driver variable to initialize

void lv_fs_drv_register(lv_fs_drv_t *drv_p)¶

Add a new drive

Parameters: drv_p -- pointer to an lv_fs_drv_t structure which is inited with the corresponding function pointers. The data will be copied so the variable can be local.

lv_fs_drv_t *lv_fs_get_drv(char letter)¶

Give a pointer to a driver from its letter

Parameters: letter -- the driver letter
Returns: pointer to a driver or NULL if not found

bool lv_fs_is_ready(char letter)¶

Test if a drive is ready or not. If the ready function was not initialized true will be returned.

Parameters: letter -- letter of the drive
Returns: true: drive is ready; false: drive is not ready

lv_fs_res_t lv_fs_open(lv_fs_file_t *file_p, const char *path, lv_fs_mode_t mode)¶

Open a file

Parameters

file_p -- pointer to a lv_fs_file_t variable
path -- path to the file beginning with the driver letter (e.g. S:/folder/file.txt)
mode -- read: FS_MODE_RD, write: FS_MODE_WR, both: FS_MODE_RD | FS_MODE_WR

Returns

LV_FS_RES_OK or any error from lv_fs_res_t enum

lv_fs_res_t lv_fs_close(lv_fs_file_t *file_p)¶

Close an already opened file

Parameters: file_p -- pointer to a lv_fs_file_t variable
Returns: LV_FS_RES_OK or any error from lv_fs_res_t enum

lv_fs_res_t lv_fs_remove(const char *path)¶

Delete a file

Parameters: path -- path of the file to delete
Returns: LV_FS_RES_OK or any error from lv_fs_res_t enum

lv_fs_res_t lv_fs_read(lv_fs_file_t *file_p, void *buf, uint32_t btr, uint32_t *br)¶

Read from a file

Parameters

file_p -- pointer to a lv_fs_file_t variable
buf -- pointer to a buffer where the read bytes are stored
btr -- Bytes To Read
br -- the number of real read bytes (Bytes Read). NULL if unused.

Returns

LV_FS_RES_OK or any error from lv_fs_res_t enum

lv_fs_res_t lv_fs_write(lv_fs_file_t *file_p, const void *buf, uint32_t btw, uint32_t *bw)¶

Write into a file

Parameters

file_p -- pointer to a lv_fs_file_t variable
buf -- pointer to a buffer with the bytes to write
btr -- Bytes To Write
br -- the number of real written bytes (Bytes Written). NULL if unused.

Returns

LV_FS_RES_OK or any error from lv_fs_res_t enum

lv_fs_res_t lv_fs_seek(lv_fs_file_t *file_p, uint32_t pos)¶

Set the position of the 'cursor' (read write pointer) in a file

Parameters

file_p -- pointer to a lv_fs_file_t variable
pos -- the new position expressed in bytes index (0: start of file)

Returns

LV_FS_RES_OK or any error from lv_fs_res_t enum

lv_fs_res_t lv_fs_tell(lv_fs_file_t *file_p, uint32_t *pos)¶

Give the position of the read write pointer

Parameters

file_p -- pointer to a lv_fs_file_t variable
pos_p -- pointer to store the position of the read write pointer

Returns

LV_FS_RES_OK or any error from 'fs_res_t'

lv_fs_res_t lv_fs_trunc(lv_fs_file_t *file_p)¶

Truncate the file size to the current position of the read write pointer

Parameters: file_p -- pointer to an 'ufs_file_t' variable. (opened with lv_fs_open )
Returns: LV_FS_RES_OK: no error, the file is read any error from lv_fs_res_t enum

lv_fs_res_t lv_fs_size(lv_fs_file_t *file_p, uint32_t *size)¶

Give the size of a file bytes

Parameters

file_p -- pointer to a lv_fs_file_t variable
size -- pointer to a variable to store the size

Returns

LV_FS_RES_OK or any error from lv_fs_res_t enum

lv_fs_res_t lv_fs_rename(const char *oldname, const char *newname)¶

Rename a file

Parameters

oldname -- path to the file
newname -- path with the new name

Returns

LV_FS_RES_OK or any error from 'fs_res_t'

lv_fs_res_t lv_fs_dir_open(lv_fs_dir_t *rddir_p, const char *path)¶

Initialize a 'fs_dir_t' variable for directory reading

Parameters

rddir_p -- pointer to a 'lv_fs_dir_t' variable
path -- path to a directory

Returns

LV_FS_RES_OK or any error from lv_fs_res_t enum

lv_fs_res_t lv_fs_dir_read(lv_fs_dir_t *rddir_p, char *fn)¶

Read the next filename form a directory. The name of the directories will begin with '/'

Parameters

rddir_p -- pointer to an initialized 'fs_dir_t' variable
fn -- pointer to a buffer to store the filename

Returns

LV_FS_RES_OK or any error from lv_fs_res_t enum

lv_fs_res_t lv_fs_dir_close(lv_fs_dir_t *rddir_p)¶

Close the directory reading

Parameters: rddir_p -- pointer to an initialized 'fs_dir_t' variable
Returns: LV_FS_RES_OK or any error from lv_fs_res_t enum

lv_fs_res_t lv_fs_free_space(char letter, uint32_t *total_p, uint32_t *free_p)¶

Get the free and total size of a driver in kB

Parameters

letter -- the driver letter
total_p -- pointer to store the total size [kB]
free_p -- pointer to store the free size [kB]

Returns

LV_FS_RES_OK or any error from lv_fs_res_t enum

char *lv_fs_get_letters(char *buf)¶

Fill a buffer with the letters of existing drivers

Parameters: buf -- buffer to store the letters ('\0' added after the last letter)
Returns: the buffer

const char *lv_fs_get_ext(const char *fn)¶

Return with the extension of the filename

Parameters: fn -- string with a filename
Returns: pointer to the beginning extension or empty string if no extension

char *lv_fs_up(char *path)¶

Step up one level

Parameters: path -- pointer to a file name
Returns: the truncated file name

const char *lv_fs_get_last(const char *path)¶

Get the last element of a path (e.g. U:/folder/file -> file)

Parameters: path -- pointer to a file name
Returns: pointer to the beginning of the last element in the path

struct _lv_fs_drv_t¶

Public Members

char letter¶

uint16_t file_size¶

uint16_t rddir_size¶

bool (*ready_cb)(struct _lv_fs_drv_t *drv)¶

lv_fs_res_t (*open_cb)(struct _lv_fs_drv_t *drv, void *file_p, const char *path, lv_fs_mode_t mode)¶

lv_fs_res_t (*close_cb)(struct _lv_fs_drv_t *drv, void *file_p)¶

lv_fs_res_t (*remove_cb)(struct _lv_fs_drv_t *drv, const char *fn)¶

lv_fs_res_t (*read_cb)(struct _lv_fs_drv_t *drv, void *file_p, void *buf, uint32_t btr, uint32_t *br)¶

lv_fs_res_t (*write_cb)(struct _lv_fs_drv_t *drv, void *file_p, const void *buf, uint32_t btw, uint32_t *bw)¶

lv_fs_res_t (*seek_cb)(struct _lv_fs_drv_t *drv, void *file_p, uint32_t pos)¶

lv_fs_res_t (*tell_cb)(struct _lv_fs_drv_t *drv, void *file_p, uint32_t *pos_p)¶

lv_fs_res_t (*trunc_cb)(struct _lv_fs_drv_t *drv, void *file_p)¶

lv_fs_res_t (*size_cb)(struct _lv_fs_drv_t *drv, void *file_p, uint32_t *size_p)¶

lv_fs_res_t (*rename_cb)(struct _lv_fs_drv_t *drv, const char *oldname, const char *newname)¶

lv_fs_res_t (*free_space_cb)(struct _lv_fs_drv_t *drv, uint32_t *total_p, uint32_t *free_p)¶

lv_fs_res_t (*dir_open_cb)(struct _lv_fs_drv_t *drv, void *rddir_p, const char *path)¶

lv_fs_res_t (*dir_read_cb)(struct _lv_fs_drv_t *drv, void *rddir_p, char *fn)¶

lv_fs_res_t (*dir_close_cb)(struct _lv_fs_drv_t *drv, void *rddir_p)¶

lv_fs_drv_user_data_t user_data¶: Custom file user data

struct lv_fs_file_t¶

Public Members

void *file_d¶

lv_fs_drv_t *drv¶

struct lv_fs_dir_t¶

Public Members

void *dir_d¶

lv_fs_drv_t *drv¶