1. 项目概述与核心价值最近在整理工作室的旧物翻出来好几块吃灰的STM32F103C8T6核心板也就是大家常说的“蓝板”或者“最小系统板”。看着这些当年玩剩下的“古董”总觉得直接扔了有点可惜。正好手头缺一个用来调试设备、偶尔输个命令的备用小键盘一个念头就冒出来了能不能用这块小小的STM32自己动手做一个USB键盘呢这个想法听起来可能有点“杀鸡用牛刀”毕竟市面上USB键盘转换器或者宏键盘套件已经很成熟了。但自己做乐趣和收获是完全不同的。你不仅能得到一个完全按自己想法定制的硬件——比如把不常用的F区键改成多媒体控制或者做一个专为某个软件像CAD、视频剪辑优化的快捷键键盘更重要的是你能从头到尾搞清楚一个USB设备是如何被电脑识别并工作的。从芯片的GPIO扫描按键到USB HID协议的数据打包再到系统驱动的交互整个链路打通之后你对“设备即插即用”的理解会深刻得多。对于电子爱好者、嵌入式初学者或者想给项目增加一个人机交互界面的开发者来说基于STM32制作USB键盘都是一个绝佳的练手项目。它综合了GPIO输入、定时器中断、USB设备协议栈等核心知识点但难度又控制在入门到进阶的范围内。用STM32 CubeMX工具进行图形化配置可以省去大量底层寄存器操作的繁琐工作让我们更专注于应用逻辑。最终你将获得一个即插即用、无需额外驱动的USB键盘它可能外观简陋但内核扎实而且完全受你控制。2. 硬件选型与电路设计思路2.1 核心控制器为什么是STM32F103选择STM32F103C8T6作为核心几乎是这个项目的“标准答案”原因有几个方面。首先它是经典的Cortex-M3内核主频72MHz对于扫描几十个按键、处理USB通信绰绰有余。其次也是最重要的一点它内置了全速USB12 Mbps设备控制器。这意味着我们不需要像早期的51单片机那样外挂一片CH375或PDIUSBD12之类的USB协议芯片单芯片就能搞定所有事情大大简化了硬件设计和成本。这块芯片的社区资源极其丰富各种库、教程、问题解答一搜一大把几乎你遇到的每一个坑前人都踩过并填平了。像我们手头的“蓝板”通常已经引出了USB的D和D-信号线到特定的引脚PA11, PA12并且板载了3.3V稳压和基本的复位电路我们只需要专注于键盘矩阵电路和USB端口即可。注意并非所有STM32F103系列都支持USB。一定要确认你芯片的具体型号像F103C6小容量是不带USB的而F103C8中容量及以上才支持。购买核心板时务必看清描述。2.2 键盘矩阵设计平衡引脚与效率一个全尺寸104键键盘如果每个键独立占用一个GPIO那需要104个引脚显然不现实。通用的方法是采用矩阵扫描。原理很简单将按键排列成行和列通过单片机引脚输出扫描行信号同时读取列线的输入状态从而通过行列坐标确定被按下的键。对于一个自制的小键盘或宏键盘我们可能不需要那么多键。假设我们设计一个包含26个字母键、10个数字键、回车、空格等常用键的紧凑键盘大约需要40-50个键。一个经典的8x8矩阵可以支持64个键这完全够用甚至还有富余。电路设计要点上拉电阻每个列线都需要一个上拉电阻通常4.7kΩ或10kΩ接到3.3V。当没有按键按下时列线被拉高为逻辑‘1’当某行被拉低且该行某列的按键被按下时对应的列线就会被拉低至‘0’。STM32的GPIO可以配置为内部上拉但为了稳定性和抗干扰尤其是在矩阵规模稍大时建议外部上拉电阻还是加上。二极管隔离这是实现“全键无冲”NKRO或至少“6键无冲”的关键。在每个按键上串联一个开关二极管如1N4148方向从行线指向列线。它的作用是防止当多个键同时按下时电流通过不同的路径反向流通导致“鬼键”Ghosting现象即检测到实际并未按下的键。对于自制键盘如果对无冲要求不高通常USB标准HID键盘默认是6键无冲为了简化焊接可以暂时不加二极管但需要了解其原理。消抖处理按键是机械触点闭合和断开瞬间会产生抖动可能导致单片机误判为多次按下。消抖可以通过硬件RC滤波电路或软件实现。我们通常采用软件消抖在检测到按键状态变化后延时10-20ms再次检测如果状态稳定则确认为有效动作。引脚规划示例8x8矩阵行线输出使用GPIOA的PA0-PA7共8个引脚配置为推挽输出。列线输入使用GPIOB的PB0-PB7共8个引脚配置为上拉输入。这样我们使用了16个GPIO实现了对64个按键的监控。你可以根据自己键盘的实际键位布局来规划行和列不一定要用满8x8。2.3 USB接口电路简单但不可马虎USB接口电路相对简单但细节决定成败。USB Connector使用标准的Micro-USB或USB Type-C母座。对于自制Micro-USB更常见引脚少易于焊接。数据线USB的DPA12和D-PA11信号线需要直接连接到连接器。为了信号完整性建议在数据线靠近芯片端串联一个22Ω左右的电阻有的设计也会用0Ω电阻代替作为调试预留。电源USB的VBUS5V接入后绝对不能直接接到STM32的VDDSTM32的工作电压是3.3V。我们需要一个LDO稳压芯片如AMS1117-3.3将5V降压为稳定的3.3V为整个系统供电。你的核心板上如果已有这个稳压电路则只需将USB的VBUS和GND接到板子的5V和GND输入点即可。电容在3.3V和GND之间靠近芯片电源引脚处放置一个0.1uF和一个10uF的电容进行去耦这是保证单片机稳定运行的基本操作。3. 软件环境搭建与CubeMX工程配置3.1 工具链准备Keil、CubeMX与驱动工欲善其事必先利其器。我们需要三个核心软件STM32CubeMXST官方的图形化配置工具它可以根据你的选择自动生成芯片初始化代码HAL库是快速开发的神器。去ST官网下载安装即可。Keil MDK-ARM (uVision)经典的ARM开发IDE用于编写、编译和调试代码。需要安装对应STM32F1系列的Device Pack。ST-LINK/V2驱动用于连接ST-LINK仿真器或那种带ST-LINK的核心板和电脑进行程序下载和调试。同样在ST官网下载。安装过程按部就班即可注意安装路径不要有中文。安装完CubeMX后第一次打开它会在线下载芯片支持包找到F1系列安装STM32F1的DFPDevice Family Pack。3.2 CubeMX工程初始化从芯片到时钟树打开CubeMX点击New Project在芯片选择器里输入STM32F103C8在结果中选中STM32F103C8Tx点击Start Project。第一步配置系统核心SYS在Pinout Configuration标签页找到System Core-SYS。Debug选择Serial Wire。这会将PA13和PA14用作SWD接口用于调试和下载程序。如果你只用串口下载可以选No Debug但强烈建议保留SWD调试方便。Timebase Source保持默认的SysTick即可。这是HAL库的时基来源。第二步配置时钟RCC找到System Core-RCC。High Speed Clock (HSE)选择Crystal/Ceramic Resonator。我们的核心板外部通常有一个8MHz的晶振这是主时钟源。Low Speed Clock (LSE)保持Disable我们暂时用不到RTC。第三步配置时钟树Clock Configuration点击顶部的Clock Configuration标签页这是关键一步。我们需要将系统时钟配置到72MHz。在输入部分将HSE旁的分频/倍频框设置为8MHz表示我们接的是8M晶振。找到PLL Source Mux选择HSE。配置PLLMUL选择x9倍频。这样PLL输出 8MHz * 9 72MHz。将System Clock Mux的源选择为PLLCLK。检查HCLKAHB总线时钟是否自动变成了72MHz。APB1总线时钟最高36MHzAPB2总线时钟最高72MHz系统会自动分频保持绿色即可。USB Clock务必确保USB Clock的源是PLLCLK并且经过一个分频器后输入到USB模块的时钟是48MHz。这是USB全速设备控制器要求的精确时钟。在F103的时钟树里通常是从PLL输出72MHz经过1.5分频得到48MHz。CubeMX通常会帮你算好你只要确认USB Clock显示为48MHz即可。第四步配置USB外设回到Pinout Configuration标签页找到Connectivity-USB。Mode选择Device (FS)即全速设备模式。此时左侧的芯片图上PA11(USB_DM)和PA12(USB_DP)应该被自动分配了。第五步配置GPIO用于键盘矩阵假设我们使用之前规划的PA0-PA7为行输出PB0-PB7为列输入。点击芯片图的PA0引脚选择GPIO_Output。依次设置PA1到PA7为GPIO_Output。在左侧的System Core-GPIO中可以批量设置这8个引脚。将输出模式设为Output Push Pull推挽输出上/下拉设为No pull-up and no pull-down默认输出电平设为High高电平即不扫描时行线为高。点击芯片图的PB0引脚选择GPIO_Input。依次设置PB1到PB7为GPIO_Input。在GPIO配置里将这8个引脚的模式设为Input上/下拉设为Pull-up上拉输入。这样我们就利用了芯片内部的上拉电阻简化了电路。3.3 生成工程代码迈出第一步点击顶部菜单的Project Manager标签页。Project填写工程名、存储路径路径务必全英文选择MDK-ARM作为Toolchain/IDE。Code Generator这里有个重要设置。勾选Generate peripheral initialization as a pair of ‘.c/.h’ files per peripheral这样每个外设的代码会单独成文件结构更清晰。勾选Backup previously generated files when re-generating重新生成代码时会备份旧文件防止误覆盖你的修改。最后点击右上角的GENERATE CODE。CubeMX会生成一个完整的Keil工程。首次生成可能会提示安装软件包确认即可。生成完毕后点击Open Project系统会自动用Keil打开这个工程。4. USB HID设备描述符配置与报告描述符详解4.1 USB枚举与描述符基础当我们的“键盘”插入电脑时电脑主机会发起一个叫做“枚举”的过程。主机会问“你是谁你能干什么” 我们的设备就需要通过一系列标准化的数据结构来回答这些数据结构就是“描述符”。对于HID人机接口设备键盘核心描述符包括设备描述符 (Device Descriptor)描述整个设备的基本信息比如厂商IDVID、产品IDPID、版本号、设备类等。配置描述符 (Configuration Descriptor)描述设备的一种工作配置供电模式、接口数量等。接口描述符 (Interface Descriptor)一个配置下可以有多个接口。对于键盘我们通常只有一个HID接口。这里会指明接口类HID、子类Boot Interface启动接口兼容性更好、协议Keyboard。HID描述符 (HID Descriptor)指向“报告描述符”的位置并说明报告的长度。端点描述符 (Endpoint Descriptor)USB通信的数据管道。HID键盘至少需要一个中断输入端点IN Endpoint用于向主机发送按键数据。中断传输保证了数据的实时性。报告描述符 (Report Descriptor)这是HID设备的“灵魂”它用一套复杂的语言HID Usage Tables定义了你这个设备能发送什么样的数据包报告每个数据位代表什么含义比如哪个字节是修饰键哪个字节是普通键值。幸运的是CubeMX和HAL库帮我们自动生成了设备、配置、接口、端点和HID描述符。我们大部分工作是理解和修改报告描述符。4.2 在CubeMX中配置HID报告描述符CubeMX可以帮我们生成一个简单的键盘报告描述符。在USB配置界面找到Device Descriptor和Configuration Descriptor子菜单。在Device Descriptor里可以修改Vendor ID和Product ID。默认的VID/PID是ST的对于自制设备我们可以使用一个测试用的ID比如0x0483ST和0x5750或者去USB-IF申请一个个人项目非商用通常用测试ID即可。在Configuration Descriptor-Interface 0-HID里我们可以设置报告描述符。但CubeMX的图形化配置对报告描述符的支持有限通常它生成的是一个非常基础的键盘描述符。更常见的做法是我们使用一个现成的、功能完善的键盘报告描述符直接替换掉CubeMX生成的默认描述符。这个描述符定义在工程目录USB_DEVICE/App/usbd_hid.c文件中的一个常量数组里变量名通常是HID_KEYBOARD_ReportDesc。4.3 键盘报告描述符拆解与修改一个标准的USB键盘报告描述符定义了主机期望从设备收到的数据格式。对于键盘它通常发送一个8字节的报告字节0 (Byte 0)修饰键Modifier Keys。每一位代表一个键左Ctrl, 左Shift, 左Alt, 左GUIWin键, 右Ctrl, 右Shift, 右Alt, 右GUI。按下为1释放为0。字节1 (Byte 1)保留字节必须为0。字节2-7 (Byte 2-7)普通按键Key Codes。最多可以同时报告6个普通按键的键值这就是USB标准键盘6键无冲的由来。键值0表示无按键。报告描述符就是用代码定义了这个8字节的结构。我们不需要从零开始写可以找一个可靠的模板。例如一个典型的Boot Keyboard报告描述符如下这是一个简化示意实际是一串十六进制数const uint8_t HID_KEYBOARD_ReportDesc[63] { 0x05, 0x01, // USAGE_PAGE (Generic Desktop) 0x09, 0x06, // USAGE (Keyboard) 0xa1, 0x01, // COLLECTION (Application) 0x05, 0x07, // USAGE_PAGE (Key Codes) 0x19, 0xe0, // USAGE_MINIMUM (Keyboard LeftControl) 0x29, 0xe7, // USAGE_MAXIMUM (Keyboard Right GUI) 0x15, 0x00, // LOGICAL_MINIMUM (0) 0x25, 0x01, // LOGICAL_MAXIMUM (1) 0x75, 0x01, // REPORT_SIZE (1) // 每个用法占1bit 0x95, 0x08, // REPORT_COUNT (8) // 有8个这样的用法8个修饰键 0x81, 0x02, // INPUT (Data,Var,Abs) // 这8个bit作为输入 0x95, 0x01, // REPORT_COUNT (1) // 下面1个字段 0x75, 0x08, // REPORT_SIZE (8) // 字段大小为8bit1字节 0x81, 0x03, // INPUT (Cnst,Var,Abs) // 这1个字节是常量保留字节 0x95, 0x06, // REPORT_COUNT (6) // 下面6个字段 0x75, 0x08, // REPORT_SIZE (8) // 每个字段8bit 0x15, 0x00, // LOGICAL_MINIMUM (0) 0x25, 0x65, // LOGICAL_MAXIMUM (101) // 最大键值 0x05, 0x07, // USAGE_PAGE (Key Codes) 0x19, 0x00, // USAGE_MINIMUM (Reserved (no event indicated)) 0x29, 0x65, // USAGE_MAXIMUM (Keyboard Application) 0x81, 0x00, // INPUT (Data,Ary,Abs) // 这6个字节是数组代表6个按键 0xc0 // END_COLLECTION };如何修改对于自制键盘我们通常不需要修改这个描述符本身除非你想增加额外的功能比如多媒体键、系统状态LED控制等。我们只需要理解我们的程序最终需要按照这个格式组装一个8字节的数组报告并通过USB发送出去。关键操作在Keil工程中找到USB_DEVICE/App/usbd_hid.c用上面这个完整的描述符数组替换掉文件中原有的HID_KEYBOARD_ReportDesc数组。然后在同一个文件中找到报告的长度定义可能在文件开头或USBD_HID_Setup函数附近确保HID_KEYBOARD_REPORT_DESC_SIZE被定义为正确的长度比如上面的例子是63。5. 键盘扫描逻辑与键值映射实现5.1 矩阵扫描算法逐行扫描法有了硬件矩阵我们需要一个软件算法来定期检测哪个键被按下。最常用的是“逐行扫描法”。其原理是依次将每一行线拉低输出0然后读取所有列线的状态。如果某列线读到了低电平0说明当前被拉低的这一行和这一列交叉点的按键被按下了。我们用一个定时器比如TIM2来产生一个周期性中断例如1ms在这个中断服务函数里执行扫描任务。这样可以确保扫描频率稳定不受主循环其他任务的影响。扫描步骤伪代码初始化所有行线为高电平1。进入定时器中断。将当前扫描行current_row拉低0其他所有行拉高1。延时一小段时间几个微秒可用HAL_Delay或空循环等待信号稳定。读取所有列线的状态存入一个变量column_state。将column_state与上一次扫描时该行的状态last_state[current_row]进行比较。如果状态发生变化从高到低是按下从低到高是释放则进行软件消抖设置一个消抖计时器在接下来的几次扫描中如果状态稳定则确认为有效按键事件。根据current_row和column_state中为0的列位计算出按键的坐标行列。将坐标转换为对应的USB HID键值Key Code。更新last_state[current_row]为当前的column_state。current_row加1指向下一行。如果超过总行数则归零。退出中断。5.2 键值映射表从坐标到HID键值我们需要建立一个二维数组keymap[ROW_COUNT][COLUMN_COUNT]作为键值映射表。数组的每个元素存储对应位置按键的HID Usage ID。这个ID是USB HID规范定义好的例如0x04对应 a/A0x05对应 b/B...0x1D对应 z/Z0x27对应 0/)0x1E对应 1/!0x2C对应 空格 (Space)0x28对应 回车 (Enter)0x2A对应 退格 (Backspace)0xE0对应 左Ctrl (作为修饰键在报告的第0字节处理)示例映射表定义// 假设是4x4矩阵实际请根据你的布局修改 #define ROW_NUM 4 #define COL_NUM 4 const uint8_t keymap[ROW_NUM][COL_NUM] { {HID_KEY_A, HID_KEY_S, HID_KEY_D, HID_KEY_F}, {HID_KEY_Q, HID_KEY_W, HID_KEY_E, HID_KEY_R}, {HID_KEY_1, HID_KEY_2, HID_KEY_3, HID_KEY_ENTER}, {HID_KEY_LEFT_CTRL, HID_KEY_SPACE, HID_KEY_BACKSPACE, HID_KEY_ESC} };注意像HID_KEY_LEFT_CTRL这样的修饰键其值通常是0xE0。在发送报告时我们需要特殊处理将其放到报告的第0字节修饰键字节的对应位上而不是放到第2-7字节的普通键数组里。5.3 状态管理与报告发送我们需要维护几个关键的数据结构按键状态矩阵一个二维数组keystate[ROW_NUM][COL_NUM]记录每个按键当前是“按下”还是“释放”状态。当前报告一个8字节的数组keyboard_report[8]其结构必须严格按照报告描述符的定义来组织。消抖计数器为每个按键设置一个计数器用于软件消抖。主循环或中断中的处理流程扫描矩阵得到变化的按键坐标和动作按下/释放。如果是按下动作且该按键的消抖计数器为0则将其状态置为“按下”并触发“按键按下处理”。如果是释放动作且该按键状态为“按下”则将其状态置为“释放”并触发“按键释放处理”。“按键按下处理”判断键值如果是修饰键如Ctrl, Shift则将keyboard_report[0]的对应位置1。如果是普通键则遍历keyboard_report[2]到keyboard_report[7]这6个字节找到一个值为0空闲的位置将HID键值填入。“按键释放处理”如果是修饰键则将keyboard_report[0]的对应位置0。如果是普通键则遍历keyboard_report[2]到keyboard_report[7]找到与释放键值相等的那个字节将其置为0。无论是否有按键状态变化只要keyboard_report的内容与上一次发送的报告不同就调用USB发送函数将新的报告发送给主机。USB HID库通常提供一个发送函数如USBD_HID_SendReport()。实操心得发送报告的频率不宜过高也不宜过低。通常可以在主循环中每隔几毫秒检查一次报告是否有变化有变化则发送。也可以在有按键事件发生时立即发送。但要注意USB中断传输有带宽限制过于频繁的发送可能造成数据堆积。实测下来在按键事件触发时发送并在没有按键时每隔10-20ms发送一次空报告所有键值为0以保持连接活性是一个比较稳定的策略。6. 主程序逻辑整合与调试技巧6.1 程序骨架搭建在main.c的主函数中我们需要完成初始化并启动各个模块然后进入主循环。int main(void) { HAL_Init(); // 初始化HAL库 SystemClock_Config(); // 配置系统时钟由CubeMX生成 MX_GPIO_Init(); // 初始化GPIO MX_TIM2_Init(); // 初始化用于键盘扫描的定时器 MX_USB_DEVICE_Init(); // 初始化USB设备 // 初始化自定义的键盘状态变量、映射表等 keyboard_init(); HAL_TIM_Base_Start_IT(htim2); // 启动定时器中断 while (1) { // 主循环处理非实时性任务 // 例如检查是否有报告需要发送处理LED指示等 keyboard_task(); // 键盘主任务函数 } }在keyboard_task()函数里我们可以实现前面提到的“检查报告变化并发送”的逻辑。6.2 调试方法与问题排查自制USB设备调试是重中之重。以下是一些实用的调试技巧1. 硬件连接检查供电用万用表测量STM32的VDD引脚是否为稳定的3.3V。USB口供电不稳可能导致枚举失败。数据线确认D和D-线没有接反、短路或虚焊。可以用万用表通断档检查。上拉电阻USB全速设备要求在D线上有一个1.5kΩ的上拉电阻接到3.3V这个电阻通常集成在STM32的USB模块内部并通过软件控制连接。在CubeMX的USB配置中确保VBUS sensing和Soft disconnect等选项配置正确。对于F103通常不需要外部上拉。2. 软件调试手段串口打印这是最直接的调试方式。在代码关键位置如USB初始化成功、收到设置请求、发送报告等通过串口打印信息。你需要先初始化一个USART并重写printf函数到串口。LED指示用板载LED或自己接一个LED用不同的闪烁模式来表示程序运行到了哪个阶段如初始化完成、USB已连接、正在发送数据等。ST-LINK调试器使用Keil的在线调试功能可以设置断点、单步执行、查看变量值是查找逻辑错误的最强武器。3. 系统级工具验证设备管理器插入你的键盘后打开Windows设备管理器查看“人体学输入设备”或“键盘”类别下是否出现了一个新的HID键盘设备并且没有黄色的感叹号。如果有感叹号说明驱动或枚举过程有问题。USBlyzer / Bus Hound这些是专业的USB协议分析软件Bus Hound在个人使用上有限制。它们可以捕获USB总线上的所有数据包让你清晰地看到主机发送了哪些请求如获取描述符你的设备回复了什么。这对于排查枚举失败、描述符错误等问题是终极工具。通过对比捕获的数据和USB规范你能精准定位问题所在。6.3 常见问题与解决方案实录问题1电脑完全没反应设备管理器里看不到新设备。排查首先检查硬件连接特别是USB的VBUS、GND、D、D-四根线。然后检查程序是否正常运行通过LED或串口。最可能的原因是USB枚举失败。解决确保时钟配置正确USB时钟必须是48MHz。检查usbd_conf.c中的USBD_LL_Init函数是否被正确调用。使用USB分析工具查看主机是否发出了Get_Descriptor请求以及你的设备是否回复。问题2电脑识别到了设备但显示“未知设备”或驱动错误。排查描述符可能有问题。特别是报告描述符的长度或内容不符合规范。解决仔细核对usbd_hid.c中的报告描述符数组。可以找一个已知能工作的描述符比如STM32 Cube库自带的HID键盘例程里的描述符直接替换试试。确保USBD_HID_Setup函数中对描述符请求的回复是正确的。问题3按键按下后电脑上字符乱跳或者一个键触发多个字符。排查键值映射错误或者矩阵扫描算法有bug产生了“鬼键”。解决首先简化测试只接一个按键看是否正常。如果正常再接两个不在同一行同一列的按键看是否正常。如果同时按下两个特定键时出现第三个键就是“鬼键”现象必须给每个按键加装隔离二极管。另外检查keymap表确保每个位置映射的键值是正确的HID Usage ID。问题4按键反应迟钝或者偶尔失灵。排查消抖时间设置过长或者扫描周期太慢。解决调整定时器中断周期和消抖计数器的阈值。通常扫描周期1-5ms消抖时间10-20ms是比较合适的。也可以尝试优化扫描代码减少中断服务函数中的耗时操作。问题5如何实现组合键如CtrlC实现组合键的本质是同时报告多个键。当Ctrl按下时你将keyboard_report[0]的对应位置1。当C键按下时你将C的键值HID_KEY_C填入keyboard_report[2]到[7]的一个空闲位置。主机同时收到修饰键位图和普通键值就会将其解释为CtrlC。你不需要在设备端做任何特殊处理只需如实报告所有被按下的键的状态即可。从一块闲置的STM32核心板到最终成为一个被电脑识别的USB键盘这个过程就像在解一道综合性的工程谜题。你需要串联起硬件电路、时钟配置、协议栈、驱动逻辑等多个环节。当第一次在记事本里敲出自己设计的键盘打出的字符时那种成就感是购买成品无法比拟的。这个项目最大的价值不在于做出了一个多好用的键盘而在于你亲手打通了从物理按键到系统交互的完整链路理解了数据是如何一层层封装、传输并被解析的。这份理解会让你在后续面对更复杂的嵌入式系统或USB设备开发时心里更有底气。