1. 为什么要在 RP2350 上折腾 USB 虚拟串口树莓派 RP2350 这颗芯片发布之后我身边不少做嵌入式的朋友都在讨论它。双核 Cortex-M33 加双核 Hazard3 RISC-V 的混合架构、150MHz 主频、520KB SRAM、还有那个可编程 IOPIO参数确实好看。但真正让我决定拿它做项目的是一个很实际的需求我需要一个能通过 USB 接口跟上位机通信的调试通道而且这个通道要足够稳定、足够通用最好插上电脑就能认出来不需要额外装驱动。USB 虚拟串口CDC-ACMCommunication Device Class - Abstract Control Model就是干这个的。它的本质是让 MCU 通过 USB 接口模拟出一个传统的串口设备上位机看到的是一个 COM 口Windows或者 /dev/ttyACMxLinux/macOS然后就可以用任何串口工具打开它、收发数据。相比传统的 UART 转 USB 芯片方案比如 CH340、CP2102CDC-ACM 不需要额外的硬件芯片直接用 MCU 自带的 USB 控制器就能实现省了 BOM 成本也省了 PCB 面积。但事情没这么简单。RP2350 的 USB 控制器虽然兼容 USB 2.0 全速规范但它的寄存器配置、端点管理、中断处理和 STM32 那套完全不一样。我翻了一遍官方数据手册和 SDK 源码发现网上关于 RP2350 USB CDC 的中文资料少得可怜大部分都是 RP2040 的而 RP2350 在 USB 部分虽然基本兼容但时钟配置和电源管理上有一些关键差异。所以这篇文章我打算把整个流程从头到尾捋一遍从 USB 协议栈的基本原理到 RP2350 的硬件配置到驱动代码的编写再到实际调试过程中踩过的坑全部摊开来讲。这篇文章适合谁看如果你正在做树莓派的毕设项目需要跟 PC 端做数据交互或者你在搞硬件调试想给自己做的板子加一个方便的调试通道又或者你只是单纯想学一下 USB 设备端的开发流程那这篇内容应该能帮到你。我会尽量把每个步骤的原因讲清楚不只是告诉你“这么写”还要告诉你“为什么这么写”。2. USB CDC-ACM 的核心原理与 RP2350 硬件适配2.1 CDC-ACM 到底是怎么工作的很多人第一次接触 USB 虚拟串口的时候会觉得它很神奇明明是一个 USB 设备为什么电脑会认成一个串口这背后的机制其实不复杂但需要理解 USB 协议的几个基本概念。USB 通信是主机主导的所有数据传输都由主机发起。设备端要做的事情是描述自己是什么设备、支持哪些功能、数据通过哪个端点传输。CDC-ACM 类设备在枚举过程中会向主机报告两组接口描述符一组是通信类接口Communication Class Interface用来传输控制信号比如波特率设置、线路状态另一组是数据类接口Data Class Interface用来传输实际的数据。主机看到这组描述符之后就知道这是一个串口设备然后加载对应的 CDC 驱动在系统里创建一个虚拟串口。整个枚举过程大致是这样的设备插入后主机先发送 GET_DESCRIPTOR 请求获取设备描述符然后获取配置描述符集合里面包含了接口描述符、端点描述符和 CDC 功能描述符。主机根据这些信息判断设备类型加载驱动然后发送 SET_CONFIGURATION 激活设备。之后主机还会发送 SET_CONTROL_LINE_STATE 和 SET_LINE_CODING 请求来设置串口参数波特率、数据位、停止位等虽然对于 USB 全速设备来说这些参数实际上不影响数据传输速率但协议要求必须响应。RP2350 的 USB 控制器支持设备模式和主机模式我们这里用的是设备模式。它内部有 16 个端点EP0 到 EP15其中 EP0 是控制端点用于枚举过程中的标准请求其他端点可以配置为中断端点、批量端点或同步端点。对于 CDC-ACM我们通常用 EP0 做控制传输EP1 做中断端点用于通知主机线路状态变化EP2 做批量端点用于实际数据收发。2.2 RP2350 相比 RP2040 在 USB 上的关键差异RP2350 的 USB 控制器基本继承了 RP2040 的设计但有几个地方需要注意。首先是时钟配置RP2350 的 USB 模块需要一个 48MHz 的时钟源这个时钟可以来自内部 PLL 或者外部晶振。RP2040 通常用 PLL_USB 来生成 48MHzRP2350 也支持这种方式但它的 PLL 配置寄存器有一些变化需要参考最新的 SDK 代码。其次是电源管理RP2350 的 USB 模块有独立的电源域控制在初始化之前需要确保 USB 电源域已经上电。这一点在 RP2040 上不太明显但在 RP2350 上如果忘记配置USB 枚举会直接失败而且不会有任何错误提示非常容易踩坑。还有一个差异是 IO 配置RP2350 的 USB DP/DM 引脚是固定的不能像 RP2040 那样通过 GPIO 功能选择来映射。RP2350 的 USB 引脚固定在 GPIO 14 和 GPIO 15具体取决于封装需要在初始化时正确配置这两个引脚的功能。2.3 为什么选择 TinyUSB 而不是自己写协议栈USB 协议栈的复杂度很高从最底层的物理层信号处理到链路层的包格式到协议层的标准请求处理再到设备类的功能实现全部自己写的话工作量巨大而且很容易在细节上出错。TinyUSB 是一个开源的跨平台 USB 协议栈支持多种 MCU 平台包括 RP2040 和 RP2350。它已经实现了 USB 设备端的核心功能包括枚举、标准请求处理、端点管理以及多种设备类CDC、HID、MSC 等。用 TinyUSB 的好处是你只需要关注设备类的具体实现底层的协议细节它帮你处理了。而且 TinyUSB 的 CDC-ACM 实现已经非常成熟在 RP2040 上经过了大量验证移植到 RP2350 上只需要做少量的适配工作。当然如果你想深入理解 USB 协议自己写一遍协议栈是很好的学习方式但在实际项目中用成熟的协议栈是更明智的选择。3. 开发环境搭建与项目骨架3.1 工具链安装与 SDK 配置RP2350 的官方开发工具链是 Raspberry Pi Pico SDK它包含了编译器配置、硬件抽象层、以及 TinyUSB 的集成。我推荐用 VS Code 加官方插件的方式来搭建环境这样代码补全和调试都比较方便。首先需要安装 ARM GCC 工具链。如果你用的是 Ubuntu可以直接通过包管理器安装sudo apt update sudo apt install gcc-arm-none-eabi libnewlib-arm-none-eabi build-essential然后克隆 Pico SDK 和 TinyUSB 仓库git clone https://github.com/raspberrypi/pico-sdk.git cd pico-sdk git submodule update --init设置环境变量让 CMake 能找到 SDKexport PICO_SDK_PATH/path/to/pico-sdk如果你用的是 Windows推荐安装 Raspberry Pi Pico 的 VS Code 扩展它会自动帮你配置好工具链和 SDK省去手动配置的麻烦。不过要注意RP2350 需要 SDK 版本 2.0.0 以上旧版本不支持。3.2 创建项目骨架用 CMake 创建一个新项目目录结构大概是这样rp2350_usb_cdc/ ├── CMakeLists.txt ├── src/ │ ├── main.c │ ├── usb_descriptors.c │ └── tusb_config.h └── build/CMakeLists.txt 的内容cmake_minimum_required(VERSION 3.13) include($ENV{PICO_SDK_PATH}/external/pico_sdk_import.cmake) project(rp2350_usb_cdc C CXX ASM) set(CMAKE_C_STANDARD 11) set(CMAKE_CXX_STANDARD 17) pico_sdk_init() add_executable(rp2350_usb_cdc src/main.c src/usb_descriptors.c ) target_link_libraries(rp2350_usb_cdc pico_stdlib tinyusb_device tinyusb_board ) pico_enable_stdio_uart(rp2350_usb_cdc 0) pico_enable_stdio_usb(rp2350_usb_cdc 1) pico_add_extra_outputs(rp2350_usb_cdc)这里有几个关键点tinyusb_device和tinyusb_board是必须链接的库前者提供设备端协议栈后者提供板级支持。pico_enable_stdio_usb打开后printf的输出会通过 USB CDC 发送这在调试的时候非常方便。3.3 TinyUSB 配置文件TinyUSB 需要一个配置文件tusb_config.h用来指定设备类、端点数量、缓冲区大小等参数。对于 CDC-ACM配置大概是这样#ifndef _TUSB_CONFIG_H_ #define _TUSB_CONFIG_H_ #define CFG_TUSB_MCU OPT_MCU_RP2040 #define CFG_TUSB_OS OPT_OS_NONE #define CFG_TUD_ENABLED 1 #define CFG_TUD_MAX_SPEED OPT_MODE_FULL_SPEED #define CFG_TUD_CDC 1 #define CFG_TUD_CDC_RX_BUFSIZE 256 #define CFG_TUD_CDC_TX_BUFSIZE 256 #define CFG_TUD_CDC_EP_BUFSIZE 64 #define CFG_TUD_ENDPOINT0_SIZE 64 #endif注意CFG_TUSB_MCU这里写的是OPT_MCU_RP2040因为 TinyUSB 目前还没有单独的 RP2350 选项但 RP2350 的 USB 寄存器兼容 RP2040所以可以直接用这个配置。CFG_TUD_CDC_RX_BUFSIZE和TX_BUFSIZE是接收和发送缓冲区的大小根据你的数据量来调整一般 256 字节够用了。4. USB 描述符编写与驱动核心代码实现4.1 设备描述符与配置描述符USB 描述符是设备向主机自我介绍的数据结构。对于 CDC-ACM 设备需要提供设备描述符、配置描述符、接口描述符、端点描述符和 CDC 功能描述符。这些描述符在usb_descriptors.c中定义。设备描述符定义了厂商 ID、产品 ID、设备类等信息tusb_desc_device_t const desc_device { .bLength sizeof(tusb_desc_device_t), .bDescriptorType TUSB_DESC_DEVICE, .bcdUSB 0x0200, .bDeviceClass TUSB_CLASS_MISC, .bDeviceSubClass MISC_SUBCLASS_COMMON, .bDeviceProtocol MISC_PROTOCOL_IAD, .bMaxPacketSize0 CFG_TUD_ENDPOINT0_SIZE, .idVendor 0x2E8A, .idProduct 0x000A, .bcdDevice 0x0100, .iManufacturer 0x01, .iProduct 0x02, .iSerialNumber 0x03, .bNumConfigurations 0x01 };idVendor这里用的是树莓派的官方 VID0x2E8A如果你只是自己做实验用这个没问题但如果要量产需要申请自己的 VID。bDeviceClass设置为TUSB_CLASS_MISC并配合 IADInterface Association Descriptor是因为 CDC-ACM 需要两个接口通信接口和数据接口IAD 告诉主机这两个接口属于同一个功能。配置描述符集合包含了接口和端点的完整描述uint8_t const desc_configuration[] { // 配置描述符 TUD_CONFIG_DESCRIPTOR(1, 2, 0, 75, 0x00, 100), // 通信接口描述符 TUD_CDC_DESCRIPTOR(0, 4, 0x81, 8, 0x02, 0x82, 64) };TUD_CDC_DESCRIPTOR这个宏展开后会生成通信接口描述符、CDC 功能描述符、中断端点描述符、数据接口描述符和批量端点描述符。参数含义分别是接口号、字符串索引、中断端点地址、中断端点大小、数据端点地址、数据端点大小。这里中断端点用的是 EP1 IN0x81数据端点用的是 EP2 OUT0x02和 EP2 IN0x82端点大小都是 64 字节。4.2 CDC 数据收发实现TinyUSB 提供了简洁的 API 来操作 CDC 接口。发送数据用tud_cdc_write()接收数据用tud_cdc_read()。但要注意这些函数不是阻塞的它们只是把数据放入缓冲区或者从缓冲区取出数据实际的 USB 传输由 TinyUSB 的任务函数在后台处理。一个典型的数据收发循环是这样的void cdc_task(void) { if (tud_cdc_available()) { uint8_t buf[64]; uint32_t count tud_cdc_read(buf, sizeof(buf)); // 处理接收到的数据 process_data(buf, count); } if (tud_cdc_write_available()) { // 发送数据 tud_cdc_write(tx_buf, tx_len); tud_cdc_write_flush(); } }这个函数需要在主循环中定期调用。tud_cdc_available()返回接收缓冲区中可用的字节数tud_cdc_write_available()返回发送缓冲区中还能写入多少字节。tud_cdc_write_flush()强制把缓冲区中的数据发送出去如果不调用这个函数数据可能会在缓冲区里等待直到缓冲区满了才发送。4.3 主循环与 TinyUSB 任务调度TinyUSB 的设备端需要定期调用tud_task()来处理 USB 事件和传输。这个函数应该在主循环中尽可能频繁地调用以保证 USB 通信的实时性。一个典型的主循环int main(void) { stdio_init_all(); tusb_init(); while (1) { tud_task(); cdc_task(); } }tusb_init()会初始化 USB 控制器和 TinyUSB 协议栈tud_task()处理 USB 中断和传输完成事件。如果你用的是 RTOS可以把tud_task()放在一个独立的任务中但要注意任务优先级和栈大小的配置。5. 调试实战从枚举失败到稳定通信5.1 枚举失败的常见原因与排查USB 设备插上电脑后如果枚举失败表现通常是设备管理器里出现一个带感叹号的未知设备或者设备反复连接断开。RP2350 上枚举失败最常见的原因是时钟配置错误。前面提到过USB 模块需要精确的 48MHz 时钟。如果时钟偏差超过 USB 规范的容差全速设备是 ±0.25%枚举就会失败。RP2350 的 USB 时钟通常来自 PLL_USB配置代码如下void usb_clock_init(void) { // 设置 PLL_USB 输出 48MHz // 假设外部晶振是 12MHz // VCO 12MHz * 100 / 2 600MHz // 输出 600MHz / 12.5 48MHz pll_init(pll_usb, 1, 100, 2, 12, 0); // 使能 USB 时钟 clk_peri_ctrl(CLK_USB, true); }这段代码的计算过程是PLL 的输入是 12MHz 晶振经过分频器REFDIV1后还是 12MHz然后乘以反馈分频器FBDIV100得到 1200MHz再经过后分频器POSTDIV12, POSTDIV212得到 1200/2/12 50MHz。等等这个结果不对应该是 48MHz。让我重新算一下12MHz * 100 / 2 / 12.5 48MHz但 POSTDIV 只能是整数。正确的配置应该是 FBDIV96, POSTDIV12, POSTDIV212这样 12 * 96 / 2 / 12 48MHz。或者 FBDIV100, POSTDIV15, POSTDIV25这样 12 * 100 / 5 / 5 48MHz。实际配置的时候建议直接用 Pico SDK 提供的set_sys_clock_48mhz()函数它会自动计算正确的 PLL 参数。如果你需要同时跑高速系统时钟和 USB可以用set_sys_clock_khz()来配置SDK 会自动处理 USB 时钟的分频。另一个常见的枚举失败原因是描述符配置错误。比如端点地址冲突、端点大小超过限制、配置描述符总长度不对等。TinyUSB 在编译时会对描述符做一些检查但有些错误只有在运行时才会暴露。我建议在调试的时候打开 TinyUSB 的日志输出把CFG_TUSB_DEBUG设置为 2 或 3这样可以看到详细的枚举过程日志。5.2 数据丢包与缓冲区溢出问题枚举成功之后下一个常见问题是数据丢包。表现是上位机发送的数据MCU 有时候收不到或者 MCU 发送的数据上位机有时候收不全。这个问题的根源通常是缓冲区管理不当。TinyUSB 的 CDC 接收缓冲区大小由CFG_TUD_CDC_RX_BUFSIZE决定默认是 64 字节。如果你的上位机发送数据的速度很快而主循环中调用cdc_task()的频率不够高缓冲区就会溢出导致数据丢失。解决办法有两个一是增大接收缓冲区比如改成 512 或 1024 字节二是提高cdc_task()的调用频率或者用中断的方式来处理接收数据。TinyUSB 提供了接收回调函数tud_cdc_rx_cb()可以在收到数据时自动调用void tud_cdc_rx_cb(uint8_t itf) { uint8_t buf[64]; uint32_t count tud_cdc_read(buf, sizeof(buf)); // 处理数据 }这个回调是在 USB 中断上下文中执行的所以处理要尽量快不要在里面做耗时操作。如果需要做复杂处理可以把数据拷贝到队列中在主循环中处理。发送方向的丢包通常是tud_cdc_write_flush()没有及时调用导致的。TinyUSB 的发送缓冲区满了之后tud_cdc_write()会返回实际写入的字节数如果小于请求的字节数说明缓冲区满了需要等待下次再写。我通常会在发送函数里加一个循环确保所有数据都写入了void cdc_send(uint8_t *data, uint32_t len) { uint32_t sent 0; while (sent len) { if (tud_cdc_write_available()) { sent tud_cdc_write(data sent, len - sent); tud_cdc_write_flush(); } else { tud_task(); } } }5.3 上位机串口工具的配置要点上位机这边我用过几个不同的串口工具各有各的特点。Windows 上常用的是 SSCOM 和串口调试助手Linux 上可以用 minicom 或 picocommacOS 上可以用 screen。配置的时候有几个要点波特率虽然对 USB CDC 的实际传输速率没有影响但有些工具会检查这个参数所以最好设置成常用的值比如 115200。数据位 8、停止位 1、无校验这是最通用的配置。流控一定要关掉因为 CDC-ACM 通常不支持硬件流控。Linux 下还有一个坑默认情况下普通用户没有权限访问 /dev/ttyACMx 设备。需要把用户加到 dialout 组sudo usermod -a -G dialout $USER然后重新登录生效。或者临时用sudo chmod 666 /dev/ttyACM0来修改权限但每次插拔后都要重新设置。5.4 用 printf 重定向做调试输出调试 USB 通信的时候最方便的方式是把printf重定向到 USB CDC这样你可以直接在串口工具里看到 MCU 打印的调试信息。Pico SDK 已经帮我们做好了这件事只需要在 CMakeLists.txt 中设置pico_enable_stdio_usb为 1然后在代码中调用stdio_init_all()即可。但要注意printf的输出是阻塞的如果 USB 没有连接或者发送缓冲区满了printf会一直等待导致程序卡住。所以在实际项目中我建议用一个非阻塞的日志函数把日志数据放入环形缓冲区在主循环中异步发送。#define LOG_BUF_SIZE 1024 static uint8_t log_buf[LOG_BUF_SIZE]; static volatile uint32_t log_head 0; static volatile uint32_t log_tail 0; void log_printf(const char *fmt, ...) { va_list args; va_start(args, fmt); char tmp[128]; int len vsnprintf(tmp, sizeof(tmp), fmt, args); va_end(args); for (int i 0; i len; i) { uint32_t next (log_head 1) % LOG_BUF_SIZE; if (next ! log_tail) { log_buf[log_head] tmp[i]; log_head next; } } } void log_task(void) { while (log_tail ! log_head) { if (tud_cdc_write_available()) { tud_cdc_write(log_buf[log_tail], 1); log_tail (log_tail 1) % LOG_BUF_SIZE; } else { break; } } tud_cdc_write_flush(); }这个环形缓冲区的实现很简单但能有效避免printf阻塞的问题。log_printf()只负责把数据写入缓冲区实际的 USB 发送由log_task()在主循环中完成。6. 常见问题速查与避坑经验6.1 枚举问题排查表现象可能原因排查方法设备管理器显示未知设备描述符配置错误用 USB 分析仪抓包检查描述符内容设备反复连接断开时钟不稳定或电源不足测量 USB 48MHz 时钟检查电源纹波枚举成功但无法打开串口驱动问题或权限问题检查系统日志Linux 下检查 dialout 组权限设备识别但无数据端点配置错误检查端点地址和方向是否匹配6.2 数据通信问题排查表现象可能原因排查方法发送数据丢包缓冲区溢出增大 TX 缓冲区检查 flush 调用接收数据丢包主循环调用频率低增大 RX 缓冲区使用接收回调数据乱码波特率不匹配虽然 CDC 不影响速率但部分工具会检查通信一段时间后断开看门狗复位或内存泄漏检查看门狗配置用内存分析工具排查6.3 几个我踩过的坑第一个坑是 RP2350 的 USB 电源域配置。RP2040 上 USB 模块的电源是默认打开的但 RP2350 需要显式配置。如果忘记这一步USB 枚举会直接失败而且不会有任何错误提示。解决办法是在初始化代码中调用powman_set_power_state()或者直接使用 SDK 提供的usb_init()函数它会自动处理电源配置。第二个坑是描述符中的字符串索引。USB 描述符中的iManufacturer、iProduct、iSerialNumber字段是字符串描述符的索引如果这些索引指向的字符串描述符没有正确定义主机在获取字符串描述符时会失败导致枚举中断。我建议在调试阶段先把这些字段设为 0等基本功能调通了再添加字符串描述符。第三个坑是 TinyUSB 的任务调度。如果你在cdc_task()中做了耗时操作比如等待某个外设响应会导致tud_task()调用不及时USB 通信出现异常。解决办法是把耗时操作放到独立的任务中或者用状态机的方式把操作拆分成多个小步骤在每次主循环中执行一步。第四个坑是 Windows 下的驱动缓存。有时候你修改了描述符中的 VID/PID但 Windows 会缓存旧的驱动信息导致新设备无法正确识别。解决办法是在设备管理器中卸载旧设备并勾选“删除驱动程序软件”然后重新插入设备。6.4 性能优化建议如果你需要高速数据传输比如把 RP2350 采集的传感器数据实时传到 PC有几个优化方向。一是增大端点缓冲区USB 全速设备的批量端点最大支持 64 字节但你可以用多个端点或者增大内部缓冲区来提高吞吐量。二是减少tud_task()的调用间隔把主循环中其他任务的执行时间尽量缩短。三是使用 DMA 来搬运数据减少 CPU 占用。实测下来RP2350 的 USB CDC 在优化之后可以稳定跑到 800KB/s 以上的吞吐量对于大多数调试和数据采集场景来说完全够用了。7. 项目扩展与进阶方向7.1 多路 CDC 接口实现TinyUSB 支持同时创建多个 CDC 接口只需要把CFG_TUD_CDC设置为大于 1 的值并在描述符中定义多个 CDC 描述符。每个 CDC 接口在主机上会显示为独立的串口可以用于不同的用途比如一个用于调试日志一个用于数据传输。实现的时候要注意端点分配每个 CDC 接口需要一个中断端点和一对批量端点RP2350 的 16 个端点足够支持多个 CDC 接口。但端点地址不能冲突需要在描述符中正确配置。7.2 结合 PIO 做高速数据采集RP2350 的 PIO可编程 IO是一个非常强大的外设可以用于实现自定义的通信协议。如果你需要采集高速数据比如 SPI 或并行接口的传感器数据可以用 PIO 来做数据采集然后通过 USB CDC 传到 PC。PIO 的优点是硬件级并行执行不占用 CPU 时间可以做到很高的采样率。7.3 在 RTOS 环境下使用 TinyUSB如果你的项目比较复杂需要用 RTOS 来管理多个任务TinyUSB 也可以很好地集成。FreeRTOS 是 Pico SDK 官方支持的 RTOS你可以把tud_task()放在一个独立的任务中用队列来传递 USB 数据。需要注意的是TinyUSB 的回调函数是在中断上下文中执行的不能直接调用 RTOS 的阻塞 API需要用xQueueSendFromISR()这类中断安全的函数。7.4 用 USB CDC 做固件升级通道一个比较实用的扩展是用 USB CDC 做固件升级IAP。基本思路是上位机通过 CDC 发送新的固件数据MCU 接收到之后写入 Flash 的指定区域然后跳转到 Bootloader 进行固件更新。这个方案的好处是不需要额外的调试器用户只需要一根 USB 线就能完成固件升级。实现的时候要注意 Flash 的擦写操作需要在 RAM 中执行因为 RP2350 的 Flash 在执行擦写时无法同时读取指令。Pico SDK 提供了flash_range_erase()和flash_range_program()函数但调用这些函数之前需要确保中断已关闭并且代码在 RAM 中运行。我在实际项目中发现USB CDC 的稳定性很大程度上取决于主循环的调度策略。如果主循环中有其他耗时任务USB 通信就容易出问题。后来我把 USB 任务放在了一个高优先级的定时器中断中每 1ms 调用一次tud_task()通信稳定性明显提升。这个方案不一定适合所有场景但如果你也遇到类似的问题可以试试这个思路。