From 9b1e76360ba86c27d2e16789524ed4c8019946cd Mon Sep 17 00:00:00 2001 From: Ivan Grokhotkov Date: Tue, 8 Feb 2022 18:14:47 +0100 Subject: [PATCH] examples: sdspi: re-enable for ESP32-S3, add Kconfig options for pins --- examples/storage/sd_card/sdspi/README.md | 80 +++++++++---------- .../sd_card/sdspi/main/Kconfig.projbuild | 31 ++++++- .../sd_card/sdspi/main/sd_card_example_main.c | 35 +++----- 3 files changed, 78 insertions(+), 68 deletions(-) diff --git a/examples/storage/sd_card/sdspi/README.md b/examples/storage/sd_card/sdspi/README.md index 1165920a0e..ebc228994c 100644 --- a/examples/storage/sd_card/sdspi/README.md +++ b/examples/storage/sd_card/sdspi/README.md @@ -1,11 +1,8 @@ -| Supported Targets | ESP32 | ESP32-S2 | ESP32-C3 | -| ----------------- | ----- | -------- | -------- | - # SD Card example (SDSPI) (See the README.md file in the upper level 'examples' directory for more information about examples.) -This example demonstrates how to use an SD card with an ESP device. Example does the following steps: +This example demonstrates how to use an SD card with an ESP device over an SPI interface. Example does the following steps: 1. Use an "all-in-one" `esp_vfs_fat_sdspi_mount` function to: - initialize SDSPI peripheral, @@ -21,44 +18,48 @@ This example support SD (SDSC, SDHC, SDXC) cards. ## Hardware -Pins can be customized. See the initialization of ``spi_bus_config_t`` and ``sdspi_slot_config_t`` structures in the example code. +This example requires a development board with an SD card socket and and SD card. + +Although it is possible to connect an SD card breakout adapter, keep in mind that connections using breakout cables are often unreliable and have poor signal integrity. You may need to use lower clock frequency when working with SD card breakout adapters. It is recommended to get familiar with [the document about pullup requirements](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/peripherals/sd_pullup_requirements.html) to understand Pullup/down resistor support and compatibility of various ESP modules and development boards. +### Pin assignments + +The GPIO pin numbers used to connect an SD card can be customized. This can be done in two ways: + +1. Using menuconfig: Run `idf.py menuconfig` in the project directory and open "SD SPI Example Configuration" menu. +2. In the source code: See the initialization of ``spi_bus_config_t`` and ``sdspi_slot_config_t`` structures in the example code. + This example doesn't utilize card detect (CD) and write protect (WP) signals from SD card slot. -### Connections for ESP32 +The table below shows the default pin assignments. -This example runs on ESP-WROVER-KIT boards without any extra modifications required, only the SD card needs to be inserted into the slot. +SD card pin | SPI pin | ESP32 pin | ESP32-S2, ESP32-S3 | ESP32-C3 and other chips | Notes +------------|---------|---------------|--------------------|---------------------------|------------- + D0 | MISO | GPIO2 | GPIO37 | GPIO6 | + D3 | CS | GPIO13 (MTCK) | GPIO34 | GPIO1 | + CLK | SCK | GPIO14 (MTMS) | GPIO36 | GPIO5 | + CMD | MOSI | GPIO15 (MTDO) | GPIO35 | GPIO4 | 10k pullup -Other ESP32 development boards need to be connected to SD card as follows: -ESP32 pin | SD card pin | SPI pin | Notes ---------------|-------------|---------|------------ -GPIO2 | D0 | MISO | -GPIO13 (MTCK) | D3 | CS | -GPIO14 (MTMS) | CLK | SCK | -GPIO15 (MTDO) | CMD | MOSI | 10k pullup +#### ESP32 related notes + +With the default pin assignments, this example runs on ESP-WROVER-KIT boards without any extra modifications required. Only the SD card needs to be inserted into the slot. + +For other development boards, adjust the pin assignments as explained above. Some boards require specific manipulation to enable UART Download mode (GPIO2 low) - eg ESP32-Azure IoT Kit needs KEY_IO0 pressed down for the time of firmware flashing operation (sets IO0 and IO2 low). See troubleshooting section for more details -### Connections for ESP32S2 +#### ESP32-S2 and ESP32-S3 related notes -ESP32S2 pin | SD card pin | SPI pin | Notes ---------------|-------------|---------|------------ -GPIO37 | D0 | MISO | -GPIO34 | D3 | CS | -GPIO36 | CLK | SCK | -GPIO35 | CMD | MOSI | 10k pullup +With the default pin assignments, this example is compatible ESP32-S2-USB-OTG and ESP32-S3-USB-OTG development boards. -### Connections for ESP32-C3 +For other development boards, adjust the pin assignments as explained above. -ESP32-C3 pin | SD card pin | SPI pin | Notes ---------------|-------------|---------|------------ -GPIO5 | CLK | SCK | -GPIO4 | CMD | MOSI | 10k pullup -GPIO6 | D0 | MISO | -GPIO1 | D3 | CS | +#### Notes for ESP32-C3 and other chips + +Espressif doesn't offer development boards with an SD card slot for these chips. Please check the pin assignments and adjust them for your board if necessary. The process to change pin assignments is described above. ### Build and flash @@ -77,7 +78,7 @@ See the Getting Started Guide for full steps to configure and use ESP-IDF to bui ## Example output -Here is an example console output. In this case a 128MB SDSC card was connected, and `EXAMPLE_FORMAT_IF_MOUNT_FAILED` menuconfig option enabled. Card was unformatted, so the initial mount has failed. Card was then partitioned, formatted, and mounted again. +Here is an example console output. In this case a 64GB SDHC card was connected, and `EXAMPLE_FORMAT_IF_MOUNT_FAILED` menuconfig option enabled. Card was unformatted, so the initial mount has failed. Card was then partitioned, formatted, and mounted again. ``` I (336) example: Initializing SD card @@ -103,25 +104,22 @@ I (7396) example: Card unmounted ### Failure to mount filesystem -``` -example: Failed to mount filesystem. If you want the card to be formatted, set the EXAMPLE_FORMAT_IF_MOUNT_FAILED menuconfig option. -``` -The example will be able to mount only cards formatted using FAT32 filesystem. If the card is formatted as exFAT or some other filesystem, you have an option to format it in the example code. Enable the `EXAMPLE_FORMAT_IF_MOUNT_FAILED` menuconfig option, then build and flash the example. +> The following error message is printed: `example: Failed to mount filesystem. If you want the card to be formatted, set the CONFIG_EXAMPLE_FORMAT_IF_MOUNT_FAILED menuconfig option.` + +The example will be able to mount only cards formatted using FAT32 filesystem. If the card is formatted as exFAT or some other filesystem, you have an option to format it in the example code. Enable the `CONFIG_EXAMPLE_FORMAT_IF_MOUNT_FAILED` menuconfig option, then build and flash the example. -### Unable to download the example BIN (or serial port not available) -``` -After the first successful flashing of the example firmware, it is not possible to flash again. -(Download mode not activated when running idf.py (==esptool.py) or the board's serial port disappears completely) -``` +### Unable to flash the example, or serial port not available (ESP32 only) + +> After the first successful flashing of the example firmware, it is not possible to flash again. Download mode not activated when running `idf.py flash` or the board's serial port disappears completely. + +Some ESP32 boards require specific handling to activate the download mode after a system reset, due to GPIO2 pin now being used as both SDSPI (MISO) and an active-low bootstrapping signal for entering download mode. For instance, the ESP32-Azure IoT Kit requires KEY_IO0 button to remain pressed during whole firmware flashing operation, as it sets both GPIO0 and GPIO2 signals low. -Some boards require specific handling to activate the Download mode after a system reset, due to GPIO2 pin now being used as both SDSPI (MISO) and a bootstrapping signal for enabling UART0 Boot (low). -(For instance, the ESP32-Azure IoT Kit requires KEY_IO0 button remain pressed during whole firmware flashing operation, as it sets both GPIO0 and GPIO2 signals low). Check you board documentation/schematics for appropriate procedure. An attempt to download a new firmware under this conditions may also result in the board's serial port disappearing from your PC device list - rebooting your computer should fix the issue. After your device is back, use `esptool --port PORT --before no_reset --baud 115200 --chip esp32 erase_flash` -to clean your board's flash, then download your firmware properly. +to erase your board's flash, then flash the firmware again. diff --git a/examples/storage/sd_card/sdspi/main/Kconfig.projbuild b/examples/storage/sd_card/sdspi/main/Kconfig.projbuild index 0a3e447f10..e7dce05f06 100644 --- a/examples/storage/sd_card/sdspi/main/Kconfig.projbuild +++ b/examples/storage/sd_card/sdspi/main/Kconfig.projbuild @@ -1,4 +1,4 @@ -menu "SD Card Example menu" +menu "SD SPI Example Configuration" config EXAMPLE_FORMAT_IF_MOUNT_FAILED bool "Format the card if mount failed" @@ -6,4 +6,33 @@ menu "SD Card Example menu" help If this config item is set, format_if_mount_failed will be set to true and the card will be formatted if the mount has failed. + + config EXAMPLE_PIN_MOSI + int "MOSI GPIO number" + default 15 if IDF_TARGET_ESP32 + default 35 if IDF_TARGET_ESP32S2 + default 35 if IDF_TARGET_ESP32S3 + default 4 # C3 and others + + config EXAMPLE_PIN_MISO + int "MISO GPIO number" + default 2 if IDF_TARGET_ESP32 + default 37 if IDF_TARGET_ESP32S2 + default 37 if IDF_TARGET_ESP32S3 + default 6 # C3 and others + + config EXAMPLE_PIN_CLK + int "CLK GPIO number" + default 14 if IDF_TARGET_ESP32 + default 36 if IDF_TARGET_ESP32S2 + default 36 if IDF_TARGET_ESP32S3 + default 5 # C3 and others + + config EXAMPLE_PIN_CS + int "CS GPIO number" + default 13 if IDF_TARGET_ESP32 + default 34 if IDF_TARGET_ESP32S2 + default 34 if IDF_TARGET_ESP32S3 + default 1 # C3 and others + endmenu diff --git a/examples/storage/sd_card/sdspi/main/sd_card_example_main.c b/examples/storage/sd_card/sdspi/main/sd_card_example_main.c index 02dd5b8994..78d404764f 100644 --- a/examples/storage/sd_card/sdspi/main/sd_card_example_main.c +++ b/examples/storage/sd_card/sdspi/main/sd_card_example_main.c @@ -1,4 +1,6 @@ /* SD card and FAT filesystem example. + This example uses SPI peripheral to communicate with SD card. + This example code is in the Public Domain (or CC0 licensed, at your option.) Unless required by applicable law or agreed to in writing, this @@ -6,8 +8,6 @@ CONDITIONS OF ANY KIND, either express or implied. */ -// This example uses SPI peripheral to communicate with SD card. - #include #include #include @@ -18,29 +18,12 @@ static const char *TAG = "example"; #define MOUNT_POINT "/sdcard" -// Pin mapping -#if CONFIG_IDF_TARGET_ESP32 - -#define PIN_NUM_MISO 2 -#define PIN_NUM_MOSI 15 -#define PIN_NUM_CLK 14 -#define PIN_NUM_CS 13 - -#elif CONFIG_IDF_TARGET_ESP32S2 - -// adapted for internal test board ESP-32-S3-USB-OTG-Ev-BOARD_V1.0 (with ESP32-S2-MINI-1 module) -#define PIN_NUM_MISO 37 -#define PIN_NUM_MOSI 35 -#define PIN_NUM_CLK 36 -#define PIN_NUM_CS 34 - -#elif CONFIG_IDF_TARGET_ESP32C3 -#define PIN_NUM_MISO 6 -#define PIN_NUM_MOSI 4 -#define PIN_NUM_CLK 5 -#define PIN_NUM_CS 1 - -#endif //CONFIG_IDF_TARGET_ESP32 || CONFIG_IDF_TARGET_ESP32S2 +// Pin assignments can be set in menuconfig, see "SD SPI Example Configuration" menu. +// You can also change the pin assignments here by changing the following 4 lines. +#define PIN_NUM_MISO CONFIG_EXAMPLE_PIN_MISO +#define PIN_NUM_MOSI CONFIG_EXAMPLE_PIN_MOSI +#define PIN_NUM_CLK CONFIG_EXAMPLE_PIN_CLK +#define PIN_NUM_CS CONFIG_EXAMPLE_PIN_CS #if CONFIG_IDF_TARGET_ESP32S2 #define SPI_DMA_CHAN host.slot @@ -104,7 +87,7 @@ void app_main(void) if (ret != ESP_OK) { if (ret == ESP_FAIL) { ESP_LOGE(TAG, "Failed to mount filesystem. " - "If you want the card to be formatted, set the EXAMPLE_FORMAT_IF_MOUNT_FAILED menuconfig option."); + "If you want the card to be formatted, set the CONFIG_EXAMPLE_FORMAT_IF_MOUNT_FAILED menuconfig option."); } else { ESP_LOGE(TAG, "Failed to initialize the card (%s). " "Make sure SD card lines have pull-up resistors in place.", esp_err_to_name(ret));