Umber
/
ESP32
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ESP32/doc/SD_CARD_WIRING.md

13 KiB
Raw Permalink Blame History

SparkFun microSD Transflash Breakout - ESP32-C5 Wiring Guide

Overview

This guide shows how to connect the SparkFun microSD Transflash Breakout board to the ESP32-C5 DevKit. ESP32-C5 does not support SDMMC/SDIO host, so the firmware uses SPI mode for SD card access.

If you also have a GPS module (e.g. GT-U7): J1 Pin 1 (3.3V) and Pin 15 (GND) must each use a Y-cable (or splice) so one leg goes to the SD breakout and one to the GPS — both devices share the same 3.3V and GND from the ESP32-C5.

Required Connections (SPI mode)

  • VCC (3.3V)
  • GND (Ground)
  • CLK (SPI SCLK)
  • DI (SPI MOSI - Data In to card)
  • DO (SPI MISO - Data Out from card)
  • CS (Chip Select)
  • CD (Card Detect, optional)

Wiring Table (SPI Mode)

SparkFun Label ESP32-C5 Pin Header Location GPIO Number Function
VCC Pin 1 J1 (Left Side) 3V3 Power
GND Pin 15 J1 (Left Side) GND Ground
SCK Pin 10 J1 (Left Side) GPIO9 SPI_CLK
DI Pin 11 J1 (Left Side) GPIO10 SPI_MOSI
DO Pin 9 J1 (Left Side) GPIO8 SPI_MISO
CS Pin 8 J1 (Left Side) GPIO7 SPI_CS
CD Pin 12 J1 (Left Side) GPIO26 Card Detect (Input Pull-up)

Note: If your SparkFun breakout does not expose CS, some breakouts tie CS to GND (always selected). The firmware expects CS on GPIO7.

Wiring Diagram (SD only)

  ┌─────────────────────────────┐         ┌──────────────────────────────┐
  │  SparkFun microSD Breakout  │         │   ESP32-C5 DevKit (J1)        │
  │                             │         │                               │
  │   VCC ──────────────────────┼─────────┼─► Pin 1  (3V3)               │
  │   GND ──────────────────────┼─────────┼─► Pin 15 (GND)               │
  │   SCK ──────────────────────┼─────────┼─► Pin 10 (GPIO9)  CLK        │
  │   DI  ──────────────────────┼─────────┼─► Pin 11 (GPIO10) MOSI       │
  │   DO  ──────────────────────┼─────────┼─► Pin 9  (GPIO8)  MISO       │
  │   CS  ──────────────────────┼─────────┼─► Pin 8  (GPIO7)  Chip Select│
  │   CD  ──────────────────────┼─────────┼─► Pin 12 (GPIO26) Card Detect│
  │                             │         │      (optional)               │
  └─────────────────────────────┘         └──────────────────────────────┘

Combined Pin Diagram (SD Card + GPS)

When using both the SparkFun microSD breakout and a GPS module (e.g. GT-U7 / NEO-6M), power and ground are shared:

  • J1 Pin 1 (3.3V) and J1 Pin 15 (GND) each need a Y-cable (or one 3.3V and one GND split): one branch to the SD breakout, one branch to the GPS. Do not rely on a single wire to the first device and then daisy‑chain to the second; use a proper Y (or star) so both get a direct connection to 3.3V and GND.
                    ESP32-C5 DevKit J1 (left) + J3 (right)
  ┌─────────────────────────────────────────────────────────────────────────┐
  │  Pin 1:  3V3  ◄────── Y-cable ──────┬────► SD Breakout VCC              │
  │                                     └────► GPS VCC                      │
  │  Pin 2:  RST   (do not connect)                                          │
  │  Pin 3:  GPIO2 (strapping – do not use)                                  │
  │  Pin 4:  GPIO3 (strapping – do not use)                                  │
  │  Pin 5:  GPIO0                                                           │
  │  Pin 6:  GPIO1  ◄──────────────────────── GPS PPS (optional)            │
  │  Pin 7:  GPIO6                                                           │
  │  Pin 8:  GPIO7  ◄──────────────────────── SD CS                         │
  │  Pin 9:  GPIO8  ◄──────────────────────── SD MISO (DO)                   │
  │  Pin 10: GPIO9  ◄──────────────────────── SD CLK (SCK)                   │
  │  Pin 11: GPIO10 ◄──────────────────────── SD MOSI (DI)                   │
  │  Pin 12: GPIO26 ◄──────────────────────── SD CD (optional)              │
  │  Pin 13: GPIO25 ◄──────────────────────── GPS PPS (alt; if not using 6)  │
  │  Pin 14: 5V     (do NOT use – would damage SD/GPS)                       │
  │  Pin 15: GND    ◄────── Y-cable ──────┬────► SD Breakout GND            │
  │                                       └────► GPS GND                    │
  └─────────────────────────────────────────────────────────────────────────┘
  ┌─────────────────────────────────────────────────────────────────────────┐
  │  J3 (right):  Pin 4 = GPIO24 (TX) ◄────── GPS RXD (optional)            │
  │               Pin 5 = GPIO23 (RX) ◄────── GPS TXD (NMEA from GPS)        │
  └─────────────────────────────────────────────────────────────────────────┘

Summary: Use Y-cables (or equivalent) on 3.3V (Pin 1) and GND (Pin 15) so the SD card and GPS each have their own lead from the ESP32-C5. Same 3.3V and GND rail, two physical wires per net.

Quick Wiring Reference

SparkFun microSD Breakout → ESP32-C5 DevKit

1. VCC   →  J1 Pin 1  (3V3)      [Left side, top; use Y-cable if also powering GPS]
2. GND   →  J1 Pin 15 (GND)      [Left side, bottom; use Y-cable if also powering GPS]
3. SCK   →  J1 Pin 10 (GPIO9)    SPI_CLK
4. DI    →  J1 Pin 11 (GPIO10)   SPI_MOSI
5. DO    →  J1 Pin 9  (GPIO8)    SPI_MISO
6. CS    →  J1 Pin 8  (GPIO7)    SPI_CS
7. CD    →  J1 Pin 12 (GPIO26)   Card Detect (optional)

Card Detect (CD) Logic

  • LOW (0V): Card is Inserted (default: CONFIG_SD_CD_ACTIVE_LOW=y)
  • HIGH (3.3V): Card is Removed (pin floats high with pull-up)

If your breakout uses inverted logic (HIGH = inserted), run idf.py menuconfig → ESP32 iperf Configuration → SD Card → uncheck Card Detect: LOW = inserted.

Breakout doesn’t support CD: Some SparkFun-style breakouts have a CD pad or through-hole that is not connected to the slot’s card-detect switch (the slot may not have a CD pin). If wiring is correct but status always shows REMOVED (or CD never changes), disable CD: idf.py menuconfig → ESP32 iperf Configuration → SD Card → set Card Detect GPIO to -1. The card will still mount and work; only insert/remove detection is disabled.

Pin Locations on ESP32-C5 DevKit

J1 (LEFT SIDE - Top to Bottom):

Pin 1:  3V3     ← VCC
Pin 2:  RST     (Reset - do not connect)
Pin 3:  GPIO2   (Strapping - do not use)
Pin 4:  GPIO3   (Strapping - do not use)
Pin 5:  GPIO0
Pin 6:  GPIO1   (GPS PPS - if used)
Pin 7:  GPIO6
Pin 8:  GPIO7   ← CS
Pin 9:  GPIO8   ← MISO (DO)
Pin 10: GPIO9   ← CLK (SCK)
Pin 11: GPIO10  ← MOSI (DI)
Pin 12: GPIO26  ← CD (optional)
Pin 13: GPIO25  (GPS PPS - if used)
Pin 14: 5V      (do not use - too high voltage)
Pin 15: GND     ← GND
Pin 16: NC      (No connection)

Important Notes

⚠️ Warnings:

  • Use 3.3V ONLY - Do NOT connect to 5V (Pin 14) - this will damage the microSD card!
  • ESP32-C5 does not have SDMMC host; SPI mode is required
  • CD is optional: LOW = inserted, HIGH = removed (with pull-up)

Current Configuration

The firmware is configured for SPI mode using:

  • CLK: GPIO9
  • MOSI: GPIO10
  • MISO: GPIO8
  • CS: GPIO7
  • CD: GPIO26 (optional)

Testing

After wiring, the firmware will automatically detect the SD card on boot. You should see:

I (xxx) sd_card: Initializing SD card via SPI...
I (xxx) sd_card: SD card mounted successfully at /sdcard
I (xxx) sd_card: SD card ready: XX.XX MB total, XX.XX MB free

If the card is not detected, check:

  1. All connections are secure
  2. Card is properly inserted in the breakout board
  3. Card is formatted (FAT32)
  4. Power supply is stable (3.3V)

Downloading files from the SD card

You can copy files off the SD card in two ways:

Over Wi‑Fi (HTTP)

When the device is on a network, an HTTP server listens on port 8080. Request a file with:

  • URL: http://<device-ip>:8080/sdcard/<path>
  • Example: http://192.168.1.100:8080/sdcard/log/data.txt

Use a browser or curl/wget to download. Paths are relative to the SD root; .. is not allowed.

Over serial (USB)

From the device console, run:

sdcard send <filename>

The firmware streams the file in a hex-encoded protocol. On the host, use the provided script (requires Python 3 and pyserial):

pip install pyserial
python3 tools/sdcard_recv.py -p /dev/ttyUSB0 -f myfile.txt -o saved.txt
  • -p / --port: serial port
  • -f / --remote: path of the file on the SD card
  • -o / --output: local path to save (default: basename of remote file)

Serial transfer is limited to 512 KB per file.

Device discovery (broadcast beacon)

When connected to Wi‑Fi, the device sends periodic UDP broadcast packets on port 5555 so a laptop on the same LAN can discover it. The payload is JSON:

{"ip":"192.168.1.73","mask":"255.255.255.0","gw":"192.168.1.1","dhcp":"OFF","mac":"3c:dc:75:82:2a:a8","fiwi_telemetry":true}
  • mac: Unique identifier per device (use for deduplication when many devices are present).
  • fiwi_telemetry: true if file fiwi-telemetry exists on the SD card, false otherwise.

Beacon interval is configurable in idf.py menuconfig → ESP32 iperf Configuration → Device discovery → Broadcast beacon interval (default 5 seconds).

On a Linux laptop:

Listen only (no download):

python3 tools/beacon_listen.py

Listen and download fiwi-telemetry from each device (files saved as fiwi-telemetry_<mac> in ./telemetry/):

python3 tools/beacon_listen.py --download --output-dir ./telemetry

Re-download every 60 seconds:

python3 tools/beacon_listen.py --download --output-dir ./telemetry --refresh 60

Devices are tracked by MAC address; each telemetry file is uniquely named.

Telemetry status file

Download stats (attempts, successful downloads) are written to telemetry-status on the SD card and persist across reboots. The file format:

attempts=10
downloads=8
---
1738857600 1234
1738857701 1235

Lines after --- are timestamp bytes (Unix epoch and bytes downloaded). View with:

sdcard read telemetry-status

Auto-delete option: In idf.py menuconfig → ESP32 iperf Configuration → Telemetry → enable Auto-delete fiwi-telemetry file after successful HTTP download to remove the telemetry file after each successful download.

fiwi-telemetry: monitor mode default

When you run monitor start, the firmware automatically writes MCS telemetry (frame rates, MCS indices, RSSI, PHY rates per device) to the fiwi-telemetry file on the SD card. The file is updated every 10 seconds while monitor mode is active. No extra configuration is needed—telemetry logging to fiwi-telemetry is the default behavior when monitor mode is running.

Troubleshooting

Card not detected:

  • Verify VCC is connected to 3V3 (Pin 1), NOT 5V
  • Check GND connection
  • Ensure card is properly seated in the breakout board
  • Try a different microSD card

Initialization fails:

  • Card may need formatting (FAT32)
  • Check for loose connections
  • Verify GPIO pins are correct
  • Some cards may not work in SPI mode - try a different brand

File system errors:

  • Card may be corrupted - reformat as FAT32
  • Check card capacity (very large cards may have issues)
  • Ensure proper power supply

CD always shows REMOVED but card works:

  • Your breakout or slot may not support Card Detect (CD pad may be unconnected). Disable CD: menuconfig → ESP32 iperf Configuration → SD Card → Card Detect GPIO = -1.