From 85dbcca432d1b658d0d848f5f7ba0a9e811afc04 Mon Sep 17 00:00:00 2001 From: Tom Igoe Date: Fri, 24 Jul 2020 08:11:38 -0400 Subject: [PATCH] Updated SD card examples for clarity and to reflect OSHWA recommendations on pin names Updated examples to make examples more uniform and clearer, and to reflect [OSHWA recommendation on pin naming](https://www.oshwa.org/2020/06/29/a-resolution-to-redefine-spi-pin-names/) --- examples/CardInfo/CardInfo.ino | 14 +-- examples/Datalogger/Datalogger.ino | 43 ++++---- examples/DumpFile/DumpFile.ino | 34 +++--- examples/Files/Files.ino | 27 +++-- .../NonBlockingWrite/NonBlockingWrite.ino | 101 +++++++++++------- examples/ReadWrite/ReadWrite.ino | 26 ++--- examples/listfiles/listfiles.ino | 38 ++++--- 7 files changed, 152 insertions(+), 131 deletions(-) diff --git a/examples/CardInfo/CardInfo.ino b/examples/CardInfo/CardInfo.ino index 1a81867..3418e92 100644 --- a/examples/CardInfo/CardInfo.ino +++ b/examples/CardInfo/CardInfo.ino @@ -4,19 +4,18 @@ 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. - + Pin numbers reflect the default SPI pins for Uno and Nano models 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 + ** SDO - pin 11 on Arduino Uno/Duemilanove/Diecimila + ** SDI - pin 12 on Arduino Uno/Duemilanove/Diecimila ** CLK - pin 13 on Arduino Uno/Duemilanove/Diecimila ** CS - depends on your SD card shield or module. - Pin 4 used here for consistency with other Arduino examples - + Pin 10 used here for consistency with other Arduino examples created 28 Mar 2011 by Limor Fried - modified 9 Apr 2012 + modified 24 July 2020 by Tom Igoe */ // include the SD library: @@ -29,11 +28,12 @@ SdVolume volume; SdFile root; // change this to match your SD shield or module; +// Default SPI on Uno and Nano: pin 10 // Arduino Ethernet shield: pin 4 // Adafruit SD shields and modules: pin 10 // Sparkfun SD shield: pin 8 // MKRZero SD: SDCARD_SS_PIN -const int chipSelect = 4; +const int chipSelect = 10; void setup() { // Open serial communications and wait for port to open: diff --git a/examples/Datalogger/Datalogger.ino b/examples/Datalogger/Datalogger.ino index c2631c0..fdbacfd 100644 --- a/examples/Datalogger/Datalogger.ino +++ b/examples/Datalogger/Datalogger.ino @@ -2,18 +2,21 @@ SD card datalogger This example shows how to log data from three analog sensors - to an SD card using the SD library. + to an SD card using the SD library. Pin numbers reflect the default + SPI pins for Uno and Nano models The circuit: analog sensors on analog ins 0, 1, and 2 SD card attached to SPI bus as follows: - ** MOSI - pin 11 - ** MISO - pin 12 + ** SDO - pin 11 + ** SDI - pin 12 ** CLK - pin 13 - ** CS - pin 4 (for MKRZero SD: SDCARD_SS_PIN) + ** CS - depends on your SD card shield or module. + Pin 10 used here for consistency with other Arduino examples + (for MKRZero SD: SDCARD_SS_PIN) created 24 Nov 2010 - modified 9 Apr 2012 + modified 24 July 2020 by Tom Igoe This example code is in the public domain. @@ -23,25 +26,26 @@ #include #include -const int chipSelect = 4; +const int chipSelect = 10; void setup() { // Open serial communications and wait for port to open: Serial.begin(9600); - while (!Serial) { - ; // wait for serial port to connect. Needed for native USB port only - } - + // wait for Serial Monitor to connect. Needed for native USB port boards only: + while (!Serial); Serial.print("Initializing SD card..."); - // see if the card is present and can be initialized: if (!SD.begin(chipSelect)) { - Serial.println("Card failed, or not present"); - // don't do anything more: - while (1); + Serial.println("initialization failed. Things to check:"); + Serial.println("1. is a card inserted?"); + Serial.println("2. is your wiring correct?"); + Serial.println("3. did you change the chipSelect pin to match your shield or module?"); + Serial.println("Note: press reset or reopen this serial monitor after fixing your issue!"); + while (true); } - Serial.println("card initialized."); + + Serial.println("initialization done."); } void loop() { @@ -73,12 +77,3 @@ void loop() { Serial.println("error opening datalog.txt"); } } - - - - - - - - - diff --git a/examples/DumpFile/DumpFile.ino b/examples/DumpFile/DumpFile.ino index 7491999..bb114b6 100644 --- a/examples/DumpFile/DumpFile.ino +++ b/examples/DumpFile/DumpFile.ino @@ -3,13 +3,16 @@ This example shows how to read a file from the SD card using the SD library and send it over the serial port. + Pin numbers reflect the default SPI pins for Uno and Nano models. The circuit: SD card attached to SPI bus as follows: - ** MOSI - pin 11 - ** MISO - pin 12 + ** SDO - pin 11 + ** SDI - pin 12 ** CLK - pin 13 - ** CS - pin 4 (for MKRZero SD: SDCARD_SS_PIN) + ** CS - depends on your SD card shield or module. + Pin 10 used here for consistency with other Arduino examples + (for MKRZero SD: SDCARD_SS_PIN) created 22 December 2010 by Limor Fried @@ -17,31 +20,29 @@ by Tom Igoe This example code is in the public domain. - */ - -#include #include -const int chipSelect = 4; +const int chipSelect = 10; void setup() { // Open serial communications and wait for port to open: Serial.begin(9600); - while (!Serial) { - ; // wait for serial port to connect. Needed for native USB port only - } - + // wait for Serial Monitor to connect. Needed for native USB port boards only: + while (!Serial); Serial.print("Initializing SD card..."); - // see if the card is present and can be initialized: if (!SD.begin(chipSelect)) { - Serial.println("Card failed, or not present"); - // don't do anything more: - while (1); + Serial.println("initialization failed. Things to check:"); + Serial.println("1. is a card inserted?"); + Serial.println("2. is your wiring correct?"); + Serial.println("3. did you change the chipSelect pin to match your shield or module?"); + Serial.println("Note: press reset or reopen this serial monitor after fixing your issue!"); + while (true); } - Serial.println("card initialized."); + + 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. @@ -62,4 +63,3 @@ void setup() { void loop() { } - diff --git a/examples/Files/Files.ino b/examples/Files/Files.ino index cabebba..85faa7c 100644 --- a/examples/Files/Files.ino +++ b/examples/Files/Files.ino @@ -2,37 +2,37 @@ SD card basic file example This example shows how to create and destroy an SD card file - The circuit: + The circuit. Pin numbers reflect the default + SPI pins for Uno and Nano models: SD card attached to SPI bus as follows: - ** MOSI - pin 11 - ** MISO - pin 12 + ** SDO - pin 11 + ** SDI - pin 12 ** CLK - pin 13 - ** CS - pin 4 (for MKRZero SD: SDCARD_SS_PIN) + ** CS - depends on your SD card shield or module. + Pin 10 used here for consistency with other Arduino examples + (for MKRZero SD: SDCARD_SS_PIN) created Nov 2010 by David A. Mellis - modified 9 Apr 2012 + modified 24 July 2020 by Tom Igoe This example code is in the public domain. - */ -#include #include +const int chipSelect = 10; File myFile; void setup() { // Open serial communications and wait for port to open: Serial.begin(9600); - while (!Serial) { - ; // wait for serial port to connect. Needed for native USB port only - } - + // wait for Serial Monitor to connect. Needed for native USB port boards only: +while (!Serial); Serial.print("Initializing SD card..."); - if (!SD.begin(4)) { + if (!SD.begin(10)) { Serial.println("initialization failed!"); while (1); } @@ -70,6 +70,3 @@ void setup() { void loop() { // nothing happens after setup finishes. } - - - diff --git a/examples/NonBlockingWrite/NonBlockingWrite.ino b/examples/NonBlockingWrite/NonBlockingWrite.ino index 29d8ec6..082a5fb 100644 --- a/examples/NonBlockingWrite/NonBlockingWrite.ino +++ b/examples/NonBlockingWrite/NonBlockingWrite.ino @@ -3,89 +3,116 @@ This example demonstrates how to perform non-blocking writes to a file on a SD card. The file will contain the current millis() - value every 10ms. If the SD card is busy, the data will be buffered + value every 10ms. If the SD card is busy, the data will be dataBuffered in order to not block the sketch. + If data is successfully written, the built in LED will flash. After a few + seconds, check the card for a file called datalog.txt + NOTE: myFile.availableForWrite() will automatically sync the file contents as needed. You may lose some unsynced data still if myFile.sync() or myFile.close() is not called. + Pin numbers reflect the default SPI pins for Uno and Nano models + Updated for clarity and uniformity with other examples + The circuit: - - Arduino MKR Zero board - - micro SD card attached + analog sensors on analog ins 0, 1, and 2 + SD card attached to SPI bus as follows: + ** SDO - pin 11 + ** SDI - pin 12 + ** CLK - pin 13 + ** CS - depends on your SD card shield or module. + Pin 10 used here for consistency with other Arduino examples + (for MKRZero SD: SDCARD_SS_PIN) + + modified 24 July 2020 + by Tom Igoe This example code is in the public domain. */ - #include +const int chipSelect = 10; + // file name to use for writing -const char filename[] = "demo.txt"; +const char filename[] = "datalog.txt"; // File object to represent file -File txtFile; - +File myFile; // string to buffer output -String buffer; - +String dataBuffer; +// last time data was written to card: unsigned long lastMillis = 0; void setup() { + // Open serial communications and wait for port to open: Serial.begin(9600); - while (!Serial); - - // reserve 1kB for String used as a buffer - buffer.reserve(1024); + // reserve 1kB for String used as a dataBuffer + dataBuffer.reserve(1024); // set LED pin to output, used to blink when writing pinMode(LED_BUILTIN, OUTPUT); - // init the SD card - if (!SD.begin()) { - Serial.println("Card failed, or not present"); - // don't do anything more: - while (1); + // wait for Serial Monitor to connect. Needed for native USB port boards only: + while (!Serial); + + Serial.print("Initializing SD card..."); + + if (!SD.begin(chipSelect)) { + Serial.println("initialization failed. Things to check:"); + Serial.println("1. is a card inserted?"); + Serial.println("2. is your wiring correct?"); + Serial.println("3. did you change the chipSelect pin to match your shield or module?"); + Serial.println("Note: press reset or reopen this serial monitor after fixing your issue!"); + while (true); } + Serial.println("initialization done."); + // If you want to start from an empty file, // uncomment the next line: - // SD.remove(filename); - + // SD.remove(filename); // try to open the file for writing - txtFile = SD.open(filename, FILE_WRITE); - if (!txtFile) { + + myFile = SD.open(filename, FILE_WRITE); + if (!myFile) { Serial.print("error opening "); Serial.println(filename); - while (1); + while (true); } // add some new lines to start - txtFile.println(); - txtFile.println("Hello World!"); + myFile.println(); + myFile.println("Hello World!"); + Serial.println("Starting to write to file..."); } void loop() { // check if it's been over 10 ms since the last line added unsigned long now = millis(); if ((now - lastMillis) >= 10) { - // add a new line to the buffer - buffer += "Hello "; - buffer += now; - buffer += "\r\n"; - + // add a new line to the dataBuffer + dataBuffer += "Hello "; + dataBuffer += now; + dataBuffer += "\r\n"; + // print the buffer length. This will change depending on when + // data is actually written to the SD card file: + Serial.print("Unsaved data buffer length (in bytes): "); + Serial.println(dataBuffer.length()); + // note the time that the last line was added to the string lastMillis = now; } // check if the SD card is available to write data without blocking - // and if the buffered data is enough for the full chunk size - unsigned int chunkSize = txtFile.availableForWrite(); - if (chunkSize && buffer.length() >= chunkSize) { + // and if the dataBuffered data is enough for the full chunk size + unsigned int chunkSize = myFile.availableForWrite(); + if (chunkSize && dataBuffer.length() >= chunkSize) { // write to file and blink LED digitalWrite(LED_BUILTIN, HIGH); - txtFile.write(buffer.c_str(), chunkSize); + myFile.write(dataBuffer.c_str(), chunkSize); digitalWrite(LED_BUILTIN, LOW); - - // remove written data from buffer - buffer.remove(0, chunkSize); + // remove written data from dataBuffer + dataBuffer.remove(0, chunkSize); } } diff --git a/examples/ReadWrite/ReadWrite.ino b/examples/ReadWrite/ReadWrite.ino index 1a9ba66..c15ecdb 100644 --- a/examples/ReadWrite/ReadWrite.ino +++ b/examples/ReadWrite/ReadWrite.ino @@ -2,44 +2,42 @@ SD card read/write This example shows how to read and write data to and from an SD card file - The circuit: + The circuit. Pin numbers reflect the default + SPI pins for Uno and Nano models: SD card attached to SPI bus as follows: - ** MOSI - pin 11 - ** MISO - pin 12 + ** SDO - pin 11 + ** SDI - pin 12 ** CLK - pin 13 - ** CS - pin 4 (for MKRZero SD: SDCARD_SS_PIN) + ** CS - pin 4 (For For Uno, Nano: pin 10. For MKRZero SD: SDCARD_SS_PIN) created Nov 2010 by David A. Mellis - modified 9 Apr 2012 + modified 24 July 2020 by Tom Igoe This example code is in the public domain. */ - -#include #include +const int chipSelect = 10; File myFile; void setup() { // Open serial communications and wait for port to open: Serial.begin(9600); - while (!Serial) { - ; // wait for serial port to connect. Needed for native USB port only - } - + // wait for Serial Monitor to connect. Needed for native USB port boards only: + while (!Serial); Serial.print("Initializing SD card..."); - if (!SD.begin(4)) { + if (!SD.begin(chipSelect)) { Serial.println("initialization failed. Things to check:"); Serial.println("1. is a card inserted?"); Serial.println("2. is your wiring correct?"); Serial.println("3. did you change the chipSelect pin to match your shield or module?"); Serial.println("Note: press reset or reopen this serial monitor after fixing your issue!"); - while (1); + while (true); } Serial.println("initialization done."); @@ -80,5 +78,3 @@ void setup() { void loop() { // nothing happens after setup } - - diff --git a/examples/listfiles/listfiles.ino b/examples/listfiles/listfiles.ino index 48f84fb..66eebb6 100644 --- a/examples/listfiles/listfiles.ino +++ b/examples/listfiles/listfiles.ino @@ -2,14 +2,17 @@ Listfiles This example shows how print out the files in a - directory on a SD card + directory on a SD card.Pin numbers reflect the default + SPI pins for Uno and Nano models The circuit: SD card attached to SPI bus as follows: - ** MOSI - pin 11 - ** MISO - pin 12 + ** SDO - pin 11 + ** SDI - pin 12 ** CLK - pin 13 - ** CS - pin 4 (for MKRZero SD: SDCARD_SS_PIN) + ** CS - depends on your SD card shield or module. + Pin 10 used here for consistency with other Arduino examples + (for MKRZero SD: SDCARD_SS_PIN) created Nov 2010 by David A. Mellis @@ -17,28 +20,34 @@ by Tom Igoe modified 2 Feb 2014 by Scott Fitzgerald - + modified 24 July 2020 + by Tom Igoe + This example code is in the public domain. */ -#include #include +const int chipSelect = 10; File root; void setup() { - // Open serial communications and wait for port to open: + // Open serial communications and wait for port to open: Serial.begin(9600); - while (!Serial) { - ; // wait for serial port to connect. Needed for native USB port only - } + // wait for Serial Monitor to connect. Needed for native USB port boards only: + while (!Serial); Serial.print("Initializing SD card..."); - if (!SD.begin(4)) { - Serial.println("initialization failed!"); - while (1); + if (!SD.begin(chipSelect)) { + Serial.println("initialization failed. Things to check:"); + Serial.println("1. is a card inserted?"); + Serial.println("2. is your wiring correct?"); + Serial.println("3. did you change the chipSelect pin to match your shield or module?"); + Serial.println("Note: press reset or reopen this serial monitor after fixing your issue!"); + while (true); } + Serial.println("initialization done."); root = SD.open("/"); @@ -75,6 +84,3 @@ void printDirectory(File dir, int numTabs) { entry.close(); } } - - -