简介这是一套基于STM32F429的嵌入式综合工程源码面向需要将FatFS文件系统、SD卡存储与以太网TCP通信结合起来的开发者和学生。资源解决的核心问题是如何在嵌入式端接收网络数据并可靠地写入SD卡生成CSV文件适合做数据采集、日志记录或网络存储类项目的参考。资源包共1482个文件以c、h源文件为主并包含Keil工程配置、链接脚本、启动文件、STM32CubeMX工程文件及编译生成的axf、hex等文件各文件分工明确从底层驱动、中间件到应用层均有覆盖。压缩包总大小约59.43MB整体代码结构完整可直接导入工程进行二次开发。目前已有8000余人学习下载说明该资源在嵌入式网络存储方向有较高的参考价值。借助这份工程读者可快速理解SDIO/SPI方式驱动SD卡、FatFS挂载与文件写入流程同时掌握lwIP协议栈下的TCP服务器搭建思路并可直接基于现有代码修改数据格式与存储逻辑节省从零搭建环境的时间。1. 在 STM32 上让传感器数据直接落进 SD 卡从一个丢帧问题说起做小批量数据记录装置时我最怕的就是串口回传上位机丢帧。波特率调高、加校验、分帧重发折腾一圈数据仍然会断而且这依赖上位机在线一旦中途断电采样记录全部作废。后来我直接把 FatFS 文件系统移植到 STM32 上把 SD 卡当成“黑匣子”传感器原始数据按行写成 .csv 文件上位机离线也能连续记录几天不丢。这篇文章把从底层驱动到文件生成的完整链路拆开讲清楚SDIO 还是 SPI 怎么选、ffconf.h 里该开哪些宏、CSV 写盘为什么慢、Excel 打开怎么会乱码以及我踩过的几个看着玄学、其实是时序和缓存问题的坑。适合正在做数据采集、环境监测、离线记录仪手里有 STM32 开发板想直接复现的人。2. 底层存储选型SDIO 与 SPI 的取舍和驱动初始化2.1 两种接法的工程差异SD 卡和 STM32 之间最常见的两种物理接口是 SDIO 和 SPI。它们决定了你能写多快、占多少引脚、以及调试时有多痛苦。SDIO 四线模式使用 CLK、CMD 加四条数据线D0-D3理论吞吐量在几十 MB/s 级别。实际用 STM32 的 SDIO 外设加 DMA写速度做到 3-5 MB/s 完全没有问题。代价是引脚占用多PCB 上四根数据线的等长和电平匹配要考虑而且 SDIO 协议的时序比 SPI 复杂。SPI 模式则只需要 CS、SCK、MOSI、MISO 四根线几乎所有带 SPI 外设的 STM32 都能用代码也简单但单线传输典型写速度在 300 KB/s 到 1 MB/s 之间取决于时钟分频。我的选择标准其实很朴素如果采集频率低每秒写几十个浮点数8 KB/s 都不到SPI 模式就绰绰有余还能省引脚。如果要做音频采样、连续高速 ADC 记录建议直接上 SDIO DMA否则底层传输会成为瓶颈。下表是两种模式的关键差异对比项SDIO 4bitSPI引脚占用6 个左右4 个典型写速度3-10 MB/s300 KB/s-1 MB/s代码复杂度较高时序敏感简单稳定CubeMX 支持需配置 SDIO 外设直接配置 SPI 外设低速率备用卡兼容性一般兼容性好许多劣质卡也能识别很多开发板默认把 SD 卡座接到 SPI原因就是接线简单。但注意SPI 模式下 SD 卡初始化有一个硬性要求初始化时钟不能太高通常控制在 400 kHz 以下等卡识别完成后再把时钟切到高速。这个时序顺序错了卡要么返回超时要么直接不响应。2.2 CubeMX 里的配置顺序在 CubeMX 中先把 SDIO 或 SPI 外设打开、引脚分配好、DMA 通道加上再生成代码。我习惯把 FCLK 先设置到 24 MHz后续出问题再往下调。SPI 模式则是 Speed Low 初始化传输时再切换 High。还有一个常被忽略的点SD 卡座的中断检测引脚。CubeMX 默认不会自动配 CDCard Detect引脚如果不检测卡插入直接 f_mount 会在上电时返回 FR_NOT_READY。我一般把 CD 引脚配成 GPIO 输入拉低表示有卡软件里先检查它再挂载。开发板正好引出这个引脚的建议在配置里把它勾选进去后面能省很多排查时间。具体到代码层SDIO 初始化流程由 HAL 生成不需要手动改写太多。真正需要确认的是 SDMMC 时钟源是否来自正确的外设时钟以及 DMA 中断优先级不要和 FatFS 的临界区冲突。CubeMX 生成的 SD 初始化函数一般长这样void MX_SDMMC1_SD_Init(void) { hsd1.Instance SDMMC1; hsd1.Init.ClockEdge SDMMC_CLOCK_EDGE_RISING; hsd1.Init.ClockPowerSave SDMMC_CLOCK_POWER_SAVE_DISABLE; hsd1.Init.BusWidth SDMMC_BUS_WIDE_4B; hsd1.Init.HardwareFlowControl SDMMC_HARDWARE_FLOW_CONTROL_ENABLE; hsd1.Init.ClockDiv 4; /* 24MHz / (2*4) 附近 */ if (HAL_SD_Init(hsd1) ! HAL_OK) { Error_Handler(); } if (HAL_SD_ConfigWideBus(hsd1, SDMMC_BUS_WIDE_4B) ! HAL_OK) { Error_Handler(); } }参数说明ClockDiv 为 4 时SDMMC 时钟是外设时钟的约 1/8低速卡也能稳定响应BusWidth 在初始化完成再切换成 4 线和协议要求一致。如果跑高速时钟始终不行可以往 2 调但建议先用 4 验证功能再逐步提速。一个容易被忽略的现象如果 SDIO 时钟线过长、走线紧挨着电源线翻车高速时偶发 CRC 错误是常态。遇到这种问题先别怀疑代码把时钟降到 12 MHz 再跑错误消失就是信号完整性问题不是软件问题。这是我在一块手焊板上吃过的亏。2.3 底层驱动的接口验证移植 FatFS 之前先验证底层能正确读卡。我写了一个不带文件系统的裸驱动测试直接踩 SDIO 命令读卡 CSD 寄存器打印卡容量和扇区数。这个步骤别跳省得后面文件系统出问题时分不清是底层还是上层问题。HAL_SD_CardInfoTypeDef card_info; HAL_SD_GetCardInfo(hsd1, card_info); printf(CardType%u, BlockSize%u, BlockNbr%lu\n, card_info.CardType, card_info.BlockSize, card_info.BlockNbr);正常逻辑下能读到 BlockNbr15155200 之类的值说明卡识别成功。读不到时看 HAL_SD_GetCardState 返回值如果一直停在 SDMMC_CARD_TRANSFER多半是时钟或供电问题。注意不少 TF 卡座是 3.3V 供电如果板子上电平标准不一致初始化反复失败。我习惯用万用表量卡座 VDD 对地电压3.0V 以下直接换电源方案这比任何代码排查都见效快。3. FatFS 接入ffconf.h 开关、挂载和目录管理3.1 源码文件组织与 diskio 层FatFS 的源码组织很清爽常见版本结构是把 ff.c、ff.h、diskio.c、diskio.h、ffconf.h 放进 Middlewares 目录。真正需要自己改的就一个 diskio.c。它是 FatFS 和 STM32 底层之间的适配层里面需要实现六七个函数disk_status、disk_initialize、disk_read、disk_write、disk_ioctl、Get_Fattime。我一般会在 disk_ioctl 里把 GET_BLOCK_SIZE、GET_SECTOR_SIZE 都做出来因为 f_mkfs 格式化时要用这些参数缺了 FatFS 会按默认值处理有些卡会格式化成奇怪的簇大小写入性能很差。disk_write 函数里还要注意FatFS 一次请求写入的扇区可能是连续的也可能跨四个扇区底层直接调用 HAL_SD_WriteBlocks 即可但要求传入的 buffer 最好是 4 字节对齐的否则 DMA 传输会触发硬件错误。常见做法是在函数开头加一句断言DRESULT disk_write(BYTE pdrv, const BYTE *buff, LBA_t sector, UINT count) { if (pdrv ! 0) return RES_PARERR; if ((uint32_t)buff % 4 ! 0) return RES_PARERR; /* DMA 对齐 */ while (HAL_SD_GetCardState(hsd1) ! SDMMC_CARD_TRANSFER); if (HAL_SD_WriteBlocks(hsd1, (uint8_t *)buff, sector, count, 1000) ! HAL_OK) { return RES_ERROR; } return RES_OK; }参数说明循环等待卡状态是防止 DMA 还没完成就发下一笔写请求超时 1000 ms 按卡最慢情况留足余量。这里最容易翻车的是把 buff 转成 uint8_t* 后直接交给 HALHAL 内部用 DMA 访问该地址如果 malloc 出来的缓冲区不对齐跑一段时间就会出现偶发的数据写错位置。3.2 ffconf.h 里必须开的开关FatFS 的所有功能开关都集中在 ffconf.h。这里我踩过的坑有几个第一个是 FF_USE_LFN默认是关的只支持 8.3 短文件名。如果你的文件名是 data_20250101.csv 这种长名不打开 LFNopen 直接返回 FR_INVALID_NAME。第二个是 FF_USE_MKFS要做格式化就要把它打开。第三个是 FF_USE_STRERROR打开后能用 f_strerror 看错误码对应文案调试时极其重要别省。我常用的一组配置配置宏设置值说明FF_USE_LFN1长文件名支持用堆栈保存FF_USE_MKFS1允许格式化操作FF_USE_STRERROR2错误码转字符串FF_USE_FIND1支持遍历文件名FF_MAX_SS4096支持 4K 扇区卡FF_FS_RTOS1开启线程安全有 RTOS 时FF_VOLUMES1单卷即可值得说明的是 FF_MAX_SS 和 FF_USE_LFN 会直接影响 RAM 占用。FF_MAX_SS 设成 4096 后FatFS 内部工作缓冲会相应变大而且 FF_USE_LFN1 时每个文件对象默认带一个 LFN 缓冲多个文件对象会吃掉好几 K RAM。如果芯片 RAM 紧张可以把 FF_LFN_BUF 调小或者从堆栈缓冲改到动态内存分配。3.3 挂载、格式化与目录创建的执行顺序挂载流程有坑全新的卡没有文件系统f_mount 第一次调用时返回 FR_NO_FILESYSTEM 是正常现象。正确做法是先 f_mount 注册卷失败后再 f_mkfs 格式化格式化完还得重新 f_mount 一次。FATFS fs; FRESULT res; res f_mount(fs, 0:, 1); if (res FR_NO_FILESYSTEM) { res f_mkfs(0:, FM_FAT | FM_SFD, 0, work_buf, sizeof(work_buf)); if (res ! FR_OK) printf(mkfs fail: %s\r\n, f_strerror(res)); res f_mount(NULL, 0:, 0); /* 先卸载 */ res f_mount(fs, 0:, 1); /* 重新挂载 */ } if (res ! FR_OK) printf(mount fail: %s\r\n, f_strerror(res)); res f_mkdir(0:/DATA); if (res ! FR_OK res ! FR_EXIST) printf(mkdir fail: %s\r\n, f_strerror(res));逻辑说明第一次挂载只用注册卷f_mount 的第二个参数是路径第三个参数 1 表示立即挂载。格式化后必须先卸载再挂载否则卷状态还是旧的。f_mkdir 返回 FR_EXIST 表示目录已在不算错误不用 panic。有个细节f_mkfs 的 work_buf 至少一个扇区大小我直接开了 4096 字节数组。格式化时如果卡的整卡容量大于 2 GB建议用 FM_FAT 而不是 FM_FAT32虽然在最新 FatFS 版本中 FM_FAT 会自动选择 FAT12/16/32但手动指定能避免一些非常规卡的分区表诡异问题。还有一点容易忽略SD 卡不是硬盘没有坏道管理FatFS 对卡上已有的坏块无能为力。格式化之前最好先把卡在电脑上慢速格式化一遍确认全卡可读再让 STM32 接管。把新卡快速格式化后直接插到设备上遇到物理坏块会表现为随机写入失败且错误码不稳定这块只能靠测试卡质量解决。4. CSV 写盘字符串转换、缓冲和同步的三个关键点4.1 避开 sprintf 的浮点坑CSV 文件一行本质上是一个字符串比如2025-08-01 10:23:45,23.54,65.2。很多新手直接用 sprintf 拼行第一个坑就在浮点格式化ARM 默认的 printf 系函数对 float 支持可能被裁剪输出可能出现空白或 0.00。而且 sprintf 处理浮点会引入相当大的代码量和耗时数据采集场景中每次采样都做一次浮点格式化并不划算。我一般把浮点数拆成整数部分和小数部分自己拼字符串void format_float(char *buf, float val, int prec) { int neg 0; if (val 0) { neg 1; val -val; } long ipart (long)val; long frac (long)((val - ipart) * 100); /* 保留两位 */ if (neg) *buf -; ipart_to_str(buf, ipart); buf strlen(buf); *buf .; frac_to_str(buf, frac); }逻辑说明先取整数部分再乘 100 取小数部分避免了浮点格式化库的依赖。参数 prec 控制保留位数我按实际传感器精度选 2 位或 3 位。注意乘 100 又 1000 会导致溢出或者进位误差比如 23.549 变成 23.54 和 23.55 的行为不同这个误差在数据记录场合可接受但如果你要写高精度原始值直接按整数存别用浮点拼文件。另一个更省事的办法把 ADC 原始值或者传感器寄存器原始值直接以整数写入 CSV上位机再做标定转换。这样既避开了浮点误差也让文件大小可控。4.2 批量写缓冲与 f_sync 的节奏FatFS 的 f_write 每次调用并不仅仅写几个字节它需要维护 FAT 表和目录项频繁小文件写入会让 FAT 表反复读改写速度会掉到十几 KB/s。所以我坚持用固定大小的缓冲区积累数据攒够 512 字节或更多再一次性 f_write。这个习惯让写速稳定提升也让卡上磨损更均匀。char line_buf[96]; uint8_t sd_buf[1024]; uint16_t sd_len 0; memset(line_buf, 0, sizeof(line_buf)); snprintf(line_buf, sizeof(line_buf), %lu,%d,%d\r\n, timestamp, adc1, adc2); memcpy(sd_buf[sd_len], line_buf, strlen(line_buf)); sd_len strlen(line_buf); if (sd_len 1000) { UINT bw; f_write(file, sd_buf, sd_len, bw); if (bw ! sd_len) printf(write partial\r\n); sd_len 0; }逻辑说明每行文本先落到 sd_buf等 sd_len 接近缓冲上限再写盘。f_write 的第三个参数是写入字节数第四个参数是返回的实际写入字节数两者不等只能说明介质有问题正常不会发生。这里的缓冲大小 1024 字节刚好覆盖两个扇区配合 FatFS 内部缓冲效率最好。f_sync 是关键中的关键。它把 FatFS 内部缓冲刷到 SD 卡同时更新目录项。每一条数据都 f_sync 一次会慢到崩溃但我建议最迟每攒满一个缓冲块就 f_sync 一次这样掉电最大可能只丢最后一小段数据。掉电后文件出现 0 字节的教训多数就是没做过 f_sync。4.3 让 Excel 直接打开不乱码CSV 文件用 Excel 打开出现中文乱码核心原因是文件编码。SD 卡里存的是 UTF-8 文本而 Windows 的老版本 Excel 默认按 ANSI 读取。解决办法是在文件开头写三个字节的 UTF-8 BOM0xEF 0xBB 0xBF。老版本的 Excel 看到 BOM 会识别为 UTF-8。STM32 侧只需在第一次打开文件时把这三字节写进去。uint8_t bom[3] {0xEF, 0xBB, 0xBF}; UINT bw; f_write(file, bom, 3, bw);这个技巧看着小但很影响交付体验。数据文件生成后直接发给同事、拖进 Excel 就能看就不会有人来问你为什么中文是乱码。如果完全没有中文内容BOM 也可以不加纯 ASCII 的 CSV 在任意平台兼容性一致。另外在 CSV 里如果字段本身包含逗号、引号需要按 RFC 4180 把该字段用双引号包起来。SD 卡日志里最常遇到的是设备序列号或地址里带逗号这个要提前转义不然后续数据分析时列会错位。5. 排查实录挂载失败、写速慢、文件乱码的五处坑5.1 挂载返回 FR_DISK_ERR 但初始化成功现象HAL_SD_Init 正常卡容量也能读到但 f_mount 返回 FR_DISK_ERR。原因多半是 FatFS 在读写测试时底层返回了错误比如 clock divider 太高导致读取 CRC 失败或者 DMA 的缓冲区没有对齐。解决思路是先在 disk_initialize 里加打印确认 HAL_SD_ReadBlocks 指定扇区能成功再挂载。我遇到过一块 128G 卡SDIO 24MHz 下 mount 成功但读取目录报错把 ClockDiv 从 4 调到 8 后完全正常。5.2 写入到一半文件大小为 0现象采集了几个小时掉电重启后 CSV 文件存在但大小为 0。原因是没有执行 f_syncFatFS 的目录项更新只存在内存里掉电全部丢失。解决每满一个缓冲块执行一次 f_sync并确认 f_close 前再次 sync。这个坑我栽过两次后来直接把 f_sync 封装在写缓冲函数末尾。5.3 文件名太长或非法字符导致 open 失败现象f_open 返回 FR_INVALID_NAME但文件名明明看上去合法。原因可能是 FF_USE_LFN 未开启也可能是文件名用了冒号、斜杠这些在 FatFS 里有特殊含义的字符。解决确保文件名的合法字符只包含字母、数字、下划线、短横线时间戳建议按 YYYYMMDD_HHMMSS 拼不带冒号。5.4 Excel 打开 CSV 中文全乱码现象电脑上用记事本打开正常Excel 打开全是乱码。这个和 4.3 节对应原因就是没有 BOM。解决方式已在前面给出写文件开头三个字节。如果已经生成了一堆没有 BOM 的文件可以写一个上位机小工具批量加 BOM不用再回采一次数据。5.5 快写时文件内容偶发错位现象写入速度提到几百 KB/s文件里偶发出现几行数据顺序错乱甚至出现重复块。原因多半是 DMA 传输和 FatFS 缓冲区复用冲突。如果开启了 D-Cache还需要做 cache clean 操作。解决第一将传输缓冲申请成 4 字节对齐第二使用 DMA 时在写操作前调用 SCB_CleanDCache()。我在某项目里就因为没有做 cache clean快速连续写入时文件数据整个乱掉排查了两天才定位到这个问题。6. 进阶用法日志循环覆盖与网口联动取数6.1 按文件名滚动记录连续记录设备最怕 SD 卡写满。一个简单方案是按日期命名文件每天一个新文件并配合固定最大文件数做滚动删除。常见做法是在初始化时遍历 DATA 目录统计文件个数超过上限就删除最旧的。DIR dir; FILINFO fno; f_findfirst(dir, fno, 0:/DATA, *_*.csv); do { count; } while (f_findnext(dir, fno) FR_OK count MAX_FILES);这段遍历逻辑可以配合 FF_USE_FIND 开关。删除最旧文件前先记录它的文件名再用 f_unlink 删掉。注意删除操作尽量在非采集时段做否则 FAT 表更新会占用写带宽。这样设备就能长期运行不会因为卡满而罢工。6.2 用 RTC 做采样时间戳CSV 每行都写一个时间戳对后续数据分析价值很大。STM32 的 RTC 可以提供秒级时间戳使用 HAL 获取时间后格式化成YYYY-MM-DD HH:MM:SS。注意 RTC 的初始日期必须校准否则生成的 CSV 时间轴是错的。我在代码里保留了一个 RTC 校时命令设备上电后通过串口或者网络设置时间再开始记录数据。6.3 联动 TCP 服务器远程取数据如果设备带了以太网可以在采集之外加一个轻量 TCP server接收上位机的读取请求把指定 CSV 文件通过 socket 发送出去。实现上不需要引入复杂的 HTTP 协议直接在 TCP 回调里根据命令返回文件名加内容。static void tcp_send_file(int sock, char *fname) { FIL file; UINT br, bw; f_open(file, fname, FA_READ); while (f_read(file, buf, sizeof(buf), br) FR_OK br 0) { tcp_write(sock, buf, br, 1); } f_close(file); }这个做法的价值在于SD 卡记录的同时也能通过网络接口把最近一段数据拉回来分析不用拔卡。配合 lwIP 的 TCP 协议栈整个逻辑不算复杂。要注意的坑是 TCP 回传期间避开 SD 卡的写操作否则写卡和读文件争用总线速度都会受影响。从那以后我每次给板子加 SD 卡记录功能都会强制走一遍四关低速写单文件、高速连续写、运行中直接掉电、反复 mount四关全过才敢交给采集流程。如果这篇文章里的某个坑能帮你省下半天排查时间那它就算起作用了。希望帮到你。本文还有配套的精品资源点击获取