SD_MMC update (#8298)

* Updated SD_MMC lib and examples

* Removed getter implementation and commented usage in examples

* squashed updates

Author: PilnyTomas

libraries/SD/examples/SD_Test/SD_Test.ino

@@ -1,21 +1,56 @@
 /*
- * Connect the SD card to the following pins:
+ * pin 1 - not used          |  Micro SD card     |
+ * pin 2 - CS (SS)           |                   /
+ * pin 3 - DI (MOSI)         |                  |__
+ * pin 4 - VDD (3.3V)        |                    |
+ * pin 5 - SCK (SCLK)        | 8 7 6 5 4 3 2 1   /
+ * pin 6 - VSS (GND)         | ▄ ▄ ▄ ▄ ▄ ▄ ▄ ▄  /
+ * pin 7 - DO (MISO)         | ▀ ▀ █ ▀ █ ▀ ▀ ▀ |
+ * pin 8 - not used          |_________________|
+ *                             ║ ║ ║ ║ ║ ║ ║ ║
+ *                     ╔═══════╝ ║ ║ ║ ║ ║ ║ ╚═════════╗
+ *                     ║         ║ ║ ║ ║ ║ ╚══════╗    ║
+ *                     ║   ╔═════╝ ║ ║ ║ ╚═════╗  ║    ║
+ * Connections for     ║   ║   ╔═══╩═║═║═══╗   ║  ║    ║
+ * full-sized          ║   ║   ║   ╔═╝ ║   ║   ║  ║    ║
+ * SD card             ║   ║   ║   ║   ║   ║   ║  ║    ║
+ * Pin name         |  -  DO  VSS SCK VDD VSS DI CS    -  |
+ * SD pin number    |  8   7   6   5   4   3   2   1   9 /
+ *                  |                                  █/
+ *                  |__▍___▊___█___█___█___█___█___█___/
  *
- * SD Card | ESP32
- *    D2       -
- *    D3       SS
- *    CMD      MOSI
- *    VSS      GND
- *    VDD      3.3V
- *    CLK      SCK
- *    VSS      GND
- *    D0       MISO
- *    D1       -
+ * Note:  The SPI pins can be manually configured by using `SPI.begin(sck, miso, mosi, cs).`
+ *        Alternatively, you can change the CS pin and use the other default settings by using `SD.begin(cs)`.
+ *
+ * +--------------+---------+-------+----------+----------+----------+
+ * | SPI Pin Name | ESP8266 | ESP32 | ESP32-S2 | ESP32-C3 | ESP32-S3 |
+ * +==============+=========+=======+==========+==========+==========+
+ * | CS (SS)      | GPIO15  | GPIO5 | GPIO5    | GPIO13   | GPIO13   |
+ * +--------------+---------+-------+----------+----------+----------+
+ * | DI (MOSI)    | GPIO13  | GPIO23| GPIO24   | GPIO14   | GPIO14   |
+ * +--------------+---------+-------+----------+----------+----------+
+ * | DO (MISO)    | GPIO12  | GPIO19| GPIO25   | GPIO15   | GPIO15   |
+ * +--------------+---------+-------+----------+----------+----------+
+ * | SCK (SCLK)   | GPIO14  | GPIO18| GPIO19   | GPIO16   | GPIO16   |
+ * +--------------+---------+-------+----------+----------+----------+
+ *
+ * For more info see file README.md in this library or on URL:
+ * https://github.com/espressif/arduino-esp32/tree/master/libraries/SD
  */
+
 #include "FS.h"
 #include "SD.h"
 #include "SPI.h"
 
+/*
+Uncomment and set up if you want to use custom pins for the SPI communication
+#define REASSIGN_PINS
+int sck = -1;
+int miso = -1;
+int mosi = -1;
+int cs = -1;
+*/
+
 void listDir(fs::FS &fs, const char * dirname, uint8_t levels){
     Serial.printf("Listing directory: %s\n", dirname);
 
@@ -175,6 +210,12 @@ void testFileIO(fs::FS &fs, const char * path){
 
 void setup(){
     Serial.begin(115200);
+    while(!Serial) { delay (10); }
+
+#ifdef REASSIGN_PINS
+    SPI.begin(sck, miso, mosi, cs);
+#endif
+    //if(!SD.begin(cs)){ //Change to this function to manually change CS pin
     if(!SD.begin()){
         Serial.println("Card Mount Failed");
         return;

libraries/SD/examples/SD_time/SD_time.ino

@@ -1,16 +1,41 @@
 /*
- * Connect the SD card to the following pins:
+ * pin 1 - not used          |  Micro SD card     |
+ * pin 2 - CS (SS)           |                   /
+ * pin 3 - DI (MOSI)         |                  |__
+ * pin 4 - VDD (3.3V)        |                    |
+ * pin 5 - SCK (SCLK)        | 8 7 6 5 4 3 2 1   /
+ * pin 6 - VSS (GND)         | ▄ ▄ ▄ ▄ ▄ ▄ ▄ ▄  /
+ * pin 7 - DO (MISO)         | ▀ ▀ █ ▀ █ ▀ ▀ ▀ |
+ * pin 8 - not used          |_________________|
+ *                             ║ ║ ║ ║ ║ ║ ║ ║
+ *                     ╔═══════╝ ║ ║ ║ ║ ║ ║ ╚═════════╗
+ *                     ║         ║ ║ ║ ║ ║ ╚══════╗    ║
+ *                     ║   ╔═════╝ ║ ║ ║ ╚═════╗  ║    ║
+ * Connections for     ║   ║   ╔═══╩═║═║═══╗   ║  ║    ║
+ * full-sized          ║   ║   ║   ╔═╝ ║   ║   ║  ║    ║
+ * SD card             ║   ║   ║   ║   ║   ║   ║  ║    ║
+ * Pin name         |  -  DO  VSS SCK VDD VSS DI CS    -  |
+ * SD pin number    |  8   7   6   5   4   3   2   1   9 /
+ *                  |                                  █/
+ *                  |__▍___▊___█___█___█___█___█___█___/
  *
- * SD Card | ESP32
- *    D2       -
- *    D3       SS
- *    CMD      MOSI
- *    VSS      GND
- *    VDD      3.3V
- *    CLK      SCK
- *    VSS      GND
- *    D0       MISO
- *    D1       -
+ * Note:  The SPI pins can be manually configured by using `SPI.begin(sck, miso, mosi, cs);`.
+ *        Alternatively you can change only the CS pin with `SD.begin(CSpin)` and keep the default settings for other pins.
+ *
+ * +--------------+---------+-------+----------+----------+----------+
+ * | SPI Pin Name | ESP8266 | ESP32 | ESP32-S2 | ESP32-C3 | ESP32-S3 |
+ * +==============+=========+=======+==========+==========+==========+
+ * | CS (SS)      | GPIO15  | GPIO5 | GPIO5    | GPIO13   | GPIO13   |
+ * +--------------+---------+-------+----------+----------+----------+
+ * | DI (MOSI)    | GPIO13  | GPIO23| GPIO24   | GPIO14   | GPIO14   |
+ * +--------------+---------+-------+----------+----------+----------+
+ * | DO (MISO)    | GPIO12  | GPIO19| GPIO25   | GPIO15   | GPIO15   |
+ * +--------------+---------+-------+----------+----------+----------+
+ * | SCK (SCLK)   | GPIO14  | GPIO18| GPIO19   | GPIO16   | GPIO16   |
+ * +--------------+---------+-------+----------+----------+----------+
+ *
+ * For more info see file README.md in this library or on URL:
+ * https://github.com/espressif/arduino-esp32/tree/master/libraries/SD
  */
 
 #include "FS.h"
@@ -25,6 +50,15 @@ const char* password = "your-password";
 long timezone = 1; 
 byte daysavetime = 1;
 
+/*
+Uncomment and setup pins you want to use for the SPI communication
+#define REASSIGN_PINS
+int sck = -1;
+int miso = -1;
+int mosi = -1;
+int cs = -1;
+*/
+
 void listDir(fs::FS &fs, const char * dirname, uint8_t levels){
     Serial.printf("Listing directory: %s\n", dirname);
 
@@ -172,6 +206,10 @@ void setup(){
 	Serial.printf("\nNow is : %d-%02d-%02d %02d:%02d:%02d\n",(tmstruct.tm_year)+1900,( tmstruct.tm_mon)+1, tmstruct.tm_mday,tmstruct.tm_hour , tmstruct.tm_min, tmstruct.tm_sec);
     Serial.println("");
 
+#ifdef REASSIGN_PINS
+    SPI.begin(sck, miso, mosi, cs);
+#endif
+    //if(!SD.begin(cs)){ //Change to this function to manually change CS pin
     if(!SD.begin()){
         Serial.println("Card Mount Failed");
         return;

libraries/SD_MMC/examples/SDMMC_Test/SDMMC_Test.ino

@@ -1,21 +1,59 @@
 /*
- * Connect the SD card to the following pins:
+ * pin 1 - D2                |  Micro SD card     |
+ * pin 2 - D3                |                   /
+ * pin 3 - CMD               |                  |__
+ * pin 4 - VDD (3.3V)        |                    |
+ * pin 5 - CLK               | 8 7 6 5 4 3 2 1   /
+ * pin 6 - VSS (GND)         | ▄ ▄ ▄ ▄ ▄ ▄ ▄ ▄  /
+ * pin 7 - D0                | ▀ ▀ █ ▀ █ ▀ ▀ ▀ |
+ * pin 8 - D1                |_________________|
+ *                             ║ ║ ║ ║ ║ ║ ║ ║
+ *                     ╔═══════╝ ║ ║ ║ ║ ║ ║ ╚═════════╗
+ *                     ║         ║ ║ ║ ║ ║ ╚══════╗    ║
+ *                     ║   ╔═════╝ ║ ║ ║ ╚═════╗  ║    ║
+ * Connections for     ║   ║   ╔═══╩═║═║═══╗   ║  ║    ║
+ * full-sized          ║   ║   ║   ╔═╝ ║   ║   ║  ║    ║
+ * SD card             ║   ║   ║   ║   ║   ║   ║  ║    ║
+ * ESP32-S3 DevKit  | 21  47  GND  39 3V3 GND  40 41  42  |
+ * ESP32-S3-USB-OTG | 38  37  GND  36 3V3 GND  35 34  33  |
+ * ESP32            |  4   2  GND  14 3V3 GND  15 13  12  |
+ * Pin name         | D1  D0  VSS CLK VDD VSS CMD D3  D2  |
+ * SD pin number    |  8   7   6   5   4   3   2   1   9 /
+ *                  |                                  █/
+ *                  |__▍___▊___█___█___█___█___█___█___/
+ * WARNING: ALL data pins must be pulled up to 3.3V with an external 10k Ohm resistor!
+ * Note to ESP32 pin 2 (D0): Add a 1K Ohm pull-up resistor to 3.3V after flashing
  *
- * SD Card | ESP32
- *    D2       12
- *    D3       13
- *    CMD      15
- *    VSS      GND
- *    VDD      3.3V
- *    CLK      14
- *    VSS      GND
- *    D0       2  (add 1K pull up after flashing)
- *    D1       4
+ * For more info see file README.md in this library or on URL:
+ * https://github.com/espressif/arduino-esp32/tree/master/libraries/SD_MMC
  */
 
 #include "FS.h"
 #include "SD_MMC.h"
 
+// Default pins for ESP-S3
+// Warning: ESP32-S3-WROOM-2 is using most of the default SD_MMC GPIOs (33-37) to interface with the on-board OPI flash.
+//   If the SD_MMC is initialized with the default pins it will result in rebooting loop.
+//   Please reassign the pins elsewhere using the mentioned command `setPins`.
+// Note: ESP32-S3-WROOM-1 does not have GPIO 33 and 34 broken out.
+// Note: The board ESP32-S3-USB-OTG has predefined default pins and the following definitions with the setPins() call will not be compiled.
+// Note: Pins in this definition block are ordered from top down in order in which they are on the full-sized SD card
+//   from left to right when facing the pins down (when connected to a breadboard)
+
+#if defined(SOC_SDMMC_USE_GPIO_MATRIX) && not defined(BOARD_HAS_SDMMC)
+    int d1  = 21; // SD pin 8 - Add a 10k Ohm pull-up resistor to 3.3V if using 4-bit mode (use_1_bit_mode = false)
+    int d0  = 47; // SD pin 7 - Add a 10k Ohm pull-up resistor to 3.3V
+    //     GND pin - SD pin 6
+    int clk = 39; // SD pin 5 - Add a 10k Ohm pull-up resistor to 3.3V
+    //    3.3V pin - SD pin 4
+    //     GND pin - SD pin 3
+    int cmd = 40; // SD pin 2 - Add a 10k Ohm pull-up resistor to 3.3V
+    int d3  = 41; // SD pin 1 - Add a 10k Ohm pull-up resistor to 3.3V to card's pin even when using 1-bit mode
+    int d2  = 42; // SD pin 9 - Add a 10k Ohm pull-up resistor to 3.3V if using 4-bit mode (use_1_bit_mode = false)
+#endif
+
+bool use_1_bit_mode = false; // Change the value to `true` to use 1-bit mode instead of the 4-bit mode
+
 void listDir(fs::FS &fs, const char * dirname, uint8_t levels){
     Serial.printf("Listing directory: %s\n", dirname);
 
@@ -172,8 +210,28 @@ void testFileIO(fs::FS &fs, const char * path){
 
 void setup(){
     Serial.begin(115200);
-    if(!SD_MMC.begin()){
-        Serial.println("Card Mount Failed");
+    while(!Serial) { delay(10); }
+    Serial.println("SDMMC_Test.ino starting!");
+
+    // If you are using any other ESP32-S3 board than ESP32-S3-USB-OTG which has preset default pins, you will
+    // need to specify the pins with the following example of SD_MMC.setPins()
+    // If you want to use only 1-bit mode, you can use the line with only one data pin (d0) begin changed.
+    // Please note that ESP32 does not allow pin changes and will fail unless you enter the same pin config as is the hardwired.
+#if defined(SOC_SDMMC_USE_GPIO_MATRIX) && not defined(BOARD_HAS_SDMMC)
+    //if(! SD_MMC.setPins(clk, cmd, d0)){ // 1-bit line version
+    if(! SD_MMC.setPins(clk, cmd, d0, d1, d2, d3)){ // 4-bit line version
+        Serial.println("Pin change failed!");
+        return;
+    }
+#endif
+
+    if(!SD_MMC.begin("/sdcard", use_1_bit_mode)){
+        Serial.println("Card Mount Failed.");
+        Serial.println("Increase log level to see more info: Tools > Core Debug Level > Verbose");
+        Serial.println("Make sure that all data pins have a 10k Ohm pull-up resistor to 3.3V");
+#ifdef SOC_SDMMC_USE_GPIO_MATRIX
+        Serial.println("Make sure that when using generic ESP32-S3 board the pins are setup using SD_MMC.setPins()");
+#endif
         return;
     }
     uint8_t cardType = SD_MMC.cardType();

libraries/SD_MMC/examples/SDMMC_time/SDMMC_time.ino

@@ -1,16 +1,31 @@
 /*
- * Connect the SD card to the following pins:
+ * pin 1 - D2                |  Micro SD card     |
+ * pin 2 - D3                |                   /
+ * pin 3 - CMD               |                  |__
+ * pin 4 - VDD (3.3V)        |                    |
+ * pin 5 - CLK               | 8 7 6 5 4 3 2 1   /
+ * pin 6 - VSS (GND)         | ▄ ▄ ▄ ▄ ▄ ▄ ▄ ▄  /
+ * pin 7 - D0                | ▀ ▀ █ ▀ █ ▀ ▀ ▀ |
+ * pin 8 - D1                |_________________|
+ *                             ║ ║ ║ ║ ║ ║ ║ ║
+ *                     ╔═══════╝ ║ ║ ║ ║ ║ ║ ╚═════════╗
+ *                     ║         ║ ║ ║ ║ ║ ╚══════╗    ║
+ *                     ║   ╔═════╝ ║ ║ ║ ╚═════╗  ║    ║
+ * Connections for     ║   ║   ╔═══╩═║═║═══╗   ║  ║    ║
+ * full-sized          ║   ║   ║   ╔═╝ ║   ║   ║  ║    ║
+ * SD card             ║   ║   ║   ║   ║   ║   ║  ║    ║
+ * ESP32-S3 DevKit  | 21  47  GND  39 3V3 GND  40 41  42  |
+ * ESP32-S3-USB-OTG | 38  37  GND  36 3V3 GND  35 34  33  |
+ * ESP32            |  4   2  GND  14 3V3 GND  15 13  12  |
+ * Pin name         | D1  D0  VSS CLK VDD VSS CMD D3  D2  |
+ * SD pin number    |  8   7   6   5   4   3   2   1   9 /
+ *                  |                                  █/
+ *                  |__▍___▊___█___█___█___█___█___█___/
+ * WARNING: ALL data pins must be pulled up to 3.3V with external 10k Ohm resistor!
+ * Note to ESP32 pin 2 (D0): Add 1K Ohm pull-up resistor to 3.3V after flashing
  *
- * SD Card | ESP32
- *    D2       -
- *    D3       SS
- *    CMD      MOSI
- *    VSS      GND
- *    VDD      3.3V
- *    CLK      SCK
- *    VSS      GND
- *    D0       MISO
- *    D1       -
+ * For more info see file README.md in this library or on URL:
+ * https://github.com/espressif/arduino-esp32/tree/master/libraries/SD_MMC
  */
 
 #include "FS.h"
@@ -25,6 +40,29 @@ const char* password = "your-password";
 long timezone = 1; 
 byte daysavetime = 1;
 
+// Default pins for ESP-S3
+// Warning: ESP32-S3-WROOM-2 is using most of the default SD_MMC GPIOs (33-37) to interface with on-board OPI flash.
+//   If the SD_MMC is initialized with default pins it will result in rebooting loop - please
+//   reassign the pins elsewhere using the mentioned command `setPins`.
+// Note: ESP32-S3-WROOM-1 does not have GPIO 33 and 34 broken out.
+// Note: The board ESP32-S3-USB-OTG has predefined default pins and the following definitions with the setPins() call will not be compiled.
+// Note: Pins in this definition block are ordered from top down in order in which they are on the full-sized SD card
+//   from left to right when facing the pins down (when connected to a breadboard)
+
+#if defined(SOC_SDMMC_USE_GPIO_MATRIX) && not defined(BOARD_HAS_SDMMC)
+    int d1  = 21; // SD pin 8 - Add a 10k Ohm pull-up resistor to 3.3V if using 4-bit mode (use_1_bit_mode = false)
+    int d0  = 47; // SD pin 7 - Add a 10k Ohm pull-up resistor to 3.3V
+    //     GND pin - SD pin 6
+    int clk = 39; // SD pin 5 - Add a 10k Ohm pull-up resistor to 3.3V
+    //    3.3V pin - SD pin 4
+    //     GND pin - SD pin 3
+    int cmd = 40; // SD pin 2 - Add a 10k Ohm pull-up resistor to 3.3V
+    int d3  = 41; // SD pin 1 - Add a 10k Ohm pull-up resistor to 3.3V to card's pin even when using 1-bit mode
+    int d2  = 42; // SD pin 9 - Add a 10k Ohm pull-up resistor to 3.3V if using 4-bit mode (use_1_bit_mode = false)
+#endif
+
+bool use_1_bit_mode = false; // Change the value to `true` to use 1-bit mode instead of the 4-bit mode
+
 void listDir(fs::FS &fs, const char * dirname, uint8_t levels){
     Serial.printf("Listing directory: %s\n", dirname);
 
@@ -164,16 +202,39 @@ void setup(){
     Serial.println("IP address: ");
     Serial.println(WiFi.localIP());
     Serial.println("Contacting Time Server");
-	configTime(3600*timezone, daysavetime*3600, "time.nist.gov", "0.pool.ntp.org", "1.pool.ntp.org");
-	struct tm tmstruct ;
+    configTime(3600*timezone, daysavetime*3600, "time.nist.gov", "0.pool.ntp.org", "1.pool.ntp.org");
+    struct tm tmstruct ;
     delay(2000);
     tmstruct.tm_year = 0;
     getLocalTime(&tmstruct, 5000);
-	Serial.printf("\nNow is : %d-%02d-%02d %02d:%02d:%02d\n",(tmstruct.tm_year)+1900,( tmstruct.tm_mon)+1, tmstruct.tm_mday,tmstruct.tm_hour , tmstruct.tm_min, tmstruct.tm_sec);
+    Serial.printf("\nNow is : %d-%02d-%02d %02d:%02d:%02d\n",(tmstruct.tm_year)+1900,( tmstruct.tm_mon)+1, tmstruct.tm_mday,tmstruct.tm_hour , tmstruct.tm_min, tmstruct.tm_sec);
     Serial.println("");
 
-    if(!SD_MMC.begin()){
-        Serial.println("Card Mount Failed");
+    // If you are using any other ESP32-S3 board than ESP32-S3-USB-OTG which has preset default pins, you will
+    // need to specify the pins with the following example of SD_MMC.setPins()
+    // If you want to use only 1-bit mode, you can use the line with only one data pin (d0) begin changed.
+    // Please note that ESP32 does not allow pin changes and will fail unless you enter the same pin config as is the hardwired.
+#if defined(SOC_SDMMC_USE_GPIO_MATRIX) && not defined(BOARD_HAS_SDMMC)
+    if(use_1_bit_mode){
+      if(! SD_MMC.setPins(clk, cmd, d0)){ // 1-bit line version
+        Serial.println("Pin change failed!");
+        return;
+      }
+    } else {
+      if(! SD_MMC.setPins(clk, cmd, d0, d1, d2, d3)){ // 4-bit line version
+        Serial.println("Pin change failed!");
+        return;
+      }
+    }
+#endif
+
+    if(!SD_MMC.begin("/sdcard", use_1_bit_mode)){
+        Serial.println("Card Mount Failed.");
+        Serial.println("Increase log level to see more info: Tools > Core Debug Level > Verbose");
+        Serial.println("Make sure that all data pins have a 10k Ohm pull-up resistor to 3.3V");
+#ifdef SOC_SDMMC_USE_GPIO_MATRIX
+        Serial.println("Make sure that when using generic ESP32-S3 board the pins are setup using SD_MMC.setPins()");
+#endif
         return;
     }
     uint8_t cardType = SD_MMC.cardType();
@@ -203,7 +264,7 @@ void setup(){
     deleteFile(SD_MMC, "/hello.txt");
     writeFile(SD_MMC, "/hello.txt", "Hello ");
     appendFile(SD_MMC, "/hello.txt", "World!\n");
-	listDir(SD_MMC, "/", 0);
+    listDir(SD_MMC, "/", 0);
 }
 
 void loop(){