Library Code
The FAT Filesystem (FatFs) Arduino Wrapper Library is adapted from ELM ChaN's code.
Download: FatFs.zip
Unzip it into Arduino/libraries/FatFs. It creates 2 examples under FatFs->Examples
Documentation
Please start by reading the FatFs overview page, and checking out detail pages for several of the API functions. The ones you'll want to understand first are f_open, f_close, f_read and f_write. These operate on file system objects described in Section A below. So say you have instantiated the FILINFO object file_info. To find the name of the current file, you would just check file_info.fname.
A. File System Object Structures
The file, directory and (file or directory) metadata objects are typed DIR, FIL and FILINFO (respectively) in the headers shown in Section B below. The other unfamiliar object types are simple typedefs: XCHAR is a char, UINT is an unsigned integer, and DWORD is an unsigned long.
-
DIR: Directory Object Structure
fs - FATFS* - Pointer to the owner file system object
id - WORD - Owner file system mount ID
index - WORD - Current read/write index number
sclust - DWORD - Table start cluster (0:Static table)
clust - DWORD - Current cluster
sect - DWORD - Current sector
dir - BYTE* - Pointer to the current SFN entry in the win[]
fn - BYTE* - Pointer to the SFN (in/out) {file[8],ext[3],status[1]}
-
FIL: File object structure
fs - FATFS* - Pointer to the owner file system object
id - WORD - Owner file system mount ID
flag - BYTE - File status flags
csect - BYTE - Sector address in the cluster
fptr - DWORD - File R/W pointer
fsize - DWORD - File size
org_clust - DWORD - File start cluster
curr_clust - DWORD - Current cluster
dsect - DWORD - Current data sector
dir_sect - DWORD - Sector containing the directory entry
dir_pt - BYTE* - Ponter to the directory entry in the window
buf[_MAX_SS] - BYTE - File R/W buffer
-
FILINFO: File status structure
fsize - DWORD - File size
fdate - WORD - Last modified date
ftime - WORD - Last modified time
fattrib - BYTE - Attribute
fname[13] - char - Short file name (8.3 format)
B. File System Operation Functions
Following are the functions available in the FatFs library. Note that we do not carry forward the 'f_' prefix found in function names of the original file system module.
General Public Functions
Several function names are overloaded. The versions with fewer parameters modify the "working copies" of the filesystem, file and directory objects. These working copies are instantiated and stored within the library, and you can remain pretty unaware of them for typical purposes such as listing, reading or writing files.
Alternatively, you can instantiate and modify your own copies of these objects that you manage manually from within your Arduino sketch.
- mount (unsigned char, FATFS*) - Mount/Unmount a logical drive
- open (FIL*, const XCHAR*, unsigned char) - Open or create a file
open (const XCHAR*, unsigned char)
- read (FIL*, void*, UINT, UINT*) - Read data from a file
read (void*, UINT, UINT*)
- write (FIL*, const void*, UINT, UINT*) - Write data to a file
write (const void*, UINT, UINT*)
- lseek (FIL*, DWORD) - Move file pointer of a file object
lseek (DWORD)
- close (FIL*) - Close an open file object
close (void)
- opendir (DIR*, const XCHAR*) - Open an existing directory
opendir (const XCHAR*)
opendir (void)
- readdir (DIR*, FILINFO*) - Read a directory item
readdir (FILINFO*)
readdir (void)
- stat (const XCHAR*, FILINFO*) - Get file status
- getfree (const XCHAR*, DWORD*, FATFS**) - Get number of free clusters on the drive
- truncate (FIL*) - Truncate file
truncate (void)
- sync (FIL*) - Flush cached data of a writing file
sync (void)
- unlink (const XCHAR*) - Delete an existing file or directory
- mkdir (const XCHAR*) - Create a new directory
- chmod (const XCHAR*, unsigned char, unsigned char) - Change attriburte of the file/dir
- utime (const XCHAR*, const FILINFO*) - Change timestamp of the file/dir
- rename (const XCHAR*, const XCHAR*) - Rename/Move a file or directory
- forward (FIL*, UINT(*)(const unsigned char*,UINT), UINT, UINT*) - Forward data to the stream
- mkfs (unsigned char, unsigned char, WORD) - Create a file system on the drive
- chdir (const XCHAR*)- Change current directory
- chdrive (unsigned char) - Change current drive
Sting Functions
You can enable the use of string functions familiar in c by changing a setting bit in the library's ffconf.h file. The following functions are added when you do.
- fputc (int, FIL*) - Put a character to the file
fputc (int)
- puts (const char*, FIL*) - Put a string to the file
puts (const char*)
- printf (FIL*, const char*, ...) - Put a formatted string to the file
printf (const char*, ...)
- gets (char*, int, FIL*) - Get a string from the file
gets (char*, int)
C. File Access and Status Codes
FA_READ |
Specifies read access to the object. Data can be read from the file. Combine with FA_WRITE for read-write access. |
FA_WRITE |
Specifies write access to the object. Data can be written to the file. Combine with FA_READ for read-write access. |
FA_OPEN_EXISTING |
Opens the file. The function fails if the file is not existing. (Default) |
FA_OPEN_ALWAYS |
Opens the file, if it is existing. If not, a new file is created. |
FA_CREATE_NEW |
Creates a new file. The function fails if the file is already existing. |
FA_CREATE_ALWAYS |
Creates a new file. If the file is existing, it is truncated and overwritten. |
Comments (0)
You don't have permission to comment on this page.