01 Overview

SD cards are the go-to removable storage for field devices: non-volatile, high capacity, and readable by any PC. This example shows how to read and write SD cards from an ESP32 using SDMMC or SPI mode, covering the full path from hardware wiring to software mounting.

Use it for long-term logging of runtime data or sensor readings, or for exporting configuration and firmware backups to a customer. The FAT filesystem is natively recognized by Windows/macOS, so no special tools are needed.

SDMMC mode uses a dedicated peripheral with a 4-bit parallel data bus, offering high throughput for large data volumes. SPI mode reuses the common SPI bus with fewer pins, but is slower—suitable for small data or pin-constrained designs.

If you only need to store a few configuration bytes, skip the SD card—use the NVS partition instead. It's simpler, more reliable, and saves power. SD cards are for 'big files' and 'removable' scenarios.

Hot-plugging is a hidden pitfall in SD design: mechanical contacts, power sequencing, and filesystem state all need attention. This example highlights these risks and gives engineering recommendations.

02 Hardware

• Slot: Standard microSD slot, with optional card-detect (CD) pin. Ensure mechanical strength to avoid contact issues from vibration.
• Power: 3.3V supply, capable of at least 500mA (card peak current). For hot-plug, the rail must be well-behaved; add TVS and decoupling caps.
• Data lines: SDMMC uses 6 lines (CLK, CMD, D0-D3); SPI uses 4 (CS, CLK, MOSI, MISO). Pull-ups as per the chip datasheet.
• Level matching: ESP32 IOs are 3.3V, and the card is 3.3V, so direct connection is fine. Mind the pin order on the slot.
• Card detect: If using CD, pull it up and use it to detect insertion/removal for software prompts.
• Layout: Keep data lines short and equal length to avoid signal distortion. Place the slot near the board edge for easy access.
• Protection: Add ESD protection on power and data lines; field environments are static-prone.

03 Software flow

1. Configure the SDMMC or SPI peripheral and initialize the driver. Use sdmmc_host_t for SDMMC, spi_bus_config_t for SPI.

2. Mount the FAT filesystem: call esp_vfs_fat_sdmmc_mount or esp_vfs_fat_spiflash_mount (note the difference). Mount point like "/sdcard".

3. Write files: use standard C library fopen/fwrite, but remember to fflush and fsync to prevent data loss on power failure.

4. Read files: fopen/fread, for export or reading configuration.

5. Before removal: ensure all files are closed, call fflush and fsync, then unmount. The product must warn the user when a write is in flight.

6. Error handling: handle card missing, mount failure, write errors with clear messages, and retry or degrade gracefully.

7. Hot-plug detection: if using CD, poll or interrupt to detect card removal and immediately stop writes and unmount.

04 Core points

• Card quality varies; fixture-test lots. Compatibility differs across brands/batches; validate with a test fixture before mass production.
• Hot-plug is critical: Power must be well-behaved, and software must handle sudden removal to avoid filesystem corruption.
• SDMMC and SPI are not interchangeable: Pins, drivers, and speeds differ; decide early.
• FAT has a 4GB per-file limit; for long logs, split files or use circular overwriting.
• Custom work: log format, slot layout, export flow.
• Don't copy SD drivers from other chips: ESP32's SDMMC peripheral and SPI implementation differ; refer to the official example.