SD Card Library

1. Overview

SD Card Library gives Ansteron Board the ability to read and write files on SD/MicroSD cards with FAT32 format. Data files can be exchanged with most computers and many other devices that support SD cards. The library can work with SD and MicroSD cards up to 32GB of storage.

2. Typical circuit

Ansteron Board accesses SD cards via its SPI interface. A level shifter is required to interface with SD cards since they work at 3.3V while Ansteron Board is 5V. Using simple resistor voltage dividers is acceptable for testing purpose. However, appropriate level shifters are recommended to ensure electrical connection will work properly as well as data integrity.

Warning: SD card may be damaged if directly connect to 5V supply and/or signal.

Note: A pull up resistor is required on /CS pin of SD card. Since SPI interface is also used when downloading program, pull-up resistor will automatically disconnect (deselect) SD card from the bus to avoid interference.

3. Example

In the example below, Ansteron Board will connect to a SD card, retrieve its capacity and then write a test message into a file name "TEST.TXT" in root directory.

4. Functions

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.

setup_SD_card(cs_pin,hs_option);

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 (PIN_Bx, PIN_Cx, PIN_Dx). Input 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.

SD_capacity();

Function will return card�s data capacity, a long integer which is the number of 512 byte blocks of the card.

SD_open_file(file_name,new);

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.

SD_read_file(buffer,length);

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.

SD_write_file(buffer,size);

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.

SD_write_string(string);

Write a zero-terminated string to opening file. Ending zero will not be written.

SD_seek_file(pos);

Move both read and write pointers to the end of being of opening file. Input pos can be FILE_END or FILE_START.

SD_close_file();

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.

SD_list_item(path,index,return_name);

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.

SD_is_directory(path);

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.

SD_file_exists(path);

Check if a file or folder with given path exists. Function returns 1 if the file or folder was found, zero otherwise.

SD_file_size(path);

Return the size of a file in byte.

SD_make_directory(path);

Create new directory. Function will return 1 if succeeded or folder exists, zero otherwise.

5. Notes

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 capacityCluster size
4GB or higher32KB
2GB16KB
1GB8KB
512MB4KB
256MB2KB
128MB1KB