开始前适用开发板：ESP32-S3 Korvo · 开发框架：ESP-IDF
适用开发板：Korvo S3 · 工程
02.beginner.sdmmc_sd· targetesp32s3
学习时长：约 20 分钟 · 难度：★★☆☆☆
学习目标
完成本节后，你将能够：
- 理解 SDMMC 与 SPI 两种 SD 卡接口的区别
- 掌握 IDF 中
esp_vfs_fat_sdmmc_mount()挂载 SD 卡的方法 - 学会使用标准 C 文件操作（fopen/fwrite/fread）读写 TF 卡
- 为后续 AVI 录制、相册、录音存储打基础
1. 这个例子在干嘛
初始化 SDMMC 接口 → 挂载 TF 卡（FAT32 文件系统）→ 创建文件写入 → 读回验证 → 屏幕显示结果。
生活类比：把 U 盘插电脑，系统自动识别盘符，然后你可以复制文件——ESP32 对 TF 卡做的事一模一样。
┌──────────┐ SDMMC/SPI ┌──────────┐ VFS ┌──────────┐
│ TF 卡 │←──────────→│ ESP32-S3 │────────→│ 标准 C IO │
│ FAT32 │ 4-bit/1-bit│ SDMMC 驱动│ /sdcard │ fopen() │
└──────────┘ └──────────┘ │ fwrite() │
│ fread() │
└──────────┘
SDMMC vs SPI 模式
| 对比 | SDMMC 4-bit | SPI 模式 |
|---|---|---|
| 数据线 | 4 根（D0~D3） | 1 根（MOSI/MISO） |
| 速度 | 快（~40 MB/s） | 慢（~2 MB/s） |
| 引脚 | CLK+CMD+D0~D3 | CLK+MOSI+MISO+CS |
| ESP32 支持 | ESP32-S3 支持 | 全系列 |
| 适用 | 推荐（速度快） | 引脚紧张时备选 |
2. 编译烧录
cd Korvo_Firmware\02.beginner.sdmmc_sd
idf.py set-target esp32s3
idf.py build flash monitor
必须插入 TF 卡（建议 FAT32 格式）。
3. 运行现象
| 阶段 | 屏幕/串口 | 说明 |
|---|---|---|
| 挂载 | SD card mounted: /sdcard | 文件系统就绪 |
| 写入 | File written: hello.txt | 创建文件 |
| 读回 | Read back: Hello from ESP32! | 验证一致 |
| 卡信息 | Name: XX, Size: XX MB | 卡容量 |
| 卸载 | SD card unmounted | 安全拔卡 |
4. 关键 API
| API | 说明 |
|---|---|
esp_vfs_fat_sdmmc_mount("/sdcard", ...) | 挂载到 VFS 路径 |
fopen("/sdcard/hello.txt", "w") | 标准 C 文件操作 |
fwrite(buf, 1, len, fp) | 写入 |
fread(buf, 1, len, fp) | 读取 |
esp_vfs_fat_sdcard_unmount("/sdcard", card) | 安全卸载 |
5. 常见问题与排查
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| 挂载失败 | 卡未插 | 插入 TF 卡 |
| 挂载失败 | 非 FAT32 | PC 上格式化为 FAT32 |
| 挂载失败 | 卡接触不良 | 清洁触点，重新插入 |
| 写入失败 | 卡只读开关 | 关闭物理只读开关 |
| 写入慢 | 卡速度等级低 | 换 Class 10 / U1 卡 |
| 文件乱码 | 中文文件名 | FAT32 需启用 LFN |
6. 动手改造建议
- 遍历文件：列出 TF 卡所有文件（
opendir/readdir） - 大文件测试：写入 1MB 数据测速
- 日志记录：传感器数据定期追加写入 CSV 文件
- AVI 准备：录像需要 SD 卡，本例是前置基础
7. 知识延伸
- VFS 是什么：Virtual File System，IDF 提供的虚拟文件系统层。挂载后用标准 C 文件 IO（fopen 等）即可操作
- FAT32 限制：单文件最大 4GB，分区最大 32GB。超过用 exFAT（需额外支持）
- 磨损均衡：SD 卡内部有控制器自动做磨损均衡，不像裸 Flash 需要手动管理
- SPIFFS vs SD 卡：SPIFFS 在内部 Flash（几 MB），SD 卡在外部（几十 GB）
8. 下一步
| 方向 | 推荐例程 | 说明 |
|---|---|---|
| AVI 录制 | AVI Recorder | 视频写 SD |
| AVI 播放 | AVI Player | 从 SD 读 |
| 相册 | Photo Album | 图片管理 |
| P4C5 版 | P4C5 SD 卡 | 同原理 |
酷世DIY · Kevincoooool