The library supports 8.3 file name format only. File names must have 8 characters or less and 3 characters extension ("FILE1.DAT", "TEST1234.TXT").
Only one file can be opened at a time. Once a file is opened, the program can either read or write the file. Reading and writing data is done in blocks of one byte or more. Data written to a file will not finalize until the file is closed.
This function must be called before other functions of the library can work. Connected SD card will be detected, initialized and its format will be checked as well. The function returns 1 if succeeded, zero if card was not detected, card is not compatible or unsupported format. For appropriate card format, please see note below.
The function takes two inputs. Value for
cs_pin can be any I/O pin on Ansteron Board (except pins B3, B4 and B5) and their names are the same as other I/O functions (
hs_option specify if high speed SPI should be used. If
hs_option is any value different than 0, SPI clock of 8 MHz will be used. Otherwise, the interface will run at 4 MHz.
Function will return card�s data capacity, a
long integer which is the number of 512 byte blocks of the card.
Open an existing file on SD card. If input
new is a non-zero value, a new file will be created if given name does not exist. Input
file_name must be the absolute path if file locates in sub folder. Function returns 1 if succeeded, 0 if failed.
Read one byte or more from the file being opened. Input
buffer is a pointer to a location where data will be written and length is the number of byte to be read. The function return number of bytes read. File is read as a stream of data, the file pointer will automatically increase by the number of bytes read. Maximum value for length is 512.
Write one byte or more from buffer into opening file. The write pointer is at the beginning of file when it was open. New data will over write all data that was in the file. To move pointer to the end of file, use function
SD_seek_file(FILE_END); before the first write. The maximum value for
size is 512. Maximum file size is 4GB � 1 byte.
Write a zero-terminated string to opening file. Ending zero will not be written.
Move both read and write pointers to the end of being of opening file. Input
pos can be
Close opening file. If data was written, file size will be updated to be accessible. If this function is not called, some of written data may be lost and file structure may be corrupted.
The functions below can only work if a file is not currently open.
List an item, which could be a file or folder (directory) at the location given by input
path and the index of that item, starting from 0. Name of the item will be written to location given by pointer
return_name if it is found. The function returns number of character of the file (or folder) name which was written to
return_name. It returns 0 if there is no more item or given path is not valid. The buffer should be big enough to store file or folder full name plus ending zero, usually 13 bytes minimum.
Check if an item with given name and location is a folder. The function returns 1 if it is a folder, zero if it�s not or the name was not found.
Check if a file or folder with given path exists. Function returns 1 if the file or folder was found, zero otherwise.
Return the size of a file in byte.
Create new directory. Function will return 1 if succeeded or folder exists, zero otherwise.
The library support file size up to 4GB (less 1 byte). However, writing to multiple small files instead of a single large file is recommended. That will make it faster and easier to view and edit files later.
If SD card is divided into multiple volumes, only the first volume with FAT32 format will be selected. Reading the capacity will reflect that volume only, not the entire card.
Recommended file system format:
SD card must be FAT32. Some disk formatting programs do not allow users to select format. In that case, to be FAT32, a volume must be formatted to have more than 65525 clusters. When formatting SD card, select small block (cluster) size for cards with small capacity. Otherwise, it will be formatted as FAT16 or FAT12 which will not work with the library.
Cluster size vs. Card capacity:
|Card capacity||Cluster size|
|4GB or higher||32KB|