SD

The SD library provides methods for navigating the directories and files on a FAT formatted SD Card.

1. Detailed Introduction

2. Introductory Programs

   1. ReadWrite

   2. Cardinfo

3. Full library usage

   1. SD

      1. Public Functions

         1. begin(uint8_t csPin = SS)

         2. open(const char *filename, uint8_t mode = FILE_READ)

         3. end(void)

         4. exists(char *filepath)

         5. mkdir(char *filepath)

         6. mkdir(char *filepath)

         7. remove(char *filepath)

         8. rmdir(char *filepath)

   2. File

      1. Constructors

         1. File(void))

         2. File(SdFile f, const char *name)

      2. Public Functions

         1. read(void *buf, uint16_t nbyte)

         2. seek(uint32_t pos)

         3. position()

         4. size()

         5. close()

         6. isDirectory(void)

         7. openNextFile(uint8_t mode = O_RDONLY)

         8. rewindDirectory(void)

      3. Virtual Public Functions

         1. write(uint8_t)

         2. write(const uint8_t *buf, size_t size)

         3. read()

         4. peek()

         5. flush()

      4. Conversion Operator

         1. bool()

      5. Print Class Functions

         1. write(const char *str)

         2. write(const char *buffer, size_t size)

   3. Utility Classes

      1. Sd2Card

      2. SdVolume

      3. SdFile

4. External Links

¶Detailed Introduction

The SD library is a wrapper around the sdfatlib library. The SD libarary contains two classes, namely the SD class and File class . The SD class is used to navigate the directory tree and to manipulate files and folders on the SD card. The File class inherits from base class Stream and provides methods for reading from and writing to individual files on the SD card.

¶Introductory Programs

¶ReadWrite

This example shows how to read and write data to and from an SD card file.

/*
 SD card read/write
 
 This example shows how to read and write data to and from an SD card file 	
 The circuit:
 * SD card attached to SPI bus as follows:
 ** MOSI - pin 11
 ** MISO - pin 12
 ** CLK - pin 13
 ** CS - pin 4
 
 created   Nov 2010
 by David A. Mellis
 updated 2 Dec 2010
 by Tom Igoe
 
 - Cleaned up all SD examples included with MPIDE for consistency in defining CS pins
 revised  24 May 2013 by Jacob Christ

 This example code is in the public domain.
 	 
*/
 
#include <SD.h>

File myFile;

// On the Ethernet Shield, CS is pin 4. It's set as an output by default.
// Note that even if it's not used as the CS pin, the hardware SS pin 
// (10 on most Arduino boards, 53 on the Mega) must be left as an output 
// or the SD library functions will not work. 

// Default SD chip select for Uno and Mega type devices
const int chipSelect_SD_default = 10; // Change 10 to 53 for a Mega

// chipSelect_SD can be changed if you do not use default CS pin
const int chipSelect_SD = chipSelect_SD_default;

void setup()
{
  Serial.begin(9600);
  Serial.print("Initializing SD card...");

  // Make sure the default chip select pin is set to so that
  // shields that have a device that use the default CS pin
  // that are connected to the SPI bus do not hold drive bus
  pinMode(chipSelect_SD_default, OUTPUT);
  digitalWrite(chipSelect_SD_default, HIGH);

  pinMode(chipSelect_SD, OUTPUT);
  digitalWrite(chipSelect_SD, HIGH);
   
  if (!SD.begin(chipSelect_SD)) {
    Serial.println("initialization failed!");
    return;
  }
  Serial.println("initialization done.");
  
  // open the file. note that only one file can be open at a time,
  // so you have to close this one before opening another.
  myFile = SD.open("test.txt", FILE_WRITE);
  
  // if the file opened okay, write to it:
  if (myFile) {
    Serial.print("Writing to test.txt...");
    myFile.println("testing 1, 2, 3.");
	// close the file:
    myFile.close();
    Serial.println("done.");
  } else {
    // if the file didn't open, print an error:
    Serial.println("error opening test.txt");
  }
  
  // re-open the file for reading:
  myFile = SD.open("test.txt");
  if (myFile) {
    Serial.println("test.txt:");
    
    // read from the file until there's nothing else in it:
    while (myFile.available()) {
    	Serial.write(myFile.read());
    }
    // close the file:
    myFile.close();
  } else {
  	// if the file didn't open, print an error:
    Serial.println("error opening test.txt");
  }
}

void loop()
{
	// nothing happens after setup
}

¶Cardinfo

This example shows how use the utility libraries on which the SD library is based in order to get info about your SD card.

/*
  SD card test 
   
 This example shows how use the utility libraries on which the'
 SD library is based in order to get info about your SD card.
 Very useful for testing a card when you're not sure whether its working or not.
 	
 The circuit:
  * SD card attached to SPI bus as follows:
 ** MOSI - pin 11 on Arduino Uno/Duemilanove/Diecimila
 ** MISO - pin 12 on Arduino Uno/Duemilanove/Diecimila
 ** CLK - pin 13 on Arduino Uno/Duemilanove/Diecimila
 ** CS - depends on your SD card shield or module

 
 created  28 Mar 2011
 by Limor Fried 

 - Cleaned up all SD examples included with MPIDE for consistency in defining CS pins
 revised  24 May 2013 by Jacob Christ
 */
 // include the SD library:
#include <SD.h>

// set up variables using the SD utility library functions:
Sd2Card card;
SdVolume volume;
SdFile root;

// change this to match your SD shield or module;
// Arduino Ethernet shield: pin 4
// Adafruit SD shields and modules: pin 10
// Sparkfun SD shield: pin 8
// On the Ethernet Shield, CS is pin 4. It's set as an output by default.
// Note that even if it's not used as the CS pin, the hardware SS pin 
// (10 on most Arduino boards, 53 on the Mega) must be left as an output 
// or the SD library functions will not work. 

// Default SD chip select for Uno and Mega type devices
const int chipSelect_SD_default = 10; // Change 10 to 53 for a Mega

// chipSelect_SD can be changed if you do not use default CS pin
const int chipSelect_SD = chipSelect_SD_default;

void setup()
{
  Serial.begin(9600);
  Serial.print("\nInitializing SD card...");

  // Make sure the default chip select pin is set to so that
  // shields that have a device that use the default CS pin
  // that are connected to the SPI bus do not hold drive bus
  pinMode(chipSelect_SD_default, OUTPUT);
  digitalWrite(chipSelect_SD_default, HIGH);

  pinMode(chipSelect_SD, OUTPUT);
  digitalWrite(chipSelect_SD, HIGH);

  // we'll use the initialization code from the utility libraries
  // since we're just testing if the card is working!
  if (!card.init(SPI_HALF_SPEED, chipSelect_SD)) {
    Serial.println("initialization failed. Things to check:");
    Serial.println("* is a card is inserted?");
    Serial.println("* Is your wiring correct?");
    Serial.println("* did you change the chipSelect pin to match your shield or module?");
    return;
  } else {
   Serial.println("Wiring is correct and a card is present."); 
  }

  // print the type of card
  Serial.print("\nCard type: ");
  switch(card.type()) {
    case SD_CARD_TYPE_SD1:
      Serial.println("SD1");
      break;
    case SD_CARD_TYPE_SD2:
      Serial.println("SD2");
      break;
    case SD_CARD_TYPE_SDHC:
      Serial.println("SDHC");
      break;
    default:
      Serial.println("Unknown");
  }

  // Now we will try to open the 'volume'/'partition' - it should be FAT16 or FAT32
  if (!volume.init(card)) {
    Serial.println("Could not find FAT16/FAT32 partition.\nMake sure you've formatted the card");
    return;
  }


  // print the type and size of the first FAT-type volume
  long volumesize;
  Serial.print("\nVolume type is FAT");
  Serial.println(volume.fatType(), DEC);
  Serial.println();
  
  volumesize = volume.blocksPerCluster();    // clusters are collections of blocks
  volumesize *= volume.clusterCount();       // we'll have a lot of clusters
  volumesize *= 512;                            // SD card blocks are always 512 bytes
  Serial.print("Volume size (bytes): ");
  Serial.println(volumesize);
  Serial.print("Volume size (Kbytes): ");
  volumesize /= 1024;
  Serial.println(volumesize);
  Serial.print("Volume size (Mbytes): ");
  volumesize /= 1024;
  Serial.println(volumesize);

  
  Serial.println("\nFiles found on the card (name, date and size in bytes): ");
  root.openRoot(volume);
  
  // list all files in the card with date and size
  root.ls(LS_R | LS_DATE | LS_SIZE);
}


void loop(void) {
  
}

¶Full library usage

¶SD

¶Public Functions

---

¶begin(uint8_t csPin = SS)

boolean begin(uint8_t csPin = SS);

Initialize the SD card. Returns true is successful, false otherwise.

¶open(const char *filename, uint8_t mode = FILE_READ)

File open(const char *filename, uint8_t mode = FILE_READ);

Open the specified file/directory with the supplied mode (e.g. read or write, etc). Returns a File object for interacting with the file. Note that currently only one file can be open at a time.

¶end(void)

void end(void) {if(root.isOpen()) root.close();}

This will close the root so it is safe to call begin again. To work without corrupting the FAT all open files should be closed before calling end.

¶exists(char *filepath)

boolean exists(char *filepath);

Determine if the requested file path exists.

¶mkdir(char *filepath)

boolean mkdir(char *filepath);

Create the requested directory heirarchy. If intermediate directories do not exist they will be created.

¶mkdir(char *filepath)

boolean mkdir(char *filepath);

Create the requested directory heirarchy. If intermediate directories do not exist they will be created.

¶remove(char *filepath)

boolean remove(char *filepath);

Delete the specified file specified in the filepath parameter.

¶rmdir(char *filepath)

boolean rmdir(char *filepath);

Delete the directory specified in the filepath parameter.

¶File

• Parent class: Stream

¶Constructors

---

¶File(void))

File(void);      

Empty Constructor

¶File(SdFile f, const char *name)

File(SdFile f, const char *name);     

¶Public Functions

---

¶read(void *buf, uint16_t nbyte)

int read(void *buf, uint16_t nbyte);

Buffered read for more efficient, high speed reading.

¶seek(uint32_t pos)

boolean seek(uint32_t pos);

Sets a file's position. pos is the new position in bytes from the beginning of the file.

¶position()

uint32_t position();

Returns The current position for a file or directory.

¶size()

uint32_t size();

Returns The total number of bytes in a file or directory.

¶close()

void close();

Close the file. This must be called before opening another file.

¶isDirectory(void)

boolean isDirectory(void);

Returns true is the file is a directory, false otherwise.

¶openNextFile(uint8_t mode = O_RDONLY)

File openNextFile(uint8_t mode = O_RDONLY);

Allows you to recurse into a directory

¶rewindDirectory(void)

void rewindDirectory(void);

Set the file's current position to zero.

¶Virtual Public Functions

¶write(uint8_t)

virtual size_t write(uint8_t);

¶write(const uint8_t *buf, size_t size)

virtual size_t write(const uint8_t *buf, size_t size);

¶read()

virtual int read();

¶peek()

virtual int peek();

Returns the current posistion in the file. Returns 0 if the file is not open.

¶flush()

virtual void flush();

Causes all modified data and directory fields to be written to the storage device.

¶Conversion Operator

¶bool()

operator bool();

¶Print Class Functions

---

The following write functions are pulled in from the Print class.

¶write(const char *str)

size_t   write(const char *str);

¶write(const char *buffer, size_t size)

size_t   write(const char *buffer, size_t size);

¶Utility Classes

The SD Library is a wrapper around a more complete set of classes. You can access these classes directly from your Arduino Sketch. See the Cardinfo example above for details on how to do this.

¶Sd2Card

Sd2Card;

¶SdVolume

SdVolume volume;

¶SdFile

SdFile root;

¶External Links

• github.com/chipKIT32/chipKIT-core/tree/master/pic32/libraries/SD - The github repository for the SD Library