1. 从一块 STM32F407 说起为什么要做 SD 卡读卡器如果你手上有一块 STM32F407VGT6 开发板插着 SD 卡想同时干三件事让电脑把板子当成 U 盘直接读写卡里的文件、让板子自己用 FatFS 读写同一个文件、还要跑 FreeRTOS 管理多个任务——这套组合在 VS code STM32CubeMX 里其实能一次配出来。核心检索词就是 VS code、STM32CubeMX、FreeRTOS、FatFS、USB_DEVICE五个东西叠在一起配置项多、依赖关系绕新手最容易卡在「USB 枚举成功但电脑不认盘」和「FatFS 挂载返回 FR_NOT_READY」这两个点上。这篇要做的是把这套工程从 CubeMX 图形配置到 EIDE 编译下载完整走一遍同时把 TaoToken 的统一 Key/API 通道配置骨架塞进 VS code 的 settings.json 和项目里的 config.toml让你在调试阶段就能用同一套 Key 去验证模型对话、代码补全和 Agent 任务不用在多个平台之间来回切。适合谁已经会点 STM32 HAL 库、想用 VS code 替代 Keil 做嵌入式开发、并且希望把 AI 辅助编码接进工作流的同学。我试过在 F407 上把 SDIO 4 线 DMA USB_OTG_FS 大容量存储 FatFS FreeRTOS 全开编译出来大约 222KB烧进去电脑能识别出一个可移动磁盘串口同时打印 FatFS 读到的文件内容。下面按可跟做的顺序拆开讲。2. TaoToken 前置统一 Key 与 API 通道准备在动 CubeMX 之前先把 AI 辅助这条线铺好后面写 usbd_storage_if.c 和调试 FatFS 时会省很多查文档的时间。TaoToken 的作用是给你一个统一的 Key 和 API 入口模型对话、代码补全、Agent 任务都走同一个通道省得每个工具单独配一遍。你需要先拿到一个 API Key。打开控制台创建 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite创建完 Key 之后API 的基础地址是https://taotoken.net/api注意这个地址不带任何查询参数直接作为 base_url 用。Key 的格式通常是 sk- 开头的一串字符复制下来先存好后面 settings.json 和 config.toml 都要用。如果你只是想先验证 Key 能不能用最快的办法是打开模型对话页面发一条消息https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite能正常返回就说明 Key 生效了。这一步别跳过因为后面在 VS code 里配完如果补全不工作你至少能确定是配置问题而不是 Key 问题。对于长期做嵌入式编码、想让 Agent 帮你批量改驱动代码的场景可以了解一下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite接入文档在这里遇到参数问题可以对照https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite3. VS code 侧配置settings.json 与 config.toml 可复制骨架VS code 里做 STM32 开发主流是 EIDE 插件。EIDE 负责工程管理、编译、烧录CubeMX 负责生成初始化代码。AI 辅助这块如果你用的是支持 OpenAI 兼容接口的插件比如 Continue、Cline 之类配置就写在 settings.json 里。先给一份 settings.json 的可复制骨架重点是 base_url 和 apiKey 两项{ eide.build.toolchain: arm-gcc, eide.build.configuration: Debug, aiAssistant.provider: openai-compatible, aiAssistant.baseUrl: https://taotoken.net/api, aiAssistant.apiKey: sk-你的Key粘贴在这里, aiAssistant.model: claude-sonnet-4-20250514, aiAssistant.maxTokens: 4096, aiAssistant.temperature: 0.2, C_Cpp.default.includePath: [ ${workspaceFolder}/Core/Inc, ${workspaceFolder}/Middlewares/Third_Party/FreeRTOS/Source/include, ${workspaceFolder}/Middlewares/Third_Party/FatFs/src, ${workspaceFolder}/Middlewares/ST/STM32_USB_Device_Library/Core/Inc ] }temperature 设 0.2 是因为嵌入式代码要的是准确不是创意。includePath 把 FreeRTOS、FatFs、USB Device 三个中间件的头文件目录都加进去不然 VS code 会满屏红波浪线。有些工具链或 Agent 框架读的是 config.toml比如你在项目根目录放一个内容骨架如下[provider] name taotoken base_url https://taotoken.net/api api_key sk-你的Key粘贴在这里 model claude-sonnet-4-20250514 timeout 60 [project] name stm32f407-sd-reader mcu STM32F407VGT6 toolchain arm-none-eabi-gcc rtos FreeRTOS filesystem FatFs usb_class MSC [agent] max_iterations 20 auto_apply falseauto_apply 设 false 是故意的Agent 改代码前先让你看一眼 diff嵌入式代码改错一个寄存器配置可能就要重新烧录排查。注意api_key 不要提交到 git。在项目根目录的 .gitignore 里加上 config.toml 和 .vscode/settings.json或者用环境变量注入。4. CubeMX 配置FreeRTOS FatFS USB_DEVICE 一次配齐打开 CubeMX 新建 STM32F407VGT6 工程按下面的顺序配顺序错了容易漏中断。时钟树先把 HSE 设成外部晶振主频拉到 168MHz。SWD 调试接口在 SYS 里把 Debug 选成 Serial Wire。关键一步把 HAL 的时基源从 SysTick 改成 TIM6 之类的通用定时器因为 SysTick 要被 FreeRTOS 占用不改的话 FreeRTOS 一启动 HAL_Delay 就废了。FreeRTOS 在 Middleware 里启用接口选 CMSIS_V1 或 V2 都行。Heap Size 建议给到 15360 字节以上因为 FatFS 和 USB 栈都要吃内存。内存分配算法选 heap_4带碎片合并长时间跑更稳。任务先建两个MainTask 和 LedIndicator优先级 MainTask 设 osPriorityNormalLedIndicator 设 osPriorityLow。SDIO 配置是重头戏。在 Connectivity 里选 SDIO模式选 4-bit Wide bus时钟分频先给 6MHz 保守一点等跑通了再往上提。DMA 标签页里给 SDIO 加一个 DMA 通道方向 Peripheral to Memory优先级 Medium。NVIC 里把 SDIO global interrupt 勾上优先级设 5。FatFs 在 Middleware 里启用配置里把「Use FATFS with SD Card」选上Code page 选简体中文那个不然长文件名可能乱码。Volume 设置里把「Use LFN」勾上Maximum sector size 设 512。USB_OTG_FS 在 Connectivity 里选模式选 Device_Only。然后在 Middleware 里启用 USB_DEVICEClass 选 Mass Storage Host 对应的 Device 端也就是 MSC。参数里 Product String 可以改成「STM32 SD Reader」VID 和 PID 保持默认或者自己填。UART1 用来打日志波特率 1152008N1。最后点 GENERATE CODE工具链选 Makefile生成到 EIDE 工程目录下。生成完之后把 startup_stm32f407xx.s 从生成目录复制到 Core/src 里EIDE 里添加源文件目录把 Core、Drivers、Middlewares 都加进来。Makefile 里的宏要加上 USE_HAL_DRIVER 和 STM32F407xx编译选项里设好芯片类型和硬件浮点。5. 代码实现USB 存储接口与 FatFS 读写回环CubeMX 生成的 usbd_storage_if.c 里有四个函数要自己填STORAGE_Init_FS、STORAGE_GetCapacity_FS、STORAGE_IsReady_FS、STORAGE_Read_FS、STORAGE_Write_FS。核心是把 SD 卡的读写桥接到 USB MSC 的回调上。int8_t STORAGE_Read_FS(uint8_t lun, uint8_t *buf, uint32_t blk_addr, uint16_t blk_len) { if (lun ! 0) return -1; if (BSP_SD_ReadBlocks((uint32_t *)buf, blk_addr, blk_len, 1000) ! MSD_OK) return -1; return 0; } int8_t STORAGE_Write_FS(uint8_t lun, uint8_t *buf, uint32_t blk_addr, uint16_t blk_len) { if (lun ! 0) return -1; if (BSP_SD_WriteBlocks((uint32_t *)buf, blk_addr, blk_len, 1000) ! MSD_OK) return -1; return 0; }GetCapacity 里返回块数和块大小块大小固定 512int8_t STORAGE_GetCapacity_FS(uint8_t lun, uint32_t *block_num, uint16_t *block_size) { if (lun ! 0) return -1; *block_num (uint32_t)((uint64_t)SD_GetCardInfo.BlockNbr * SD_GetCardInfo.BlockSize / 512); *block_size 512; return 0; }MainTask 里做 FatFS 读写回环。先挂载再打开文件读然后写回验证void StartMainTask(void const *argument) { FATFS fs; FIL fil; FRESULT res; UINT bw, br; char rbuf[128]; if (f_mount(fs, , 1) ! FR_OK) { printf(FatFS mount failed\r\n); vTaskDelete(NULL); } printf(FatFS mounted OK\r\n); for (;;) { res f_open(fil, abcd.txt, FA_READ | FA_OPEN_ALWAYS); if (res FR_OK) { f_read(fil, rbuf, sizeof(rbuf) - 1, br); rbuf[br] \0; printf(read %d bytes: %s\r\n, br, rbuf); f_close(fil); } else { printf(f_open failed: %d\r\n, res); } vTaskDelay(pdMS_TO_TICKS(10000)); } }LedIndicator 任务就简单闪 PA1void StartLedTask(void const *argument) { for (;;) { HAL_GPIO_TogglePin(GPIOA, GPIO_PIN_1); vTaskDelay(pdMS_TO_TICKS(500)); } }printf 重定向到 UART1在 usart.c 里加int __io_putchar(int ch) { HAL_UART_Transmit(huart1, (uint8_t *)ch, 1, HAL_MAX_DELAY); return ch; }编译前确认 FreeRTOS 的 heap 够大USB 和 FatFS 同时跑的时候内存吃紧heap_4 的 ucHeap 数组建议 20KB 起步。6. 验证请求与成功结果读卡器枚举 FatFS 回环编译用 EIDE 的 RebuildGCC 编出来大概 222KB。烧录前把板子 USB 口接到电脑串口接好SD 卡插上。EIDE 里配好烧录器ST-Link 或 J-Link点 Upload To Device。烧完复位等几秒。电脑设备管理器里应该出现一个 USB 大容量存储设备文件资源管理器里多一个可移动磁盘。如果没出现先看串口有没有打印「FatFS mounted OK」再看 USB 枚举日志。打开那个磁盘新建 abcd.txt随便写点内容保存。串口监视器里应该每 10 秒打印一次文件内容。改一下文件再保存下一次打印就是新内容。这就是读写回环验证通过。验证 Key 是否生效在 VS code 里打开一个 .c 文件选中一段函数让 AI 解释或补全。如果返回正常说明 settings.json 里的 base_url 和 apiKey 配对了。也可以直接在模型对话页面发一条「解释 STORAGE_Read_FS 的参数含义」测试https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite7. 本篇常见错排查电脑不认盘串口打印 mount OK多半是 USB 描述符里的 VID/PID 和容量返回不对。检查 STORAGE_GetCapacity_FS 返回的 block_num 是不是 0SD 卡没初始化成功时 BlockNbr 是 0电脑会认为容量为 0 直接忽略。f_mount 返回 FR_NOT_READYSDIO 时钟太快或者 DMA 没配好。把 SDIO 时钟从 6MHz 降到 4MHz 试试同时确认 SDIO 的 DMA 中断优先级不高于 FreeRTOS 的 syscall 优先级。FreeRTOS 一启动 HAL_Delay 就卡死时基源没改。回 CubeMX 把 SYS 的 Timebase Source 从 SysTick 改成 TIM6重新生成代码。编译报 undefined reference to_writeprintf 重定向没加全。除了 __io_putchar有些 GCC 版本还要加 _write 和 _close 的空实现。USB 枚举成功但写入文件后读出来是乱码FatFS 的 sector size 和 USB MSC 的 block size 不一致。确认两边都是 512FatFs 配置里 Maximum sector size 设 512。AI 补全不工作先确认 settings.json 里 baseUrl 是 https://taotoken.net/api 没有多余斜杠apiKey 没有过期。如果用的是 Agent 类工具检查 config.toml 的 provider 段有没有被正确读取。接入文档里有各工具的配置示例https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteKey 管理在控制台可以随时新建或吊销https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite8. 把 Key 和工程一起管起来这套工程跑通之后你手上就有了一个能同时做 USB 读卡器和 FatFS 读写的 F407 模板。后面要加功能比如通过 USB 接收命令控制 LED或者把 SD 卡数据通过 UART 转发都可以在这个骨架上叠。TaoToken 的 Key 建议单独放一个环境变量文件不要硬编码在 settings.json 里。VS code 的 settings.json 支持 ${env:TAOTOKEN_API_KEY} 这种写法config.toml 也可以用环境变量注入。这样换机器或者分享工程的时候不会泄露 Key。长期做嵌入式 Agent 任务的话Coding Plan 那条线可以看看它适合让 AI 帮你批量处理驱动适配、寄存器配置检查这类重复劳动https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite最后提醒一句USB MSC 和 FatFS 同时访问 SD 卡的时候注意加互斥。FreeRTOS 里可以用二值信号量保护 SDIO 的读写不然 USB 正在写块的时候 FatFS 去读容易出 FR_DISK_ERR。这个坑我在第一次跑的时候就踩了现象是文件内容偶尔丢一段加了互斥之后就没再复现。
