1.. _libs_filesystem:
2
3======================
4File System Interfaces
5======================
6
7LVGL has a :ref:`overview_file_system` module
8to provide an abstraction layer for various file system drivers.
9
10LVG has built in support for:
11
12- `FATFS <http://elm-chan.org/fsw/ff/00index_e.html>`__
13- STDIO (Linux and Windows using C standard function .e.g ``fopen``, ``fread``)
14- POSIX (Linux and Windows using POSIX function .e.g ``open``, ``read``)
15- WIN32 (Windows using Win32 API function .e.g ``CreateFileA``, ``ReadFile``)
16- MEMFS (read a file from a memory buffer)
17- LITTLEFS (a little fail-safe filesystem designed for microcontrollers)
18- Arduino ESP LITTLEFS (a little fail-safe filesystem designed for Arduino ESP)
19- Arduino SD (allows for reading from and writing to SD cards)
20
21You still need to provide the drivers and libraries, this extension
22provides only the bridge between FATFS, STDIO, POSIX, WIN32 and LVGL.
23
24.. _libs_filesystem_usage:
25
26Usage
27*****
28
29In ``lv_conf.h`` enable ``LV_USE_FS_...`` and assign an upper cased
30letter to ``LV_FS_..._LETTER`` (e.g. ``'S'``). After that you can access
31files using that driver letter. E.g. ``"S:path/to/file.txt"``.
32
33Working with common prefixes
34""""""""""""""""""""""""""""
35
36A **default driver letter** can be set by ``LV_FS_DEFAULT_DRIVER_LETTER``,
37which allows skipping the drive prefix in file paths.
38
39For example if ``LV_FS_DEFAULT_DRIVER_LETTER`` is set the ``'S'`` *"path/to/file.txt"* will mean *"S:path/to/file.txt"*.
40
41This feature is useful if you have only a single driver and don't want to bother with LVGL's driver layer in the file paths.
42It also helps to use a unified path with LVGL's file system and normal file systems.
43The original mechanism is not affected, so a path starting with drive letter will still work.
44
45The **working directory** can be set with ``LV_FS_..._PATH``. E.g.
46``"/home/joe/projects/"`` The actual file/directory paths will be
47appended to it, allowing to skip the common part.
48
49Caching
50"""""""
51
52:ref:`Cached reading <overview_file_system_cache>` is also supported if ``LV_FS_..._CACHE_SIZE`` is set to
53not ``0`` value. :cpp:func:`lv_fs_read` caches this size of data to lower the
54number of actual reads from the storage.
55
56To use the memory-mapped file emulation an ``lv_fs_path_ex_t`` object must be
57created and initialized. This object can be passed to :cpp:func:`lv_fs_open` as
58the file name:
59
60.. code-block:: c
61
62  lv_fs_path_ex_t mempath;
63  lv_fs_file_t file;
64  uint8_t *buffer;
65  uint32_t size;
66
67  /* Initialize buffer */
68  ...
69
70  lv_fs_make_path_from_buffer(&mempath, LV_FS_MEMFS_LETTER, (void*)buffer, size);
71  lv_fs_res_t res = lv_fs_open(&file, (const char *)&mempath, LV_FS_MODE_RD);
72
73.. _libs_filesystem_api:
74
75API
76***
77
78