Lib sd card fat file system

From openPicus Wiki
Jump to: navigation, search

Contents

Introduction

The FAT (File Allocation Table) is a industry standard file systems. It is used in lots of systems, like PCs, tablets, smartphones, cameras, etc... It was used from floppy disks, and is used nowadays in solid state memory cards.
In conjunction with a SD or a microSD card, Flyport can use FAT file system features. A large amount of storage space can be used on a very small space: some GBytes in about 15.0×11.0×1.0 mm (0.59×0.43×0.039 in)... not bad for an embedded device!

FAT Library

SD memory card uses SPI bus. Using the provided library, all the SPI parameters are automatically set. User should only write in firmware what Flyport pins are connected to SD card connector, using the function SDInit.
If it is used a Nest carrier board (Grove Nest or Music Nest), the pinout is just provided in firmware API SDOnNest.
Following is a list of available APIs

DOWNLOAD

Lastest library revision can be downloaded here


API List

Init & Utils

Name Parameters Return Description
SDInit int pin_sck - pin used as SPI SCLK signal

int pin_si - pin used as SPI MISO signal
int pin_so - pin used as SPI MOSI signal
int pin_cs - pin used as SD Chip Select signal
int pin_cd - pin used as SD Card Detect signal
BYTE _nTimeout - timeout of operation (expressed in about 0.1 sec scale, 255 to wait forever)

BOOL result of operation Initializes the hardware/software SD card module. If the SD card is not inserted, loops waiting to mount it until the SD ready is ready.
SDOnNest int _nest - Nest carrier board definition to use. Can be SD_GROVE, SD_MUSIC and SD_IOT_BOARD

BYTE _nTimeout - timeout of operation (expressed in about 0.1 sec scale, 255 to wait forever)

BOOL result of operation Initializes the hardware/software SD card module using a Nest carrier board
SDUnMount None BOOL result of operation Unmounts SD Card disk in software libraries. Useful to provide removable disk drives application.
SDFreeSpace None DWORD >0: amount of KB available

DWORD 0: operation failed (for example read only configuration set) or no available space left

Retrieve available free space on disk (in KB)
SDGetErr None Error number from above list Retrieve error number of last operation failed

Files Management

Name Parameters Return Description
SDFileCheck char* nfile_check - char[] with filename to check TRUE - operation success

FALSE - operation failed

Checks for a file existence
SDFileSize char* nfile_size - char[] with filename to check DWORD >=0 - file size

-1 - Operation failed

Provides file size (in bytes)
SDFileDateTime char* nfile_tm - char[] with filename to check

struct tm* SDtime - struct tm to fill with date and time of file timestamp

TRUE - operation success

FALSE - operation failed

Provides file date/time timestamp
SDFileCreate char* nfile_create - char[] with filename to create TRUE - operation success

FALSE - operation failed

Creates/overwrites a file on current directory
SDFileDelete char* nfile_delete- char[] with filename to delete TRUE - operation success

FALSE - operation failed

Creates/overwrites a file on current directory
SDFileAppend char* nfile_append - char[] with filename to create

char* buff_to_app - char[] with data to write
unsigned int to_write - number of chars to write

TRUE - operation success

FALSE - operation failed

Appends data on a file on current directory
SDFileRead char* nfile_read - name of file to be read

char* destBuff - buffer to fill with data read
unsigned long to_read - amount of data to read from file

WORD - amount of data read Reads data form a file
SDFileReadAt char* nfile_read - name of file to be read

char* destBuff - buffer to fill with data read
unsigned long to_read - amount of data to read from file
unsigned long start - starting position (absolute position from, 0 is first data of file)

WORD - amount of data read Reads data form a file
SDFileRename char* nfile_to_change - original file name

char* nfile_new_name - new file name or file path/name

TRUE - operation success

FALSE - operation failed

Renames a file to new name
SDFileMove char* nfile_to_change - original file name

char* npath_to_use - new directory path for (use SDDirGet to retrieve current directory)

TRUE - operation success

FALSE - operation failed

Moves a file to another directory

Directory management

Name Parameters Return Description
SDDirGet char* ndir_get - char[] to fill with path

int size_max - ndir_get max array size to prevent overflows

TRUE - operation success

FALSE - operation failed

Gets current directory path
SDDirChange char* ndir_chg - char[] with directory to change TRUE - operation success

FALSE - operation failed

Changes current directory
SDDirBack None TRUE - operation success

FALSE - operation failed

Moves to parent directory (if possible)
SDDirDelete char* ndir_delete - char[] with directory name to delete TRUE - operation success

FALSE - operation failed

Deletes a subfolder from current directory
SDDirCreate char* ndir_create - char[] with directory name to create TRUE - operation success

FALSE - operation failed

Renames a directory. Can be used also to move directory to other path
SDDirRename char* ndir_to_change - original directory name

char* ndir_new_name - new directory name or path/name

TRUE - operation success

FALSE - operation failed

Renames a directory. Can be used also to move directory to other path

Data Stream

Name Parameters Return Description
SDStreamEOF FIL* fobj - file object to be used (NOTE: remember to use '&' operator) TRUE - EOF reached

FALSE - EOF not reached

Provides End Of File for opened stream file
SDStreamOpen FIL* fobj - file object to be used (NOTE: remember to use '&' operator)

char* nfileRead - name of the file to be opened

TRUE - operation success

FALSE - operation failed

Opens stream file
SDStreamClose FIL* fobj - file object to be used (NOTE: remember to use '&' operator) TRUE - operation success

FALSE - operation failed

Closes stream file
SDStreamRead FIL* fobj - file object to be used (NOTE: remember to use '&' operator)

char* destBuff - buffer to fill with data read
unsigned long len - amount of data to read from file

WORD - amount of data read Reads data stream from file
SDStreamReadAt FIL* fobj - file object to be used (NOTE: remember to use '&' operator)

char* destBuff - buffer to fill with data read
unsigned long len - amount of data to read from file
unsigned long start - starting position (absolute position from, 0 is first data of file)

WORD - amount of data read Read data stream starting form a provided position
SDStreamWrite FIL* fobj - file object to be used (NOTE: remember to use '&' operator)

char* srcBuff - buffer to fill with data read
unsigned long to_write - amount of data to write on file

WORD - amount of data written Writes (appends) data stream to a file

Error values list

Following is a table of possible error codes returned by SDGetErr() function

  • (0) Succeeded
  • (1) A hard error occured in the low level disk I/O layer
  • (2) Assertion failed
  • (3) The physical drive cannot work
  • (4) Could not find the file
  • (5) Could not find the path
  • (6) The path name format is invalid
  • (7) Acces denied due to prohibited access or directory full
  • (8) Acces denied due to prohibited access
  • (9) The file/directory object is invalid
  • (10) The physical drive is write protected
  • (11) The logical drive number is invalid
  • (12) The volume has no work area
  • (13) There is no valid FAT volume on the physical drive
  • (14) The f_mkfs() aborted due to any parameter error
  • (15) Could not get a grant to access the volume within defined period
  • (16) The operation is rejected according to the file shareing policy
  • (17) LFN working buffer could not be allocated
  • (18) Number of open files > _FS_SHARE
  • (20) SD library not Initialized
  • (21) SD card not present
  • (22) SD not ready
  • (23) File not found
  • (24) Generic Error


External reference

The FAT library uses elm chan FATFs library and some custom files to provide easy to use APIs, specifically designed for Flyport modules. If you want to take a look at the original library you can find it here: elm-chan's module
Special thanks to Elm Chan for the great work and for releasing it open source!

Personal tools
Namespaces

Variants
Actions
START HERE
DEVELOPMENT
HARDWARE INFO
RESOURCES
PHASED OUT
Toolbox