# Exercise 19: SD Card Diagnostics

This exercise exists to develop and test a reusable SD card diagnostics library, `sdcard_diag`, under a simple sketch that prints the current card status to the serial console.

The immediate goal is operational: when a board in the field has an SD-related problem, the serial output from this exercise should help identify which card was installed and what the board could read from it at the time of the problem.

## What It Reports

The sketch prints:

- PMU and SD rail status
- SD pin map and pin levels
- SPI idle probe results for `HSPI` and `FSPI`
- Mount result and working SPI bus/frequency
- Card type and capacity
- Filesystem total, used, and free space
- Root directory summary and a few sample entries
- CID-derived identity fields:
  - `mid`
  - `manufacturer_guess`
  - `oem`
  - `product`
  - `revision`
  - `serial`
  - `date`
  - `CID raw`

## Important Certainty Boundary

The following fields are read from the card and should be treated as authoritative:

- `mid`
- `oem`
- `product`
- `revision`
- `serial`
- `date`
- `CID raw`

The `manufacturer_guess` field is not authoritative. It is a best-effort interpretation of `mid` using community-observed mappings. This matters because:

- the public SD documentation describes the `MID` field, but does not provide a public authoritative `MID -> vendor name` table
- counterfeit or reprogrammed cards may present misleading identity data
- some real cards may use manufacturer IDs not covered by the current lookup table

Also note the difference between a retail brand and a CID-reported card identity:

- the label printed on the card or the Amazon listing may identify a reseller, storefront brand, or private-label marketer
- the CID fields identify what the card itself reports electronically
- those two may match, but they do not have to match
- for troubleshooting, trust the printed `CID:` line and `CID raw:` more than marketplace branding

For issue work, always keep the full `CID:` line and the `CID raw:` line.

## Typical Output

```text
CID: mid=0x03 manufacturer_guess=SanDisk oem=SD product=SD32G revision=8.5 serial=0x2CC7ADB4 date=2025-12
CID raw: 03 53 44 53 44 33 32 47 85 2C C7 AD B4 01 9C 6B
```

That output usually tells you much more than a retail package label. Even if `manufacturer_guess` is `Unknown`, the remaining fields are still valuable for correlation.

## Build

From the repository root:

```bash
source /home/jlpoole/rnsenv/bin/activate
pio run -d exercises/19_SD_Card_diag/ -e cy
```

## Upload

```bash
source /home/jlpoole/rnsenv/bin/activate
pio run -d exercises/19_SD_Card_diag/ -e cy -t upload --upload-port /dev/ttytCY
```

## Monitor

```bash
date
source /home/jlpoole/rnsenv/bin/activate
pio device monitor -b 115200 --port /dev/ttytCY
```

## If `manufacturer_guess` Is `Unknown`

Use the following process:

1. Capture the full `CID:` line and `CID raw:` line from the serial log.
2. Use `mid`, `oem`, and `product` together when searching. `mid` alone is often not enough.
3. Compare the card against the references below.
4. If the card still cannot be identified, record the raw CID in the issue so the lookup table in `sdcard_diag` can be extended later.

Suggested search terms:

```text
SD CID MID 0xNN OID XX product YYYYY
```

or

```text
microSD CID 03 53 44 53 44 33 32 47 ...
```

## Reference URLs

These pages are useful when investigating an unknown or suspicious card.

Official SD/SD-3C references:

- SD Association Physical Layer Simplified Specification downloads page:
  `https://www.sdcard.org/downloads/pls/`
- SD Association simplified specification PDF referenced during development:
  `https://www.sdcard.org/cms/wp-content/themes/sdcard-org/dl.php?f=Part1_Physical_Layer_Simplified_Specification_Ver6.00.pdf`
- SD-3C home page:
  `https://www.sd-3c.com/Default.aspx`

Community and field-reference pages:

- IT-SD secure digital card registers:
  `https://www.it-sd.com/articles/secure-digital-card-registers/`
- Camera Memory Speed CID notes:
  `https://www.cameramemoryspeed.com/sd-memory-card-faq/reading-sd-card-cid-serial-psn-internal-numbers/`
- Zero Alpha SD technology explainer:
  `https://zeroalpha.com.au/services/data-recovery-blog/sd/secure-digital-sd-memory-card-technology-explained`

## Notes For Issue Assignees

- Treat `manufacturer_guess` as a clue, not proof.
- Treat `CID raw` as evidence.
- If the board mounts the card but CID parsing fails, retain the mount and filesystem details anyway.
- If a new legitimate `MID` is identified, update the lookup table in `lib/sdcard_diag/SdCardDiag.cpp` and add provenance for the new mapping.
