Reference   Language | Libraries | Comparison | Changes

Some things to keep in mind when using the SD Library


The communication between the microcontroller and the SD card uses the SPI protocol. This communication method is implemented on different pins depending on the board family. Classic Arduino form factor (as in Uno, Leonardo , WiFi rev2) as well as the Classic Nano, Nano Every, Nano 33 IoT, and Nano 33 BLE implement the SPI on digital pins 11, 12, and 13. The Classic large format of the Mega uses pins 50, 51, and 52. Arduino Micro uses pins 14, 15, and 16. Additionally, another pin must be used to select the SD card. Microcontrollers implement an internal selection pin, known as SS or CS. This pin is, in most Arduino boards, pin 10, pin 53 (on the Mega), or pin 17 (on the Micro). Those are the values that will be selected by default if no other pin specified in the call to SD.begin(). The shields carrying an SD card memory slots place the SS pin differently. Please check which is the required pin for each different board and use that to call the SD.begin() function with the right parameter. Check later in the page for further information on SS pins for different shields. Note that even if you don't use the hardware SS pin, it must be left as an output or the SD library won't work. Different boards use different pins for this functionality, so be sure you’ve selected the correct pin in SD.begin().

Not all the functions are listed on the main SD library page, because they are part of the library's utility functions.

Formatting/Preparing the card

(NB : whenever referring to the SD card, it means SD and microSD sizes, as well as SD and SDHD formats)

Most SD cards work right out of the box, but it's possible you have one that was used in a computer or camera and it cannot be read by the SD library. Formatting the card will create a file system that the Arduino can read and write to.

It's not desirable to format SD cards frequently, as it shortens their life span.

You’ll need a SD reader and computer to format your card. The library supports the FAT16 and FAT32 filesystems, but use FAT16 when possible. The process to format is fairly straightforward.

Windows : right click on your card’s directory and choose “Format” from the drop down. Make sure you choose FAT as the filesystem.

OSX : Open Disk Utility (located in Applications>Utilities). Choose the Card, click on the erase tab, select MS-DOS(FAT) as the Format, and click Erase. NB: OSX places a number of “hidden” files on the device when it formats a drive. To format a SD car without the extra files on OSX, follow these notes on Ladyada’s site.

Linux: With a SD card inserted, open a terminal window. At the prompt, type df, and press enter. The windows will report the device name of your SD card, it should look something like /dev/sdb1. Unmount the SD card, but leave it in the computer. Type sudo mkdosfs -F 16 /dev/sdb1, replacing the device name with yours. Remove the SD card and replace it to verify it works.

File Naming

FAT file systems have a limitation when it comes to naming conventions. You must use the 8.3 format, so that file names look like “NAME001.EXT”, where “NAME001” is an 8 character or fewer string, and “EXT” is a 3 character extension. People commonly use the extensions .TXT and .LOG. It is possible to have a shorter file name (for example, mydata.txt, or time.log), but you cannot use longer file names. Read more on the 8.3 convention.

Opening/Closing files

When you use file.write(), it doesn't write to the card until you flush() or close(). Whenever you open a file, be sure to close it to save your data.

As of version 1.0, it is possible to have multiple files open.

Different Shields/boards

There are a number of different shields that support SD cards. This list is not exclusive, but are commonly used.

The MEM / ENV shield

The MEM / ENV shield come with an SD card slot onboard. The shields fit on top of any Arduino MKR board (Zero, WiFi, LoRa, Sigfox, NBIoT, GSM, or Vidor). The CS pin for the SD card is on pin 4. Make sure you call SD.begin(4) to use the SD card functionality.

Arduino Ethernet Shield

The Ethernet Shield comes with an SD card slot onboard. The shield fits on top of your Arduino. Because the Ethernet module uses pin 10, the CS pin for the SD card has been moved to pin 4. Make sure you use SD.begin(4) to use the SD card functionality.

Adafruit Micro-SD breakout Board

This board supports Micro-SD cards, ans you’ll need to wire it up before you can use it. On the board, connect GND to ground, 5v to 5v, CLK to Pin 13 on your Arduino, DO to pin 12, DI to pin 11, and CS to pin 10. If you are already using pin 10, you can use a different pin, as long as you remember to change the pin in SD.begin().

Sparkfun SD Shield

The Sparkfun shield fits on your Arduino or Genuino board and uses pin 8 for CS. You will need use SD.begin(8) to use the card. NB: the Sparkfun shield was recently updated. Older versions look similar, but were lacking a connection to the 3.3V bus and did not have the onboard hex inverter.

See Also

  • SD library - Your reference for the SD Card library.

  • Datalogger - How to log data from three analog sensors to an SD card.
  • DumpFile - How to read a file from the SD card.
  • Files - How to create and destroy an SD card file.
  • Listfiles - how print out the files in a directory on a SD card.
  • ReadWrite - How to read and write data to and from an SD card.
  • CardInfo - Get info about your SD card.

Last revision 2015/08/17 by SM
Reference Home

Corrections, suggestions, and new documentation should be posted to the Forum.

The text of the Arduino reference is licensed under a Creative Commons Attribution-ShareAlike 3.0 License. Code samples in the reference are released into the public domain.