# 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**.