For LilyGo

exercises/13_SD_Card_Diagnostics/README.md

@@ -0,0 +1,71 @@
+## 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.