## Exercise 13: SD Card Diagnostics

Dedicated SD hardware + software diagnostics for T-Beam Supreme.

This exercise is meant to isolate SD failures like:
- card only works after reinsertion,
- intermittent mount loss,
- one unit never mounts while others do,
- possible interconnect / socket / power rail issues.

### What it does

1. Uses the `startup_sd` watcher library from Exercise 12 for continuous card presence monitoring.
2. Logs PMU telemetry repeatedly:
   - BLDO1 (SD rail enable state)
   - VBUS voltage
   - battery voltage and battery-present flag
3. Samples SD SPI GPIO logic levels (`CS`, `SCK`, `MISO`, `MOSI`) at runtime.
4. Runs SPI idle-byte probes on both `HSPI` and `FSPI`.
5. Runs full mount matrix scans:
   - buses: `HSPI`, then `FSPI`
   - frequencies: `400k`, `1M`, `4M`, `10M`
6. Performs SD file I/O validation when mounted:
   - append to `/diag/sd_diag_probe.log`
   - flush
   - reopen and read back verification token
7. Every few cycles, power-cycles SD rail (BLDO1) and re-tests mount.
8. Shows live status on OLED and detailed logs on Serial.

### Build

```bash
source /home/jlpoole/rnsenv/bin/activate
pio run -e amy
```

### Upload (using your udev aliases)

```bash
source /home/jlpoole/rnsenv/bin/activate
pio run -e amy -t upload --upload-port /dev/ttytAMY
```

### Monitor

```bash
pio device monitor --port /dev/ttytAMY --baud 115200
```

### Interpreting key log lines

- `Mount OK bus=... hz=...`
  - SD stack works at that bus/speed.
- `Mount FAIL ...` on all combos
  - usually hardware path, socket contact, power rail, interconnect, or card format issue.
- `SPI probe ... ff=8`
  - typical idle/pull-up style response.
- `SPI probe ... zero=8`
  - suspicious: line stuck low/short or bus contention.
- `BLDO1=0` while testing
  - SD rail is off; card cannot function.
- `I/O FAIL` after mount success
  - media/filesystem instability or write path issue.

### Practical A/B troubleshooting workflow

1. Use one known-good SD card and test it in a known-good unit and Amy.
2. Compare whether `Mount OK` appears in both units.
3. If Amy never gets `Mount OK` but good unit does, suspect Amy hardware path.
4. Gently flex/reseat board stack while monitoring logs for mount transitions.
5. If behavior changes with pressure/reseat, interconnect/socket contact is likely root cause.