1# File system
2
3LVGL has a 'File system' abstraction module that enables you to attach any type of file system.
4A file system is identified by an assigned drive letter.
5For example, if an SD card is associated with the letter `'S'`, a file can be reached using `"S:path/to/file.txt"`.
6
7## Ready to use drivers
8The [lv_fs_if](https://github.com/lvgl/lv_fs_if) repository contains prepared drivers using POSIX, standard C and the [FATFS](http://elm-chan.org/fsw/ff/00index_e.html) API.
9See its [README](https://github.com/lvgl/lv_fs_if#readme) for the details.
10
11## Adding a driver
12
13### Registering a driver
14To add a driver, a `lv_fs_drv_t` needs to be initialized like below. The `lv_fs_drv_t` needs to be static, global or dynamically allocated and not a local variable.
15```c
16static lv_fs_drv_t drv;                   /*Needs to be static or global*/
17lv_fs_drv_init(&drv);                     /*Basic initialization*/
18
19drv.letter = 'S';                         /*An uppercase letter to identify the drive */
20drv.cache_size = my_cache_size;           /*Cache size for reading in bytes. 0 to not cache.*/
21
22drv.ready_cb = my_ready_cb;               /*Callback to tell if the drive is ready to use */
23drv.open_cb = my_open_cb;                 /*Callback to open a file */
24drv.close_cb = my_close_cb;               /*Callback to close a file */
25drv.read_cb = my_read_cb;                 /*Callback to read a file */
26drv.write_cb = my_write_cb;               /*Callback to write a file */
27drv.seek_cb = my_seek_cb;                 /*Callback to seek in a file (Move cursor) */
28drv.tell_cb = my_tell_cb;                 /*Callback to tell the cursor position  */
29
30drv.dir_open_cb = my_dir_open_cb;         /*Callback to open directory to read its content */
31drv.dir_read_cb = my_dir_read_cb;         /*Callback to read a directory's content */
32drv.dir_close_cb = my_dir_close_cb;       /*Callback to close a directory */
33
34drv.user_data = my_user_data;             /*Any custom data if required*/
35
36lv_fs_drv_register(&drv);                 /*Finally register the drive*/
37
38```
39
40Any of the callbacks can be `NULL` to indicate that operation is not supported.
41
42
43### Implementing the callbacks
44
45#### Open callback
46The prototype of `open_cb` looks like this:
47```c
48void * (*open_cb)(lv_fs_drv_t * drv, const char * path, lv_fs_mode_t mode);
49```
50
51`path` is the path after the drive letter (e.g. "S:path/to/file.txt" -> "path/to/file.txt"). `mode` can be `LV_FS_MODE_WR` or `LV_FS_MODE_RD` to open for writes or reads.
52
53The return value is a pointer to a *file object* that describes the opened file or `NULL` if there were any issues (e.g. the file wasn't found).
54The returned file object will be passed to other file system related callbacks. (see below)
55
56### Other callbacks
57The other callbacks are quite similar. For example `write_cb` looks like this:
58```c
59lv_fs_res_t (*write_cb)(lv_fs_drv_t * drv, void * file_p, const void * buf, uint32_t btw, uint32_t * bw);
60```
61
62For `file_p`, LVGL passes the return value of `open_cb`, `buf` is the data to write, `btw` is the Bytes To Write, `bw` is the actually written bytes.
63
64For a template of these callbacks see [lv_fs_template.c](https://github.com/lvgl/lvgl/blob/master/examples/porting/lv_port_fs_template.c).
65
66
67## Usage example
68
69The example below shows how to read from a file:
70```c
71lv_fs_file_t f;
72lv_fs_res_t res;
73res = lv_fs_open(&f, "S:folder/file.txt", LV_FS_MODE_RD);
74if(res != LV_FS_RES_OK) my_error_handling();
75
76uint32_t read_num;
77uint8_t buf[8];
78res = lv_fs_read(&f, buf, 8, &read_num);
79if(res != LV_FS_RES_OK || read_num != 8) my_error_handling();
80
81lv_fs_close(&f);
82```
83*The mode in `lv_fs_open` can be `LV_FS_MODE_WR` to open for writes only or `LV_FS_MODE_RD | LV_FS_MODE_WR` for both*
84
85This example shows how to read a directory's content. It's up to the driver how to mark directories in the result but it can be a good practice to insert a `'/'` in front of each directory name.
86```c
87lv_fs_dir_t dir;
88lv_fs_res_t res;
89res = lv_fs_dir_open(&dir, "S:/folder");
90if(res != LV_FS_RES_OK) my_error_handling();
91
92char fn[256];
93while(1) {
94    res = lv_fs_dir_read(&dir, fn);
95    if(res != LV_FS_RES_OK) {
96        my_error_handling();
97        break;
98    }
99
100    /*fn is empty, if not more files to read*/
101    if(strlen(fn) == 0) {
102        break;
103    }
104
105    printf("%s\n", fn);
106}
107
108lv_fs_dir_close(&dir);
109```
110
111## Use drives for images
112
113[Image](/widgets/core/img) objects can be opened from files too (besides variables stored in the compiled program).
114
115To use files in image widgets the following callbacks are required:
116- open
117- close
118- read
119- seek
120- tell
121
122
123
124## API
125
126```eval_rst
127
128.. doxygenfile:: lv_fs.h
129  :project: lvgl
130
131```
132