qmk_firmware/docs/zh-cn/hand_wire.md

手工搭建指南

模块清单

你需要的模块有：（x为你设计的键盘的键数）

• QMK所兼容的主控板（Teensy, Pro-Micro, QMK Proton C 等）
• x 个键轴 （MX, Matias, Gateron 等）
• x 个通孔二极管（译注：即普通的直插二极管）
• 定位板及卫星轴
• 电线
• 电烙铁
• 松香/焊油
• 通风的环境/风扇通风
• 剪线钳

可选地但比较有用的：

• 剥线钳/一把锋利的剪刀
• 镊子及小尖嘴钳
• 焊台/一位助手

前期工作

组装PCB矩阵的方法多种多样，这份指引会描述一些基础信息并给出一些推荐方案。

既然我们要进行手工飞线搭建，这里就假设你已经有了定位板。如果你想构建完全定制化的配列，有 ai03 Plate Generator 以及 Swillkb Plate & Case Builder 这样的工具可以助你设计出一个新的。

首先从安装键轴及卫星轴开始，考虑厚度及材质的影响，可能需要热熔胶来固定。

设计矩阵 :id=planning-the-matrix

如果你在参考已有的手工搭建指南（比如自制键盘固件目录下的键盘），可以跳过该步骤，确保是按照文中的矩阵方案连线即可。

如果你的方案是将每个开关的一个引脚与两边的开关相连（行方向），另一个引脚与上下的开关相连（列方向），并串联一个二极管到一端，最常用的方案是二极管背对着连接到行方向的引脚（列向行）。即让远离二极管黑线一端连接到开关上（电流只能从一个方向通过二极管）。

可以很容易地设计出正交连接的键盘（如Planck）。 （译注：这里的“正交”意思是行列方向连接规整）

作者：RoastPotatoe "如何手工搭建Planck键盘" （英文）内的图例

键盘配列越大，功能越丰富，则矩阵也会更复杂。Keyboard Firmware Builder 可以帮助你设计矩阵配列（下图为通过 Keyboard Layout Editor 导出的全尺寸ISO键盘）。

必须时刻留意矩阵的行列数总和不能超出控制器的IO引脚数，因此上图的方案可以使用 Proton C 或 Teensy++ 控制器，但常规 Teensy 或 Pro Micro 不行。

常见微控制器板 :id=common-microcontroller-boards

控制器板	控制器方案	# I/O引脚数	引脚图
Pro Micro*	ATmega32u4	20	链接
Teensy 2.0	ATmega32u4	25	链接
QMK Proton C	STM32F303xC	36	链接 1, 2
Teensy++ 2.0	AT90USB1286	46	链接

*Elite C 与 Pro Micro 除将 Micro USB 替换为 USB-C 外其余无差别。

一些主控板专门为手工接线设计，除可直接连接少量开关外还有额外的引脚，但这些通常会更贵一些，也更难掌控。

控制器板	控制器方案	# I/O引脚数
Swiss helper	ATmega32u4	20
Postage 主控板	ATmega32u4	25
Postage mini 主控板	ATmega32u4	25

矩阵布线

布线方案不是唯一的，要达成的效果是可以正确连接所有的焊点并不会出现预期外的短路。

公开的材料和技术方案：

（译注：链接文章及标题恕不翻译）

技术方案	示例	优点	缺点	图片
间断开口的线缆	Sasha Solomon's Dactyl 以及 Cribbit's modern hand wire	整洁	线缆开口的操作会有些困难
适宜长度的线缆	u/xicolinguada's ortho build	剥线容易	较难固定位置
漆包线	fknraiden's custom board	可以直接焊接（烧掉绝缘层）	外观差？
弯折二极管引脚作为行方向连线	Matt3o's Brownfox	焊点更少	绝缘性差
硬线（如铜管）	u/d_stilgar's invisible hardline 以及 u/jonasfasler's first attempt	非常漂亮	难度高，没有物理绝缘
用绝缘胶带（如高温胶带*）隔离开的裸线	Matt3o's 65% on his website	简单（不用剥线）	丑拒
铜箔胶带	ManuForm Dactyl	非常简单	只适用于定位板/外壳与开关底部平齐的情况

（*译注：原文是聚酰亚胺胶带，在中国通常叫高温胶带）

以上方案可以结合使用，在焊接前请准备好各种长度的线缆。

分体键盘的注意事项

如果你想制作的是分体键盘（如Dactyl），每一半边都需要一个控制器以及连通两方的通信用线（如TRRS或硬连接线）。更多资料参见QMK分体键盘文档。 （译注：TRRS即一种常用的4线耳机线插口，具体信息请查阅维基百科或这份知乎文章）

焊接

你可以找到很多焊接指导及技巧，这里列出了最相关及最关键的部分：

要想焊接的牢固需要确保焊料与焊接两端的金属面充分地接触，一个好办法（也不是必须）是上锡前先（将线缆）在针脚上绕一圈或先拧在一起。

如果二极管还在包装条上且需要弯折（作为绕圈的起点处或用于连接到邻接处），一个简便的办法是找一个盒子、桌子或尺子的直边上进行弯折。由于弯折统一在二极管一侧，也有助于区分二极管的方向。

如果你的电烙铁有温控功能，将其设置在 315ºC（600ºF）。

热起来后，给电烙铁上锡 - 即融化一部分锡料到烙铁头上然后立刻用湿海绵或烙铁头海绵擦掉，这样烙铁头上会有一层光滑明亮的焊料，以防止氧化且有助于焊料的焊接操作。

接下来进行焊接，先将烙铁头在焊接面上接触一会儿进行加热，然后上焊料焊接两侧。加热焊接面的目的是为了确保焊料可以粘附且不会过早冷却下来。

不能让焊料/焊点加热过度，热量会通过接触面烧毁原件（融毁开关外壳等）。并且，由于焊锡中有帮助“浸润”（即上锡）的助焊剂，加热的越久助焊剂蒸发掉的越多，最终导致焊接点虚焊，除了看起来糟糕外，还有导致电路短路的风险。

焊接二极管

从左上角的那个开关开始，将二极管放到开关上（用镊子，如果有的话）并纵向放直，有黑线的一端朝向你。让二极管间并联（二极管的阴极不应连接到其它二极管的阳极），二极管的阳极应连接到开关的左引脚上，而弯曲的阴极应朝向右边放置，如图：

在放稳二极管后，拿起焊锡，将其与左轴脚同时接触到电烙铁上 - 在松香的帮助下焊锡会很容易地覆盖在二极管及轴脚上。二极管可能会有些位移，此时你可以抓住二极管另外一端弯折过的引脚，小心地放回到位置上 - 但请留意另一端是会迅速变得烫手的。如果二极管容易乱跑，可以使用尖嘴钳之类的东西在焊接时辅助保持稳固。

松香加热时升起的烟有害，注意保护口鼻，不要熏到眼睛或皮肤。

焊接到位时，可以将焊点升起的烟吹走以免熏脸，也能帮助焊点快速降温。焊点在冷却后会形成沙哑状（无光泽）的表面，但请注意此时它依旧非常烫，需要几分钟时间的冷却才可以触摸，多吹吹有助于快速冷却。

在第一个二极管焊接完毕后，第二个二极管需要焊接轴脚以及上一个二极管弯折的那一端，看起来像这样：

在焊接完毕一整行后，用剪线钳剪掉二极管上方（绕轴脚后多出的部分），以及这一行最后侧多出来的引脚部分。在每一行焊接完毕后都要记得这一步。

在你完成了所有的二极管的焊接工作后，最好是逐一测试一下以确保焊接牢固稳定 - 再往后不是不能回头修正，但会越来越困难。

纵向上的焊接

这一步你有几个可选项需考虑 - 给横向电缆进行绝缘处理是个好主意（毕竟二极管没有绝缘层），但如果你足够小心，横向电缆裸露着也行 - 但仍旧不建议这么做。如果你用的是单芯线，先将外皮整个褪下来再酌情装回去可能是最好的办法，但会因尺寸及材质原因造成操作困难，你可以将线缆上需要焊接到开关轴的部分裸露出来。

如果你使用多股线/铜绞线，可能最简单的方案就是用不固定长度的小段电线来纵向连接开关。通过融化掉焊接点的外皮的方式来用一整根线不是不可以，但这里不推荐这样做，这种操作会产生更多的有害烟尘，也会毁掉你的电烙铁。

在进行焊接操作前，先预弯折好线缆（如果是单芯线），或至少心中已经规划好焊接路线顺序（特别是你要做的设计是错列的时）。实际上焊接顺序不是特别重要，因为我们是通过焊接方案来确定键映射定义的 - 只要确保一行上的所有按键都有独自的列，且从左到右依次排列。

如果你不做任何的绝缘处理，可以将纵向的线升高一些，焊接在轴脚尖端上 - 如果线缆本身足够稳固，不会短路到连接着二极管的横线线缆上。

连接控制器

在矩阵焊接完成后，可以将其焊接到微控制器板上了。

将微控制器放在预期的位置上，同时要考虑到安装及外壳对齐问题。须记得USB槽的位置是可以与微控制器分开的，只需使用一小段公对母线接驳下即可。

找到微控制器板的引脚定义/文档（链接）并将所有的I/O引脚标出来（留意像teensy这种的控制器，模拟I/O引脚可能是数字I/O引脚的两倍），将线缆连接到这些引脚上。

---

针对 Teensy 2.0 的特殊说明

Teensy 上的部分引脚有点特殊，像 D6（片上LED），及一些 UART、SPI、I2C或PWM通道，不过只是在你计划着在键盘上还有其它功能设计时才需避免使用。如果你还不是很确定以后会不会增加什么功能上去，引脚应该还是足够充足到可以剩一部分出来的。

那些无论在什么控制器上都不应去使用的引脚，有：GND、VCC、AREF以及RST - 其它所有引脚都是可以用且也能在固件中访问的到的。

---

将电线切割为控制器到各行/列上某一点距离的长度。可以焊到各行的任意位置上，只需要确保是在二极管之后 - 焊接到二极管前面（轴脚侧）的话该行将无法正常使用。

这里用排线的话会显得非常整洁，你也可以考虑如何排布线缆以连接到各行/列的近处。

在往控制器上焊接电线时，请记住各引脚连接的是哪一行/列，在后续制作固件时我们需要用到这些信息来定义矩阵。

在你往下继续以前，请确保控制器已装配到位 - 切掉线缆再重新焊接非常麻烦！

一些基础的固件配置

至此，在你构建好固件后，键盘就应该能正常工作了。

通过 Keyboard Firmware Builder 网站可以轻松地创建一个简单的固件。通过 Keyboard Layout Editor 可以自己制作配列数据，之后就可以导入进来并重新构建矩阵信息（如果你没有在先前的 设计矩阵 完成的话）。

继续完成剩下的步骤，在逐一配置完所有的按键后就可以编译下载固件了。其中 .hex 文件可以用来直接刷写到键盘上，而 .zip 包中的源代码可以用来添加高级功能并通过 构建第一个固件 中详述的方法进行本地构建。

Keyboard Firmware Builder提供的源代码是QMK的，但版本是2017年初的。如果要用现今版本的QMK来构建 .zip 中的源代码，需要在打开 .zip 后遵循以下几步：

1. 解压 kb 目录到 qmk_firmware/keyboards/handwired/。
2. 进入解压的 kb 目录，转到 keymaps/default/ 目录下，打开 keymap.c。
3. 找到并删除 action_get_macro 代码段：

    const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) {
        ...
        return MACRO_NONE;
    }
   

4. 保存并关闭 keymap.c。

刷写固件

安装 QMK Toolbox.

在 “Local File” 栏处定位到你新创建的 .hex 文件，在 “MicroController” 中选择你的控制器板（常见型号这里有）。

插上你的键盘后在QMK Toolbox中点击reset（重置）按钮（如果没有重置按钮，短接一下Reset和接地引脚）再点击“Flash”（刷写）按钮。

测试固件

可以用 QMK配置器的键盘测试器、Keyboard Tester 或 Keyboard Checker 进行测试，也可以打开一个文本编辑器并试着输入 - 你应该能成功输入键映射方案中的所有字符。对每个按键进行测试，并记录下不能正常工作的按键。对这些不能正常工作的按键，这里有一个快速排查指引：

1. 将键盘翻过来，用一段金属物短接一下轴脚 - 这么做可以排除掉需要更换掉的坏轴的可能性。
2. 检查轴脚上的焊点 - 应该是饱满且完整覆盖的。如果你稍加用力就能将其弄下来，那么就是焊接不到位。
3. 检查二极管的焊点 - 如果二极管虚焊了，部分行可以使用，但其它的可能就不行了。
4. 检查连接到各行的焊点 - 如果这里虚焊了，这些行就无法正常使用。
5. 检查 Teensy 两侧的进/出线的焊点 - 两侧的线缆都必须确保已被良好地焊接。
6. 检查 <project_name>.h 文件中是否有错误或不当的 KC_NO - 如果不确定在哪里，用已有的 kxy 变量替换一下。
7. 检查固件文件确实经过编译且正确刷写到Teensy上了。除非你在终端看到了错误消息，或是刷写时出现了弹框，否则一切应该是正常的。
8. 使用万用表实测一下，触发开关时是否成功闭合（按下时可以连通电路）。

如果你完成了上述所有检查，应当留意有时可能是多种因素共同造成了开关的异常，因此最后将其短路掉来排查问题并没有什么害处。

即将完成

在确认键盘可以正常使用后，如果你用的是独立的控制器模块（非手工构建用），须将其固定好。办法有很多，比如热熔胶、双面胶带、3D打印的盒子、电工胶带等。

如果你觉得成就感满满，可以试着增加一些额外的功能，比如 轴内LED，轴内RGB，RGB背光 甚至可以是 OLED显示屏！

固件的潜力非常大 - 阅览 docs.qmk.fm 可以看到全部功能的列表，也能深入了解人们是如何使用那些五花八门的键盘的。随时欢迎到 OLKB subreddit 或 QMK Discord 上寻求帮助！

其它指引链接

• matt3o 的分步指引 (BrownFox build) 以及他的 个人站点 和 指导视频
• Cribbit：“现代化的手工搭建指南 - 强大，简洁，友好”
• Sasha Solomon：“打造我的第一把键盘”
• RoastPotatoe： “如何手工搭建Planck键盘”
• Masterzen：“手工搭建键盘记录”

遗留内容

以前本页内还有其它内容，现在我们已经将他们单独分离出去了。以下的内容是一些重定向链接，以供那些从老链接地址过来的人能找到自己要找的内容。

序: 键盘矩阵是如何工作的（以及为什么需要二极管） :id=preamble-how-a-keyboard-matrix-works-and-why-we-need-diodes

• 键盘矩阵是如何工作的