Cross-platform SD card workflow (macOS support)

[mbreiser]

Summary

Enable SD card preparation on macOS. Currently prepare_sd_card.m uses Windows-specific path handling, preventing develop-on-Mac, run-on-Windows workflow.

Tasks

• Research macOS FAT32 formatting tools
• Test prepare_sd_card.m on macOS (identify path handling issues)
• Update path handling for cross-platform compatibility
• Consider if git-based experiment organization reduces need for cross-platform SD copying

Context

We develop/test on Mac but always run experiments on Windows. FAT32 directory entry behavior may differ across platforms.

Related

• Issue Update experiment creation to use prepare_sd_card #7 (Update experiment creation to use prepare_sd_card)

[taylorlm88]

There is a file under maDisplayTools/testing called prepare_sd_card_crossplatform.m that I created to make it possible to test the other sd related code I'd written on my mac, but critically I was not using an SD card so compatibility issues with the format or saving of the patterns onto the SD card itself are likely not addressed in it. Another issue that might pop up is Mac saving hidden files on the SD card that might mess up the indexing.

[taylorlm88]

If it's helpful to you, I went back to the claude chat that made the original changes to make prepare_sd_card.m work on my mac and had it implement updates that deals with the actual formatting of the sd card, hidden files, and other mac issues that might occur in real life implementation. Attached is a document discussing these issues that might be useful to you.

CROSSPLATFORM_UPDATES.md

[mbreiser]

Mac SD Card Investigation — Final Results (Mar 9, 2026)

mkfs.fat (dosfstools) test

Hypothesis: macOS newfs_msdos produces FAT32 metadata that differs from what the G4.1 firmware expects. Tested with Linux-style mkfs.fat from Homebrew dosfstools.

Test 1 — Default mkfs.fat:

sudo mkfs.fat -F 32 -n PATSD /dev/disk4s1

Copied 16 reference patterns, dot_clean -m, fatsort. Result: FAILED on controller.

BPB (Boot Parameter Block) comparison

Dumped and compared the FAT32 boot sector from a working Windows card vs the Mac mkfs.fat card:

Field	Windows (works)	Mac mkfs.fat (fails)
OEM Name	MSDOS5.0	mkfs.fat
Reserved Sectors	2362	32
Hidden Sectors	2048	0
Data Start Sector	32,768 (aligned)	30,448 (unaligned)

Test 2 — mkfs.fat with Windows-matching geometry + OEM patch:

sudo mkfs.fat -F 32 -n PATSD -R 2362 -h 2048 -s 8 /dev/disk4s1
printf 'MSDOS5.0' | sudo dd of=/dev/disk4s1 bs=1 seek=3 count=8 conv=notrunc

After patching, BPB nearly identical to Windows (Hidden Sectors matched, OEM matched, data start off by only 16 sectors). Copied patterns, cleaned, fatsorted. Result: STILL FAILED on controller.

Conclusion

Mac cannot prepare SD cards for the G4.1 controller, regardless of:

• Copy method (cp, cp -X, COPYFILE_DISABLE, cat, dd, ditto, Python shutil)
• Cleanup (dot_clean, fatsort)
• Format tool (diskutil/newfs_msdos, mkfs.fat/dosfstools)
• BPB geometry (default or Windows-matched with OEM patch)

The remaining differences are .Spotlight-V100 (kernel-level, undeletable) and possibly subtle FAT32 directory entry metadata that macOS adds during mount. The root cause is likely in how macOS writes to FAT32 at the kernel level, not in the formatting tool or copy method.

Recommendation: Format and deploy SD cards on Windows or Linux only. Long-term fix: firmware update to use filename-based access instead of dirIndex.