FAT Filesystem Support¶
ESP-IDF uses FatFs library to work with FAT filesystems. FatFs library resides in fatfs
component. Although it can be used directly, many of its features can be accessed via VFS using C standard library and POSIX APIs.
Additionally, FatFs has been modified to support run-time pluggable disk IO layer. This allows mapping of FatFs drives to physical disks at run-time.
Using FatFs with VFS¶
esp_vfs_fat.h
header file defines functions to connect FatFs with VFS. esp_vfs_fat_register
function allocates a FATFS
structure, and registers a given path prefix in VFS. Subsequent operations on files starting with this prefix are forwarded to FatFs APIs. esp_vfs_fat_unregister
function deletes the registration with VFS, and frees the FATFS
structure.
Most applications will use the following flow when working with esp_vfs_fat_
functions:
- Call
esp_vfs_fat_register
, specifying path prefix where the filesystem has to be mounted (e.g."/sdcard"
), FatFs drive number, and a variable which will receive a pointer toFATFS
structure. - Call
ff_diskio_register
function to register disk IO driver for the drive number used in step 1. - Call
f_mount
function (and optionallyf_fdisk
,f_mkfs
) to mount the filesystem using the same drive number which was passed toesp_vfs_fat_register
. See FatFs documentation for more details. - Call POSIX and C standard library functions to open, read, write, erase, copy files, etc. Use paths starting with the prefix passed to
esp_vfs_register
(such as"/sdcard/hello.txt"
). - Optionally, call FatFs library functions directly. Use paths without a VFS prefix in this case (
"/hello.txt"
). - Close all open files.
- Call
f_mount
function for the same drive number, with NULLFATFS*
argument, to unmount the filesystem. - Call
ff_diskio_register
with NULLff_diskio_impl_t*
argument and the same drive number. - Call
esp_vfs_fat_unregister
to remove FatFs from VFS, and free theFATFS
structure allocated on step 1.
Convenience functions, esp_vfs_fat_sdmmc_mount
and esp_vfs_fat_sdmmc_unmount
, which wrap these steps and also handle SD card initialization, are described in the next section.
Warning
doxygenfunction: Cannot find function “esp_vfs_fat_register” in doxygen xml output for project “esp32-idf” from directory: xml/
Warning
doxygenfunction: Cannot find function “esp_vfs_fat_unregister” in doxygen xml output for project “esp32-idf” from directory: xml/
Using FatFs with VFS and SD cards¶
esp_vfs_fat.h
header file also provides a convenience function to perform steps 1–3 and 7–9, and also handle SD card initialization: esp_vfs_fat_sdmmc_mount
. This function does only limited error handling. Developers are encouraged to look at its source code and incorporate more advanced versions into production applications. esp_vfs_fat_sdmmc_unmount
function unmounts the filesystem and releases resources acquired by esp_vfs_fat_sdmmc_mount
.
Warning
doxygenfunction: Cannot find function “esp_vfs_fat_sdmmc_mount” in doxygen xml output for project “esp32-idf” from directory: xml/
Warning
doxygenstruct: Cannot find class “esp_vfs_fat_sdmmc_mount_config_t” in doxygen xml output for project “esp32-idf” from directory: xml/
Warning
doxygenfunction: Cannot find function “esp_vfs_fat_sdmmc_unmount” in doxygen xml output for project “esp32-idf” from directory: xml/
FatFS disk IO layer¶
FatFs has been extended with an API to register disk IO driver at runtime.
Implementation of disk IO functions for SD/MMC cards is provided. It can be registered for the given FatFs drive number using ff_diskio_register_sdmmc
function.
Warning
doxygenfunction: Cannot find function “ff_diskio_register” in doxygen xml output for project “esp32-idf” from directory: xml/
Warning
doxygenstruct: Cannot find class “ff_diskio_impl_t” in doxygen xml output for project “esp32-idf” from directory: xml/
Warning
doxygenfunction: Cannot find function “ff_diskio_register_sdmmc” in doxygen xml output for project “esp32-idf” from directory: xml/