Your first file, over SPI
Six wires, a sketch that writes one line and reads it straight back, and a serial monitor that tells you which of the six is wrong. This is the version to get working before you try anything faster.
The six wires
Leave the Mode control on SPI. Four signals, plus 3V3 and GND, and the two holes printed NC stay empty — that is what SPI mode means on this board.
If you have the full-size board, CD and WP stay empty too. They are switches, and this sketch does not read them.
Before you upload
Put a card in. Push it until it clicks — both sockets are push-push, so the card sits flush and clicks again to release. A card that is only half in reads as no card.
The card should be formatted FAT32 or exFAT. A card straight out of its packet usually is. A card out of a camera or a Raspberry Pi usually is not, and formatting it on a computer is faster than debugging it.
What good looks like
card mounted, 30436 MB
read back: written by an ESP32Two lines. The first says the card answered and the ESP32 could read its capacity; the second says a file was written and read back correctly, which means both directions of the bus work.
If you get the first line and not the second, the bus is fine and the filesystem is not. If you get neither, it is the wiring or the supply, in that order.
Where the speed went
This sketch asks for a 24 MHz SPI clock, which is what the bench used, and on that bench SPI sustained about 1.4 MB/s writing. That is plenty for a logger, and about half of what the same card managed in 4-bit mode.
The next page is the two extra wires.
The code
Mount the card, print what it is, write a line to /hello.txt and read it back. If the last line the monitor prints is the line the sketch wrote, all six wires are right and the card is formatted.
// Wiring for this sketch. Either board, SPI mode. Holes counted from the
// GND end, with the name printed on the front and then on the back.
//
// ESP32-S3 3V3 -> 3V3 (hole 2)
// ESP32-S3 GND -> GND (hole 1)
// ESP32-S3 GPIO10 -> CS (hole 4, printed DATA3 on the back)
// ESP32-S3 GPIO11 -> MOSI (hole 5, printed CMD on the back)
// ESP32-S3 GPIO12 -> SCK (hole 6, printed CLK on the back)
// ESP32-S3 GPIO13 -> MISO (hole 7, printed DATA0 on the back)
//
// The two holes printed NC stay empty, and so do CD and WP on the
// full-size board. Any four free GPIOs will do - these are the ones the
// bench used.
//
// Arduino IDE: Tools > Board "ESP32S3 Dev Module", USB CDC On Boot
// "Enabled", Flash Size to match your board, Serial Monitor at 115200.
// No library to install: SD.h and SPI.h ship with the ESP32 core.
#include <SPI.h>
#include <SD.h>
#define SD_CS 10
#define SD_MOSI 11
#define SD_SCK 12
#define SD_MISO 13
SPIClass sdSPI(FSPI);
void setup() {
Serial.begin(115200);
delay(500);
sdSPI.begin(SD_SCK, SD_MISO, SD_MOSI, SD_CS);
if (!SD.begin(SD_CS, sdSPI, 24000000)) {
Serial.println("no card - check 3V3 and GND first, then the four signals");
return;
}
Serial.printf("card mounted, %llu MB\n", SD.cardSize() / (1024ULL * 1024ULL));
File f = SD.open("/hello.txt", FILE_WRITE);
if (!f) {
Serial.println("mounted, but could not open /hello.txt - is the card write protected?");
return;
}
f.println("written by an ESP32");
f.close();
f = SD.open("/hello.txt");
Serial.print("read back: ");
while (f.available()) Serial.write(f.read());
f.close();
}
void loop() {}The clock is set to 24 MHz, which is what the bench measured with. If it fails to mount, drop the last argument of SD.begin() to 4000000 and try again — a slow mount that works tells you the wiring is marginal rather than wrong.
When it does not work
Check the supply before the signals: the red LED on the module should be lit, and a meter between GND and 3V3 should read 3.3 V. Then check that the card is formatted FAT32 or exFAT — a brand-new card usually is, a card that has been used by something else often is not. Then count the four signal holes again from the GND end.
The wiring is marginal rather than wrong. Shorten the jumper wires, especially the ground one, and press the module's pins properly home in the breadboard. A mount that only works at the slowest speed is the same diagnosis at the other end of the scale.
On the full-size board, check the little plastic slider on the side of the card — if it is in the locked position some card readers refuse the write. Otherwise the card's filesystem is damaged; format it on a computer as FAT32 and try again.
That is the board, not the card. Set the monitor to 115200, and on an ESP32-S3 make sure Tools > USB CDC On Boot is Enabled — without it the sketch's Serial output never reaches the USB port.
Two more wires, a different library, and the pins you may not use on a classic ESP32.
Switching to 4-bit mode →Edit this page — content/books/sd/your-first-file.mdx
Questions about this product
See what other owners have asked, and read their solutions.
This page covers several products. Choose yours to see the right discussions.
Discuss this article
Ask about this page. The answer stays here, on the page it belongs to, for whoever hits the same wall next.