# STM32F407ZGT6_USBFS_260517

**Repository Path**: fuchaow/STM32F407ZGT6_USBFS_260517

## Basic Information

- **Project Name**: STM32F407ZGT6_USBFS_260517
- **Description**: STM32F407ZGT6实现USB CDC ，基于FreeRTOS + ringbuffer 
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-02
- **Last Updated**: 2026-06-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# STM32F407 USB CDC + FreeRTOS + RingBuffer

# V1.1
在V1.0基础上，成功移植了letter-shell，实现foc电机控制调试命令框架，具体命令功能待实现。
命令说明和使用，请参考Foc电机调试命令.md文档

# V1.0
基于 STM32F407ZGT6 的 USB CDC（虚拟串口）项目，集成 FreeRTOS 实时操作系统和环形缓冲区，实现高效稳定的 USB 数据收发功能。
## 📋 项目概述

本项目演示了如何在 STM32F407 平台上构建一个基于 FreeRTOS 的 USB CDC 通信系统，采用环形缓冲区作为数据中转，实现数据的可靠接收和回显。

### 主要特性

- ✅ **USB CDC 虚拟串口**：支持 USB FS Device，实现虚拟串口通信
- ✅ **FreeRTOS 多任务**：使用 CMSIS-RTOS V2 API 进行任务管理
- ✅ **环形缓冲区**：自定义高性能环形缓冲区，支持中断安全读写
- ✅ **数据回显功能**：从 USB 接收的数据自动回传给主机
- ✅ **模块化设计**：应用层与底层驱动分离，易于扩展
- ✅ **CMake 构建系统**：支持 CLion IDE 开发

## 🛠️ 技术栈

### 硬件平台
- **MCU**: STM32F407ZGT6 (ARM Cortex-M4, 168MHz)
- **USB**: USB FS Device (全速设备)
- **Flash**: 1MB
- **SRAM**: 192KB

### 软件组件
- **HAL 库**: STM32Cube HAL Driver
- **RTOS**: FreeRTOS (CMSIS-RTOS V2 接口)
- **USB 协议栈**: STM32 USB Device Library (CDC Class)
- **构建工具**: CMake 3.22+
- **开发环境**: CLion / STM32CubeMX
- **编译器**: ARM GCC (arm-none-eabi-gcc)

## 📁 项目结构

    STM32F407ZGT6_USBFS_260517/
    ├── Core/
    │   ├── Inc/
    │   │   ├── main.h
    │   │   ├── stm32f4xx_hal_conf.h
    │   │   └── FreeRTOSConfig.h
    │   └── Src/
    │       ├── main.c
    │       ├── freertos.c
    │       └── gpio.c
    ├── USB_DEVICE/
    │   ├── App/
    │   │   ├── usb_device.c/h
    │   │   ├── usbd_cdc_if.c/h
    │   │   └── usbd_desc.c/h
    │   └── Target/
    │       └── usbd_conf.c/h
    ├── app/
    │   ├── utilities/
    │   │   └── hk_ringbuffer.c/h
    │   └── app_usb_task.c/h
    ├── Middlewares/
    │   ├── ST/STM32_USB_Device_Library/
    │   └── Third_Party/FreeRTOS/Source/
    ├── Drivers/
    │   ├── CMSIS/
    │   └── STM32F4xx_HAL_Driver/
    ├── cmake/
    ├── CMakeLists.txt
    └── STM32F407XX_FLASH.ld

## 🔧 核心功能模块

### 1. 环形缓冲区 (hk_ringbuffer)

**位置**: `app/utilities/hk_ringbuffer.c/h`

**特性**:
- 动态内存分配（FreeRTOS heap）
- 缓冲区大小自动对齐到 2 的幂（优化模运算）
- 支持中断安全的读写操作
- 零拷贝接口（GetReadPtr/GetWritePtr）
- 线程安全（临界区保护）

**主要 API**:
- `RingBuffer_Create(size)` - 创建缓冲区
- `RingBuffer_Write(handle, data, length)` - 写入数据
- `RingBuffer_WriteFromISR(handle, data, length)` - 中断写入
- `RingBuffer_Read(handle, buffer, length)` - 读取数据
- `RingBuffer_GetReadableSize(handle)` - 获取可读大小

### 2. USB CDC 数据接收

**位置**: `USB_DEVICE/App/usbd_cdc_if.c`

**工作流程**:
1. USB 主机发送数据 → USB 端点接收
2. `CDC_Receive_FS()` 回调被调用（中断上下文）
3. 数据写入环形缓冲区（`RingBuffer_WriteFromISR`）
4. 准备下一个接收包（`USBD_CDC_ReceivePacket`）

### 3. USB 数据处理任务

**位置**: `app/app_usb_task.c`

**任务配置**:
- 任务名称: `UsbDataTask`
- 栈大小: 1KB (256 × 4 bytes)
- 优先级: `osPriorityNormal`
- 轮询间隔: 1ms

**工作流程**:
1. 从环形缓冲区读取数据（最多 64 字节）
2. 通过 USB CDC 发送回主机（回显）
3. 如果 USB 忙，重试最多 10 次
4. 延时 1ms 后继续下一轮

### 4. 初始化流程

**位置**: `Core/Src/main.c`

**启动顺序**:
1. HAL_Init()
2. SystemClock_Config() (168MHz)
3. MX_GPIO_Init()
4. MX_USB_DEVICE_Init() (USB 枚举，此时 RTOS 未启动)
5. APP_USB_Task_Create() (创建环形缓冲区 + USB 任务)
6. osKernelInitialize() (初始化 FreeRTOS)
7. MX_FREERTOS_Init()
8. osKernelStart() (启动调度器)

**重要设计决策**:
- ⚠️ **环形缓冲区不在 `CDC_Init_FS()` 中创建**：因为此时 FreeRTOS 调度器未启动，`pvPortMalloc()` 会失败
- ✅ **在任务创建时初始化缓冲区**：确保 RTOS 已就绪，可以安全分配内存

## 🚀 快速开始

### 环境要求

- **IDE**: CLion 2023+ 或 STM32CubeIDE
- **编译器**: ARM GCC 10+ (arm-none-eabi-gcc)
- **CMake**: 3.22+
- **调试器**: ST-Link V2/V3 或 J-Link
- **串口工具**: XCOM、PuTTY、Minicom 等

### 编译步骤

#### 方法 1: CLion (推荐)

1. 打开项目文件夹
2. CLion 自动检测 CMakeLists.txt
3. 选择构建配置（Debug/Release）
4. 点击 "Build" → "Build Project"

#### 方法 2: 命令行

    cd STM32F407ZGT6_USBFS_260517
    mkdir build && cd build
    cmake .. -DCMAKE_TOOLCHAIN_FILE=../cmake/gcc-arm-none-eabi.cmake -DCMAKE_BUILD_TYPE=Debug
    make -j8

### 烧录和运行

1. **连接硬件**:
    - ST-Link 连接到 SWD 接口
    - USB FS 连接到 PC

2. **烧录固件**:

   openocd -f interface/stlink.cfg -f target/stm32f4x.cfg \
   -c "program build/STM32F407ZGT6_USBFS_260517.elf verify reset exit"

3. **测试通信**:
    - 打开串口助手（如 XCOM）
    - 选择 USB CDC 虚拟串口（COM 端口号在设备管理器查看）
    - 波特率任意（USB 虚拟串口不受波特率限制）
    - 发送数据，应该立即收到回显

## 📊 性能参数

| 参数 | 值 | 说明 |
|------|-----|------|
| 环形缓冲区大小 | 512 字节 | 可容纳最大突发数据 |
| 任务轮询间隔 | 1 ms | 响应延迟 < 2ms |
| 单次最大传输 | 64 字节 | USB FS 端点最大包大小 |
| USB 忙重试次数 | 10 次 | 避免数据丢失 |
| 任务栈使用 | ~400 字节 | 1KB 栈空间充足 |
| CPU 占用率 | < 5% | 空闲时几乎不占用 CPU |

## 🔍 调试技巧

### 1. 查看 USB 枚举状态

在 Windows 设备管理器中查看：
- 通用串行总线控制器 → STM32 Virtual COM Port
- 端口 (COM & LPT) → STM32 Virtual COM Port (COMx)

### 2. 常见问题

**问题 1**: USB 无法枚举
- 检查 USB 电缆和数据线连接
- 确认 `MX_USB_DEVICE_Init()` 在调度器启动前调用
- 检查时钟配置（USB 需要 48MHz）

**问题 2**: 数据接收不到
- 确认环形缓冲区已正确初始化（`CDC_InitRingBuffer()`）
- 检查 `CDC_Receive_FS()` 中是否写入缓冲区
- 验证任务是否正常创建并运行

**问题 3**: 数据丢失
- 增大环形缓冲区（当前 512 字节）
- 缩短任务轮询间隔（当前 1ms）
- 增加 USB 忙时的重试次数

## 📝 版本历史

### v1.0 (2026-05-19)

**功能**:
- ✅ 基础 USB CDC 通信
- ✅ FreeRTOS 任务管理
- ✅ 环形缓冲区数据中转
- ✅ 数据回显功能
- ✅ 中断安全的读写操作

**已知问题**:
- 轮询方式存在微小延迟（~1ms）
- USB 忙时可能丢弃少量数据（重试后 < 1%）

**后续优化方向**:
- [ ] 使用信号量实现事件驱动（零延迟）
- [ ] 批量发送优化（提高带宽利用率）
- [ ] 流量控制（XON/XOFF）
- [ ] 添加统计信息（收发计数器）

## 📄 许可证


---

**最后更新**: 2026-05-19  
**硬件平台**: STM32F407ZGT6  
**软件版本**: FreeRTOS V10.x, STM32 HAL V1.x