microReticulumTbeam/exercises/13_SD_Card_Diagnostics

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

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

Upload (using your udev aliases)

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

Monitor

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.