From bb8756114095d8f86b9947e60fe2c00c69ca2bfe Mon Sep 17 00:00:00 2001 From: Tomas Pilny Date: Wed, 3 May 2023 09:32:25 +0200 Subject: [PATCH 01/16] Updated preferences.rst --- docs/source/tutorials/preferences.rst | 49 +++++++++++++++++---------- 1 file changed, 31 insertions(+), 18 deletions(-) diff --git a/docs/source/tutorials/preferences.rst b/docs/source/tutorials/preferences.rst index eb0397af543..3cb54f1928c 100644 --- a/docs/source/tutorials/preferences.rst +++ b/docs/source/tutorials/preferences.rst @@ -233,9 +233,9 @@ Like so: .. code-block:: arduino - String myString = myPreferences.getString("myStringKey"); + float myFloat = myPreferences.getFloat("pi"); -This will retrieve the String value from the namespace key ``"myStringKey"`` and assign it to the String type variable ``myString``. +This will retrieve the float value from the namespace key ``"pi"`` and assign it to the float type variable ``myFloat``. Summary @@ -277,9 +277,10 @@ When started, the system has no way of knowing which of the above conditions is // not the complete setup(), but in setup(), include this... stcPrefs.begin("STCPrefs", RO_MODE); // Open our namespace (or create it - // if it doesn't exist) in in RO mode. + // if it doesn't exist) in RO mode. - bool tpInit = stcPrefs.isKey("nvsInit"); // Test for the existence of the "already initialized" key. + bool tpInit = stcPrefs.isKey("nvsInit"); // Test for the existence + // of the "already initialized" key. if (tpInit == false) { // If tpInit is 'false', the key "nvsInit" does not yet exist therefore this @@ -289,13 +290,15 @@ When started, the system has no way of knowing which of the above conditions is // The .begin() method created the "STCPrefs" namespace and since this is our - // first-time run we will create our keys and store the initial "factory default" values. + // first-time run we will create + // our keys and store the initial "factory default" values. stcPrefs.putUChar("curBright", 10); stcPrefs.putString("talChan", "one"); stcPrefs.putLong("talMax", -220226); stcPrefs.putBool("ctMde", true); - stcPrefs.putBool("nvsInit", true); // Create the "already initialized" key and store a value. + stcPrefs.putBool("nvsInit", true); // Create the "already initialized" + // key and store a value. // The "factory defaults" are created and stored so... stcPrefs.end(); // Close the namespace in RW mode and... @@ -456,10 +459,12 @@ This is best explained with an example. Here the ``Bytes`` methods are used to s Serial.begin(115200); delay(250); - mySketchPrefs.begin("myPrefs", RW_MODE); // open (or create) the namespace "myPrefs" in RW mode + mySketchPrefs.begin("myPrefs", RW_MODE); // open (or create) the namespace + // "myPrefs" in RW mode mySketchPrefs.clear(); // delete any previous keys in this namespace - // Create an array of test values. We're using hex numbers throughout to better show how the bytes move around. + // Create an array of test values. We're using hex numbers + // throughout to better show how the bytes move around. int16_t myArray[] = { 0x1112, 0x2122, 0x3132, 0x4142, 0x5152, 0x6162, 0x7172 }; Serial.println("Printing myArray..."); @@ -468,22 +473,28 @@ This is best explained with an example. Here the ``Bytes`` methods are used to s } Serial.println("\r\n"); - // In the next statement, the second sizeof() needs to match the data type of the elements of myArray - Serial.print("The number of elements in myArray is: "); Serial.println( sizeof(myArray) / sizeof(int16_t) ); - Serial.print("But the size of myArray in bytes is: "); Serial.println( sizeof(myArray) ); + // In the next statement, the second sizeof() needs + // to match the data type of the elements of myArray + Serial.print("The number of elements in myArray is: "); + Serial.println( sizeof(myArray) / sizeof(int16_t) ); + Serial.print("But the size of myArray in bytes is: "); + Serial.println( sizeof(myArray) ); Serial.println(""); - Serial.println("Storing myArray into the Preferences namespace \"myPrefs\" against the key \"myPrefsBytes\"."); + Serial.println( + "Storing myArray into the Preferences namespace \"myPrefs\" against the key \"myPrefsBytes\"."); // Note: in the next statement, to store the entire array, we must use the // size of the arrray in bytes, not the number of elements in the array. mySketchPrefs.putBytes( "myPrefsBytes", myArray, sizeof(myArray) ); - Serial.print("The size of \"myPrefsBytes\" is (in bytes): "); Serial.println( mySketchPrefs.getBytesLength("myPrefsBytes") ); + Serial.print("The size of \"myPrefsBytes\" is (in bytes): "); + Serial.println( mySketchPrefs.getBytesLength("myPrefsBytes") ); Serial.println(""); - int16_t myIntBuffer[20] = {}; // No magic about 20. Just making a buffer (array) big enough. + int16_t myIntBuffer[20] = {}; // No magic about 20. Just making a buffer (array) big enough. Serial.println("Retrieving the value of myPrefsBytes into myIntBuffer."); Serial.println(" - Note the data type of myIntBuffer matches that of myArray"); - mySketchPrefs.getBytes( "myPrefsBytes", myIntBuffer, mySketchPrefs.getBytesLength("myPrefsBytes") ); + mySketchPrefs.getBytes("myPrefsBytes", myIntBuffer, + mySketchPrefs.getBytesLength("myPrefsBytes")); Serial.println("Printing myIntBuffer..."); // In the next statement, sizeof() needs to match the data type of the elements of myArray @@ -492,9 +503,11 @@ This is best explained with an example. Here the ``Bytes`` methods are used to s } Serial.println("\r\n"); - Serial.println("We can see how the data from myArray is actually stored in the namespace as follows."); - uint8_t myByteBuffer[40] = {}; // No magic about 40. Just making a buffer (array) big enough. - mySketchPrefs.getBytes( "myPrefsBytes", myByteBuffer, mySketchPrefs.getBytesLength("myPrefsBytes") ); + Serial.println( + "We can see how the data from myArray is actually stored in the namespace as follows."); + uint8_t myByteBuffer[40] = {}; // No magic about 40. Just making a buffer (array) big enough. + mySketchPrefs.getBytes("myPrefsBytes", myByteBuffer, + mySketchPrefs.getBytesLength("myPrefsBytes")); Serial.println("Printing myByteBuffer..."); for (int i = 0; i < mySketchPrefs.getBytesLength("myPrefsBytes"); i++) { From b8bae5f9d8740b831d52f4b6c70e73c36322b9a4 Mon Sep 17 00:00:00 2001 From: Tomas Pilny Date: Wed, 3 May 2023 09:32:56 +0200 Subject: [PATCH 02/16] Added into FAQ info about SPIFFS failed mount --- docs/source/faq.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/source/faq.rst b/docs/source/faq.rst index 97520b35673..6af19fc804f 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -15,3 +15,20 @@ How to compile libs with different debug level? ----------------------------------------------- The short answer is ``esp32-arduino-lib-builder/configs/defconfig.common:44``. A guide explaining the process can be found here + +SPIFFS mount failed +------------------- +When you come across and error like this: + +.. code-block:: shell + + E (588) SPIFFS: mount failed, -10025 + [E][SPIFFS.cpp:47] begin(): Mounting SPIFFS failed! Error: -1 + +Try enforcing format on fail in your code by adding ``true`` in the ``begin`` method such as this: + +.. code-block:: c++ + + SPIFFS.begin(true); + +See the method prototype for reference: ``bool begin(bool formatOnFail=false, const char * basePath="/spiffs", uint8_t maxOpenFiles=10, const char * partitionLabel=NULL);`` \ No newline at end of file From ade126537ec59704a3b37882a846081607f13992 Mon Sep 17 00:00:00 2001 From: Tomas Pilny Date: Tue, 23 May 2023 17:08:05 +0200 Subject: [PATCH 03/16] Updated troubleshooting --- docs/source/troubleshooting.rst | 81 +++++++++++++++++++++++++++++++-- 1 file changed, 78 insertions(+), 3 deletions(-) diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst index 40e0a632b39..4aee53f9786 100644 --- a/docs/source/troubleshooting.rst +++ b/docs/source/troubleshooting.rst @@ -56,11 +56,15 @@ Solution Here are some steps that you can try to: -* Check your USB cable and try a new one. -* Change the USB port. +* Check your USB cable and try a new one (some cables are only for charging and there is no data connection). +* Change the USB port - prefer direct connection to computer and avoid USB hubs. Some USB ports may share power source with other ports used for example for charging phone. * Check your power supply. +* Make sure that nothing is connected to pins labeled **TX** and **RX**. * In some instances, you must keep **GPIO0** LOW during the uploading process via the serial interface. * Hold down the **“BOOT”** button in your ESP32 board while uploading/flashing. +* Solder a **10uF** capacitor in parallel with **RST** and **GND**. +* If you bought your dev board from questionable seller they might have scammed you and send ESP8266 instead of ESP32. +* If you are using external power connected to pins it is easy to confuse pins **CMD** (which is usually next to the 5V pin) and **GND**. In some development boards, you can try adding the reset delay circuit, as described in the *Power-on Sequence* section on the `ESP32 Hardware Design Guidelines `_ in order to get into the download mode automatically. @@ -68,7 +72,7 @@ Hardware -------- Why is my computer not detecting my board? -************************************************** +****************************************** If your board is not being detected after connecting to the USB, you can try to: @@ -119,3 +123,74 @@ Sample code to check SDK WPA3 support at compile time: #ifndef CONFIG_ESP32_WIFI_ENABLE_WPA3_SAE #warning "No WPA3 support." #endif + +ESP32-S3 is rebooting even with bare minimum sketch +*************************************************** +Some ESP32-S3 are equipped with Quad SPI (QSPI) or Octal SPI (OPI) PSRAM and if you upload such board with default settings for ESP32-S3 it will result in rebooting with message similar to this: + +https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/flash_psram_config.html + +.. code-block:: bash + + E (124) esp_core_dump_flash: Core dump flash config is corrupted! CRC=0x7bd5c66f instead of 0x0 + Rebooting... + ⸮⸮⸮ESP-ROM:esp32s3-20210327 + Build:Mar 27 2021 + rst:0xc (RTC_SW_CPU_RST),boot:0x18 (SPI_FAST_FLASH_BOOT) + Saved PC:0x40376af0 + SPIWP:0xee + Octal Flash Mode Enabled + For OPI Flash, Use Default Flash Boot Mode + mode:SLOW_RD, clock div:1 + load:0x3fce3808,len:0x44c + load:0x403c9700,len:0xbec + load:0x403cc700,len:0x2920 + entry 0x403c98d8 + + assert failed: do_core_init startup.c:326 (flash_ret == ESP_OK) + +To fix the issue, you will need to find out the precise module you are using and set **PSRAM** in the Arduino IDE Tools according to the following table. + +How to determine the module version: +------------------------------------ + +* First determine if you have a `WROOM-1 `_ or `WROOM-2 `_ module - this is written on the module shielding almost at the top, right under the ESP logo and company name (Espresif) right after the ESP32-S3 - for example ESP32-S3-WROOM-2. +* Then locate the version code on left bottom corner on the module shielding. The markings are very small and it might be really difficult to read with naked eyes - try using a camera with careful lighting. + +With this knowledge find your module in the table and note what is written in the **PSRAM** column. + +- If the results is empty (-) you don't need to change anything +- For QSPI go to Tools > PSRAM > QSPI PSRAM +- For OPI go to Tools > PSRAM > OPI PSRAM + +Note that WROOM-2 has always OPI. + ++---------+--------+------------+-------+ +| Module | Code | Flash Mode | PSRAM | ++=========+========+============+=======+ +| WROOM-1 | N4 | QSPI | - | ++---------+--------+------------+-------+ +| WROOM-1 | N8 | QSPI | - | ++---------+--------+------------+-------+ +| WROOM-1 | N16 | QSPI | - | ++---------+--------+------------+-------+ +| WROOM-1 | H4 | QSPI | - | ++---------+--------+------------+-------+ +| WROOM-1 | N4R2 | QSPI | QSPI | ++---------+--------+------------+-------+ +| WROOM-1 | N8R2 | QSPI | QSPI | ++---------+--------+------------+-------+ +| WROOM-1 | N16R2 | QSPI | QSPI | ++---------+--------+------------+-------+ +| WROOM-1 | N4R8 | QSPI | OPI | ++---------+--------+------------+-------+ +| WROOM-1 | N8R8 | QSPI | OPI | ++---------+--------+------------+-------+ +| WROOM-1 | N16R8 | QSPI | OPI | ++---------+--------+------------+-------+ +| WROOM-2 | N16R8V | OPI | OPI | ++---------+--------+------------+-------+ +| WROOM-2 | N16R8V | OPI | OPI | ++---------+--------+------------+-------+ +| WROOM-2 | N32R8V | OPI | OPI | ++---------+--------+------------+-------+ From 8b8b8c2267419301567157fef56bb31fa4a2a9c7 Mon Sep 17 00:00:00 2001 From: Tomas Pilny Date: Wed, 24 May 2023 09:45:47 +0200 Subject: [PATCH 04/16] Moved SPIFFS paragraph from FAQ to troubleshooting --- docs/source/faq.rst | 19 +------------------ docs/source/troubleshooting.rst | 21 +++++++++++++++++++++ 2 files changed, 22 insertions(+), 18 deletions(-) diff --git a/docs/source/faq.rst b/docs/source/faq.rst index 6af19fc804f..af26ec96927 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -14,21 +14,4 @@ Note that modifying ``sdkconfig`` or ``sdkconfig.h`` files found in the arduino- How to compile libs with different debug level? ----------------------------------------------- -The short answer is ``esp32-arduino-lib-builder/configs/defconfig.common:44``. A guide explaining the process can be found here - -SPIFFS mount failed -------------------- -When you come across and error like this: - -.. code-block:: shell - - E (588) SPIFFS: mount failed, -10025 - [E][SPIFFS.cpp:47] begin(): Mounting SPIFFS failed! Error: -1 - -Try enforcing format on fail in your code by adding ``true`` in the ``begin`` method such as this: - -.. code-block:: c++ - - SPIFFS.begin(true); - -See the method prototype for reference: ``bool begin(bool formatOnFail=false, const char * basePath="/spiffs", uint8_t maxOpenFiles=10, const char * partitionLabel=NULL);`` \ No newline at end of file +The short answer is ``esp32-arduino-lib-builder/configs/defconfig.common:44``. A guide explaining the process can be found here \ No newline at end of file diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst index 4aee53f9786..62cd78ccfb7 100644 --- a/docs/source/troubleshooting.rst +++ b/docs/source/troubleshooting.rst @@ -124,6 +124,27 @@ Sample code to check SDK WPA3 support at compile time: #warning "No WPA3 support." #endif +SPIFFS mount failed +------------------- +When you come across and error like this: + +.. code-block:: shell + + E (588) SPIFFS: mount failed, -10025 + [E][SPIFFS.cpp:47] begin(): Mounting SPIFFS failed! Error: -1 + +Try enforcing format on fail in your code by adding ``true`` in the ``begin`` method such as this: + +.. code-block:: c++ + + SPIFFS.begin(true); + +See the method prototype for reference: ``bool begin(bool formatOnFail=false, const char * basePath="/spiffs", uint8_t maxOpenFiles=10, const char * partitionLabel=NULL);`` + +SD card mount fail +------------------ +TODO + ESP32-S3 is rebooting even with bare minimum sketch *************************************************** Some ESP32-S3 are equipped with Quad SPI (QSPI) or Octal SPI (OPI) PSRAM and if you upload such board with default settings for ESP32-S3 it will result in rebooting with message similar to this: From 0937ed0d5ba88c4818a2da6ba4d073656f436ea3 Mon Sep 17 00:00:00 2001 From: Tomas Pilny Date: Wed, 24 May 2023 09:46:43 +0200 Subject: [PATCH 05/16] Minor updates --- docs/source/tutorials/cdc_dfu_flash.rst | 2 +- docs/source/tutorials/io_mux.rst | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/source/tutorials/cdc_dfu_flash.rst b/docs/source/tutorials/cdc_dfu_flash.rst index 03b9c5ce1df..2c8c9ef0f08 100644 --- a/docs/source/tutorials/cdc_dfu_flash.rst +++ b/docs/source/tutorials/cdc_dfu_flash.rst @@ -23,7 +23,7 @@ ESP32-S3 CDC and DFU It's important that your board includes the USB connector attached to the embedded USB from the SoC. If your board doesn't have the USB connector, you can attach an external one to the USB pins. -These instructions it will only work on the supported devices with the embedded USB peripheral. This tutorial will not work if you are using an external USB-to-serial converter like FTDI, CP2102, CH340, etc. +These instructions will only work on the supported devices with the embedded USB peripheral. This tutorial will not work if you are using an external USB-to-serial converter like FTDI, CP2102, CH340, etc. For a complete reference to the Arduino IDE tools menu, please see the `Tools Menus <../guides/tools_menu.html>`_ reference guide. diff --git a/docs/source/tutorials/io_mux.rst b/docs/source/tutorials/io_mux.rst index 562810eae05..781347fdb32 100644 --- a/docs/source/tutorials/io_mux.rst +++ b/docs/source/tutorials/io_mux.rst @@ -35,6 +35,7 @@ To use this functionality, we must be aware of some precautions: * Some of the GPIOs are **INPUT** only. * Some peripherals have output signals and must be used on GPIO's capable to be configured as **OUTPUT**. * Some peripherals, mostly the high speed ones, ADC, DAC, Touch, and JTAG use dedicated GPIOs pins. +* Some pins are used to connect flash memory on the module - this prevents them from any other use - if a peripheral is routed to one of these pins the device will not able to boot. .. warning:: Before assigning the peripheral pins in your design, double check if the pins you're using are appropriate. From e2468bd670ee88a72ad1ea3795b22a633995011b Mon Sep 17 00:00:00 2001 From: Tomas Pilny Date: Wed, 24 May 2023 14:48:22 +0200 Subject: [PATCH 06/16] Updated troubleshooting --- docs/source/troubleshooting.rst | 57 +++++++++++++++++++++++---------- 1 file changed, 40 insertions(+), 17 deletions(-) diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst index 62cd78ccfb7..0d92ac29f81 100644 --- a/docs/source/troubleshooting.rst +++ b/docs/source/troubleshooting.rst @@ -33,7 +33,7 @@ Solution To avoid this error, you can install the ``python-is-python3`` package to create the symbolic links. .. code-block:: bash - + sudo apt install python-is-python3 If you are not using Ubuntu, you can check if you have the Python correctly installed or the presence of the symbolic links/environment variables. @@ -44,7 +44,7 @@ Flashing Why is my board not flashing/uploading when I try to upload my sketch? ********************************************************************** -To be able to upload the sketch via serial interface, the ESP32 must be in the download mode. The download mode allows you to upload the sketch over the serial port and to get into it, you need to keep the **GPIO0** in LOW while a resetting (**EN** pin) cycle. +To be able to upload the sketch via the serial interface, the ESP32 must be in the download mode. The download mode allows you to upload the sketch over the serial port, and to get into it, you need to keep the **GPIO0** in LOW while resetting (**EN** pin) the cycle. If you are trying to upload a new sketch and your board is not responding, there are some possible reasons. Possible fatal error message from the Arduino IDE: @@ -54,19 +54,19 @@ Possible fatal error message from the Arduino IDE: Solution ^^^^^^^^ -Here are some steps that you can try to: +Here are some steps that you can try: * Check your USB cable and try a new one (some cables are only for charging and there is no data connection). -* Change the USB port - prefer direct connection to computer and avoid USB hubs. Some USB ports may share power source with other ports used for example for charging phone. +* Change the USB port - prefer direct connection to the computer and avoid USB hubs. Some USB ports may share the power source with other ports used, for example, for charging a phone. * Check your power supply. * Make sure that nothing is connected to pins labeled **TX** and **RX**. * In some instances, you must keep **GPIO0** LOW during the uploading process via the serial interface. -* Hold down the **“BOOT”** button in your ESP32 board while uploading/flashing. +* Hold down the **“BOOT”** button on your ESP32 board while uploading/flashing. * Solder a **10uF** capacitor in parallel with **RST** and **GND**. -* If you bought your dev board from questionable seller they might have scammed you and send ESP8266 instead of ESP32. -* If you are using external power connected to pins it is easy to confuse pins **CMD** (which is usually next to the 5V pin) and **GND**. +* If you bought your dev board from a questionable seller, they might have scammed you and sent ESP8266 instead of ESP32. +* If you are using external power connected to pins, it is easy to confuse pins **CMD** (which is usually next to the 5V pin) and **GND**. -In some development boards, you can try adding the reset delay circuit, as described in the *Power-on Sequence* section on the `ESP32 Hardware Design Guidelines `_ in order to get into the download mode automatically. +In some development boards, you can try adding the reset delay circuit, as described in the *Power-on Sequence* section on the `ESP32 Hardware Design Guidelines `_ to get into the download mode automatically. Hardware -------- @@ -74,7 +74,7 @@ Hardware Why is my computer not detecting my board? ****************************************** -If your board is not being detected after connecting to the USB, you can try to: +If your board is not being detected after connecting to the USB, you can try the following: Solution ^^^^^^^^ @@ -91,8 +91,8 @@ Wi-Fi Why does the board not connect to WEP/WPA-"encrypted" Wi-Fi? ************************************************************ -Please note that WEP/WPA has significant security vulnerabilities and its use is strongly discouraged. -The support may therefore be removed in the future. Please migrate to WPA2 or newer. +Please note that WEP/WPA has significant security vulnerabilities, and its use is strongly discouraged. +The support may, therefore, be removed in the future. Please migrate to WPA2 or newer. Solution ^^^^^^^^ @@ -108,7 +108,7 @@ Nevertheless, it may be necessary to connect to insecure networks. To do this, t Why does the board not connect to WPA3-encrypted Wi-Fi? ******************************************************* -WPA3 support is resource intensive and may not be compiled into the used SDK. +WPA3 support is resource-intensive and may not be compiled into the used SDK. Solution ^^^^^^^^ @@ -126,7 +126,7 @@ Sample code to check SDK WPA3 support at compile time: SPIFFS mount failed ------------------- -When you come across and error like this: +When you come across an error like this: .. code-block:: shell @@ -143,11 +143,27 @@ See the method prototype for reference: ``bool begin(bool formatOnFail=false, co SD card mount fail ------------------ -TODO +Even though you made sure that the pins are correctly connected, and not using restricted pins, you may still get an error such as this: + +.. code-block:: shell + + [ 1065][E][sd_diskio.cpp:807] sdcard_mount(): f_mount failed: (3) The physical drive cannot work + +Most of the problems originate from a poor connection caused by Dupont cables, and one of the best solutions is to **solder all the connections** or use good quality connectors. + +If you want to try the software approach before soldering, try manually specifying SPI pins, like this: + +.. code-block:: c++ + + int SD_CS_PIN = 19; + SPI.begin(18, 36, 26, SD_CS_PIN); + SPI.setDataMode(SPI_MODE0); + SD.begin(SD_CS_PIN); -ESP32-S3 is rebooting even with bare minimum sketch -*************************************************** -Some ESP32-S3 are equipped with Quad SPI (QSPI) or Octal SPI (OPI) PSRAM and if you upload such board with default settings for ESP32-S3 it will result in rebooting with message similar to this: + +ESP32-S3 is rebooting even with a bare minimum sketch +***************************************************** +Some ESP32-S3 boards are equipped with Quad SPI (QSPI) or Octal SPI (OPI) PSRAM. If you upload such a board with default settings for ESP32-S3, it will result in rebooting with a message similar to this: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/flash_psram_config.html @@ -170,6 +186,7 @@ https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/flash_p assert failed: do_core_init startup.c:326 (flash_ret == ESP_OK) + To fix the issue, you will need to find out the precise module you are using and set **PSRAM** in the Arduino IDE Tools according to the following table. How to determine the module version: @@ -215,3 +232,9 @@ Note that WROOM-2 has always OPI. +---------+--------+------------+-------+ | WROOM-2 | N32R8V | OPI | OPI | +---------+--------+------------+-------+ + + +Further Help +------------ + +If you encounter any other issues or need further assistance, please consult the `ESP32 Arduino Core `_ documentation or seek help from the `ESP32 community forums `_. From 7ae2c68e5dc2ed59bb7c5ca67c82d9eed40a355a Mon Sep 17 00:00:00 2001 From: Tomas Pilny Date: Tue, 30 May 2023 15:10:33 +0200 Subject: [PATCH 07/16] Updated SD README files and example comments --- libraries/SD/README.md | 46 ++++++---- libraries/SD_MMC/README.md | 88 +++++++++++++++++++ .../SD_MMC/examples/SDMMC_Test/SDMMC_Test.ino | 14 +++ libraries/SD_MMC/src/SD_MMC.cpp | 2 +- 4 files changed, 131 insertions(+), 19 deletions(-) create mode 100644 libraries/SD_MMC/README.md diff --git a/libraries/SD/README.md b/libraries/SD/README.md index 2cc472dc809..b3c4aabcfbd 100644 --- a/libraries/SD/README.md +++ b/libraries/SD/README.md @@ -1,42 +1,52 @@ - # SD library -This library provides the integration of ESP32 and SD (Secure Digital) cards without additional modules. - +This library provides the integration of ESP32 and SD (Secure Digital) and MMC (Multi Media Card) cards without additional modules. This library is using SPI to interface with the cards. Please not that SPI mode is slower than the intended SD or MMC mode, however, provides more flexibility as the SPI module is available on all ESP SoCs and can be routed to any GPIO through GPIO matrix. ## Sample wiring diagram: +![Connections](http://i.imgur.com/4CoXOuR.png) -![SD card pins](http://i.imgur.com/4CoXOuR.png) - -For others SD formats: - +For other SD formats: ![Other SD card formats](https://upload.wikimedia.org/wikipedia/commons/thumb/a/ab/MMC-SD-miniSD-microSD-Color-Numbers-Names.gif/330px-MMC-SD-miniSD-microSD-Color-Numbers-Names.gif) - Image source: [Wikipedia](https://upload.wikimedia.org/wikipedia/commons/thumb/a/ab/MMC-SD-miniSD-microSD-Color-Numbers-Names.gif/330px-MMC-SD-miniSD-microSD-Color-Numbers-Names.gif) -```diff -- Warning: Some ESP32 modules have different pinouts! -``` +> **Warning** +Some ESP32 modules have different pin outs! +## Default SPI pins: +Note that SPI pins can be configured before using `SPI.begin(sck, miso, mosi, cs);` alternatively you can change only the CS pin with `SD.begin(CSpin)` ++--------------+---------+-------+----------+----------+----------+ +| SPI Pin Name | ESP8266 | ESP32 | ESP32-S2 | ESP32-C3 | ESP32-S3 | ++==============+=========+=======+==========+==========+==========+ +| CS | GPIO15 | GPIO5 | GPIO5 | GPIO13 | GPIO13 | ++--------------+---------+-------+----------+----------+----------+ +| MOSI | GPIO13 | GPIO23| GPIO24 | GPIO14 | GPIO14 | ++--------------+---------+-------+----------+----------+----------+ +| MISO | GPIO12 | GPIO19| GPIO25 | GPIO15 | GPIO15 | ++--------------+---------+-------+----------+----------+----------+ +| CLK | GPIO14 | GPIO18| GPIO19 | GPIO16 | GPIO16 | ++--------------+---------+-------+----------+----------+----------+ ## FAQ: -**Do I need any additional modules, like Arduino SD module?** +**Do I need any additional modules**, like **the **Arduino**** SD module**?** No, just wire your SD card directly to ESP32. +Tip: If you are using a microSD card and have a spare adapter to full-sized SD, you can solder Dupont pins on the adapter. **What is the difference between SD and SD_MMC libraries?** SD runs on SPI, and SD_MMC uses the SDMMC hardware bus on the ESP32. - - - -**Can I change the CS pin?** - -Yes, just use: `SD.begin(CSpin)` +The SPI uses 4 communication pins + 2 power connections and operates on up to 80MHz. The SPI option offers flexibility on pin connection because the data connections can be routed through GPIO matrix to any data pin. +SD-SPI speed is approximately half of the SD-MMC even when used on 1-bit line. +You can read more about SD SPI in the [documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/sdspi_host.html) + +SD_MMC is supported only by ESP32 and ESP320S3 and can be connected only to dedicated pins. SD_MMC allows to use of 1, 4 or 8 data pins + 2 additional communication pins and 2 power pins. The data pins need to be pulled up externally. +You can read more about SD_MMC in the [documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/sdmmc_host.html) +1-bit: SD_MMC_ speed is approximately two-times faster than SPI mode +4-bit: SD_MMC speed is approximately three-times faster than SPI mode. diff --git a/libraries/SD_MMC/README.md b/libraries/SD_MMC/README.md new file mode 100644 index 00000000000..a6a18278b2d --- /dev/null +++ b/libraries/SD_MMC/README.md @@ -0,0 +1,88 @@ +# SD_MMC library + +This library provides the integration of ESP32 and ESP32-S3 with SD (Secure Digital) and MMC (Multi Media Card) cards using a built-in SDMMC module. + +Please note that SD_MMC is only available for ESP32 and ESP32-S3. For other SoCs please use the SD library based on SPI. + +## Wiring: + +![MMC pins](https://commons.wikimedia.org/wiki/File:15-04-29-MMC-Karte-dscf4734-e.jpg) + +Image source: [Wikipedia](https://commons.wikimedia.org/wiki/File:15-04-29-MMC-Karte-dscf4734-e.jpg) + +### Pin assignments for ESP32 + +On ESP32, SD_MMC peripheral is connected to specific GPIO pins and cannot be changed (rerouted). Please see the table below for the pin connections. + +When using an ESP-WROVER-KIT board, this example runs without any extra modifications required. Only an SD card needs to be inserted into the slot. + +ESP32 pin | SD card pin | Notes +--------------|-------------|------------ +GPIO14 (MTMS) | CLK | 10k pullup in SD mode +GPIO15 (MTDO) | CMD | 10k pullup in SD mode +GPIO2 | D0 | 10k pullup in SD mode, pull low to go into download mode (see Note about GPIO2 below!) +GPIO4 | D1 | not used in 1-line SD mode; 10k pullup in 4-line SD mode +GPIO12 (MTDI) | D2 | not used in 1-line SD mode; 10k pullup in 4-line SD mode (see Note about GPIO12 below!) +GPIO13 (MTCK) | D3 | not used in 1-line SD mode, but card's D3 pin must have a 10k pullup + + +### Pin assignments for ESP32-S3 + +On ESP32-S3, SDMMC peripheral is connected to GPIO pins using GPIO matrix. This allows arbitrary GPIOs to be used to connect an SD card or MMC. The GPIOs can be configured based on +``` + setPins(int clk, int cmd, int d0)) + setPins(int clk, int cmd, int d0, int d1, int d2, int d3)) +``` + +The table below lists the default pin assignments. + +When using an ESP32-S3-USB-OTG board, this example runs without any extra modifications required. Only an SD card needs to be inserted into the slot. + +ESP32-S3 pin | SD card pin | Notes +--------------|-------------|------------ +GPIO36 | CLK | 10k pullup +GPIO35 | CMD | 10k pullup +GPIO37 | D0 | 10k pullup +GPIO38 | D1 | not used in 1-line SD mode; 10k pullup in 4-line mode +GPIO33 | D2 | not used in 1-line SD mode; 10k pullup in 4-line mode +GPIO34 | D3 | not used in 1-line SD mode, but card's D3 pin must have a 10k pullup + +### 4-line and 1-line SD modes + +By default, this library uses 4-bit line mode, utilizing 6 pins: CLK, CMD, D0 - D3 and 2 power lines (3.3V and GND). It is possible to use 1-bit line mode (CLK, CMD, D0, 3.3V, GND) by passing the second argument `mode1bit==true`: +``` + SD_MMC.begin("/sdcard", true); +``` + +Note that even if card's D3 line is not connected to the ESP chip, it still has to be pulled up, otherwise the card will go into SPI protocol mode. + +### Note about GPIO2 (ESP32 only) + +GPIO2 pin is used as a bootstrapping pin, and should be low to enter UART download mode. One way to do this is to connect GPIO0 and GPIO2 using a jumper, and then the auto-reset circuit on most development boards will pull GPIO2 low along with GPIO0, when entering download mode. + +- Some boards have pulldown and/or LED on GPIO2. LED is usually ok, but pulldown will interfere with D0 signals and must be removed. Check the schematic of your development board for anything connected to GPIO2. + +### Note about GPIO12 (ESP32 only) + +GPIO12 is used as a bootstrapping pin to select output voltage of an internal regulator which powers the flash chip (VDD_SDIO). This pin has an internal pulldown so if left unconnected it will read low at reset (selecting default 3.3V operation). When adding a pullup to this pin for SD card operation, consider the following: + +## FAQ: + +**Do I need any additional modules**, like **the **Arduino**** SD module**?** + +No, just wire your SD card directly to ESP32. + +Tip: If you are using a microSD card and have a spare adapter to full-sized SD, you can solder Dupont pins on the adapter. + + +**What is the difference between SD and SD_MMC libraries?** + +SD runs on SPI, and SD_MMC uses the SDMMC hardware bus on the ESP32. +The SPI uses 4 communication pins + 2 power connections and operates on up to 80MHz. The SPI option offers flexibility on pin connection because the data connections can be routed through GPIO matrix to any data pin. +SD-SPI speed is approximately half of the SD-MMC even when used on 1-bit line. +You can read more about SD SPI in the [documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/sdspi_host.html) + +SD_MMC is supported only by ESP32 and ESP320S3 and can be connected only to dedicated pins. SD_MMC allows to use of 1, 4 or 8 data pins + 2 additional communication pins and 2 power pins. The data pins need to be pulled up externally. +You can read more about SD_MMC in the [documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/sdmmc_host.html) +1-bit: SD_MMC_ speed is approximately two-times faster than SPI mode +4-bit: SD_MMC speed is approximately three-times faster than SPI mode. diff --git a/libraries/SD_MMC/examples/SDMMC_Test/SDMMC_Test.ino b/libraries/SD_MMC/examples/SDMMC_Test/SDMMC_Test.ino index 024ea4bfdea..8e90fe50cc2 100644 --- a/libraries/SD_MMC/examples/SDMMC_Test/SDMMC_Test.ino +++ b/libraries/SD_MMC/examples/SDMMC_Test/SDMMC_Test.ino @@ -11,6 +11,9 @@ * 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" @@ -172,6 +175,17 @@ void testFileIO(fs::FS &fs, const char * path){ void setup(){ Serial.begin(115200); + /* + // If you want to change the pin assigment on ESP32-S3 uncomment this block and the appropriate + // line depending if you want to use 1-bit or 4-bit line. + // Please note that ESP32 does not allow pin change and will always fail. + //if(! setPins(int clk, int cmd, int d0)){ + //if(! setPins(int clk, int cmd, int d0, int d1, int d2, int d3)){ + Serial.println("Pin change failed!"); + return; + } + */ + if(!SD_MMC.begin()){ Serial.println("Card Mount Failed"); return; diff --git a/libraries/SD_MMC/src/SD_MMC.cpp b/libraries/SD_MMC/src/SD_MMC.cpp index 83cf9aa0dd1..51bae727095 100644 --- a/libraries/SD_MMC/src/SD_MMC.cpp +++ b/libraries/SD_MMC/src/SD_MMC.cpp @@ -93,7 +93,7 @@ bool SDMMCFS::begin(const char * mountpoint, bool mode1bit, bool format_if_mount sdmmc_slot_config_t slot_config = SDMMC_SLOT_CONFIG_DEFAULT(); #ifdef SOC_SDMMC_USE_GPIO_MATRIX // SoC supports SDMMC pin configuration via GPIO matrix. - // Chech that the pins have been set either in the constructor or setPins function. + // Check that the pins have been set either in the constructor or setPins function. if (_pin_cmd == -1 || _pin_clk == -1 || _pin_d0 == -1 || (!mode1bit && (_pin_d1 == -1 || _pin_d2 == -1 || _pin_d3 == -1))) { log_e("SDMMCFS: some SD pins are not set"); From 0da71043f2e60612f7564ce90e3e29233ac46ca2 Mon Sep 17 00:00:00 2001 From: Tomas Pilny Date: Tue, 30 May 2023 15:15:20 +0200 Subject: [PATCH 08/16] Updated troubleshooting with SD issue --- docs/source/troubleshooting.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst index 0d92ac29f81..c778631f10b 100644 --- a/docs/source/troubleshooting.rst +++ b/docs/source/troubleshooting.rst @@ -151,6 +151,8 @@ Even though you made sure that the pins are correctly connected, and not using r Most of the problems originate from a poor connection caused by Dupont cables, and one of the best solutions is to **solder all the connections** or use good quality connectors. +Note that with SD_MMC lib all the data pins need to be pulled up with an external 10k to 3.3V. This applies especially to card's D3 which needs to be pulled up even when using 1-bit line connection and the D3 is not used. + If you want to try the software approach before soldering, try manually specifying SPI pins, like this: .. code-block:: c++ From 270cf97341005986f16b8fb7cacb080a56eb61dc Mon Sep 17 00:00:00 2001 From: Tomas Pilny Date: Tue, 30 May 2023 17:19:58 +0200 Subject: [PATCH 09/16] Added note about S3 pins --- libraries/SD_MMC/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/libraries/SD_MMC/README.md b/libraries/SD_MMC/README.md index a6a18278b2d..d77f0c75e6f 100644 --- a/libraries/SD_MMC/README.md +++ b/libraries/SD_MMC/README.md @@ -47,6 +47,8 @@ GPIO38 | D1 | not used in 1-line SD mode; 10k pullup in 4-line m GPIO33 | D2 | not used in 1-line SD mode; 10k pullup in 4-line mode GPIO34 | D3 | not used in 1-line SD mode, but card's D3 pin must have a 10k pullup +On some ESP32-S3 boards, the default pins are used for OPI and this will result in problems - please reassign the pins elsewhere using the mentioned command `setPins`. + ### 4-line and 1-line SD modes By default, this library uses 4-bit line mode, utilizing 6 pins: CLK, CMD, D0 - D3 and 2 power lines (3.3V and GND). It is possible to use 1-bit line mode (CLK, CMD, D0, 3.3V, GND) by passing the second argument `mode1bit==true`: From 550282cf5e6ef9a7a1505ffa677764dd579582fc Mon Sep 17 00:00:00 2001 From: Tomas Pilny Date: Wed, 31 May 2023 08:11:08 +0200 Subject: [PATCH 10/16] Updated SDMMC test setPins calls + added definition for default pins --- libraries/SD_MMC/examples/SDMMC_Test/SDMMC_Test.ino | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/libraries/SD_MMC/examples/SDMMC_Test/SDMMC_Test.ino b/libraries/SD_MMC/examples/SDMMC_Test/SDMMC_Test.ino index 8e90fe50cc2..934df606946 100644 --- a/libraries/SD_MMC/examples/SDMMC_Test/SDMMC_Test.ino +++ b/libraries/SD_MMC/examples/SDMMC_Test/SDMMC_Test.ino @@ -19,6 +19,15 @@ #include "FS.h" #include "SD_MMC.h" +// Default pins for ESP-S3 +// Note: if it's ok to use default pins, you do not need to call the setPins +int clk = 36; +int cmd = 35; +int d0 = 37; +int d1 = 38; +int d2 = 33; +int d3 = 39; // GPIO 34 is not broken-out on ESP32-S3-DevKitC-1 v1.1 + void listDir(fs::FS &fs, const char * dirname, uint8_t levels){ Serial.printf("Listing directory: %s\n", dirname); @@ -179,8 +188,8 @@ void setup(){ // If you want to change the pin assigment on ESP32-S3 uncomment this block and the appropriate // line depending if you want to use 1-bit or 4-bit line. // Please note that ESP32 does not allow pin change and will always fail. - //if(! setPins(int clk, int cmd, int d0)){ - //if(! setPins(int clk, int cmd, int d0, int d1, int d2, int d3)){ + //if(! setPins(clk, cmd, d0)){ + //if(! setPins(clk, cmd, d0, d1, d2, d3)){ Serial.println("Pin change failed!"); return; } From fa8b1e0590eb16a931268e1d1b03d46877381259 Mon Sep 17 00:00:00 2001 From: Tomas Pilny Date: Wed, 31 May 2023 08:31:09 +0200 Subject: [PATCH 11/16] Updated SD_MMC comments --- libraries/SD_MMC/README.md | 4 +++- libraries/SD_MMC/examples/SDMMC_Test/SDMMC_Test.ino | 4 ++++ 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/libraries/SD_MMC/README.md b/libraries/SD_MMC/README.md index d77f0c75e6f..e31a967294e 100644 --- a/libraries/SD_MMC/README.md +++ b/libraries/SD_MMC/README.md @@ -47,7 +47,9 @@ GPIO38 | D1 | not used in 1-line SD mode; 10k pullup in 4-line m GPIO33 | D2 | not used in 1-line SD mode; 10k pullup in 4-line mode GPIO34 | D3 | not used in 1-line SD mode, but card's D3 pin must have a 10k pullup -On some ESP32-S3 boards, the default pins are used for OPI and this will result in problems - please reassign the pins elsewhere using the mentioned command `setPins`. +Warning: ESP32-S3-WROOM-2 is using most of the default 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 that ESP32-S3-DevKitC-1 v1.1 does NOT have GPIOs 33 and 34 broken out, so it will be necessary to change at least the pin for D2 and D3. ### 4-line and 1-line SD modes diff --git a/libraries/SD_MMC/examples/SDMMC_Test/SDMMC_Test.ino b/libraries/SD_MMC/examples/SDMMC_Test/SDMMC_Test.ino index 934df606946..46445a92a8a 100644 --- a/libraries/SD_MMC/examples/SDMMC_Test/SDMMC_Test.ino +++ b/libraries/SD_MMC/examples/SDMMC_Test/SDMMC_Test.ino @@ -20,6 +20,10 @@ #include "SD_MMC.h" // Default pins for ESP-S3 +// Warning: ESP32-S3-WROOM-2 is using most of the default 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: if it's ok to use default pins, you do not need to call the setPins int clk = 36; int cmd = 35; From 825c50d6c5dddf09daa9019f52a2c29fab464356 Mon Sep 17 00:00:00 2001 From: Tomas Pilny Date: Wed, 31 May 2023 10:24:43 +0200 Subject: [PATCH 12/16] Added pin table to SD_MMC readme --- libraries/SD_MMC/README.md | 32 ++++++++++++++++++++++++++------ 1 file changed, 26 insertions(+), 6 deletions(-) diff --git a/libraries/SD_MMC/README.md b/libraries/SD_MMC/README.md index e31a967294e..cf85f6a1ee8 100644 --- a/libraries/SD_MMC/README.md +++ b/libraries/SD_MMC/README.md @@ -6,10 +6,30 @@ Please note that SD_MMC is only available for ESP32 and ESP32-S3. For other SoCs ## Wiring: -![MMC pins](https://commons.wikimedia.org/wiki/File:15-04-29-MMC-Karte-dscf4734-e.jpg) +![SD cards pins](https://upload.wikimedia.org/wikipedia/commons/thumb/a/ab/MMC-SD-miniSD-microSD-Color-Numbers-Names.gif/330px-MMC-SD-miniSD-microSD-Color-Numbers-Names.gif) + +Image source: [Wikipedia](https://upload.wikimedia.org/wikipedia/commons/thumb/a/ab/MMC-SD-miniSD-microSD-Color-Numbers-Names.gif/330px-MMC-SD-miniSD-microSD-Color-Numbers-Names.gif) + +![SD and MMC pins](https://upload.wikimedia.org/wikipedia/commons/f/ff/15-04-29-MMC-Karte-dscf4734-e.jpg) Image source: [Wikipedia](https://commons.wikimedia.org/wiki/File:15-04-29-MMC-Karte-dscf4734-e.jpg) +pin number (refer to the picture) | micro SD - SD mode | micro SD - SPI mode | mini SD - SD mode | mini SD - SPI mode | SD - SD mode | SD - SPI mode | MMC (MMC3) - MMC mode | MMC (MMC3) - SPI mode | MMCplus / MMCmobile (MMC4) - MMC mode | MMCplus / MMCmobile (MMC4) - SPI mode +----------------------------------|--------------------|---------------------|-------------------|--------------------|--------------|---------------|-----------------------|-----------------------|---------------------------------------| +1 | D2 | not used | D3 | CS | D3 | CS | RES | CS | D3 | CS +2 | D3 | CS | CMD | DI | CMD | DI | CMD | DI | CMD | DI +3 | CMD | DI | VSS1 (GND) | VSS1 (GND) | VSS1 (GND) | VSS1 (GND) | VSS1 (GND) | VSS1 (GND) | VSS1 (GND) | VSS1 (GND) +4 | VDD (3.3V) | VDD (3.3V) | VDD (3.3V) | VDD (3.3V) | VDD (3.3V) | VDD (3.3V) | VDD (3.3V) | VDD (3.3V) | VDD (3.3V) | VDD (3.3V) +5 | CLK | SCLK | CLK | SCLK | CLK | SCLK | CLK | SCLK | CLK | SCLK +6 | VSS (GND) | VSS (GND) | VSS2 (GND) | VSS2 (GND) | VSS2 (GND) | VSS2 (GND) | VSS2 (GND) | VSS2 (GND) | VSS2 (GND) | VSS2 (GND) +7 | D0 | DO | D0 | DO | D0 | DO | DAT | DO | D0 | DO +8 | D1 | not used | D1 | not used | D1 | not used | - | - | D1 | not used +9 | - | - | D2 | not used | D2 | not used | - | - | D2 | not used +10 | - | - | For future use | For future use | - | - | - | - | D3 | not used +11 | - | - | For future use | For future use | - | - | - | - | D4 | not used +12 | - | - | - | - | - | - | - | - | D5 | not used +13 | - | - | - | - | - | - | - | - | D6 | not used + ### Pin assignments for ESP32 On ESP32, SD_MMC peripheral is connected to specific GPIO pins and cannot be changed (rerouted). Please see the table below for the pin connections. @@ -28,7 +48,7 @@ GPIO13 (MTCK) | D3 | not used in 1-line SD mode, but card's D3 pin must ### Pin assignments for ESP32-S3 -On ESP32-S3, SDMMC peripheral is connected to GPIO pins using GPIO matrix. This allows arbitrary GPIOs to be used to connect an SD card or MMC. The GPIOs can be configured based on +On ESP32-S3, SDMMC peripheral is connected to GPIO pins using GPIO matrix. This allows arbitrary GPIOs to be used to connect an SD card or MMC. The GPIOs can be configured with the following commands: ``` setPins(int clk, int cmd, int d0)) setPins(int clk, int cmd, int d0, int d1, int d2, int d3)) @@ -49,7 +69,7 @@ GPIO34 | D3 | not used in 1-line SD mode, but card's D3 pin must Warning: ESP32-S3-WROOM-2 is using most of the default 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 that ESP32-S3-DevKitC-1 v1.1 does NOT have GPIOs 33 and 34 broken out, so it will be necessary to change at least the pin for D2 and D3. +> **Note:** ESP32-S3-DevKitC-1 v1.1 does NOT have GPIOs 33 and 34 broken out, so it will be necessary to change at least the pin for D2 and D3. ### 4-line and 1-line SD modes @@ -58,7 +78,7 @@ By default, this library uses 4-bit line mode, utilizing 6 pins: CLK, CMD, D0 - SD_MMC.begin("/sdcard", true); ``` -Note that even if card's D3 line is not connected to the ESP chip, it still has to be pulled up, otherwise the card will go into SPI protocol mode. +> **Note:** Even if card's D3 line is not connected to the ESP chip, it still has to be pulled up, otherwise the card will go into SPI protocol mode. ### Note about GPIO2 (ESP32 only) @@ -72,14 +92,14 @@ GPIO12 is used as a bootstrapping pin to select output voltage of an internal re ## FAQ: -**Do I need any additional modules**, like **the **Arduino**** SD module**?** +#### Do I need any additional modules, like the Arduino SD module? No, just wire your SD card directly to ESP32. Tip: If you are using a microSD card and have a spare adapter to full-sized SD, you can solder Dupont pins on the adapter. -**What is the difference between SD and SD_MMC libraries?** +#### What is the difference between SD and SD_MMC libraries? SD runs on SPI, and SD_MMC uses the SDMMC hardware bus on the ESP32. The SPI uses 4 communication pins + 2 power connections and operates on up to 80MHz. The SPI option offers flexibility on pin connection because the data connections can be routed through GPIO matrix to any data pin. From dc5fc60a5dc979cb1af75b133dbaed277c7c5fc6 Mon Sep 17 00:00:00 2001 From: Tomas Pilny Date: Thu, 8 Jun 2023 14:38:18 +0200 Subject: [PATCH 13/16] Updated table in SD_SPI --- libraries/SD/README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/libraries/SD/README.md b/libraries/SD/README.md index b3c4aabcfbd..17128d1c2a4 100644 --- a/libraries/SD/README.md +++ b/libraries/SD/README.md @@ -16,18 +16,18 @@ Image source: [Wikipedia](https://upload.wikimedia.org/wikipedia/commons/thumb/a Some ESP32 modules have different pin outs! ## Default SPI pins: -Note that SPI pins can be configured before using `SPI.begin(sck, miso, mosi, cs);` alternatively you can change only the CS pin with `SD.begin(CSpin)` +Note that SPI pins can be configured by using `SPI.begin(sck, miso, mosi, cs);` alternatively you can change only the CS pin with `SD.begin(CSpin)` +--------------+---------+-------+----------+----------+----------+ | SPI Pin Name | ESP8266 | ESP32 | ESP32-S2 | ESP32-C3 | ESP32-S3 | +==============+=========+=======+==========+==========+==========+ -| CS | GPIO15 | GPIO5 | GPIO5 | GPIO13 | GPIO13 | +| CS (SS) | GPIO15 | GPIO5 | GPIO5 | GPIO13 | GPIO13 | +--------------+---------+-------+----------+----------+----------+ -| MOSI | GPIO13 | GPIO23| GPIO24 | GPIO14 | GPIO14 | +| DI (MOSI) | GPIO13 | GPIO23| GPIO24 | GPIO14 | GPIO14 | +--------------+---------+-------+----------+----------+----------+ -| MISO | GPIO12 | GPIO19| GPIO25 | GPIO15 | GPIO15 | +| DO (MISO) | GPIO12 | GPIO19| GPIO25 | GPIO15 | GPIO15 | +--------------+---------+-------+----------+----------+----------+ -| CLK | GPIO14 | GPIO18| GPIO19 | GPIO16 | GPIO16 | +| SCK (SCLK) | GPIO14 | GPIO18| GPIO19 | GPIO16 | GPIO16 | +--------------+---------+-------+----------+----------+----------+ ## FAQ: From 11d3285a307312fa186b1efdbd5e7de822ea5e32 Mon Sep 17 00:00:00 2001 From: Tomas Pilny Date: Thu, 15 Jun 2023 14:56:12 +0200 Subject: [PATCH 14/16] Updated based on comments --- docs/source/troubleshooting.rst | 5 ++--- docs/source/tutorials/cdc_dfu_flash.rst | 2 +- libraries/SD/README.md | 2 +- libraries/SD_MMC/README.md | 2 +- 4 files changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst index c778631f10b..f9135dc4040 100644 --- a/docs/source/troubleshooting.rst +++ b/docs/source/troubleshooting.rst @@ -59,11 +59,10 @@ Here are some steps that you can try: * Check your USB cable and try a new one (some cables are only for charging and there is no data connection). * Change the USB port - prefer direct connection to the computer and avoid USB hubs. Some USB ports may share the power source with other ports used, for example, for charging a phone. * Check your power supply. -* Make sure that nothing is connected to pins labeled **TX** and **RX**. +* Make sure that nothing is connected to pins labeled **TX** and **RX**. Please refer to the pin layout table - some TX and RX pins may not be labeled on the dev board. * In some instances, you must keep **GPIO0** LOW during the uploading process via the serial interface. * Hold down the **“BOOT”** button on your ESP32 board while uploading/flashing. * Solder a **10uF** capacitor in parallel with **RST** and **GND**. -* If you bought your dev board from a questionable seller, they might have scammed you and sent ESP8266 instead of ESP32. * If you are using external power connected to pins, it is easy to confuse pins **CMD** (which is usually next to the 5V pin) and **GND**. In some development boards, you can try adding the reset delay circuit, as described in the *Power-on Sequence* section on the `ESP32 Hardware Design Guidelines `_ to get into the download mode automatically. @@ -149,7 +148,7 @@ Even though you made sure that the pins are correctly connected, and not using r [ 1065][E][sd_diskio.cpp:807] sdcard_mount(): f_mount failed: (3) The physical drive cannot work -Most of the problems originate from a poor connection caused by Dupont cables, and one of the best solutions is to **solder all the connections** or use good quality connectors. +Most of the problems originate from a poor connection caused by prototyping cables/wires, and one of the best solutions is to **solder all the connections** or use good quality connectors. Note that with SD_MMC lib all the data pins need to be pulled up with an external 10k to 3.3V. This applies especially to card's D3 which needs to be pulled up even when using 1-bit line connection and the D3 is not used. diff --git a/docs/source/tutorials/cdc_dfu_flash.rst b/docs/source/tutorials/cdc_dfu_flash.rst index 2c8c9ef0f08..7d4572d6ef2 100644 --- a/docs/source/tutorials/cdc_dfu_flash.rst +++ b/docs/source/tutorials/cdc_dfu_flash.rst @@ -23,7 +23,7 @@ ESP32-S3 CDC and DFU It's important that your board includes the USB connector attached to the embedded USB from the SoC. If your board doesn't have the USB connector, you can attach an external one to the USB pins. -These instructions will only work on the supported devices with the embedded USB peripheral. This tutorial will not work if you are using an external USB-to-serial converter like FTDI, CP2102, CH340, etc. +These instructions will only work on the supported devices with the embedded USB peripheral. This tutorial will not work if you are using an external USB-to-serial converter like FTDI, CP210x, CH340, etc. For a complete reference to the Arduino IDE tools menu, please see the `Tools Menus <../guides/tools_menu.html>`_ reference guide. diff --git a/libraries/SD/README.md b/libraries/SD/README.md index 17128d1c2a4..2f6272b4814 100644 --- a/libraries/SD/README.md +++ b/libraries/SD/README.md @@ -46,7 +46,7 @@ The SPI uses 4 communication pins + 2 power connections and operates on up to 80 SD-SPI speed is approximately half of the SD-MMC even when used on 1-bit line. You can read more about SD SPI in the [documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/sdspi_host.html) -SD_MMC is supported only by ESP32 and ESP320S3 and can be connected only to dedicated pins. SD_MMC allows to use of 1, 4 or 8 data pins + 2 additional communication pins and 2 power pins. The data pins need to be pulled up externally. +SD_MMC is supported only by ESP32 and ESP32-S3 and can be connected only to dedicated pins. SD_MMC allows to use of 1, 4 or 8 data pins + 2 additional communication pins and 2 power pins. The data pins need to be pulled up externally. You can read more about SD_MMC in the [documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/sdmmc_host.html) 1-bit: SD_MMC_ speed is approximately two-times faster than SPI mode 4-bit: SD_MMC speed is approximately three-times faster than SPI mode. diff --git a/libraries/SD_MMC/README.md b/libraries/SD_MMC/README.md index cf85f6a1ee8..ca34079d411 100644 --- a/libraries/SD_MMC/README.md +++ b/libraries/SD_MMC/README.md @@ -106,7 +106,7 @@ The SPI uses 4 communication pins + 2 power connections and operates on up to 80 SD-SPI speed is approximately half of the SD-MMC even when used on 1-bit line. You can read more about SD SPI in the [documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/sdspi_host.html) -SD_MMC is supported only by ESP32 and ESP320S3 and can be connected only to dedicated pins. SD_MMC allows to use of 1, 4 or 8 data pins + 2 additional communication pins and 2 power pins. The data pins need to be pulled up externally. +SD_MMC is supported only by ESP32 and ESP32-S3 and can be connected only to dedicated pins. SD_MMC allows to use of 1, 4 or 8 data pins + 2 additional communication pins and 2 power pins. The data pins need to be pulled up externally. You can read more about SD_MMC in the [documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/sdmmc_host.html) 1-bit: SD_MMC_ speed is approximately two-times faster than SPI mode 4-bit: SD_MMC speed is approximately three-times faster than SPI mode. From 8c8ab680f707bf635282aa0a59bd4440d45c4313 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1=C5=A1=20Piln=C3=BD?= <34927466+PilnyTomas@users.noreply.github.com> Date: Wed, 30 Aug 2023 13:47:15 +0200 Subject: [PATCH 15/16] Update io_mux.rst --- docs/source/tutorials/io_mux.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/tutorials/io_mux.rst b/docs/source/tutorials/io_mux.rst index 781347fdb32..12e0a9c9c0c 100644 --- a/docs/source/tutorials/io_mux.rst +++ b/docs/source/tutorials/io_mux.rst @@ -35,7 +35,7 @@ To use this functionality, we must be aware of some precautions: * Some of the GPIOs are **INPUT** only. * Some peripherals have output signals and must be used on GPIO's capable to be configured as **OUTPUT**. * Some peripherals, mostly the high speed ones, ADC, DAC, Touch, and JTAG use dedicated GPIOs pins. -* Some pins are used to connect flash memory on the module - this prevents them from any other use - if a peripheral is routed to one of these pins the device will not able to boot. +* Some pins are used to connect flash memory on the module - this prevents them from any other use - if a peripheral is routed to one of these pins the device will not be able to boot. .. warning:: Before assigning the peripheral pins in your design, double check if the pins you're using are appropriate. From b7ef411ba9c077cae0bf43e5e182fc29d639257e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1=C5=A1=20Piln=C3=BD?= <34927466+PilnyTomas@users.noreply.github.com> Date: Wed, 30 Aug 2023 13:48:43 +0200 Subject: [PATCH 16/16] Update README.md --- libraries/SD/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/libraries/SD/README.md b/libraries/SD/README.md index 2f6272b4814..df74e4a2f8b 100644 --- a/libraries/SD/README.md +++ b/libraries/SD/README.md @@ -1,6 +1,6 @@ # SD library -This library provides the integration of ESP32 and SD (Secure Digital) and MMC (Multi Media Card) cards without additional modules. This library is using SPI to interface with the cards. Please not that SPI mode is slower than the intended SD or MMC mode, however, provides more flexibility as the SPI module is available on all ESP SoCs and can be routed to any GPIO through GPIO matrix. +This library provides the integration of ESP32 and SD (Secure Digital) and MMC (Multi Media Card) cards without additional modules. This library is using SPI to interface with the cards. Please note that SPI mode is slower than the intended SD or MMC mode, however, provides more flexibility as the SPI module is available on all ESP SoCs and can be routed to any GPIO through GPIO matrix. ## Sample wiring diagram: @@ -16,7 +16,7 @@ Image source: [Wikipedia](https://upload.wikimedia.org/wikipedia/commons/thumb/a Some ESP32 modules have different pin outs! ## Default SPI pins: -Note that SPI pins can be configured by using `SPI.begin(sck, miso, mosi, cs);` alternatively you can change only the CS pin with `SD.begin(CSpin)` +Note that SPI pins can be configured by using `SPI.begin(sck, miso, mosi, cs);` alternatively, you can change only the CS pin with `SD.begin(CSpin)` +--------------+---------+-------+----------+----------+----------+ | SPI Pin Name | ESP8266 | ESP32 | ESP32-S2 | ESP32-C3 | ESP32-S3 |