1. 项目缘起：当Arduino遇上国产MCU的USB键盘梦

最近在捣鼓一个桌面小工具，核心需求是想用一块小巧的开发板，通过USB接口模拟成一个键盘，自动执行一些按键序列，比如快速输入一串复杂的密码、或者一键打开某个软件组合。这个想法本身不新鲜，用Arduino Leonardo或者Pro Micro这类原生支持USB HID的板子很容易实现。但手头正好有几片沁恒微电子的CH32x033系列MCU，价格非常香，性能也足够，就琢磨着能不能用它来搞。一查资料，CH32x033是基于RISC-V内核的，自带USB FS Device接口，硬件底子是完全支持的。那剩下的问题就是软件环境了。

直接用官方的MounRiver Studio开发当然没问题，但对于习惯了Arduino生态的玩家来说，每次都要配置一套新的IDE、学习新的库函数，门槛还是有点高。能不能在Arduino IDE里直接开发CH32x033的USB键盘功能呢？这样一来，海量的Arduino库和社区资源就能直接为我所用，开发效率会高很多。这个“Ch32x033 Arduino 环境USB 键盘开发”的项目，就是要把这条路走通。它本质上是一个开发环境的搭建和核心功能的实现过程，目标是在Arduino IDE这个我们熟悉的舞台上，让CH32x033这块国产MCU唱好USB HID键盘这出戏。

这对于喜欢折腾硬件的朋友来说，价值很明显。一方面，你可以用极低的成本（CH32x033芯片或核心板很便宜）获得一个功能完整的USB键盘设备，用于自动化、宏按键、人机交互等各种创意项目。另一方面，你无需脱离熟悉的Arduino编程模式，降低了从8位AVR世界过渡到32位RISC-V MCU进行USB开发的学习曲线。下面，我就把自己从环境搭建、代码移植、功能实现到调试踩坑的完整过程分享出来。

2. 环境搭建：让Arduino IDE认识CH32x033

万事开头难，第一步就是要让Arduino IDE能够支持CH32x033这块板子。Arduino IDE本身并不原生支持CH32系列，我们需要通过添加第三方硬件支持包来实现。

2.1 安装CH32核心支持包

目前，社区已经有热心开发者将CH32系列移植到了Arduino框架下。最常用的是OpenW-CH32这个核心包。安装步骤如下：

1. 打开Arduino IDE：确保你使用的是较新版本的Arduino IDE，比如1.8.x或2.0以上版本。
2. 添加开发板管理器网址：点击文件->首选项。在“附加开发板管理器网址”一栏中，填入以下URL：

   https://github.com/openwch/arduino_core_ch32/releases/download/github_actions/package_openwch_index.json

   如果你之前添加过其他网址，可以换行并列添加。
3. 安装核心：点击工具->开发板->开发板管理器...。在搜索框中输入“CH32”，你应该能找到“OpenW-CH32 Cortex-Mx Boards”这个选项。选择最新版本，点击“安装”。这个过程会下载编译工具链、相关库和板级定义文件。

安装完成后，在工具->开发板的下拉菜单里，你应该就能看到“OpenW-CH32 Cortex-Mx Boards”分类，其下包含CH32V、CH32F等多个系列的子选项。对于CH32x033，我们通常选择“CH32Vxxx”系列中对应的板子，比如“CH32V003F4P6”或类似的，具体取决于你使用的芯片型号和封装。如果你的板子不在列表，可能需要选择一款引脚兼容的，或者后续手动修改板级配置。

2.2 安装USB库的依赖

我们的目标是USB键盘，这依赖于USB HID功能。在Arduino for CH32的核心包中，USB功能通常是通过一个名为USBDevice的库来提供的，但这个库可能不会随核心包自动安装完整。

我们需要手动检查并安装必要的库。点击项目->加载库->管理库...，打开库管理器。尝试搜索“USBHID”或“CH32 USB”。你可能会找到一些通用的USB HID库，但对于CH32，更可能的是需要依赖核心包自带的底层驱动。一个关键点是，许多实现是基于PluggableUSB和HID这些Arduino Leonardo/Micro使用的核心库概念移植的。对于CH32核心包，我们通常需要确保USBDevice库的存在。有时它已经集成在硬件包路径里了。

更直接的方法是查看示例。安装好核心包后，在文件->示例中，找到“OpenW-CH32 Cortex-Mx Boards”分类，看看下面是否有“USB”或“HID”相关的例子，比如“Keyboard”或“Mouse”。如果有，说明环境基本就绪。如果没有，你可能需要从开源仓库（如OpenW-CH32的GitHub）手动下载libraries目录下的相关库文件，拷贝到你的Arduino本地库文件夹中。

2.3 驱动安装与端口识别

这是第一个容易踩坑的地方。当你通过USB线将CH32x033开发板连接到电脑时，电脑需要识别它。在两种模式下，电脑会看到不同的设备：

1. 编程模式（Bootloader模式）：大部分CH32开发板通过拉低某个引脚（如BOOT0）或按复位键进入此模式。此时，芯片内置的USB DFU（设备固件升级）或串口引导程序会运行，电脑会识别为一个USB串口（CDC）设备或DFU设备。你需要安装对应的USB转串口驱动（如CH340、CP2102等，根据板载转换芯片而定）或DFU驱动，才能在Arduino IDE的端口列表中看到它，并进行程序上传。
2. 运行模式（我们的键盘模式）：当我们的键盘程序运行时，芯片会将自己枚举为一个USB HID键盘设备。此时，电脑会把它识别为一个键盘，而不是串口。因此，在程序上传后，你很可能在Arduino IDE的端口列表中就看不到这个设备了，因为它的身份变了。

操作流程：首先，确保板子处于编程模式（具体操作看板子说明，通常是按住某个按钮再上电或按复位），在Arduino IDE中选择正确的端口，上传程序。上传完成后，板子会自动复位运行新程序，切换为HID键盘模式。此时如果你想再次上传程序，就需要重新让板子进入编程模式。

注意：有些CH32核心板可能使用了ft232r usb uart驱动或pl2303 usb转串口驱动等芯片，务必根据板子实际使用的USB转串口芯片型号，在电脑上安装正确的驱动，否则连第一步上传都无法进行。驱动安装失败是新手最常见的问题之一。

3. 代码实现：从“Hello World”到按键发送

环境准备好后，我们来编写第一个USB键盘程序。在Arduino for CH32的环境下，实现USB键盘功能通常有两种思路：一是使用类似原生Arduino Leonardo的Keyboard库的API；二是直接调用底层USBDevice和HID库的接口。这里我们以第一种更直观的方式为例，并解释其背后的原理。

3.1 基础键盘按键发送

首先，我们实现一个最简单的功能：上电后，延迟几秒（给你时间打开记事本），然后自动输入字符串“Hello World”。

#include <Keyboard.h> // 假设我们有或移植了Keyboard库 void setup() { // 初始化键盘功能 Keyboard.begin(); // 给用户一点时间切换焦点到文本编辑器 delay(3000); // 模拟按键输入 Keyboard.print("Hello World"); // 按一下回车 Keyboard.write(KEY_RETURN); } void loop() { // 主循环可以空着，或者执行其他逻辑 // 一旦调用Keyboard.print()，数据就会通过USB发送出去 }

这段代码看起来和标准Arduino Leonardo的键盘程序一模一样，这就是在Arduino环境下开发的好处——API统一。但关键在于，这个Keyboard.h库需要针对CH32的USB底层进行适配。在OpenW-CH32核心包中，可能已经包含了这个库。如果没有，你需要找到一个为CH32实现的Keyboard库。它的内部实际上会调用USBDevice.send()之类的函数，将HID键盘报告描述符和数据包通过USB端点发送给主机。

3.2 深入HID报告描述符

如果你想更深入地控制，或者遇到现成库不满足需求的情况（比如实现多媒体键、系统控制键），就需要了解HID报告描述符。USB HID设备通过一个叫做“报告描述符”的数据结构告诉电脑它是什么设备、能发送哪些数据。对于键盘，这个描述符定义了哪些字节代表按键码，哪些字节代表修饰键（Ctrl, Shift等）。

在CH32的Arduino核心中，这个描述符通常已经在底层库（如USBHID或HID）中定义好了。但你可以修改它来扩展功能。例如，一个标准的键盘报告描述符可能只支持6键无冲，如果你想支持更多，或者加入鼠标、摇杆等复合设备，就需要修改它。

修改描述符是一个高级话题，通常需要你找到核心包中HID库的源代码，修改descriptor.c或类似文件中的数组。这里不展开，但你需要知道这是自定义HID设备的钥匙。

3.3 实现矩阵键盘扫描

一个更实际的场景是，我们可能用CH32x033连接一个实际的4*3矩阵键盘或4x4矩阵键盘，将物理按键转换为USB按键事件。这就涉及到GPIO扫描逻辑。

#include <Keyboard.h> // 假设4x4矩阵键盘，行设为输出，列设为输入上拉 const int rowPins[4] = {PA0, PA1, PA2, PA3}; // 行，输出 const int colPins[4] = {PA4, PA5, PA6, PA7}; // 列，输入，内部上拉 // 映射表：行列位置对应的按键字符或键值 char keyMap[4][4] = { {'1','2','3','A'}, {'4','5','6','B'}, {'7','8','9','C'}, {'*','0','#','D'} }; void setup() { for (int i = 0; i < 4; i++) { pinMode(rowPins[i], OUTPUT); digitalWrite(rowPins[i], HIGH); // 默认行输出高电平 pinMode(colPins[i], INPUT_PULLUP); // 列输入，启用内部上拉 } Keyboard.begin(); delay(1000); // 等待USB枚举 } void loop() { for (int r = 0; r < 4; r++) { // 将当前行拉低，其他行拉高 digitalWrite(rowPins[r], LOW); delayMicroseconds(10); // 短暂稳定时间 for (int c = 0; c < 4; c++) { // 扫描每一列 if (digitalRead(colPins[c]) == LOW) { // 按键按下 char key = keyMap[r][c]; // 这里简单处理，实际应加入消抖和释放检测 Keyboard.press(key); // 对于'A'等字符，Keyboard.press会处理 delay(50); // 简单消抖和模拟按下时间 Keyboard.release(key); // 等待按键释放（简单实现） while(digitalRead(colPins[c]) == LOW) { delay(1); } } } // 恢复当前行为高电平 digitalWrite(rowPins[r], HIGH); } delay(10); // 扫描间隔 }

这段代码展示了基本的矩阵键盘扫描逻辑，并将其映射到USB键盘按键。需要注意的是，实际的产品代码必须加入按键消抖（软件延时或硬件RC滤波）和非阻塞扫描（避免while死等），否则会影响其他任务执行和USB通信。

4. 核心挑战：USB枚举与HID报告描述符调试

在开发过程中，最棘手的部分往往不是逻辑代码，而是让电脑稳定、正确地识别你的设备。这就是USB枚举和描述符配置。

4.1 枚举失败常见原因

当你把烧写好程序的板子插上电脑，可能遇到以下几种情况：

• 设备管理器出现未知设备或感叹号：这通常意味着驱动问题。对于标准的HID键盘，Windows/macOS/Linux通常都有内置驱动，不需要额外安装。如果出现感叹号，大概率是你的设备报告描述符不符合规范，系统无法正确识别。需要使用usb抓包软件（如Wireshark配合USBPcap，或Bus Hound）来抓取枚举过程的数据包，对比标准的HID键盘描述符进行分析。
• 设备被识别为其他HID设备：比如被识别为鼠标或者游戏手柄。这说明你的报告描述符中“用途页(Usage Page)”和“用途(Usage)”设置错误。键盘的用途页应该是0x01(Generic Desktop)，用途是0x06(Keyboard)。
• 设备反复连接断开：这可能是电源问题（USB供电不足），也可能是程序逻辑有误导致USB堆栈崩溃、芯片复位。检查你的代码中是否有阻塞USB中断服务程序(ISR)的长时间操作。确保loop()函数或任何扫描函数不会长时间阻塞而不执行yield()或处理USB事件。

4.2 使用Wireshark进行USB抓包分析

当枚举出现问题时，抓包是终极调试手段。以Windows为例：

1. 安装Wireshark和USBPcap驱动。
2. 以管理员身份运行Wireshark。
3. 在捕获接口中选择“USBPcap1”等与你的USB根集线器相关的接口。
4. 插入你的CH32设备，开始抓包。
5. 过滤你的设备地址（如usb.device_address == 1.2.3）。

在抓取的数据中，重点关注“控制传输(Control Transfer)”中的“设置描述符(Get Descriptor)”请求。你会看到主机请求设备描述符、配置描述符、接口描述符和HID报告描述符。将你的设备回复的报告描述符与一个已知可用的描述符（比如Arduino Leonardo的）进行逐字节对比，差异点往往就是问题所在。

4.3 CH32x033的USB时钟配置陷阱

这是一个针对CH32x033的特定坑点。CH32x033的USB模块需要精确的48MHz时钟。这个时钟可以由内部HSI（高速内部RC振荡器）经过PLL倍频得到，也可以由外部晶振提供。内部HSI的精度对于全速USB（12Mbps）来说，有时可能处于临界状态，可能导致枚举不稳定或通信偶尔出错。

解决方案：

1. 使用外部晶振：如果板子上有8MHz或12MHz外部晶振，在Arduino板型配置或启动代码中，确保系统时钟和USB时钟源配置正确指向外部晶振和PLL。
2. 调整内部时钟校准：如果只能用内部HSI，可以尝试在代码初始化阶段，微调HSI的校准值（如果芯片支持）。查阅CH32x033的参考手册，看是否有相关的校准寄存器。
3. 修改PLL参数：检查核心包中关于该型号的system_ch32v00x.c或类似时钟配置文件，确保PLL配置计算出的USB时钟是准确的48MHz。

时钟问题导致的故障非常隐蔽，可能表现为10次插拔中有1-2次识别失败，或者长时间工作后按键偶尔失灵。通过逻辑分析仪测量USB数据线的D+/D-信号波形，可以观察时钟是否同步。

5. 功能进阶：复合设备与自定义HID

实现基本键盘后，你可能不满足于此。CH32x033的USB外设功能可以支持更复杂的设备类型。

5.1 实现键盘+鼠标的复合设备

你可以让同一个CH32设备同时枚举为一个键盘和一个鼠标。这需要在USB配置描述符中定义两个接口(Interface)，一个属于HID键盘类，另一个属于HID鼠标类。报告描述符也需要合并或分别定义。

在Arduino环境下，如果底层USBDevice库支持，你可以同时调用Keyboard和Mouse库。但更常见的情况是，你需要修改底层的USB描述符配置，启用复合设备支持，并确保两个HID接口的报告描述符都能正确上报。这需要对USB协议和核心包的USB栈有较深的理解，可能需要直接修改核心包中的USB库源代码。

5.2 实现自定义HID设备

除了标准的键盘鼠标，HID协议还支持“供应商自定义(Vendor Defined)”类型。你可以定义自己的报告格式，用于在设备和电脑之间传输任意数据。例如，做一个自定义的游戏手柄、传感器数据采集器或者控制面板。

实现步骤：

1. 修改报告描述符：在描述符中定义你自己的输入/输出/特征报告，指定其大小和用途页。
2. 编写上位机软件：电脑端需要编写程序（可以用Python的hidapi，C#的HidLibrary等）来读取和写入这些自定义报告。这就是usb控制的范畴了，你可以通过USB直接控制板载的LED、读取ADC值等。
3. 下位机代码：在CH32端，你需要使用底层HID API（如USBHID.sendReport()）来发送自定义结构的数据，并解析从主机接收到的数据。

这种方式功能强大，但兼容性不如标准键盘鼠标，需要自行开发电脑端驱动或软件。

6. 功耗优化与稳定性实战

对于一个可能长期插在电脑上的小工具，功耗和稳定性值得关注。

6.1 降低功耗

CH32x033本身功耗不高，但在USB总线供电下，仍可优化：

• 睡眠模式：当没有按键操作时，可以让MCU进入睡眠模式（Sleep或Stop模式），由外部中断（如矩阵键盘的行列变化中断）唤醒。在Arduino框架下，可能需要直接调用HAL库函数进入低功耗模式，并配置好唤醒源。
• 关闭无用外设：在初始化时，只开启用到的GPIO、定时器和USB模块，其他外设时钟默认关闭。
• 降低主频：如果不需高性能，可以在初始化时降低系统主频。但要注意，USB模块所需的48MHz时钟必须保证，这通常由独立的PLL提供，与系统主频可以不同。

6.2 提升USB通信稳定性

• 端点缓冲区管理：USB通信使用端点缓冲区。确保你的键盘报告发送频率不要过高，避免缓冲区溢出。在Keyboard.press()后，适当延时或检查发送状态。
• 错误处理与重枚举：在代码中加入对USB连接状态的检测。如果检测到USB断开（例如，通过检查USBDevice.isConnected()状态），则进行软复位或重新初始化USB堆栈，尝试重新枚举。
• ESD防护：如果设备需要经常插拔，考虑在USB数据线上添加ESD保护二极管，防止静电损坏芯片的USB引脚。

7. 从开发板到产品：烧录与量产考虑

最后，当你的键盘固件开发完成后，需要考虑如何部署。

7.1 脱离Arduino IDE的烧录方式

在项目前期，我们通过Arduino IDE和板载的USB转串口工具进行上传，这依赖于芯片的引导程序。对于最终产品，你可能需要更可靠、更快速的烧录方式：

• SWD/JTAG调试器：使用DAP-Link、J-Link等调试器通过SWD接口直接烧录芯片内部的Flash。这是最专业的方式，可以擦写整个芯片，包括引导程序区域。
• 官方ISP工具：沁恒可能提供通过串口或USB的ISP（在系统编程）工具。你需要将芯片置于特定的引导模式，然后使用上位机软件进行烧录。
• 自制烧录器：像arduino uno自制kazzo烧录器这样的项目，是针对特定老旧芯片的，对于CH32不适用。但你可以用另一块Arduino或STM32，模拟SWD协议来对CH32进行编程，不过这需要深入了解SWD协议。

7.2 固件保护与版本管理

对于商业产品，你可能需要：

• 读保护：通过设置芯片的选项字节(Option Bytes)，启用Flash读保护，防止固件被轻易读出拷贝。
• 写保护：保护特定的Flash扇区，比如引导程序区。
• 固件升级：预留USB DFU或串口IAP（在应用编程）功能，以便产品出厂后可以通过USB或串口进行固件升级。这需要在最初的引导程序中就实现DFU/IAP逻辑，或者在应用程序中预留升级接口。

整个“Ch32x033 Arduino 环境USB 键盘开发”的过程，就是从环境搭建、功能实现、深度调试到产品化思考的完整链条。它不仅仅是一个简单的“点灯”项目，而是涉及了USB协议、HID设备类、时钟系统、低功耗设计等多个嵌入式开发的核心知识点。用Arduino环境来操作，就像获得了一把好用的扳手，但真正要把螺丝拧紧，还是需要你对机器本身的构造有足够的了解。希望这篇详细的梳理，能帮你绕过我踩过的那些坑，更顺畅地实现自己的USB HID设备创意。