1| Supported Targets | ESP32 | ESP32-S2 | ESP32-C3 |
2| ----------------- | ----- | -------- | -------- |
3
4# SD Card example (SDSPI)
5
6(See the README.md file in the upper level 'examples' directory for more information about examples.)
7
8This example demonstrates how to use an SD card with an ESP device. Example does the following steps:
9
101. Use an "all-in-one" `esp_vfs_fat_sdspi_mount` function to:
11    - initialize SDSPI peripheral,
12    - probe and initialize the card connected to SPI bus (DMA channel 1, MOSI, MISO and CLK lines, chip-specific SPI host id),
13    - mount FAT filesystem using FATFS library (and format card, if the filesystem cannot be mounted),
14    - register FAT filesystem in VFS, enabling C standard library and POSIX functions to be used.
152. Print information about the card, such as name, type, capacity, and maximum supported frequency.
163. Create a file using `fopen` and write to it using `fprintf`.
174. Rename the file. Before renaming, check if destination file already exists using `stat` function, and remove it using `unlink` function.
185. Open renamed file for reading, read back the line, and print it to the terminal.
19
20This example support SD (SDSC, SDHC, SDXC) cards.
21
22## Hardware
23
24Pins can be customized. See the initialization of ``spi_bus_config_t`` and ``sdspi_slot_config_t`` structures in the example code.
25
26It 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.
27
28This example doesn't utilize card detect (CD) and write protect (WP) signals from SD card slot.
29
30### Connections for ESP32
31
32This example runs on ESP-WROVER-KIT boards without any extra modifications required, only the SD card needs to be inserted into the slot.
33
34Other ESP32 development boards need to be connected to SD card as follows:
35
36ESP32 pin     | SD card pin | SPI pin | Notes
37--------------|-------------|---------|------------
38GPIO2         | D0          | MISO    |
39GPIO13 (MTCK) | D3          | CS      |
40GPIO14 (MTMS) | CLK         | SCK     |
41GPIO15 (MTDO) | CMD         | MOSI    | 10k pullup
42
43Some 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
44
45### Connections for ESP32S2
46
47ESP32S2 pin   | SD card pin | SPI pin | Notes
48--------------|-------------|---------|------------
49GPIO37        | D0          | MISO    |
50GPIO34        | D3          | CS      |
51GPIO36        | CLK         | SCK     |
52GPIO35        | CMD         | MOSI    | 10k pullup
53
54### Connections for ESP32-C3
55
56ESP32-C3 pin  | SD card pin | SPI pin | Notes
57--------------|-------------|---------|------------
58GPIO5         | CLK         | SCK     |
59GPIO4         | CMD         | MOSI    | 10k pullup
60GPIO6        | D0          | MISO    |
61GPIO1        | D3          | CS      |
62
63### Build and flash
64
65Build the project and flash it to the board, then run monitor tool to view serial output:
66
67```
68idf.py -p PORT flash monitor
69```
70
71(Replace PORT with serial port name.)
72
73(To exit the serial monitor, type ``Ctrl-]``.)
74
75See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
76
77
78## Example output
79
80Here 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.
81
82```
83I (336) example: Initializing SD card
84I (336) example: Using SPI peripheral
85I (336) gpio: GPIO[13]| InputEn: 0| OutputEn: 1| OpenDrain: 0| Pullup: 0| Pulldown: 0| Intr:0
86W (596) vfs_fat_sdmmc: failed to mount card (13)
87W (596) vfs_fat_sdmmc: partitioning card
88W (596) vfs_fat_sdmmc: formatting card, allocation unit size=16384
89W (7386) vfs_fat_sdmmc: mounting again
90Name: XA0E5
91Type: SDHC/SDXC
92Speed: 20 MHz
93Size: 61068MB
94I (7386) example: Opening file /sdcard/hello.txt
95I (7396) example: File written
96I (7396) example: Renaming file /sdcard/hello.txt to /sdcard/foo.txt
97I (7396) example: Reading file /sdcard/foo.txt
98I (7396) example: Read from file: 'Hello XA0E5!'
99I (7396) example: Card unmounted
100```
101
102## Troubleshooting
103
104### Failure to mount filesystem
105
106```
107example: Failed to mount filesystem. If you want the card to be formatted, set the EXAMPLE_FORMAT_IF_MOUNT_FAILED menuconfig option.
108```
109The 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.
110
111
112### Unable to download the example BIN (or serial port not available)
113```
114After the first successful flashing of the example firmware, it is not possible to flash again.
115(Download mode not activated when running idf.py (==esptool.py) or the board's serial port disappears completely)
116```
117
118Some 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).
119(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).
120Check you board documentation/schematics for appropriate procedure.
121
122An 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
123
124`esptool --port PORT --before no_reset --baud 115200 --chip esp32 erase_flash`
125
126to clean your board's flash, then download your firmware properly.
127
128