2. CubeMX基础与工程生成：从界面到第一个MDK工程

好，咱们正式开始动手。这一章我会带你走一遍CubeMX的完整流程——从打开软件、配时钟、选引脚，到最后生成一个能用的MDK-ARM工程。说白了，就是让你知道「点哪里、填什么、为什么这么填」。

我个人习惯是，拿到一个新板子，第一件事不是写代码，而是先把CubeMX工程搭好。为什么？因为后面所有USB调试的坑，有一半其实是在这一步埋下的。

2.1 CubeMX界面速览

打开CubeMX，你会看到几个主要区域。别被密密麻麻的选项吓到，其实常用的就这几块：

区域	作用	我常用的操作
Pinout & Configuration	引脚分配、外设配置	在这里勾选USB、配置时钟源
Clock Configuration	时钟树图形化配置	调整HCLK到最大频率
Project Manager	工程名称、IDE选择、堆栈设置	选MDK-ARM，设好路径
Pinout View	芯片引脚图可视化	检查引脚冲突

嗯，这里要注意：Pinout View 里的引脚颜色是有含义的。绿色表示已分配，黄色表示有警告，红色就是冲突。我在项目里见过有人把USART和USB的引脚配到同一个IO上，编译不报错，但板子就是不工作——后来查了半天才发现是CubeMX里标红了没注意。

2.2 时钟树配置——别让USB跑不起来

时钟配置是USB能否正常工作的关键。USB全速模式需要48MHz的时钟，这个时钟来源必须精确。我刚开始做USB项目时，随便配了个内部RC振荡器，结果枚举时断时续……后来才发现，内部振荡器精度不够，必须用外部晶振+PLL。

具体步骤是这样的：

1. 选择时钟源：在 RCC 里把 HSE 设为 Crystal/Ceramic Resonator。
2. 进入Clock Configuration：图形化界面里，把 HSE 作为PLL输入。
3. 设置PLL参数：比如STM32F103，外部8MHz晶振，PLL倍频9倍，得到72MHz系统时钟。
4. 配置USB预分频器：确保 USB Prescaler 输出48MHz。

我曾经遇到过一个坑：客户板子上用的晶振是12MHz，我按8MHz的倍频参数配，结果USB时钟算出来是72MHz，但USB分频后只有36MHz——枚举直接失败。所以，一定要根据实际晶振频率算PLL。

2.3 引脚分配——USB专用引脚不能乱接

USB外设有固定的引脚，不能随意映射。以STM32F103C8T6为例：

信号	引脚	说明
USB_DP	PA12	D+线，必须接1.5kΩ上拉电阻
USB_DM	PA11	D-线
USB_CONNECT	PC13（可选）	控制上拉电阻的GPIO

在CubeMX里，你只需要在 Pinout & Configuration 里勾选 USB 外设，软件会自动分配这些引脚。但要注意：不要手动去改USB的引脚，改了之后硬件连不上。

2.4 生成MDK-ARM工程

配置完成后，切换到 Project Manager 标签页：

• Project Name：给工程起个名字，比如 USB_Device_Demo。
• Project Location：选一个路径，我建议不要用中文路径，否则MDK编译可能报错。
• Toolchain / IDE：选 MDK-ARM。
• Firmware Package：选你用的HAL库版本，我一般用最新的稳定版。

然后点击右上角的 GENERATE CODE。CubeMX会生成一个完整的MDK工程，包含初始化代码、HAL库文件和启动文件。

2.5 核心流程一览

下面这张图概括了从CubeMX到MDK工程的完整流程，我把它画成了流程图，方便你对照操作：

2.6 生成后的工程结构

打开生成的MDK工程，你会看到这样的文件结构：

USB_Device_Demo/
├── Core/
│   ├── Inc/          # 头文件
│   ├── Src/          # 源文件（main.c, usb_device.c等）
│   └── Startup/      # 启动文件
├── Drivers/
│   ├── CMSIS/        # CMSIS核心文件
│   └── STM32F1xx_HAL_Driver/  # HAL库驱动
├── USB_Device/       # USB设备库（由CubeMX生成）
│   ├── App/          # 用户回调
│   ├── Target/       # 硬件配置
│   └── Core/         # USB协议栈核心
└── MDK-ARM/
    └── USB_Device_Demo.uvprojx  # 工程文件

嗯，这里要注意：USB_Device 文件夹里的文件是CubeMX自动生成的，不要手动修改。如果你需要定制USB行为，去修改 App 目录下的回调函数。

2.7 第一次编译

打开MDK，点击 Build 按钮。如果一切顺利，你会看到：

Build started: Project: USB_Device_Demo
*** Using Compiler 'V5.06 update 6', folder: ...
Compiling main.c...
Compiling usb_device.c...
...
Linking...
Program Size: Code=1234 RO-data=56 RW-data=12 ZI-data=256
Build finished successfully: 0 errors, 0 warnings.

如果出现错误，多半是路径问题或芯片选型不一致。检查一下 Project Manager 里的芯片型号是否和实际板子一致。