本节目标分清 SDIO 与 SPI 两种接法学会用 FATFS 挂载 TF 卡并用标准 C 文件 API 完成读写一、本节要解决的问题ESP32 自带几 MB Flash装完程序后剩下的空间有限而且数据不方便拿到电脑上。遇到记录日志、存图片、放音频等需求时最方便的方案就是插一张MicroSD/TF 卡。要让 ESP32 用上 TF 卡需要三层东西配合物理接口用 SDIO 还是 SPI 方式与卡通信文件系统卡上存的是 FAT 文件系统需要FATFS组件来解析统一接口ESP-IDF 通过VFS虚拟文件系统把 FATFS 挂到某个路径下之后就能用标准 C 的fopen/fread/fwrite操作卡上文件不必自己写扇区读写。二、硬件基础2.1 从 MMC 到 SD 卡MMCMulti-Media Card1997 年由西门子和 SanDisk 推出7 针引脚、体积小支持 1bit 模式SD 卡在 MMC 基础上发展而来向下兼容MMC 今天基本退出消费市场衍生出的eMMCBGA 封装、焊接在板上在嵌入式领域很常见SDIOSecure Digital Input and Output安全数字输入输出在 SD 卡接口基础上增加了低速 I/O 标准既能读卡也能连接蓝牙、WiFi、GPS 等 SDIO 外设。2.2 SDIO 与 SPI 两种接法MicroSD 卡同时支持 SPI 和 SDIO 两种通信模式本板/本工程用的是SDIO 4bit 模式对比项SDIO 模式SPI 模式信号线CLK、CMD、D0~D3 共 6 根CS、CLK、MOSI、MISO 共 4 根数据宽度1bit 或 4bit 并行固定 1bit速度快本工程 4bit、默认 20MHz相对慢受 SPI 时钟限制引脚使用 SDMMC 外设专用引脚性能最好任意 GPIO布线灵活挂载 APIesp_vfs_fat_sdmmc_mount()esp_vfs_fat_sdspi_mount()特殊限制D2/D0 等引脚与 ESP32 启动配置有关见 2.4无此类限制注意教程只实现了 SDIO 方式。如果以后引脚不够或布线不方便改成 SPI 方式时要把挂载函数换成esp_vfs_fat_sdspi_mount()其余文件操作代码不用改——VFS 已经把底层差异屏蔽掉了。2.3 ESP32 的 SDMMC 外设与卡槽ESP32 的 SDMMC 主机外设有两个卡槽每个卡槽都可以单独使用信号卡槽 0卡槽 1CMDGPIO11GPIO15CLKGPIO6GPIO14D0GPIO7GPIO2D1GPIO8GPIO4D2GPIO9GPIO12D3GPIO10GPIO13D4~D7GPIO16 / GPIO17 / GPIO5 / GPIO18无卡槽 0 的引脚GPIO6~GPIO11与 ESP32 模组内部 Flash 的引脚冲突所以实际只能用卡槽 1SDMMC_HOST_DEFAULT()的默认配置就是卡槽 1。注意MicroSD 卡的 CD 插入检测与 D3 引脚公用没有独立的 WP 写保护引脚所以检测卡是否插入要另想办法如定期尝试挂载。2.4 上拉与两个坑引脚SD 协议要求 CMD、D0~D3 接上拉电阻10K~90K。ESP32 内部带可编程上拉代码里用一个标志打开slot_config.flags|SDMMC_SLOT_FLAG_INTERNAL_PULLUP;教程作者踩过的两个坑板级设计要牢记D2 GPIO12如果外部接 10K 上拉ESP32 上电时会误判 Flash 供电为 1.8VGPIO12 是启动配置脚程序直接起不来官方解决办法是烧 eFuse 强制 3.3V本板选择不焊这个上拉D0 GPIO2如果外部接 10K 上拉会影响启动模式导致无法烧录程序。因此板子把 D0、D2 的外部上拉 NC 掉、改用内部上拉作者实测工作正常。注意这是作者实践结论官方注释也写明内部上拉不够、“仅用于调试/示例”。正式产品设计时上拉方案要结合自己的原理图和启动配置引脚一起评估不要直接照抄。三、知识点3.1 FATFS VFS挂载点挂载成功后卡上文件出现在 VFS 的某个目录下本工程是/sdcard后面所有路径都要带这个前缀例如/sdcard/hello.txt。挂载需要准备三样东西sdmmc_host_t用哪个主机外设、哪个卡槽、频率SDMMC_HOST_DEFAULT()默认卡槽 1、20MHzsdmmc_slot_config_t管脚配置与总线宽度SDMMC_SLOT_CONFIG_DEFAULT()默认 1bit本工程改成 4bitesp_vfs_fat_sdmmc_mount_config_t文件系统层面的参数。3.2 挂载参数的取舍esp_vfs_fat_sdmmc_mount_config_tmount_config{.format_if_mount_failedtrue,//挂载失败是否执行格式化.max_files5,//最大可打开文件数.allocation_unit_size16*1024//执行格式化时的分配单元大小分配单元越大读写越快};format_if_mount_failed true挂载失败就格式化。实验阶段方便空卡、格式不对都能自动处理但会把卡上原有数据清掉max_files 5最多同时打开 5 个文件每个打开的文件都占描述符和内存够用即可allocation_unit_size 16 * 1024格式化时的分配单元簇大小越大顺序读写越快小文件多时越浪费空间。四、代码分析4.1 工程结构sdcard/ ├── CMakeLists.txt ├── main/ │ ├── CMakeLists.txt # SRCS main.c │ └── main.c # 挂载 写/读/重命名 卸载 └── sdkconfig # 目标芯片 esp324.2 挂载准备 host / slot / mount_configsdmmc_card_t*card;constcharmount_point[]MOUNT_POINT;ESP_LOGI(TAG,Initializing SD card);ESP_LOGI(TAG,Using SDMMC peripheral);//默认配置速度20MHz,使用卡槽1sdmmc_host_thostSDMMC_HOST_DEFAULT();//默认的IO管脚配置sdmmc_slot_config_tslot_configSDMMC_SLOT_CONFIG_DEFAULT();//4位数据slot_config.width4;//不适用通过IO矩阵进行映射的管脚只使用默认支持的SDMMC管脚可以获得最大性能#if0slot_config.clkCONFIG_EXAMPLE_PIN_CLK;slot_config.cmdCONFIG_EXAMPLE_PIN_CMD;slot_config.d0CONFIG_EXAMPLE_PIN_D0;slot_config.d1CONFIG_EXAMPLE_PIN_D1;slot_config.d2CONFIG_EXAMPLE_PIN_D2;slot_config.d3CONFIG_EXAMPLE_PIN_D3;#endif// Enable internal pullups on enabled pins. The internal pullups// are insufficient however, please make sure 10k external pullups are// connected on the bus. This is for debug / example purpose only.//管脚启用内部上拉slot_config.flags|SDMMC_SLOT_FLAG_INTERNAL_PULLUP;被#if 0 ... #endif关住的是一段自定义 SDIO 引脚的示例CONFIG_EXAMPLE_PIN_*宏未定义所以保持关闭不经过 GPIO 交换矩阵、直接用 SDMMC 专用引脚才能获得最大性能slot_config.width 4表示启用 4bit 数据线这是 SDIO 比 SPI 快的主要来源挂载代码与错误处理ESP_LOGI(TAG,Mounting filesystem);retesp_vfs_fat_sdmmc_mount(mount_point,host,slot_config,mount_config,card);if(ret!ESP_OK){if(retESP_FAIL){ESP_LOGE(TAG,Failed to mount filesystem. );}else{ESP_LOGE(TAG,Failed to initialize the card (%s). Make sure SD card lines have pull-up resistors in place.,esp_err_to_name(ret));}return;}ESP_LOGI(TAG,Filesystem mounted);// Card has been initialized, print its propertiessdmmc_card_print_info(stdout,card);ESP_FAIL一般表示卡能通信但文件系统有问题其他错误码多是接线、上拉或卡本身的问题。4.3 读写文件标准 C API写文件和读文件各封装成一个函数用的全是标准 C 库接口staticesp_err_ts_example_write_file(constchar*path,char*data){ESP_LOGI(TAG,Opening file %s,path);FILE*ffopen(path,w);if(fNULL){ESP_LOGE(TAG,Failed to open file for writing);returnESP_FAIL;}fprintf(f,data);fclose(f);ESP_LOGI(TAG,File written);returnESP_OK;}staticesp_err_ts_example_read_file(constchar*path){ESP_LOGI(TAG,Reading file %s,path);FILE*ffopen(path,r);if(fNULL){ESP_LOGE(TAG,Failed to open file for reading);returnESP_FAIL;}charline[EXAMPLE_MAX_CHAR_SIZE];fgets(line,sizeof(line),f);fclose(f);// strip newlinechar*posstrchr(line,\n);if(pos){*pos\0;}ESP_LOGI(TAG,Read from file: %s,line);returnESP_OK;}写fopen(path, w)→fprintf→fclosefclose之后数据才可靠落盘读fopen(path, r)→fgets读一行 →fclose再把行尾的\n去掉后打印。主流程依次演示了 写、重命名、读、再写、再读、卸载constchar*file_helloMOUNT_POINT/hello.txt;chardata[EXAMPLE_MAX_CHAR_SIZE];snprintf(data,EXAMPLE_MAX_CHAR_SIZE,%s %s!\n,Hello,card-cid.name);rets_example_write_file(file_hello,data);constchar*file_fooMOUNT_POINT/foo.txt;// Check if destination file exists before renamingstructstatst;if(stat(file_foo,st)0){// Delete it if it existsunlink(file_foo);}// Rename original fileif(rename(file_hello,file_foo)!0){ESP_LOGE(TAG,Rename failed);return;}rets_example_read_file(file_foo);先写/sdcard/hello.txt内容是Hello 卡的 CID 名字!重命名前先用stat判断目标文件是否存在存在就unlink删掉再rename成/sdcard/foo.txt读回并打印再用同样方式写/sdcard/nihao.txt内容Nihao 卡名!并读回。注意教程与仓库代码的差异教程代码清单里没有给出s_example_write_file()/s_example_read_file()的实现只调用了它们仓库里两个函数完整存在见本节代码。另外仓库还多了一段被#if 0关掉的格式化示例esp_vfs_fat_sdcard_format()教程未提及。学习和引用时以仓库代码为准。4.4 卸载// All done, unmount partition and disable SDMMC peripheralesp_vfs_fat_sdcard_unmount(mount_point,card);ESP_LOGI(TAG,Card unmounted);卸载会把文件系统刷盘并释放 SDMMC 外设卸载后card句柄失效再访问/sdcard/...会失败。五、关键 API 速查API作用SDMMC_HOST_DEFAULT()生成默认 host 配置卡槽 1、20MHzSDMMC_SLOT_CONFIG_DEFAULT()生成默认管脚配置默认 1bitesp_vfs_fat_sdmmc_mount()初始化 SDMMC 并把 FATFS 挂到挂载点返回卡对象sdmmc_card_print_info()打印卡信息名称、容量、速度等esp_vfs_fat_sdcard_unmount()卸载文件系统并释放外设esp_vfs_fat_sdcard_format()格式化卡仓库中被#if 0关掉未启用fopen()/fprintf()/fgets()/fclose()标准 C 文件读写VFS 转发给 FATFSstat()/unlink()/rename()判断文件是否存在、删除、重命名六、编译与现象验证cdesp32-board/sdcard# 工程当前配置的目标就是 esp32idf.py build idf.py-pCOM端口flash monitor依次打印Initializing SD card、Using SDMMC peripheral、Mounting filesystem、Filesystem mounted然后是一段卡信息sdmmc_card_print_info的输出接着Opening file /sdcard/hello.txt、File written、Renaming file /sdcard/hello.txt to /sdcard/foo.txt、Read from file: Hello 卡名!再Opening file /sdcard/nihao.txt、Read from file: Nihao 卡名!最后Card unmounted。把卡插到电脑上能看到foo.txt和nihao.txt两个文件。