STM32CubeMX配置USB Device：模拟串口设备

原创于 2025-12-07 14:44:09 发布 · 881 阅读

14 ·

CC 4.0 BY-SA版权

文章标签：

#STM32 # 虚拟串口 # USB CDC

AI助手已提取文章相关产品：

如何用 STM32 实现一个“插上就认 COM 口”的虚拟串口？💻🔌

你有没有遇到过这种情况：手里的开发板只有一个硬件串口，但一边要烧录程序，一边又要实时输出调试日志……结果只能来回拔线、切换跳帽，烦不胜烦？🤯

或者你的产品明明功能都做好了，客户却说：“这设备连电脑怎么还要装驱动？”——其实他们不是不想装，而是怕出问题，更怕你给的 INF 文件被杀毒软件直接干掉。

那有没有一种方式，能让我们的 STM32 不用额外芯片、不用外接转换器、插上 USB 就能在 Windows 上自动识别成 COM 端口 ，而且还能像普通串口一样读写数据？

当然有！而且它早就集成在你每天用的 STM32 芯片里了 —— 没错，就是 USB CDC（Communication Device Class）虚拟串口技术 。✨

今天我们就来手把手带你打通这条“看不见的串口通道”，从零开始配置一个真正即插即用、跨平台兼容、代码自动生成的 USB 虚拟串口系统，全程使用 STM32CubeMX + HAL 库 ，不碰寄存器也能搞定！

为什么我们需要“虚拟串口”？🤔

先别急着点开 CubeMX，咱们得先搞清楚：传统串口真不够用了吗？

说实话，在很多场景下，UART 真的挺香：简单、稳定、协议清晰，Keil 里 printf 重定向一下就能打日志。但它有几个硬伤：

🚫 物理接口有限 ：多数 Cortex-M 芯片最多就 3~5 个 UART 外设；
🚫 需要电平转换 ：TTL 到 RS232 得加 MAX3232 这类芯片；
🚫 不能热插拔 ：插拔可能干扰通信，甚至烧坏串口；
🚫 远距离传输麻烦 ：走长线还得隔离、屏蔽、抗干扰……

而 USB 呢？几乎每台设备都有，支持热插拔、供电、高速传输，还自带枚举机制。如果能让 STM32 “伪装”成一个标准串口设备，那岂不是一举多得？

于是， USB CDC-ACM （Abstract Control Model）应运而生。它的本质是：
👉 让你的 MCU 通过 USB 接口模拟出一个“虚拟 COM 端口”，PC 端看到的就是一个普通的串口号（比如 COM8），可以用串口助手、Python pyserial 、Qt 上位机随便连，完全无感！

💡 小知识：Windows 自带的 usbser.sys 驱动就是专门用来处理这类 CDC 设备的。只要你 VID/PID 合法，系统会自动加载，根本不需要用户手动安装驱动！

技术核心：CDC 是怎么“骗过”电脑的？🧠

你以为 USB 和串口是两种完全不同协议？没错，但从应用层来看，CDC 的设计非常聪明 —— 它把 USB 协议封装成了“看起来像串口”的模样。

它是怎么做到的？

USB CDC-ACM 设备对外暴露两个逻辑接口：

🔹 控制接口（Control Interface）

这个接口并不传实际数据，而是用来模拟传统串口的一些控制信号和参数设置：

波特率（Baudrate）
数据位、停止位、校验位
DTR/RTS 流控信号

⚠️ 注意：这些参数大多数时候只是“形式上传递”，因为 USB 本身没有波特率概念！真正的数据速率由 USB 全速（12Mbps）决定。但 PC 端的串口工具仍然会发送这些配置命令，所以我们必须能接收并响应，否则某些软件会报错或拒绝连接。

🔹 数据接口（Data Interface）

这才是真正的数据通道，采用 批量传输（Bulk Transfer） 方式进行双向通信：

方向	端点类型	功能
主机 → MCU	OUT 端点	接收来自 PC 的数据
MCU → 主机	IN 端点	发送数据到 PC

每个端点都有最大包大小限制（通常是 64 字节），数据以 packet 为单位分批传输。

当设备插入 PC 后：
1. STM32 发送一系列描述符（Device Descriptor, Config Descriptor, String Descriptor…）
2. PC 解析发现这是个 CDC 类设备
3. 自动加载 usbser.sys 驱动
4. 分配一个 COMx 号码
5. 用户打开该 COM 口即可通信 ✅

整个过程就像插了个 CH340 或 CP2102 模块一样自然。

准备工作：硬件与时钟要求 ⚙️

别以为点了 CubeMX 就万事大吉。要想 USB 正常工作，有几个关键前提必须满足，尤其是 时钟源 ！

✅ 必须保证 USB 时钟为 48MHz！

STM32 的 USB FS 控制器对时钟精度要求极高，必须提供精确的 48MHz 时钟。常见方案如下：

对于 STM32F1/F4 系列（如 F407VG）：

使用外部晶振 HSE（通常 8MHz）
配置 PLL，将主频倍频的同时，分频出 48MHz 给 OTG_FS
示例：HSE=8MHz → PLLMUL×9 = 72MHz（系统时钟），同时 PLL 设置为 USB 专用分频输出 48MHz

📌 在 STM32CubeMX 中，你会看到这样的提示：

"USB clock needs to be configured to 48MHz"

如果你没启用 HSE 或者 PLL 没正确配置，这里会标红警告 ❌

特殊情况：部分型号支持内部 HSI48？

有的 STM32L0/L4 等低功耗系列内置了 HSI48 振荡器（48MHz 内部 RC），可以直接供 USB 使用，无需外部晶振。但在 F4/F1 上不行，必须靠 PLL + HSE。

所以记住一句话： 没有 48MHz，就没有 USB！

开始动手：STM32CubeMX 配置全流程 🛠️

我们以 STM32F407VGT6 为例，目标是让它通过 PA11/PA12 引脚连接 USB D+/D-，实现虚拟串口功能。

第一步：创建新工程

打开 STM32CubeMX，选择芯片型号，进入图形化界面。

第二步：配置 RCC（复位与时钟控制）

设置 High Speed Clock (HSE) 为 Crystal/Ceramic Resonator
启用时钟输出 MCO1（可选，用于调试）
确保 PLL 提供了 48MHz 输出（查看 Clock Configuration 标签页）

✅ 检查点：在 Clock Tree 图中确认 OTG_FS 分支显示为 48.0 MHz

第三步：启用 USB_OTG_FS 外设

在 Pinout 视图中找到 USB_OTG_FS ，点击启用。

默认情况下，它会自动映射到：
- PA11 → USB_DM
- PA12 → USB_DP

这两个引脚会被自动设为 Alternate Function 模式（AF10），不需要手动改。

💡 小贴士：PA9 是 VBUS 检测引脚，如果你希望实现“软插拔”或电源管理，可以启用它；否则也可以禁用 VBUS Sensing（后面讲技巧）。

第四步：配置 USB Device 中间件

左侧菜单 → Middleware → USB_DEVICE → 点击 Add

然后在右侧参数区设置：
- Class: Communication Device Class (CDC)
- Mode: Device Only （因为我们不做 OTG 主机）
- 参数建议：

参数	推荐值	说明
VID	`0x0483`	ST 官方厂商 ID，Windows 已知，免驱友好
PID	`0x5740`	可自定义，避免与其他设备冲突
Max Packet Size (EP0)	64 bytes	标准控制端点大小
CDC Tx Buffer Size	2048	发送缓冲区
CDC Rx Buffer Size	2048	接收缓冲区

📌 提示：修改 PID 可防止多个设备冲突。例如你有两个不同产品，可以用不同的 PID 区分。

第五步：生成代码

Project Manager 设置好项目名称、路径、IDE（Keil/IAR/SW4STM32 等）

Generate Code！

等待几秒，CubeMX 会自动生成完整的初始化框架，包括：
- usbd_cdc.c/h ：CDC 类实现
- usbd_desc.c ：设备描述符
- usb_device.c/h ：USB 设备初始化入口
- 回调函数模板

🎉 成功！你现在拥有了一个可以编译下载的 USB 设备工程！

关键代码解析：哪些是你必须懂的？📚

虽然大部分代码是自动生成的，但以下几个部分你一定要理解透彻，否则出了问题都不知道在哪查。

1. 初始化流程： `MX_USB_DEVICE_Init()`

void MX_USB_DEVICE_Init(void)
{
  if (USBD_Init(&hUsbDeviceFS, &FS_Desc, DEVICE_FS) != USBD_OK)
    Error_Handler();

  if (USBD_RegisterClass(&hUsbDeviceFS, &USBD_CDC) != USBD_OK)
    Error_Handler();

  if (USBD_CDC_RegisterInterface(&hUsbDeviceFS, &USBD_Interface_fops_FS) != USBD_OK)
    Error_Handler();

  if (USBD_Start(&hUsbDeviceFS) != USBD_OK)
    Error_Handler();
}

这段代码做了四件事：
1. 初始化 USB 设备句柄
2. 注册 CDC 类驱动
3. 绑定用户操作接口（重点！）
4. 启动设备监听

其中 USBD_Interface_fops_FS 是一个结构体，定义了回调函数指针：

USBD_CDC_ItfTypeDef USBD_Interface_fops_FS =
{
  .Init = CDC_Init_FS,
  .DeInit = CDC_DeInit_FS,
  .Control = CDC_Control_FS,
  .Receive = CDC_Receive_FS
};

这些函数都在 usbd_cdc_if.c 文件里，你可以在这里扩展自己的逻辑。

2. 接收回调函数： `CDC_Receive_FS()` —— 数据来了怎么办？

这是最最关键的函数之一。每当 PC 发送数据过来，HAL 层就会调用这个函数，并把数据指针和长度传进来。

uint8_t UserRxBufferFS[APP_RX_DATA_SIZE]; // 全局接收缓存
uint32_t rx_head = 0; // 环形缓冲头

static int8_t CDC_Receive_FS(uint8_t* Buf, uint32_t *Len)
{
    for(uint32_t i = 0; i < *Len; i++)
    {
        UserRxBufferFS[rx_head] = Buf[i];
        rx_head = (rx_head + 1) % RX_BUFFER_SIZE;
    }

    // ⚠️ 关键！必须重新启动接收，否则只触发一次
    USBD_CDC_ReceivePacket(&hUsbDeviceFS);

    return USBD_OK;
}

🔥 重点提醒：

如果你不调用 USBD_CDC_ReceivePacket() ，那么下次主机发数据时，MCU 就不会再进这个回调了！很多人卡在这一步，以为“收不到数据”，其实是忘了重启接收。

此外，这里的复制操作如果是大数据量，建议改用 DMA + 双缓冲机制，或者发消息给 RTOS 任务处理，避免阻塞中断上下文。

3. 发送函数： `CDC_Transmit_FS()` —— 如何安全地往外发？

发送函数是你主动调用的，一般封装成一个易用接口：

uint8_t CDC_Transmit(uint8_t* Buf, uint16_t Len)
{
    uint8_t result = USBD_BUSY;
    while (result == USBD_BUSY)
    {
        result = CDC_Transmit_FS(Buf, Len);
    }
    return (result == USBD_OK) ? 0 : 1;
}

注意： CDC_Transmit_FS() 是非阻塞的，如果当前总线忙，会返回 USBD_BUSY 。所以最好加上重试机制，或者结合事件标志（Event Flags）异步处理。

你也可以把它包装成 printf 的底层输出：

int __io_putchar(int ch)
{
    uint8_t temp = ch;
    CDC_Transmit(&temp, 1);
    return ch;
}

// 然后就可以直接用：
printf("Hello from Virtual COM Port!\r\n");

是不是瞬间高级了很多？😎

实战技巧：让虚拟串口更稳定、更好用 💡

光跑通 Demo 还不够，真正的工程要考虑稳定性、兼容性和用户体验。下面是一些我在项目中总结的最佳实践。

✅ 技巧一：修改设备信息，让它看起来更专业

默认生成的设备名是 “STM32 Board CDC in FS Mode”，太粗糙了。我们可以改字符串描述符，让它变成：

“SmartSensor Pro v1.0” by “MyTech Inc.”

修改文件： usbd_desc.c

/* 替换原始字符串 */
const uint8_t USBD_MANUFACTURER_STRING[] = "MyTech Inc.";
const uint8_t USBD_PRODUCT_STRING[]       = "SmartSensor Pro v1.0";
const uint8_t USBD_SERIALNUMBER_STRING[]  = "SN-123456789";

这样在设备管理器里看起来才像个正规产品 👔

✅ 技巧二：解决 Windows 驱动签名警告

即使用了官方 VID=0x0483，Windows 10/11 有时仍会弹窗提示“未签名驱动”。虽然不影响使用，但客户体验很差。

解决方案有两种：

方案 A：使用 WCID（Windows Compatible ID）

添加一个特殊的 Microsoft OS 描述符，告诉 Windows：“我是一个已知兼容设备”。

具体做法是在 usbd_cdc.c 中添加 os_compatible_id_descriptor ，并在 USBD_Get_Frame_WorkingString() 等函数中注册。

🔗 参考文档：ST AN4875，《How to design a USB device with WCID》

完成后，Windows 会自动识别为“USB CDC 控制设备”，不再弹窗。

方案 B：签署 INF 驱动（适合量产）

打包一个带数字签名的 .inf 文件，随产品发布。适用于企业级部署。

✅ 技巧三：实现“软插拔”功能（模拟断开再连接）

有时候你想让 PC 端重新识别设备（比如升级完固件后），但又不能真的拔线。

这时候可以用：

USBD_Stop(&hUsbDeviceFS);         // 停止设备
HAL_Delay(100);
USBD_Start(&hUsbDeviceFS);        // 重新启动

或者更彻底一点，控制 D+ 上拉电阻：

// 断开 USB 连接（去使能上拉）
HAL_GPIO_WritePin(GPIOA, GPIO_PIN_12, GPIO_PIN_RESET);
HAL_Delay(200);

// 重新连接
HAL_GPIO_WritePin(GPIOA, GPIO_PIN_12, GPIO_PIN_SET);
HAL_Delay(500);

这样主机就会认为你“拔了一次又插回去”，重新枚举设备。

✅ 技巧四：优化接收性能，防丢包

默认的接收机制是“中断 + 缓冲”，但如果主机连续高速发数据（比如每秒几千字节），容易造成缓冲区溢出。

改进方法：

增大 CDC Rx Buffer Size （CubeMX 里设为 2048 或更大）
使用环形队列 + 临界区保护
在 CDC_Receive_FS 中尽快拷贝数据，不要做复杂处理
结合 FreeRTOS，收到数据后发消息通知处理任务

示例结构：

typedef struct {
    uint8_t buf[RX_BUF_SIZE];
    uint16_t head, tail;
    osMutexId_t mutex;
} ring_buffer_t;

ring_buffer_t usb_rx_buf;

void push_to_ring(uint8_t* data, uint32_t len) {
    osMutexAcquire(usb_rx_buf.mutex, osWaitForever);
    for(...) { /* 入队 */ }
    osMutexRelease(usb_rx_buf.mutex);
}

✅ 技巧五：用 Wireshark 抓包分析 USB 通信（超实用！）

怀疑通信有问题？别猜了，直接抓包看！

工具推荐：
- Wireshark + USBPcap （开源免费）
- 安装后可在 Wireshark 中选择 USB 接口进行捕获

你能看到：
- 枚举全过程（SETUP 请求、描述符交换）
- 每一笔 Bulk 传输的数据内容
- 是否出现 NAK、STALL 等异常

简直是 USB 调试神器 🔍

常见问题排查清单 ❌✅

问题现象	可能原因	解决办法
电脑无反应，不识别设备	48MHz 时钟未到位	检查 HSE 和 PLL 设置
识别为“未知设备”	描述符错误或未完成枚举	用 Wireshark 抓包检查
只能发不能收	忘记调用 `USBD_CDC_ReceivePacket()`	在接收回调末尾补上
收到乱码或丢包	接收缓冲太小或处理太慢	扩大缓冲 + 异步处理
Windows 提示“驱动未签名”	缺少 WCID 或 INF 签名	添加兼容 ID 或签署驱动
插拔后无法重连	没释放资源或状态混乱	加 `USBD_Stop/Start` 重启