基于树莓派Pico的自定义USB键盘制作：从电路设计到CircuitPython编程

1. 项目概述与核心思路

前阵子在网上冲浪，看到一个挺有意思的梗图：一个键盘上只有几个特定的字母，刚好能拼出一句“国粹”。当时就觉得，这玩意儿要是真能做出来，不仅是个有趣的桌面摆件，还能在特定场景下（比如快速输入常用短语）派上用场。于是，一个基于Raspberry Pi Pico的自定义键盘项目就这么诞生了。

这个项目的核心，就是利用一块廉价的微控制器，模拟成一个标准的USB人机接口设备（HID），也就是电脑能直接识别的键盘。它不依赖于复杂的键盘主控芯片，而是通过编程，让Pico的每一个GPIO引脚都对应一个独立的按键。当你按下连接在某个GPIO上的机械轴时，Pico就会通过USB协议，向电脑发送一个对应的键值码，从而实现输入。这种方法的自由度极高，你可以定义任意布局、任意功能的键盘，从简单的数字小键盘到复杂的宏键盘，甚至是这种“专精于某一句话”的趣味键盘。

整个制作过程融合了硬件和软件：硬件部分包括3D建模打印外壳、焊接轴体电路；软件部分则集中在为Pico刷写固件并编写按键映射逻辑。我选择使用CircuitPython作为开发环境，因为它对USB HID设备的支持非常友好，库函数封装得很好，几行代码就能实现键盘功能，大大降低了嵌入式开发的门槛。无论你是想复刻这个“国粹键盘”，还是想制作属于自己的个性化输入设备，这篇教程都能给你提供一个清晰、可复现的路径。

2. 核心硬件选型与物料清单解析

制作一个可用的自定义键盘，硬件是基石。选对部件，不仅能保证功能正常，还能提升最终成品的质感和使用体验。下面我结合自己的踩坑经验，详细拆解每一个关键部件的选择逻辑和注意事项。

2.1 主控核心：为什么是Raspberry Pi Pico？

在众多微控制器中，我选择了树莓派基金会出品的Raspberry Pi Pico。原因主要有三点：性价比、生态和USB功能。

首先，Pico的价格极具竞争力，通常只需二三十元。它搭载了RP2040双核ARM Cortex-M0+处理器，性能对于键盘扫描这种任务绰绰有余。最关键的是，RP2040芯片原生支持USB 1.1（全速12Mbps），并且其硬件结构使得实现USB设备功能相对容易。相比之下，一些更古老的AVR芯片虽然也能做USB键盘，但往往需要额外的USB转串口芯片或更复杂的固件开发。

其次，Pico的生态非常繁荣。除了官方的MicroPython和C/C++ SDK，CircuitPython对它的支持尤为完善。CircuitPython由Adafruit主导开发，其设计哲学就是“极简”和“易用”，特别适合快速原型开发。对于键盘项目，Adafruit_HID库已经封装好了所有发送键盘按键、鼠标移动的底层协议，我们只需要调用简单的函数，比如keyboard.press(Keycode.A)，就能实现按键发送，完全不用去啃复杂的USB协议手册。

最后，Pico的引脚布局规整，GPIO数量充足（本项目用了10个GPIO，Pico有26个可用），并且有专门的3.3V输出和接地引脚，方便为按键矩阵供电。它的BOOTSEL按钮和可移动存储模式（当插入USB时显示为一个U盘），使得刷写固件像拷贝文件一样简单，这对新手极其友好。

注意：市面上有一些Pico的兼容板，价格可能更便宜。在选购时，务必确认其使用的主控是RP2040，并且USB接口和数据引脚是完好可用的。有些劣质兼容板的USB稳定性可能较差。

2.2 输入灵魂：机械轴与键帽的搭配学问

键盘的手感很大程度上由机械轴决定。我选择了最经典的Cherry MX轴体，并且是板载式版本。这里有两个关键点容易混淆：轴体类型和安装方式。

轴体类型：Cherry MX轴主要有青轴（Click）、红轴（Linear）、茶轴（Tactile）等，区别在于段落感和压力克数。对于这个趣味小键盘，手感选择全凭个人喜好。我用了红轴，因为直上直下比较安静。

安装方式：这是新手最容易踩坑的地方。机械轴分为PCB安装式和钢板安装式。

• PCB安装式：轴体底部除了两个金属引脚，还有两个额外的塑料定位柱。这三个“脚”需要插入PCB板上对应的三个孔中固定。
• 钢板安装式：轴体底部只有两个金属引脚。它需要依靠一块金属或塑料定位板来固定，轴体是卡在定位板上的孔里的。

本项目必须使用钢板安装式轴体！因为我们的“电路板”实际上是用飞线直接连接Pico的GPIO，并没有一块真正的PCB来提供那三个固定孔。如果你错买了PCB安装式轴体，那两个多余的塑料柱会无法安装，要么剪掉（破坏轴体），要么就无法牢固固定。

键帽的“高度”与“一致性”：键帽不是随便买一套就能用的。大多数键帽是“阶梯高度”，即不同行的键帽高度和倾斜角度不同，以符合人体工学。例如，数字键“F5”那一行的键帽和字母键“T”那一行的形状就不同。

对于我们的自定义键盘，按键位置完全打乱了原有的行序。如果你使用阶梯高度的键帽，装上去后会高低错落，非常别扭且难按。因此，必须选择统一高度的键帽。目前主流的统一高度键帽有两种：

1. XDA高度：球帽造型，所有键帽高度一致，顶部是平的或微球面。
2. DSA高度：比XDA稍矮，也是球帽，所有键帽高度和造型完全一致。

我选择了一套XDA高度的键帽，视觉上整齐划一，手感也不错。另外，由于这个键盘需要两个“U”键，而标准键帽套装通常每个字母只有一个，我特意选了一套附赠数字小键盘键帽的套装，用里面的“*”号键来代替第二个“U”，因为它的颜色和主键区一致。

卫星轴：对于长度超过1个标准键位（1u）的按键，比如空格键和回车键，为了防止按压时跷跷板，需要安装卫星轴来平衡。我选用的是适合钢板安装的卫星轴。安装时要注意润滑，否则可能会有杂音。卫星轴的组装稍复杂，通常包含一根金属钢丝、两个塑料底座和两个滑动假轴。建议先在地面上组装好（钢丝卡入底座和假轴），再整体卡入定位板上为它预留的长条形孔位中。

2.3 结构基础：外壳设计与3D打印实践

外壳承担着固定所有元件的重任。我使用Autodesk Fusion 360进行设计，将上盖（定位板）和下盖设计为一体式。设计核心是上盖的开口。

开口尺寸的精确计算：每个Cherry MX轴体需要穿过一个方孔。这个方孔的标准尺寸是14mm x 14mm。轴体之间的中心距标准是19.05mm（即0.75英寸）。这两个尺寸必须精确，否则轴体要么塞不进去，要么装上去歪歪扭扭。在Fusion 360中，我使用矩形草图工具，配合尺寸约束和矩形阵列，快速且准确地绘制出了所有轴孔。

卫星轴开口：对于空格键（本例中我们用的是2u长度的键位，即两个标准键宽），需要在轴体方孔的两侧，再开两个小方孔来固定卫星轴的底座。这个尺寸需要根据你购买的卫星轴型号来确定，通常需要查阅卫星轴的产品说明书或社区维基。

打印工艺选择：为了获得光滑、无层纹的表面质感，我使用光固化树脂3D打印机来打印上盖。树脂打印的精度极高，能完美呈现14mm的方孔，并且表面如玻璃般平滑，无需后期打磨。下盖对表面要求不高，为了节省成本，我使用了普通的FDM熔融沉积打印机（即常见的挤塑料丝的打印机）来打印。当然，上下盖全部用同一种工艺打印也完全没问题。

材料建议：对于FDM打印，推荐使用PETG或ABS材料，它们比PLA强度更高，更耐温，不易因长时间使用或环境温度变化而变形。对于树脂打印，选择标准的刚性树脂即可。

3. 电路设计与焊接实操详解

硬件准备就绪后，下一步就是让电路“活”起来。自定义键盘的电路原理其实非常简单，就是一个“一对多”的并联扫描电路，但焊接和走线的细节决定了成品的可靠性与美观度。

3.1 电路原理：共地扫描与GPIO检测

我们采用的不是复杂的矩阵扫描（常用于全尺寸键盘以节省GPIO），而是更直接的“一轴一线”连接方式。每个按键开关都独立连接到一个GPIO引脚上。其工作原理如下：

1. 共接高电平：每个Cherry MX轴体有两个金属引脚（引脚A和引脚B）。我们将所有轴体的引脚A（通常标记为“C”或公共端）用一根导线并联起来，然后统一连接到Pico的3.3V输出引脚上。这意味着，在未按下时，引脚A始终处于3.3V高电平。
2. 独立检测：每个轴体的引脚B，分别用一根独立的导线，连接到Pico的一个GPIO引脚上（例如GP2, GP3, GP4...）。在程序中，我们将这些GPIO配置为输入模式，并启用内部下拉电阻。
3. 按键检测：当按键未被按下时，轴体内部断开，GPIO引脚通过内部下拉电阻被拉到低电平（0V），程序读到的值是False或0。当按键被按下时，轴体内部导通，3.3V的高电平从引脚A直接传到引脚B，GPIO引脚读到高电平（3.3V），程序读到的值是True或1。程序通过持续扫描这些GPIO的状态变化，就能判断哪个键被按下了。

这种方式的优点是电路直观，编程简单，几乎没有按键冲突（鬼键）问题。缺点是每个按键占用一个GPIO，不适合键位很多的情况。但对于我们这个10键键盘，Pico的GPIO完全够用。

3.2 焊接步骤与工艺要点

焊接是连接硬件灵魂的步骤，好的焊点不仅牢固，也更安全。

工具准备：你需要一把可调温电烙铁（建议温度设置在320°C-350°C）、焊锡丝（建议含松香芯的中细规格）、助焊剂、吸锡器或吸锡线、镊子，以及耐热胶带或热缩管。

步骤一：处理轴体引脚

1. 将Cherry MX轴体插入3D打印好的上盖定位板中，确保卡紧。
2. 观察轴体底部的两个金属引脚。用钳子或指甲，将每个引脚轻轻向外弯折约45度，使其变成“L”形。这样做的目的是为了在后续焊接时，导线能更容易地搭在引脚上并固定住。
3. （关键）取一段导线（建议使用AWG 22-24的硅胶线，柔软耐折），剥开约2-3mm的线头，预先上好锡（即用烙铁融化一点焊锡包裹住裸露的铜丝）。

步骤二：焊接“共地线”

1. 剪取一段足够长的导线作为“共地线”（即连接所有轴体引脚A的线）。
2. 将这根线的一端焊接在Pico的3V3(OUT)引脚上。
3. 将这根线依次穿过每个轴体弯曲的引脚A下方，用烙铁快速点焊，使导线与每个引脚A都牢固连接。操作时，先将上好锡的线头搭在弯折的引脚上，然后用烙铁头同时接触线和引脚，送入焊锡丝，焊锡熔化流动包裹住连接点后迅速移开烙铁。
4. 确保每个焊点都饱满、光滑呈圆锥形，没有虚焊（焊锡只堆在表面未与引脚融合）或冷焊（焊点粗糙无光泽）。

步骤三：焊接独立的GPIO线

1. 为每个轴体的引脚B准备一根独立导线，建议用不同颜色区分，方便后续排查。
2. 参考之前的引脚映射表，将每根导线的一端，焊接到对应的轴体引脚B上。
3. 将每根导线的另一端，焊接到Pico对应的GPIO引脚上。例如，连接“K”键的导线另一端焊接到GP3。
4. 焊接Pico引脚时要格外小心。Pico的焊盘较小，烙铁温度不宜过高，停留时间要短（1-2秒），避免过热损坏芯片或导致焊盘脱落。可以使用镊子固定导线。

步骤四：绝缘与整理

1. 所有焊接完成后，必须检查是否有焊锡搭桥（两个不该连接的焊点被焊锡连在了一起）。用放大镜仔细查看，如有搭桥，用吸锡线清理。
2. 使用电气绝缘胶带（如聚酰亚胺胶带，俗称金手指胶带）或热缩管，将所有暴露的焊点、Pico的金属引脚排针仔细包裹起来，防止在安装时因金属接触导致短路。
3. 用扎带或线缆固定座，将壳内杂乱的导线梳理整齐，这不仅美观，也能避免线材被挤压脱落。

实操心得：焊接时，在焊点上使用少量助焊剂，能让焊锡流动更顺畅，焊点更光亮牢固。焊接Pico这类精密器件时，一个第三只手持工具（或“焊锡助手”）能帮你稳稳地固定导线和板子，解放双手。

4. 固件编程与功能实现全流程

硬件电路搭建完毕，接下来就是注入“灵魂”——编程。我们将使用CircuitPython，让Pico变身成为一个即插即用的USB键盘。

4.1 搭建CircuitPython开发环境

CircuitPython的开发流程极其简单，本质上就是向一个U盘里拷贝文件。

1. 获取固件：访问CircuitPython官网，找到Raspberry Pi Pico的页面，下载最新的.uf2格式固件文件。
2. 进入BOOTSEL模式：断开Pico的USB连接。按住Pico板上的白色BOOTSEL按钮不放，同时将Pico通过Micro USB线连接到电脑。此时，电脑会识别到一个名为RPI-RP2的可移动磁盘。
3. 刷写固件：将下载好的.uf2文件（例如adafruit-circuitpython-raspberry_pi_pico-xx.x.x.uf2）直接拖拽或复制到RPI-RP2磁盘中。复制完成后，Pico会自动重启。
4. 验证安装：重启后，电脑会识别到一个新的可移动磁盘，名字通常变为CIRCUITPY。这说明CircuitPython固件已经刷写成功。打开这个磁盘，你会看到一些默认的文件，如boot_out.txt。

4.2 安装必要的库文件

CircuitPython通过库文件来扩展功能。我们需要Adafruit_HID库来实现键盘模拟。

1. 访问Adafruit的CircuitPython库包页面，下载最新的库包（通常是一个.zip文件）。
2. 解压这个库包，在里面找到adafruit_hid这个文件夹。
3. 打开CIRCUITPY磁盘，如果里面没有lib文件夹，就新建一个。
4. 将adafruit_hid整个文件夹复制到CIRCUITPY磁盘的lib文件夹内。

4.3 编写键盘逻辑代码

现在，在CIRCUITPY磁盘的根目录下，创建一个名为code.py的文件。CircuitPython会在每次启动时自动运行这个文件。将以下代码写入code.py：

import time import board import digitalio import usb_hid from adafruit_hid.keyboard import Keyboard from adafruit_hid.keycode import Keycode # 初始化USB键盘设备 keyboard = Keyboard(usb_hid.devices) # 定义按键引脚映射 # 格式： (GPIO引脚对象, 对应的键盘键值) keymap = [ (board.GP2, Keycode.BACKSPACE), (board.GP3, Keycode.K), (board.GP4, Keycode.C), (board.GP6, Keycode.U), (board.GP7, Keycode.F), (board.GP8, Keycode.Y), (board.GP10, Keycode.O), (board.GP11, Keycode.U), # 第二个U键 (board.GP12, Keycode.KEYPAD_PLUS), # 用数字小键盘的+号键代替回车 (board.GP13, Keycode.SPACEBAR), ] # 初始化所有按键引脚为输入模式，并启用内部下拉电阻 keys = [] for pin, keycode in keymap: key_pin = digitalio.DigitalInOut(pin) key_pin.direction = digitalio.Direction.INPUT key_pin.pull = digitalio.Pull.DOWN # 启用内部下拉电阻，默认读到低电平 keys.append((key_pin, keycode)) # 记录按键之前的状态，用于检测按下和释放事件 prev_states = [False] * len(keys) print("自定义键盘已启动！") # 主循环，持续扫描按键状态 while True: for i, (key_pin, keycode) in enumerate(keys): current_state = key_pin.value # 读取当前引脚电平，True为高电平（按下） # 检测按键按下事件（从低电平变为高电平） if current_state and not prev_states[i]: print(f"按键按下: {keycode}") keyboard.press(keycode) # 检测按键释放事件（从高电平变为低电平） elif not current_state and prev_states[i]: print(f"按键释放: {keycode}") keyboard.release(keycode) # 更新前一个状态 prev_states[i] = current_state # 加入一个短暂的延迟，防止扫描过于频繁消耗CPU time.sleep(0.01)

代码逻辑深度解析：

1. 导入库：board库用于访问Pico的特定GPIO；digitalio用于控制数字输入输出；usb_hid和adafruit_hid是核心，提供了模拟USB HID设备的能力。
2. 初始化键盘对象：Keyboard(usb_hid.devices)这行代码创建了一个键盘对象，它通过USB与电脑通信。
3. 建立键位映射表：keymap列表是核心配置。每个元素是一个元组，第一个是GPIO引脚（如board.GP2），第二个是对应的Keycode。Keycode包含了所有标准键盘键值，比如Keycode.A,Keycode.ENTER等。这里我将GP12映射为KEYPAD_PLUS，是因为我外壳的回车键位是2u，而标准回车键是2.25u，我用了一个2u的“+”键帽来代替。
4. 引脚初始化：遍历keymap，为每个GPIO引脚创建一个DigitalInOut对象。设置方向为输入(INPUT)，并启用内部下拉电阻(Pull.DOWN)。这意味着当按键未按下（电路断开）时，引脚被电阻拉至低电平（0）；按下时，3.3V高电平输入，引脚变为高电平（1）。
5. 状态扫描与事件检测：主循环不断读取每个引脚的状态(key_pin.value)。我们通过对比当前状态和上一次循环的状态(prev_states)，来精确判断是“按下”事件（从0变1）还是“释放”事件（从1变0）。只有在检测到事件时，才调用keyboard.press()或keyboard.release()函数，这符合标准键盘的行为，也避免了长按重复触发的问题。
6. 防抖与延迟：机械开关在闭合瞬间会产生物理抖动，可能导致微控制器误判为多次按下。代码中通过time.sleep(0.01)（10毫秒）的延迟，以及“检测状态变化”而非“检测当前状态”的逻辑，在一定程度上实现了软件防抖。对于要求更高的场景，可以增加更复杂的防抖算法。

保存code.py文件后，CircuitPython会自动重新加载并运行新代码。此时，将键盘插入电脑USB口，电脑应该会识别出一个新的键盘设备。打开一个文本编辑器，按下你焊接的按键，对应的字母就应该出现了。

5. 组装、测试与问题排查实录

当所有部件都准备妥当，代码也运行无误后，最后的组装阶段就是将散件变成一件完整作品的过程。这个阶段需要耐心和细心，同时这也是问题最容易暴露的时候。

5.1 系统化组装步骤

1. 功能预测试：在完全封闭外壳前，务必进行最后一次裸板测试。将焊接好所有线路的Pico和轴板通过USB连接电脑，打开一个记事本，用镊子或导线依次短接每个轴体的两个引脚（模拟按键），检查屏幕上输入是否正确。这一步能排除组装后因内部挤压导致短路或断路的问题。
2. 安装键帽：确认所有按键功能正常后，将键帽对准轴体的十字柱，垂直用力按下，直到听到“咔哒”一声，表示键帽已卡紧。对于空格等大键，需要先将卫星轴的假轴部分卡入键帽背面的卡扣，然后再整体按下。
3. 内部绝缘与固定：这是保证长期使用稳定性的关键。用电气绝缘胶带（如聚酰亚胺胶带）将Pico上所有裸露的焊点和金属排针仔细包裹起来，特别是USB口附近的5V和GND引脚。由于我没有为Pico设计专门的固定柱，我用一小块双面泡沫胶将它粘在了底壳内部一个平整的位置，防止其晃动导致焊点脱落或短路。
4. 理线与收尾：使用尼龙扎带或线卡将壳内杂乱的导线捆扎整齐，固定在壳体内侧，避免其干扰底部盖板的安装或接触到Pico的引脚。
5. 合盖与出线：将上盖（已安装轴体和键帽）与下盖对齐。特别注意：要将Pico的USB线从底壳预留的线槽中穿出。然后使用4颗M3x8mm的自攻螺丝或机械螺丝，从底壳四角的支柱孔位拧入上盖，将上下壳紧固。拧螺丝时应对角线逐步拧紧，避免单边受力导致外壳变形或产生缝隙。
6. 最终外观处理：我用丙烯颜料填充了3D打印外壳上的Logo凹槽，待干透后，一件个性化的桌面玩具就诞生了。

5.2 常见问题与故障排查指南

即使按照教程操作，你也可能会遇到一些问题。下面是我在制作和调试过程中遇到的一些典型情况及其解决方法。

一个高级调试技巧：在代码中添加详细的打印信息。例如，在检测按键事件的if语句里，不仅打印按下的键值，也打印对应的GPIO编号。这样当按键失灵时，你可以通过观察串口输出，快速判断是程序没检测到电平变化（硬件或焊接问题），还是键值映射错了（软件问题）。

组装完成后，如果发现某个键手感涩滞或回弹不畅，可能是键帽安装不正或卫星轴没有润滑到位。可以拔下键帽，检查卫星轴钢丝是否完全卡入卡扣，必要时可以涂抹少量特氟龙或硅基润滑脂。整个制作过程，从构思到成品，最大的成就感不仅在于它能够工作，更在于你完全掌控了从物理结构到逻辑功能的每一个细节。这种将想法通过代码和焊枪变为实物的过程，正是创客精神的精髓所在。