271 lines
13 KiB
Markdown
271 lines
13 KiB
Markdown
# 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:
|
||
|
||
```text
|
||
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`):
|
||
|
||
```bash
|
||
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:
|
||
|
||
```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):**
|
||
```bash
|
||
python3 tools/beacon_listen.py
|
||
```
|
||
|
||
**Listen and download fiwi-telemetry from each device** (files saved as `fiwi-telemetry_<mac>` in `./telemetry/`):
|
||
```bash
|
||
python3 tools/beacon_listen.py --download --output-dir ./telemetry
|
||
```
|
||
|
||
**Re-download every 60 seconds:**
|
||
```bash
|
||
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:
|
||
|
||
```text
|
||
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**.
|