• If you are citizen of an European Union member nation, you may not use this service unless you are at least 16 years old.

  • Dokkio Sidebar (from the makers of PBworks) is a Chrome extension that eliminates the need for endless browser tabs. You can search all your online stuff without any extra effort. And Sidebar was #1 on Product Hunt! Check out what people are saying by clicking here.



Page history last edited by David S 12 years, 5 months ago

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



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_openf_closef_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.