WebbotLib AVR library
WebbotLib It just does it
  C++ documentation  C documentation

FileSystem/FAT.h

Overlays a FAT file system on top of an underlying storage element.
The underlying storage element must be capable of reading / writing 512 byte (sector) blocks.
Prior to use then the storage element must have been formatted.
For an SD card then this may have been done using something like the free download from http://www.sdcard.org/consumers/formatter/
The benefit of the FAT system is that the same media can be shared with Windows and other operating systems. So it produces a truly 'hot pluggable hard drive' for removable media. ie an SD card may be 'removable' but an 'EEPROM' chip may not. But why not use the same code for both - SD card for debugging and EEPROM for release - as an example. WebbotLib lets you do that without changes.
The FAT system is cool. But before it can be used then you must connect the underlying device to the FAT file system and this may look a bit complex.
The key is to use the 'diskInit' command and thats a bit fiddly too!
So here is an example for an SD card:-
// Choose which pins will simulate the SPI bus - in this case the hardware ones
#define MOSI B2
#define MISO B3
#define SCLK B1
#define CS F0
 
// Create the sd card
SD_CARD card = MAKE_SD_CARD(CS);
 
// Build a list of the devices that are on the same bus
SPI_DEVICE_LIST PROGMEM devices[] = { &card._device_ };
 
// Create the software bus
SPI_SW software_spi = MAKE_SW_SPI(devices, MOSI, MISO, SCLK);
 
// Create the disk file system
DISK disk;
Then in your appInitHardware:-
// Initialise the card
sdCardInit(&card);
 
// Try to make it into a hard drive
diskInit(&disk, 1, sdCardGetStorageClass(), &card);

 

Function

 


boolean diskInit(DISK *disk, uint8_t numBuffers, const STORAGE_CLASS* class, void* device)

Initialise a disk interface.
'numBuffers' is the number of 512 byte buffers to be used and must be at least 1. Larger numbers will make this module work faster.
Returns FALSE if failed, else TRUE

boolean diskFlush(const DISK *disk)

Flush all pending changes to the disk.

uint32_t  diskFreeSpace(const DISK* disk)

Return the number of available Kb on the disk.

int8_t diskMkdir(DISK* disk,const char* dirname)

Create a directory.
The returned value can be:
0 if the directory was successfully created
-1 if it already exists
-2 if the parent directory has run out of space
-3 if the disk is full

boolean fileFindFirst(const DISK* disk,FILE_ITERATOR *list,const char* dirname)

Find the first file entry in a directory.
Returns FALSE if the directory doesn't exist or contains no files. Otherwise it will return TRUE and the file information can be retrieved from the FILE_ITERATOR. The file iterator is then passed into the file_findNext call to retrieve the next file.
Example: to list the contents of the root folder
FILE_ITERATOR f;
boolean ok;
ok = fileFindFirst(&disk, &f, "/");
while(ok){
    rprintf("%s (%lu bytes)", f.filename, f.fileSize);
    if(f.attribute.flags.isDirectory){
        rprintf(" <dir>");
    }
    rprintf("\n");
    ok = fileFindNext(&f);
}

boolean fileFindNext(FILE_ITERATOR *list)

Return the next file in the directory.
Returns FALSE if there are no more files.

int8_t fileOpen(DISK* disk, FATFILE* file,const char* filename,char mode)

Open a file.
The mode parameter can either be:
'r' - To open an existing file for read access
'w' - To create a new file for read write access
'a' - To write to the end of an existing file (ie append), or create the file if it doesn't exist.
The function will return 0 if the file has been opened successfully in which case the FILE variable is initialised and can then be used in the remaining file operations.
A negative return value indicates an error as follows:-
-1 = The file doesn't exist when opening for read
-2 = The file already exists when opening for write
-3 = The directory doesn't exist
-4 = You are trying to write a read only file
-5 = The disk is full
-6 = The mode parameter is invalid

void fileClose(FATFILE* file)

Close a file.
This will flush any outstanding changes to the disk and then close the file.

void fileFlush(FATFILE* file)

Flush any file changes to the disk.
This the equivalent of closing the file and then re-opening it - but is much faster.
In order to reduce the amount of reading from, and writing to, the disk then some data is held in memory. This function will force any changes to the file to be flushed out to the disk.
If your application keeps a file open for writing for a period of time (such as a data logger) then it is wise to call this function every now and then. Otherwise, when you turn off the power then some data may be lost.

boolean fileSetPos(FATFILE *file,uint32_t pos)

Set the current position in the file for fileReadNext or fileWriteNext.
When a file is opened the current position is set to the start of the file unless you open in append mode in which case it will be set to the end of the file.
This function allows you to change the current position.
The function will return FALSE if you have specified a position beyond the end of the file - in which case the current position will remain unchanged.

uint32_t fileGetPos(const FATFILE* file)

Return the current position in the file.

uint32_t fileGetSize(const FATFILE* file)

Return the size of the file in bytes.

size_t fileReadNext(FATFILE *file,size_t size,void *buf)

Perform a sequential read from the current file position.
The returned value is the number of bytes actually read. This will normally be the same as the number of bytes requested unless you are trying to read beyond the end of the file.
Example: to open an existing file and dump its contents out using rprintf
FATFILE file;
char buffer[80];
if(fileOpen(&disk,&file,"/TEST.TXT",'r')==0){
    size_t bytes;
    while( bytes=fileReadNext(&file,sizeof(buffer),buffer)) > 0 ){
        rprintfStrLen(buffer,0,bytes);
    }
    fileClose(&file);
}

size_t fileWriteNext(FATFILE *file, size_t size,const void *buf)

Perform a sequential write to the file.
This will write to the current position and then update the current position ready for the next call.
The returned value is the number of bytes actually written which will be the same as the specified value unless the disk is full.

size_t fileRead(FATFILE *file,uint32_t offset, size_t size,void *buf)

Perform a random read from the file.
This function ignores the current file position and allows you read from any position within the file.
The returned value is the number of bytes actually read. This will always be the same as the number of bytes requested - unless you are trying to read beyond the end of the file.

size_t fileWrite(FATFILE* file,uint32_t offset,size_t size,const void* buf)

Perform a random write into a file.
This will ignore the current file position and allow you to write anywhere within the file. The returned value is the number of bytes actually written which will be the same as the specified value unless the disk is full.

boolean fileExists(DISK * disk,const char* filename)

Test if a file already exists.
Return TRUE if it does exist, or FALSE if it doesn't.

boolean fileDelete(DISK * disk,const char* filename)

Delete a file.
This will return FALSE if the file doesn't exist or is marked as read only.

Writer fileGetWriter(const FATFILE* file)

Return a Writer to allow rprintf output to be redirected to the file.
This is useful if you are creating a text file and writing out formatted text and numbers.
Example: Write out some data to a file.
// Assume on entry that rprintf is going to your PC
if(fileExists(&disk,"/TEST.TXT")){
    rprintf("Delete file first\n"); // => PC
    fileDelete(&disk,"/TEST.TXT");
}
 
FATFILE f; // Holds the reference to the open file
rprintf("Write to /TEST.TXT\n"); // => PC
if(fileOpen(&disk,&f,"/TEST.TXT",'w')==0){
    // Redirect output to the file
    Writer old = rprintfInit(fileGetWriter(&f));
    // Write out some stuff
    for(int line = 1; line < 100; line++){
        rprintf("Line %d: ABCDEFGHIJKLMNOPQRSTUVWXYZ\n",line); // => file
    }
    // Close the file
    fileClose(&f);
    // Restore rprintf to go to its original location
    rprintfInit(old);
    rprintf("Done\n"); // => PC
}else{
    rprintf("Couldn't create file\n"); // => PC
}

Valid XHTML 1.0 Transitional