从零打造专属机械键盘：基于CircuitPython的USB HID输入设备实践

1. 项目概述打造你的专属“一键”键盘如果你对市面上千篇一律的键盘感到厌倦或者一直想亲手制作一个独一无二的输入设备那么这个项目就是为你准备的。今天我们不谈那些复杂的全尺寸客制化键盘而是从一个精巧、有趣且极具学习价值的“极简”项目开始一个只能输入“VOTE”投票单词的专用机械键盘。别小看它这个麻雀虽小五脏俱全的项目将带你完整走一遍从电路板PCB设计理解、硬件焊接组装到使用CircuitPython进行嵌入式编程的全过程。无论你是电子爱好者、创客还是对硬件编程感兴趣的软件开发者这都是一次绝佳的动手实践。这个项目的核心价值在于“聚焦”。它剥离了复杂键盘的层层嵌套让你能清晰地看到机械键盘最本质的工作原理开关矩阵扫描。通过一个仅有6个按键的矩阵配合Adafruit Trinket M0这块小巧但功能强大的微控制器我们就能实现一个被电脑识别为标准USB键盘的设备。你将亲手焊接每一个二极管、安装每一个轴体、编写每一行控制代码最终收获的不仅是一个能用的工具更是对“输入设备如何与计算机对话”这一问题的深刻理解。整个项目成本可控所需工具常见周末花上半天时间你就能拥有一个充满个人印记的创意作品。2. 核心硬件解析与选型考量2.1 PCB项目的骨架与艺术画布在这个项目中PCB印刷电路板扮演着双重角色它既是所有电子元件的电气连接骨架也是键盘外观设计的视觉核心。原作者使用了KiCad进行设计并采用PCB铣床如Bantam Tools制作这为外观个性化留下了巨大空间。为什么选择自行设计/定制PCB而非使用万用板对于键盘矩阵电路使用万用板洞洞板飞线理论上可行但会面临几个严峻挑战一是布线混乱容易引入干扰和接触不良二是无法保证开关安装的整齐和稳固三是几乎无法实现美观、一体化的成品效果。一块定制PCB能精准定位每个轴体的安装孔和二极管焊盘确保所有开关对齐其上的覆铜走线代替了手工导线可靠性极高更重要的是PCB本身的颜色、质感如黑色阻焊、沉金工艺直接构成了键盘的“底板”外观是实现高颜值成品的关键。关于PCB制作方式的补充说明项目资料中提到文件适用于铣床制作。如果你想通过常规的PCB打样工厂如嘉立创、捷配等生产通常需要提供Gerber文件。虽然原文件可能需要根据工厂的工艺规范进行调整如最小线宽、线距、孔径但基本的单面板设计使其适配性很强。你只需在下单时将下载的Gerber文件包上传即可。对于颜色除了工厂提供的绿、蓝、黑、红、紫等标准阻焊颜色你还可以像指南中建议的使用高品质贴纸或喷漆来进一步个性化这比直接定制特殊颜色的PCB通常更经济、灵活。2.2 微控制器大脑Trinket M0项目的核心控制单元是Adafruit Trinket M0。选择它而非更常见的Arduino Pro Micro或Raspberry Pi Pico有几个非常实际的理由原生CircuitPython支持Trinket M0出厂即预装CircuitPython这意味着你可以像操作U盘一样直接拖拽编辑code.py文件来更新程序无需任何额外的编译、烧录软件开发体验极其友好特别适合Python开发者或初学者快速上手。内置USB HID库CircuitPython的adafruit_hid库已经深度集成使得将设备模拟为键盘、鼠标变得异常简单几行代码就能实现省去了在Arduino环境中手动配置USB描述符等复杂步骤。尺寸与引脚恰到好处Trinket M0体积小巧正好适配这个紧凑的键盘PCB。其有限的GPIO引脚5个恰好满足本项目3x2矩阵3列2行5个引脚的需求没有资源浪费设计非常精炼。实操注意确保你拿到的是“Trinket M0”而不是旧版的“Trinket”基于ATtiny85。旧版Trinket存储和性能有限难以流畅运行CircuitPython和HID库。2.3 机械轴与键帽触感的来源轴体选择PCB Mount vs Plate Mount指南明确要求使用PCB Mount五脚轴类型的Cherry MX兼容轴。这两个额外的塑料定位脚能插入PCB上对应的定位孔其核心作用是防止轴体在焊接时或受到侧向力时发生旋转或歪斜。对于这种无定位板Plate的裸露PCB设计定位脚是保证所有键帽高度一致、对齐整齐的关键。如果使用Plate Mount三脚轴焊接时稍有不对称或者用力按压键帽边缘轴体就可能轻微扭转导致手感不一致和视觉上的不齐后期调整非常麻烦。键帽的“单位”与寻配难题键帽尺寸以“单位u”衡量1u就是一个标准字母键的宽度。本项目的难点在于非标准长度的键帽一个3u的空格键。常规键盘空格键多为6.25u或7u3u极为罕见。原作者使用了特定键帽套装的增补包。对于国内玩家解决方案有搜索“3u空格键”在一些客制化键帽商城或二手交易平台如淘宝、闲鱼上有时能单独买到。使用“平衡杆”或“卫星轴”兼容的3u键帽注意本项目未安装稳定器所以必须确认键帽底部是三个独立的十字柱可以直接插在三个轴体上而不是一个长条形结构。替代方案如果实在找不到可以用三个1u的键帽并排代替空格虽然外观上失去了长空格的美感但功能完全正常不失为一种务实的做法。注意购买键帽时务必确认其“十字菊花”开口与Cherry MX轴心兼容这是最通用的标准。3. 焊接组装全流程详解与避坑指南组装顺序至关重要合理的顺序能避免“焊好的零件挡住未焊位置”的尴尬。推荐顺序二极管 → 跳线 → 排针/主控 → 机械轴。3.1 二极管焊接方向是生命线二极管是键盘实现“无冲突”按键NKRO的基础元件。它只允许电流单向通过确保了在矩阵扫描中微控制器能唯一确定被按下的键位。操作步骤辨认方向所有二极管身上的色环条纹代表阴极负极。按照图示确保所有色环朝向PCB的同一边缘如上边缘。这是本步骤唯一且最重要的检查点一旦焊反该按键将无法被识别。安装与固定将二极管引脚穿过PCB孔位在正面元件面将引脚向外侧轻轻掰弯使其能临时固定住然后再翻转PCB进行焊接。这个小技巧能让你在焊接时无需额外工具固定。焊接与修剪在背面焊接面进行焊接形成饱满的圆锥形焊点。之后用水口钳或尖头剪钳紧贴焊点剪掉多余引脚。剪下的引脚请保留一小段下一步跳线要用。避坑心得焊接温度建议烙铁温度设置在320°C-350°C之间。温度过低会导致焊点冷焊虚焊看起来粗糙不亮温度过高可能烫坏PCB焊盘或二极管。先剪脚还是先焊接一定要先焊接再剪脚。如果先剪短散热会变快可能导致焊接困难形成不良焊点。3.2 安装跳线单面PCB的桥梁由于本项目使用的是单面PCB正面元件面的铜箔走线无法在某个点交叉因此需要用一根导线跳线在物理上连接两个本不直接相连的电路节点。操作步骤取上一部剪下的一截二极管引脚或其他细导线弯成一个小“U”形。将其插入PCB正面标注跳线位置的两个孔中。在正面将引脚掰弯固定然后在PCB背面将这两个引脚与它们各自对应的焊盘焊接起来。最后剪掉背面多余的引脚。关键检查用万用表的“通断档”测量一下跳线连接的两个焊盘确认已经导通。这个小步骤能避免后续调试时一个令人头疼的隐蔽故障。3.3 安装微控制器为大脑安家Trinket M0通过一排排针与PCB连接。这里采用“双排针”方式既能固定又能电气连接。操作步骤裁剪排针用剪钳将一条40Pin的直排针剪成两段5Pin的长度。裁剪时最好用钳子夹住需要的那一端剪掉多余部分这样切口更整齐。安装排针到PCB将两段排针的短针一端插入PCB正面指定的5个孔位中。从PCB背面铜箔面将排针的长针部分与焊盘焊接固定。这样排针就像两个小柱子一样立在PCB正面了。安装Trinket M0将Trinket M0的母座对准并插到这两排“柱子”上。注意方向确保Trinket M0的USB口朝向PCB边缘预留缺口的方向。最终焊接在PCB正面将Trinket M0的排母引脚与排针的短针部分焊接在一起。至此微控制器被牢牢固定并且上下两面都与PCB实现了电气连接。重要提示焊接排针和主控时建议先焊接一个对角线的引脚检查主控是否平整贴紧PCB调整无误后再焊接其余引脚。这样可以防止主控“翘起”。3.4 焊接机械轴最后的拼图在焊接所有其他元件之后最后安装机械轴。这是因为轴体体积较大先焊会严重阻碍背面其他元件的焊接空间。操作步骤将轴体的5个脚两个金属引脚三个塑料定位脚对准PCB上的所有孔位轻轻按压直至轴体底部与PCB贴合。翻转PCB在背面将两个金属引脚焊接到焊盘上。焊点应光滑饱满将整个焊盘覆盖。重复以上步骤焊接所有轴体。关于空格键轴体的特殊处理 指南中提到3u空格键由三个轴体共同支撑由于没有稳定器按压边缘会较硬。提供的解决方案是拆开两端的轴体移除其中的弹簧。这是一个非常巧妙的“土办法”。如何拆轴使用小号一字螺丝刀插入轴体上下盖的四个卡扣缝隙中轻轻撬开。务必小心内部有一个细小的金属弹片触发片可能弹出丢失。移除弹簧取下弹簧后这两个轴体就变成了仅提供物理支撑和触底感的“哑巴轴”只有中间的轴体负责触发。这确实能大大降低边缘按压的力度但也会让两端按键的按压感变得非常奇怪空洞、无段落。是否这样做取决于你对空格键手感一致性的要求。我个人建议首次制作时可以先不修改体验一下原设计后续再根据感受决定。4. CircuitPython软件配置与核心代码解读硬件组装完成后我们就需要赋予它灵魂——程序。4.1 环境搭建与库文件部署确保CircuitPython用USB线将Trinket M0连接电脑。如果电脑识别出一个名为CIRCUITPY的U盘并且盘内有boot_out.txt等文件说明CircuitPython已在运行。如果没有你需要去Adafruit官网下载对应Trinket M0的.uf2固件文件将其拖入出现的TRINKETBOOT盘符进行刷机。获取库文件访问CircuitPython官方库包页面下载与你的CircuitPython主版本号可在boot_out.txt里查看匹配的库包。解压后找到lib文件夹。部署库文件在CIRCUITPY盘符的根目录下新建一个名为lib的文件夹如果不存在。将库包中lib文件夹内的adafruit_hid文件夹和adafruit_dotstar.mpy文件复制到CIRCUITPY盘的lib文件夹内。adafruit_hid是实现键盘鼠标功能的核心adafruit_dotstar是用于控制板载RGB LED的本项目未使用但库包依赖它。4.2 核心代码深度解析将项目代码保存为code.py并放入CIRCUITPY根目录后设备会自动重启并运行。我们来深入理解一下这段代码import board from digitalio import DigitalInOut, Direction, Pull import usb_hid from adafruit_hid.keyboard import Keyboard from adafruit_hid.keycode import Keycode from adafruit_hid.keyboard_layout_us import KeyboardLayoutUS # 初始化USB HID键盘设备 kbd Keyboard(usb_hid.devices) kbdLayout KeyboardLayoutUS(kbd) # 状态记录与引脚映射 state [] # 记录当前被按下的按键ID pins {} # 存储初始化后的引脚对象 # 按键矩阵映射表定义了每个按键在矩阵中的行、列位置和唯一ID buttonMap [ dict(rowD4, colD0, id1), # 按键1: 行D4, 列D0 dict(rowD4, colD1, id2), # 按键2: 行D4, 列D1 dict(rowD4, colD2, id3), # 按键3: 行D4, 列D2 dict(rowD3, colD2, id4), # 按键4: 行D3, 列D2 dict(rowD3, colD0, id5), # 按键5: 行D3, 列D0 (空格) dict(rowD3, colD1, id6)] # 按键6: 行D3, 列D1 (回车) # 初始化行引脚D4, D3为输出模式 for pin in [D4, D3]: p DigitalInOut(getattr(board, pin)) p.direction Direction.OUTPUT pins[pin] p # 存入字典方便后续通过名称调用 # 初始化列引脚D0, D1, D2为输入模式并启用内部下拉电阻 for pin in [D0, D1, D2]: p DigitalInOut(getattr(board, pin)) p.direction Direction.INPUT p.pull Pull.DOWN # 关键启用下拉确保无按键时引脚为低电平 pins[pin] p # 按键ID到键盘键值的映射字典这是自定义功能的核心 buttonIDtoKeycode { 1: Keycode.V, 2: Keycode.O, 3: Keycode.T, 4: Keycode.E, 5: Keycode.SPACE, 6: Keycode.ENTER} # 主循环持续扫描矩阵 while True: oldState state # 保存上一循环的按键状态 newState [] # 准备存储本轮扫描到的新状态 newBtn None # 记录本轮新按下的按键ID # --- 矩阵扫描阶段 --- for button in buttonMap: r pins[button[row]] # 取出当前按键对应的行引脚对象 r.value True # 将该行设置为高电平激活当前行 if pins[button[col]].value: # 读取对应列引脚的电平 # 如果列为高电平说明该行该列的交叉点按键被按下 newState [button[id]] # 将该按键ID加入新状态列表 if not button[id] in oldState: # 如果上一状态中没有此ID newBtn button[id] # 标记为“新按下”的按键 r.value False # 将该行重新设置为低电平关闭当前行准备扫描下一行 # --- 按键动作执行阶段 --- # 释放所有在旧状态中但不在新状态中的按键即已松开的键 for oldID in oldState: if not oldID in newState: kbd.release(buttonIDtoKeycode[oldID]) # 如果检测到有新按键被按下则发送按下指令 if newBtn: kbd.press(buttonIDtoKeycode[newBtn]) state newState # 更新状态为下一轮循环做准备代码逻辑精要矩阵扫描程序通过快速轮流将每一行ROW置为高电平同时读取所有列COL的电平。当某个按键被按下其所在的行和列导通在对应的行被激活时其所在的列就能读到高电平从而精确定位按键。下拉电阻列引脚设置为Pull.DOWN内部下拉电阻至关重要。这确保了当没有按键按下时列引脚被稳定地拉低到低电平0避免因引脚悬空产生随机噪声信号导致的误触发。状态比较通过比较oldState和newState程序能判断出“从按下到松开”和“从松开到按下”这两种状态变化从而准确地发送press()和release()命令模拟真实键盘的行为。4.3 功能自定义与扩展修改buttonIDtoKeycode字典你就可以轻松改变每个按键的输出。Keycode类包含了几乎所有标准键盘键值例如Keycode.A,Keycode.LEFT_CONTROL,Keycode.F1等。进阶想法组合键CircuitPython HID库支持同时按下多个键。例如想实现CtrlC可以修改动作为kbd.press(Keycode.LEFT_CONTROL, Keycode.C)。多媒体键使用ConsumerControl类需额外导入adafruit_hid.consumer_control和adafruit_hid.consumer_control_code可以发送音量调节、播放暂停等系统级媒体键。层功能你可以增加一个切换层Layer的按键。通过一个全局变量记录当前层在buttonIDtoKeycode映射时根据当前层变量返回不同的键值就能实现一层输出字母另一层输出数字或宏命令的功能。5. 故障排查与常见问题实录即使按照指南操作第一次制作也难免遇到问题。以下是我在多次制作中总结的排查清单现象可能原因排查步骤与解决方案电脑完全无法识别设备1. USB线仅供电无数据2. Trinket M0未进入CircuitPython模式3. 焊接短路或虚焊导致主控故障。1. 换一条已知良好的数据线2. 双击Trinket M0上的复位按钮看是否出现CIRCUITPY盘符3. 检查USB口附近和主控引脚有无桥接短路重新焊接可疑焊点。电脑识别为“CIRCUITPY”但按键无反应1.code.py代码有语法错误未运行2. 库文件缺失或路径错误3. 矩阵扫描引脚定义与PCB实际布线不符。1. 打开CIRCUITPY盘符下的code.py检查是否有红色错误提示2. 确认lib文件夹内存在adafruit_hid和adafruit_dotstar.mpy3.重点用万用表通断档逐一检查每个按键按下时其对应的行、列引脚是否导通二极管正向导通。某个或某一行/列按键全部失灵1. 对应二极管焊反或损坏2. 对应行或列引脚的焊点虚焊/断路3. PCB走线在加工时有断线。1. 检查失灵按键对应的二极管方向2. 用万用表测量失灵按键的行、列引脚到Trinket M0对应引脚是否连通3. 检查PCB上对应走线是否有物理损伤。按键连发或幽灵按键1. 矩阵中某条列线未启用下拉电阻代码错误2. PCB或焊接点有轻微短路导致交叉干扰3. 主控引脚模式设置错误。1. 确认代码中所有列引脚都设置了p.pull Pull.DOWN2. 用放大镜仔细检查矩阵交叉点附近的焊盘有无锡渣桥接3. 确认board模块的引脚名如D0与Trinket M0的物理引脚对应正确。空格键手感不一致或卡涩1. 三个轴体安装不齐导致键帽受力不均2. 如移除了两端轴体弹簧轴芯无复位力可能卡住。1. 不装键帽单独按压每个轴体检查是否都顺畅回弹。重新焊接歪斜的轴体2. 如果移除了弹簧确保轴体的上下盖合拢紧密内部弹片未脱落。最有效的调试工具——万用表当按键失灵时别急着重写代码。首先用万用表的“通断档”进行物理排查。这是区分“硬件问题”和“软件问题”最快的方法。先确保每条电气连接都是通的每个按键按下时都能导通对应的行和列注意二极管方向正向导通反向截止。完成所有步骤后拧上尼龙支柱你的专属键盘就站起来了。它不仅仅是一个输入“VOTE”的工具更是一个凝结了你从电路理解、手工焊接到编程调试全过程的物理结晶。每一次按下都是对你动手能力的肯定。这个项目最大的魅力在于其清晰的扩展路径理解了3x2矩阵你就能设计6x8的矩阵学会了映射单个键值你就能编写复杂的宏和层功能。它就像一把钥匙为你打开了客制化输入设备这扇大门。