做嵌入式开发的朋友应该都有过这种经历：设备跑起来了，想把里面的数据导出来，要么串口慢慢拉，要么SD卡拔来拔去，既慢又容易出问题。2018年5月我做了一个基于STM32的USB OTG工程，目标非常明确——让STM32通过USB OTG接口直接读取U盘里的文件，设备需要更新配置或者导出日志时，插上U盘就能搞定，整个过程不需要上位机，也不需要额外的读卡器。这篇博客就来完整拆解这个“STM32 USB OTG读取U盘文件系统”工程的搭建过程，包括硬件选型、CubeMX配置、FatFS移植、代码实现和踩坑实录，适合正在做USB Host、想要让MCU直接读写U盘的朋友参考。
1. 项目背景与整体思路
1.1 为什么要在STM32上直接读U盘
先说清楚这个项目的实际需求。当时手头的设备是一个数据采集终端，每天会产生一批日志文件和参数记录。原来的方案是把数据存到板载Flash里，需要导出时通过串口发给电脑，量大时差不多要等十几分钟，用户体验很差。后来想换成SD卡方案，但SD卡需要额外的卡座，用户手里不一定有，而且拔卡插卡容易损坏卡座。
U盘方案就顺理成章了。U盘是通用存储设备，基本人手一个，插上USB口就能识别，不需要额外硬件，设备外壳开个USB座的口就行。而且U盘的读写速度相比串口有数量级的提升，一个10MB的日志文件，串口115200bps大概要拉十几分钟，U盘方式几秒钟就完成了。
当时对比过几个方案，我简单列了个表格：
| 方案 | 优点 | 缺点 |
|---|---|---|
| SD卡 + FatFS | 体积小、速度快 | 需要专用卡座，用户操作不便 |
| 串口传输 | 实现简单 | 速度慢，需要PC端配合 |
| 网络传输 | 无需复杂线缆 | 硬件成本高，配置麻烦 |
| U盘 + USB OTG | 通用性强、热插拔、速度快 | USB协议栈复杂，兼容性问题多 |
最终选了U盘方案，核心原因就一个：通用性。用户不需要学习任何操作，手边有U盘就能用，这对现场维护来说太重要了。
1.2 整体架构与工作流程
整个工程分成四个层次，从下到上依次是：硬件层、USB Host库、FatFS文件系统、应用层。
硬件层就是STM32芯片内置的USB OTG控制器，加上外部U盘的物理连接。中间层是STM32CubeMX生成的USB Host库，它负责跟U盘通信，处理USB协议栈里和MSC（Mass Storage Class）相关的部分。再往上，FatFS负责将U盘的裸扇区转换成我们熟悉的文件操作接口，f_open、f_read、f_write。最上面就是自己的应用逻辑，比如读取配置文件、写日志等。
工作流程大概是这样的：STM32上电后初始化USB Host控制器，然后开始检测U盘是否插入。当检测到U盘时，USB Host库会自动完成枚举过程，识别设备类型。识别为MSC大容量存储设备后，U盘就变成了一个可用的块设备。此时应用层调用FatFS的挂载函数，把FAT文件系统挂载到U盘上，之后就可以像直接用PC操作U盘一样读写文件了。
这个分层架构的优点是职责清晰，每一层只关注自己的事。USB Host库不需要理解什么是文件，FatFS只需要把扇区抽象成文件和目录，应用层不需要关心U盘的底层协议，大大降低了开发难度。我不用从零实现USB协议栈，也不用手动解析FAT表，这几百行代码量省得相当值。
2. 硬件接口与协议基础
2.1 STM32 OTG硬件特性与接线
当时用是STM32F407VET6，这颗芯片内置了USB OTG_FS控制器，引脚是PA11（OTG_FS_DM）和PA12（OTG_FS_DP），支持USB 2.0全速（12Mbps）速率，自带FS PHY，不需要外部PHY芯片，硬件设计非常省事。这里说的FS是Full Speed，也就是12Mbps，不是480Mbps的USB 2.0高速，对于读取U盘文件这种场景，12Mbps的实际传输速率在1MB/s左右，虽然不算快，但完全够用。
接线方面，USB座的D+接PA12，D-接PA11，VBUS接5V，GND接GND，看起来很简单，但有一个坑：U盘工作电流可能达到几百毫安，开发板自带的USB座如果直接从板载3.3V LDO取电，大概率带不动U盘。我当时的做法是用一个电源控制开关（比如STM32F4开发板上常见的NCP380或类似芯片），由GPIO控制U盘VBUS的通断，供电直接从5V电源轨拉。
这里分享一个经验：U盘枚举失败的第一大原因就是供电不足。如果U盘插上去完全没反应，先量一下VBUS电压是不是5V，再量一下D+/D-的对地电阻，全速设备D+上应该有1.5kΩ上拉到3.3V，没有上拉就说明PHY没有正常工作。
2.2 USB枚举与MSC协议简述
虽然USB Host库把协议细节都封装好了，但理解基本原理对排查问题非常有帮助。USB设备接入后，主机端要完成一系列枚举动作：
- 检测设备插入：U盘上电后，内部会在D+线上拉一个1.5kΩ电阻（全速设备），主机检测到D+电平变化，就知道有设备插入了。
- 设备复位：主机将D+/D-拉到低电平至少10ms，让设备复位，进入默认地址0状态。
- 设置地址：主机发送SET_ADDRESS请求，给设备分配一个唯一地址。
- 读取描述符：主机读取设备描述符、配置描述符、接口描述符、端点描述符等，获取设备的基本信息。
- 配置设备：主机发送SET_CONFIGURATION请求，让设备进入配置状态。
- 开始数据传输：配置完成后，设备和主机之间通过批量端点（Bulk Endpoint）进行数据交换。
MSC（Mass Storage Class）协议是基于Bulk-Only Transport（BOT）的，简单理解就是主机发送命令块（CBW），设备执行后返回状态块（CSW）。每个CBW是31字节，包含命令标签和具体的SCSI命令（比如READ CAPACITY、READ 10、WRITE 10等）。比如读取一个扇区，主机发送一个READ CAPACITY命令获取U盘总容量，然后发送READ 10命令指定起始扇区和长度，数据通过Bulk端点返回，最后设备返回一个CSW告诉主机命令执行成功或失败。
这套协议栈的逻辑其实很像快递流程：CBW就是快递单，上面写清楚了要做什么（取件还是送件）、从哪里取（起始扇区）、取多少（扇区数），CSW就是回执单，告诉快递公司这个单子执行成功了。理解了这个流程，之后排查“U盘能识别但读不出数据”这种问题就方便多了，至少能判断是卡在命令阶段还是数据阶段。
3. CubeMX工程配置实战
3.1 时钟树与引脚配置
第一步是配置系统时钟。USB控制器必须工作48MHz，这个频率可以由PLLQ或HSI48提供。我用的是外部8MHz晶振，系统主频跑168MHz，APB1是42MHz，APB2是84MHz，PLLQ设置为48MHz给USB使用。在CubeMX的Clock Configuration界面里，把“48MHz CLOCK”的来源选为PLLQRC，并确认输出是48MHz即可。
时钟配置错了会出现一个很经典的现象：U盘偶尔能识别，但速度异常慢，或者经常报告数据错误。这是因为USB的位同步依赖于准确的48MHz时钟，偏差超过一定范围就无法正常通信。
引脚配置相对简单，CubeMX会自动分配PA11/PA12给USB功能。需要注意的是，如果你的板子VBUS电源开关由GPIO控制，需要在GPIO_Init中手动配置这个引脚为推挽输出，并默认输出高电平（使能供电）。我在刚开始调试时忘了这个设置，导致U盘一直没有供电，枚举卡在“设备插入检测”阶段，白白排查了很久。
3.2 中间件组件配置
CubeMX配置USB Host主要有两个地方：
第一个是USB_OTG_FS，在“Connectivity”菜单下，将Mode改为“Host Only”，速度选择Full Speed。这里不要去选“Device Only”或“Host/Device dual role”，我们这个项目只需要Host功能。
第二个是USB_HOST中间件，在“Middleware”菜单下找到USB_HOST，在Class for Host IP选项里选择“Mass Storage Host Class”。这里要注意：如果选了多个Class（比如同时选HID和MSC），代码会多一点，但可能引入不必要的复杂度。如果只是读取U盘，只选MSC就够了。
配置完成后，CubeMX还会自动生成一个usbh_diskio.c文件，这个文件是FatFS和USB Host库之间的桥梁，后面会详细讲解。
3.3 中断优先级与生成工程
中断配置是一个很容易被忽视的环节。USB_OTG_FS的全局中断（OTG_FS_IRQHandler）必须使能，否则USB Host库的底层驱动无法工作。中断优先级方面，建议把USB的中断优先级设为较高（抢占优先级1，子优先级0），因为USB协议是有时间限制的，比如控制传输的超时是5秒，但如果系统正在进行长时间的关键运算，中断响应不及时，可能导致设备控制传输超时。
生成工程时选择Keil MDK-ARM V5，编译器选AC5或AC6都行，不过AC6对代码优化更激进，有时候会暴露一些未定义行为的隐患，如果遇到奇怪的问题，可以先换回AC5试试。
生成后的工程结构大致如下：
- usb_host.c/h：USB Host初始化入口
- usbh_conf.c/h：底层配置，包含HAL_HCD_IRQHandler等回调
- usbh_msc.c：MSC类驱动
- usbh_diskio.c：FatFS与USB Host桥接层
- app_usb_host.c/h：用户回调接口
4. FatFS文件系统移植
4.1 为什么选FatFS
U盘相当于是个裸块设备，没有文件系统的话，读写数据要自己计算扇区，还要手动维护文件分配表，太痛苦了。FAT文件系统的实现方案里，FatFS可以说是嵌入式领域应用最广的开源方案。它开源、轻量、支持FAT12/16/32和exFAT，用起来很简单，在淘宝几块钱的开发板上都有现成的移植，资料多，遇到问题好查。
你可能会问，STM32官方不是说有ST提供的FAT文件系统组件吗？确实有，CubeMX里也集成了FatFS，但它本质上就是FatFS本身，只是帮你生成了底层接口。所以直接用CubeMX自带的FatFS就行，不用额外下载。
4.2 FatFS关键配置参数
CubeMX生成FatFS时，会有一个配置文件ffconf.h，里面对应很多宏。这里列出几个关键参数的我的设置：
| 宏 | 值 | 说明 |
|---|---|---|
| FF_USE_LFN | 1 | 长文件名支持，1表示静态缓冲区，2表示动态堆栈 |
| FF_VOLUMES | 1 | 只有U盘一个卷 |
| FF_MIN_SS | 512 | 最小扇区大小 |
| FF_MAX_SS | 512 | 最大扇区大小，很多U盘物理扇区就是512字节 |
| FF_USE_MKFS | 0 | 不需要格式化功能，省点Flash空间 |
| FF_FS_RPATH | 1 | 支持相对路径，方便切换目录 |
| FF_CODE_PAGE | 936 | 中文编码，如果文件都是英文名可以设成437省空间 |
重点说一下FF_USE_LFN。FAT文件系统默认只支持8.3短文件名（8个字符主文件名+3个字符扩展名），超过这个长度或者包含中文就会被截断。如果U盘里的文件是中文名或者长文件名的，必须打开这个宏。但打开后有个代价，需要一块缓冲区存储长文件名的路径，FF_USE_LFN为1时是静态数组，会占内存比较可观，STM32F407有192KB RAM，无所谓，但对于小内存的MCU就要慎重了。
4.3 diskio底层接口实现
CubeMX生成FatFS时，会自动生成diskio.c和usbh_diskio.c，其中disk_read、disk_write、disk_ioctl这几个函数在usbh_diskio.c里已经实现了对USBH_MSC_Read/Write的调用。看一下核心代码：
DRESULT disk_read(BYTE pdrv, BYTE *buff, LBA_t sector, UINT count) { if (USBH_MSC_Read(&hUsbHostFS, 0, sector, buff, count) == USBH_OK) { return RES_OK; } return RES_ERROR; } DRESULT disk_write(BYTE pdrv, const BYTE *buff, LBA_t sector, UINT count) { if (USBH_MSC_Write(&hUsbHostFS, 0, sector, (uint8_t *)buff, count) == USBH_OK) { return RES_OK; } return RES_ERROR; }这里的pdrv是卷号，单卷系统就是0；sector是扇区号（LBA）；count是扇区数。USBH_MSC_Read的第二个参数是LUN（逻辑单元号），大多数U盘都是单LUN，填0；第三个参数是块地址；第四个参数是数据缓冲区；第五个参数是块数。
这里要注意：USBH_MSC_Read/Write的块大小是512字节，而FatFS默认的扇区大小也是512字节，两者刚好对应。如果未来遇到4K扇区的U盘，这里就会出现错位，需要做扇区地址换算，不过目前市面上绝大多数U盘逻辑扇区都是512字节，不用太担心。
还有一个很重要的点：USBH_MSC_Read的缓冲区要求4字节对齐。如果你在函数里面定义一个大数组作为缓冲区，编译器可能默认4字节对齐，但保险起见可以在数组定义处加上__attribute__((aligned(4)))。这个坑我踩过，现象是读取数据偶尔出现错位或者CRC错误，排查了好久才发现是对齐问题。
5. 核心代码实现与调试
5.1 初始化流程与主循环
CubeMX生成的主函数结构是这样的：
int main(void) { HAL_Init(); SystemClock_Config(); MX_GPIO_Init(); MX_USB_HOST_Init(); MX_FATFS_Init(); // 用户代码 while (1) { USBH_Process(&hUsbHostFS); // 你的应用代码 } }MX_USB_HOST_Init()内部会对USB Host库进行初始化，注册MSC类，并启动USB Host。主循环里的USBH_Process是整个USB协议栈的轮询引擎，负责处理状态机、枚举、数据传输等工作，必须被频繁调用。如果让它执行间隔太长（比如你在主循环里做了耗时的Flash写入、打印大量调试信息等），会导致USB枚举超时或者数据传输超时。
我当时的做法是：把USBH_Process放在主循环的最前面，然后所有应用逻辑都放后面，确保每次循环都会调用它。如果使用了实时操作系统（RTOS），则建议专门开一个线程，优先级设置为普通或者略低于关键实时任务，循环调用USBH_Process即可。
5.2 U盘挂载与文件读取示例
USB Host库识别到U盘并完成枚举后，状态会变成HOST_CLASS，此时才能安全地调用FatFS接口。我在主循环里加了一个状态检测，当检测到U盘就绪时，执行文件读取操作：
uint8_t previousState = 0; while (1) { USBH_Process(&hUsbHostFS); // 检查USB主机状态 if (USBH_GetState(&hUsbHostFS) == HOST_CLASS) { if (!previousState) { printf("U盘已连接，开始读取文件\r\n"); UDisk_ReadConfigFile(); previousState = 1; } } else { previousState = 0; } }UDisk_ReadConfigFile函数负责挂载文件系统和读取文件：
void UDisk_ReadConfigFile(void) { FRESULT res; FATFS fs; FIL file; UINT bytesRead; char buf[128]; // 挂载U盘 res = f_mount(&fs, "", 1); if (res != FR_OK) { printf("挂载失败: %d\r\n", res); return; } // 打开根目录下的config.txt文件 res = f_open(&file, "config.txt", FA_READ); if (res != FR_OK) { printf("打开文件失败: %d\r\n", res); f_mount(NULL, "", 0); // 卸载 return; } // 读取文件内容 res = f_read(&file, buf, sizeof(buf) - 1, &bytesRead); if (res == FR_OK) { buf[bytesRead] = '\0'; printf("文件内容: %s\r\n", buf); } f_close(&file); f_mount(NULL, "", 0); // 操作完毕后卸载 }这里有几个细节值得注意：
f_mount的第二个参数传空字符串""表示挂载到根路径，第三个参数1表示强制立即挂载。如果传0，系统会延迟到第一次文件操作时才挂载，虽然也能用，但错误处理会麻烦一些。
f_mount(NULL, "", 0)是卸载文件系统。这个操作在拔掉U盘前调用，可以防止数据丢失。但要注意：如果卸载后USB Host库仍然认为U盘连接着，再次挂载时需要重新枚举。如果用户在不通知系统的情况下直接拔掉U盘，重新插上后还需要重新枚举。
我在实际项目中是这样处理的：检测到USBH_GetState从HOST_CLASS变为其他状态时，执行一次f_mount(NULL, "", 0)清理现场，等下次U盘就绪时再重新挂载。
5.3 完整示例：目录遍历与多个文件读取
只读一个配置文件太简单，实际项目中往往需要遍历U盘里的所有文件。FatFS提供了f_opendir、f_readdir、f_closedir等接口，下面是一个读取根目录下所有文件的示例：
void UDisk_ListFiles(void) { DIR dir; FILINFO fno; FRESULT res; res = f_opendir(&dir, ""); if (res != FR_OK) { printf("打开目录失败: %d\r\n", res); return; } while (1) { res = f_readdir(&dir, &fno); if (res != FR_OK || fno.fname[0] == 0) { break; // 结束或出错 } if (fno.fattrib & AM_DIR) { printf("[目录] %s\r\n", fno.fname); } else { printf("[文件] %s, 大小: %lu字节\r\n", fno.fname, fno.fsize); } } f_closedir(&dir); }如果需要在子目录里操作，用f_chdir切换当前目录，或者直接用带路径的文件名打开，比如"dir1/data.txt"。FatFS的路径分隔符是/，注意不是反斜杠。
6. 常见问题与排查技巧实录
6.1 枚举失败：U盘插上没反应
现象是USBH_GetState一直卡在HOST_ENUMERATION或HOST_DEV_WAIT_FOR_RESET等状态，或者根本没检测到设备。排查顺序：
- 用万用表量VBUS有没有5V。没有5V就看电源开关电路和GPIO控制。
- 量D+/D-对地电压。U盘插入后D+应该被拉高到大约3V，如果一直低电平，可能是U盘没供电或者线缆问题。这里有个经验：USB线缆质量差会导致D+/D-上电平不稳定，建议用短一点、屏蔽好的线。
- 换一个U盘测试。U盘兼容性是老生常谈，有些U盘的枚举时序比较“特殊”，遇到兼容性问题，可以先换个品牌USB 2.0的U盘确认到底是硬件问题还是协议问题。
- 检查中断是否挂了。在HAL_HCD_IRQHandler里加一个调试计数器，看插入时有没有触发中断。如果一直不触发，检查CubeMX是否使能了OTG_FS_IRQn。
6.2 文件系统挂载失败
U盘枚举成功，但f_mount返回FR_NO_FILESYSTEM（错误码13），说明U盘里没有FAT文件系统，或者FatFS不认识。最常见原因是U盘格式化成exFAT或NTFS，而FatFS配置里没开exFAT支持。STM32CubeMX生成的FatFS默认支持FAT12/16/32，不支持exFAT，需要到ffconf.h里把FF_USE_EXFAT宏改为1。不过exFAT支持会明显增加代码体积，而且很多老U盘默认就是FAT32，所以如果不是必须用超过4GB的单文件，我建议直接方案更简单：用PC把U盘格式化成FAT32。
有些U盘出厂时分区比较奇怪，只有一个LUN，但分区表类型不是FAT，也会导致挂载失败。先用PC确认U盘文件系统类型，再用f_mount，基本都能解决。
6.3 读取数据错误或超时
如果文件能打开，但读取的数据偶尔不对或者读取超时，优先排查这几个点：
- 缓冲区对齐：USBH_MSC_Read要求4字节对齐，数组加上aligned(4)属性。
- 主循环堵塞：检查主循环中是否有耗时过长的操作（比如HAL_Delay、Flash写操作），可以在USBH_Process调用前加一个计数器打印执行间隔。
- 多任务竞争：如果用了RTOS，多个任务同时访问U盘驱动导致数据被破坏，必须加互斥锁保护。
- FatFS缓冲区大小：FATFS每次读写一个扇区，如果应用层给f_read的缓冲区小于扇区大小，FatFS内部会做拼接，性能会下降，但不会出错。如果数据量大，建议用512倍数的大缓冲区。
6.4 调试工具与技巧
USB协议调试比较麻烦，串口打印是基础手段。我在USBH_Process调用前加了一个状态打印，每次状态变化就输出一行，这样能清楚看到枚举进度：
static USBH_StatusTypeDef printState = USBH_IDLE; if (USBH_GetState(&hUsbHostFS) != printState) { printState = USBH_GetState(&hUsbHostFS); printf("USB状态: %d\r\n", printState); }如果卡在某个状态，就可以把问题定位到具体的协议阶段。比如一直卡在HOST_ENUMERATION，可能是控制传输超时；卡在HOST_CLASS_REQUEST，可能是MSC类驱动初始化失败。结合USB协议栈的代码，能精准定位问题。
有条件的话，买一个便宜的USB协议分析仪或者用逻辑分析仪抓D+/D-数据，能看到主机给设备发了什么命令、设备怎么回复的，对排查USB兼容性问题帮助极大。不过普通逻辑分析仪带宽可能不够，抓全速USB信号至少需要100MHz采样率，建议买专用的USB分析仪以免白花钱。
6.5 供电与插拔问题
U盘热插拔是个大问题，如果用户正在读写文件时拔掉U盘，可能导致文件系统损坏。我做的方案是在硬件上加一个电源管理芯片（比如TPS2065或NCP380），在软件上每次读写前检查USBH_GetState，当状态不是HOST_CLASS时，禁止任何文件操作。另外，在检测到U盘拔出后，立即调用f_mount(NULL, "", 0)卸载文件系统，将缓冲区中的数据刷新到U盘。这个卸载操作不能省，否则可能会导致最后一个文件的数据没有写入U盘。
供电方面，U盘启动瞬间的电流可能达到500mA，如果用USB Hub或者劣质线缆供电，电压跌落会导致U盘内部逻辑复位，表现为“插入后能枚举，但读写时设备消失”。我后来改成了独立5V电源供电，加上一个大电容（220uF以上），问题就消失了。
7. 实操总结与后续扩展
这个工程做下来，我的体会是：STM32 USB Host协议栈和文件系统移植本身并不难，CubeMX生成代码已经完成了90%的体力活，真正的难点在于硬件供电设计、U盘兼容性处理、以及对协议底层原理的理解。我见过很多人卡在供电和枚举阶段，其实大部分原因不是代码写错，而是硬件设计不够健壮。
如果你打算把这套方案用到实际产品里，建议在出厂前就找几种市面上常见的U盘做兼容性测试，至少覆盖USB 2.0和USB 3.0的U盘，因为USB 3.0的U盘虽然速率高，但在全速USB Host下表现往往不如USB 2.0的U盘稳定。另外，文件名和文件内容编码建议统一用英文和UTF-8，避免中文编码在不同设备上出现乱码问题。
后来我在这个基础上还扩展了几个功能：一个是通过U盘升级固件，把hex文件放到U盘里，设备启动时检测到就自动烧录；另一个是数据记录，设备运行时的传感器数据直接以CSV格式写入U盘，用户拿到电脑上就能用Excel打开分析。这两个功能在项目交付时都得到了很好的反馈，也证明了“MCU + U盘”这个组合在工业现场的实用价值确实很高。
