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/)

Author: tigoe

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:

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 <SPI.h>
 #include <SD.h>
 
-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");
   }
 }
-
-
-
-
-
-
-
-
-

examples/DumpFile/DumpFile.ino

@@ -3,45 +3,46 @@
 
   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
   modified 9 Apr 2012
   by Tom Igoe
 
   This example code is in the public domain.
-
 */
-
-#include <SPI.h>
 #include <SD.h>
 
-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() {
 }
-

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 <SPI.h>
 #include <SD.h>
 
+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.
 }
-
-
-

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 <SD.h>
 
+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);
   }
 }