Basic Library
Digital I/O
Analog I/O
Advanced I/O
Time
Math
Trigonometry
Random Numbers
Bits and Bytes
Interrupts
Serial Comm.
Standard Library
Servo Motor
Stepping Motor
Character LCD
EEPROM
SPI
I2C (Wire)
SD Card
SD (File Operations)
Ethernet
Ethernet (Server)
Ethernet (Client)
Firmata
Periodic Operation
Power Save
Clock (RTC)
SoftwareSerial
Utility
SD (File Operations)
The SD (File Operations) library allows for reading from and writing to individual files on an SD card.
available
Description
Check if there are any bytes available for reading from the file.
Syntax
file.available()
Parameters
file: An instance of the File class (returned by SD.open())
Returns
The number of bytes available (int).
close
Description
Close the file and ensure that any data written to it is physically saved to the SD card.
Syntax
file.close()
Parameters
None
Returns
None
flush
Description
Ensures that any bytes written to the file are physically saved to the SD card. This is done automatically when the file is closed.
Syntax
file.flush()
Parameters
None
Returns
None
peek
Description
Read a byte from the file without advancing to the next one. That is, successive calls to peek() will return the same value, as will the next call to read().
Syntax
file.peek()
Parameters
None
Returns
The next byte (or character), or -1 if none is available.
position
Description
Get the current position within the file (i.e. the location to which the next byte will be read from or written to).
Syntax
file.position()
Parameters
None
Returns
The position within the file (unsigned long)
Description
Print data to the file, which must have been opened for writing. Prints numbers as a sequence of digits, each an ASCII character (e.g. the number 123 is sent as the three characters '1', '2', '3').
Syntax
file.print(data)
file.print(data, BASE)Parameters
data: The data to print (char, byte, int, long, or string)
BASE (optional): The base in which to print numbers: BIN for binary (base 2), DEC for decimal (base 10), OCT for octal (base 8), HEX for hexadecimal (base 16).Returns
Byte
print() will return the number of bytes written, though reading that number is optional.
println
Description
Print data, followed by a carriage return and newline, to the File, which must have been opened for writing. Prints numbers as a sequence of digits, each an ASCII character (e.g. the number 123 is sent as the three characters '1', '2', '3').
Syntax
file.println(data)
file.println(data, BASE)Parameters
data: The numbers or character string to print
BASE: The base in which to print numbers (BYTE, BIN, DEC, HEX, OCT)Returns
Byte
println() will return the number of bytes written, though reading that number is optional.
seek
Description
Seek to a new position in the file, which must be between 0 and the size of the file (inclusive).
Syntax
file.seek(unsigned long pos)
Parameters
pos: The position to which to seek (unsigned long)
Returns
True for success, false for failure (boolean).
size
Description
Get the size of the file.
Syntax
file.size()
Parameters
None
Returns
The size of the file in bytes (unsigned long).
read
Description
Reads a byte from the file.
Syntax
file.read()
Parameters
None
Returns
The next byte (or character), or -1 if none is available (or at the end of a file).
write
Description
Write data or a character string to the file.
Syntax
file.write(data)
file.write(buf, len)Parameters
data: The byte, char, or string (char *) to write
buf: An array of characters or bytes
len: The number of elements in bufReturns
Byte
write() will return the number of bytes written, though reading that number is optional.
isDirectory
Description
Directories (or folders) are special kinds of files, this function reports if the current file is a directory or not.
Syntax
file.isDirectory()
Parameters
None
Returns
True if directory, false if file.
openNextFile
Description
Reports the next file or folder in a directory.
Syntax
file.openNextFile()
Parameters
None
Returns
char: The next file or folder in the path.
rewindDirectory
Description
rewindDirectory() will bring you back to the first file in the directory, used in conjunction with openNextFile().
Syntax
file.rewindDirectory()
Parameters
None
Returns
None
Sample Program
This sample program runs a test of all operations (write, read, get size, remove) by accessing the Micro SD.
#include <Arduino.h>
#include <SD.h>
void setup(){
Serial.begin(9600);
while(!Serial.available()); // wait to press key
Serial.read(); //dummy
if(!SD.begin()){
Serial.println("Card failed, or not present.");
while(1);
}
}
void loop(){
File file = SD.open("sample.txt", FILE_WRITE);
if(file){
//Write
Serial.println("Success to open sample.txt and write hello.");
file.println("Hello, my SD");
file.close();
//Read
file = SD.open("sample.txt", FILE_READ);
Serial.println("Reading file...");
while(file.available()){
Serial.print((char)file.read());
delay(50);
}
Serial.println();
//Size
Serial.print("File Size:");
Serial.println(file.size());
file.close();
digitalWrite(PIN_LED0, 0);
//Remove
Serial.println("Remove the file? y/n");
while(!Serial.available());
if(Serial.read() == 'y'){
SD.remove("sample.txt");
Serial.println("sample.txt has been removed");
}
delay(400);
} else {
Serial.println("Failed to open file.");
digitalWrite(PIN_LED0, 0);
while(1);
}
}