「App:Library:LVGL:docs:Overview:File system」の版間の差分
提供: robot-jp wiki
ナビゲーションに移動検索に移動| 1行目: | 1行目: | ||
| − | https://docs.lvgl.io/8.2/overview/ | + | https://docs.lvgl.io/8.2/overview/file-system.html |
__NOTOC__ | __NOTOC__ | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
= File system = | = File system = | ||
LVGL has a 'File system' abstraction module that enables you to attach any type of file system. A file system is identified by an assigned drive letter. For example, if an SD card is associated with the letter <code>'S'</code>, a file can be reached using <code>"S:path/to/file.txt"</code>. | LVGL has a 'File system' abstraction module that enables you to attach any type of file system. A file system is identified by an assigned drive letter. For example, if an SD card is associated with the letter <code>'S'</code>, a file can be reached using <code>"S:path/to/file.txt"</code>. | ||
2022年7月1日 (金) 11:34時点における版
https://docs.lvgl.io/8.2/overview/file-system.html
File system
LVGL has a 'File system' abstraction module that enables you to attach any type of file system. A file system is identified by an assigned drive letter. For example, if an SD card is associated with the letter 'S', a file can be reached using "S:path/to/file.txt".
Ready to use drivers
The lv_fs_if repository contains prepared drivers using POSIX, standard C and the FATFS API. See its README for the details.
Adding a driver
Registering a driver
To 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.
static lv_fs_drv_t drv; /*Needs to be static or global*/ lv_fs_drv_init(&drv); /*Basic initialization*/ drv.letter = 'S'; /*An uppercase letter to identify the drive */ drv.cache_size = my_cahce_size; /*Cache size for reading in bytes. 0 to not cache.*/ 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.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.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.
Implementing the callbacks
Open callback
The prototype of open_cb looks like this:
void * (*open_cb)(lv_fs_drv_t * drv, const char * path, lv_fs_mode_t mode);
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.
The 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). The returned file object will be passed to other file system related callbacks. (see below)
Other callbacks
The other callbacks are quite similar. For example write_cb looks like this:
lv_fs_res_t (*write_cb)(lv_fs_drv_t * drv, void * file_p, const void * buf, uint32_t btw, uint32_t * bw);
For 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.
For a template of these callbacks see lv_fs_template.c.
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 writes only 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 directories in the result but it can be a good practice to insert a '/' in front of each 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 drives for images
Image objects can be opened from files too (besides variables stored in the compiled program).
To use files in image widgets the following callbacks are required:
- open
- close
- read
- seek
- tell
API
Typedefs
- typedef uint8_t lv_fs_res_t[1]
Enums
- enum [anonymous][6]
- [7]Errors in th[8]e file system module. Values:
- enumerator LV_FS_RES_OK[9]
- enumerator LV[10]_FS_RES_HW_ERR[11]
- enumerator LV_FS_[12]RES_FS_ERR[13]
- enumerator LV_FS_[14]RES_NOT_EX[15]
- enumerator LV_FS_[16]RES_FULL[17]
- enumerator LV_F[18]S_RES_LOCKED[19]
- enumerator LV_FS_[20]RES_DENIED[21]
- enumerator LV_FS_[22]RES_BUSY[23]
- enumerator LV_F[24]S_RES_TOUT[25]
- enumerator LV_F[26]S_RES_NOT_IMP[27]
- enumerator LV_FS_R[28]ES_OUT_OF_MEM[29]
- enumerator LV_FS_RES_[30]INV_PARAM[31]
- enumerator LV_FS_RES[32]_UNKNOWN[33]
Functions
- void lv_fs_drv_init(lv_fs_drv_t *drv)[51]
- Initialize a file system driver w[52]ith 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)[53]
- Add a new drive
- Parameters
- drv [54]-- pointer to an lv_fs_drv_t structure which is inited with the corresponding function pointers. Only pointer is saved, so the driver should be static or dynamically allocated.
- lv_fs_drv_t *lv_fs_get_drv(char letter)[55]
- Give a pointer to a driver from its[56] letter
- Parameters
- letter -- the driver letter
- Returns
- pointer to a driver or NULL if not found
- bool lv_fs_is_ready(char letter)[57]
- Test if a drive is ready or [58]not. If the
readyfunction was not initializedtruewill 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)[59]
- 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)[61]
- Close an already opened file
- Parameter[62]s
- 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_read(lv_fs_file_t *file_p, void *buf, uint32_t btr, uint32_t *br)[63]
- Read from a file
- Parameters
-
- file_p -- pointer to a lv_fs_file_t variabl[64]e
- 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)[65]
- Write into a file
- Parameters
-
- file_p -- pointer to a lv_fs_file_t variable
- b[66]uf -- 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, lv_fs_whence_t whence)[67]
- Set the position of the 'cursor' (read write pointer) in a file
- Parameters[68]
-
- file_p -- pointer to a lv_fs_file_t variable
- pos -- the new position expressed in bytes index (0: start of file)
- whence -- tells from where set the position. See @lv_fs_whence_t
- 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)[69]
- Give the position of the read write pointer
- Paramete[70]rs
-
- 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_dir_open(lv_fs_dir_t *rddir_p, const char *path)[71]
- Initialize a 'fs_dir_t' variable for directory reading
- Para[72]meters
-
- 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)[73]
- Read the next filename form a directory. The name of t[74]he 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)[75]
- Close the directory reading
- Parameters
- [76]rddir_p -- pointer to an initialized 'fs_dir_t' variable
- Returns
- LV_FS_RES_OK or any error from lv_fs_res_t enum
- char *lv_fs_get_letters(char *buf)[77]
- Fill a buffer with the letters[78] 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)[79]
- Return with the extension of the file[80]name
- Parameters
- fn -- string with a filename
- Returns
- pointer to the beginning extension or empty string if no extension
- char *lv_fs_up(char *path)[81]
- Step up one level
- P[82]arameters
- path -- pointer to a file name
- Returns
- the truncated file name
- const char *lv_fs_get_last(const char *path)[83]
- Get the last element of a path (e.g. U:/[84]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[85]
- Public Members [86]
- char letter[87]
- u[88]int16_t cache_size[89]
- bool (*re[90]ady_cb)(struct _lv_fs_drv_t *drv)[91]
- void *(*open_cb)(struct _lv_fs_d[92]rv_t *drv, const char *path, lv_fs_mode_t mode)[93]
- lv_fs_res_t (*close_cb)(struct _lv_fs_drv_t *drv, void *file_p)[94]
- [95]
- lv_fs_res_t (*read_cb)(struct _lv_fs_drv_t *drv, void[96] *file_p, void *buf, uint32_t btr, uint32_t *br)[97]
- lv_fs_res_t (*write_cb)(struct _lv_fs_drv_t *drv, void *file_p, const void *buf, uint32_t b[98]tw, uint32_t *bw)[99]
- lv_fs_res_t (*seek_cb)(struct _lv_fs_drv_t *drv, void *file_p, uint32_t pos, lv_fs_whence_t whence[100])[101]
- lv_fs_res_t (*tell_cb)(struct _lv_fs_drv_t *drv, void *file_p, uint32_t *pos_p)[102]
- [103]
