# 手工搭建指南 <!--- original document: 0.15.17:docs/hand_wire.md git diff 0.15.17 HEAD -- docs/hand_wire.md | cat --> ## 模块清单 你需要的模块有:(*x*为你设计的键盘的键数) * QMK所兼容的主控板(Teensy, Pro-Micro, QMK Proton C 等) * *x* 个键轴 (MX, Matias, Gateron 等) * *x* 个通孔二极管(译注:即普通的直插二极管) * 定位板及卫星轴 * 电线 * 电烙铁 * 松香/焊油 * 通风的环境/风扇通风 * 剪线钳 可选地但比较有用的: * 剥线钳/一把锋利的剪刀 * 镊子及小尖嘴钳 * 焊台/一位助手 ## 前期工作 组装PCB矩阵的方法多种多样,这份指引会描述一些基础信息并给出一些推荐方案。 既然我们要进行手工飞线搭建,这里就假设你已经有了定位板。如果你想构建完全定制化的配列,有 [ai03 Plate Generator](https://kbplate.ai03.me/) 以及 [Swillkb Plate & Case Builder](http://builder.swillkb.com/) 这样的工具可以助你设计出一个新的。 首先从安装键轴及卫星轴开始,考虑厚度及材质的影响,可能需要热熔胶来固定。 ## 设计矩阵 :id=planning-the-matrix 如果你在参考已有的手工搭建指南(比如[自制键盘固件目录](https://github.com/qmk/qmk_firmware/tree/master/keyboards/handwired)下的键盘),可以跳过该步骤,确保是按照文中的矩阵方案连线即可。 如果你的方案是将每个开关的一个引脚与两边的开关相连(行方向),另一个引脚与上下的开关相连(列方向),并串联一个二极管到一端,最常用的方案是二极管背对着连接到行方向的引脚(列向行)。即让远离二极管黑线一端连接到开关上(电流只能从一个方向通过二极管)。 可以很容易地设计出正交连接的键盘(如Planck)。 (译注:这里的“正交”意思是行列方向连接规整) ![Planck矩阵示例图](https://i.imgur.com/FRShcLD.png) [作者:RoastPotatoe "如何手工搭建Planck键盘"](https://blog.roastpotatoes.co/guide/2015/11/04/how-to-handwire-a-planck/) (英文)内的图例 键盘配列越大,功能越丰富,则矩阵也会更复杂。[Keyboard Firmware Builder](https://kbfirmware.com/) 可以帮助你设计矩阵配列(下图为通过 [Keyboard Layout Editor](https://www.keyboard-layout-editor.com) 导出的全尺寸ISO键盘)。 ![ISO键盘矩阵示例图](https://i.imgur.com/UlJ4ZDP.png) 必须时刻留意矩阵的行列数总和不能超出控制器的IO引脚数,因此上图的方案可以使用 Proton C 或 Teensy++ 控制器,但常规 Teensy 或 Pro Micro 不行。 ### 常见微控制器板 :id=common-microcontroller-boards | 控制器板 | 控制器方案 | # I/O引脚数 | 引脚图 | | :------------ |:-------------:| ------:| ------ | | Pro Micro* | ATmega32u4 | 20 | [链接](https://learn.sparkfun.com/tutorials/pro-micro--fio-v3-hookup-guide/hardware-overview-pro-micro#Teensy++_2.0) | | Teensy 2.0 | ATmega32u4 | 25 | [链接](https://www.pjrc.com/teensy/pinout.html) | | [QMK Proton C](https://qmk.fm/proton-c/) | STM32F303xC | 36 | [链接 1](https://i.imgur.com/RhtrAlc.png), [2](https://deskthority.net/wiki/QMK_Proton_C) | | Teensy++ 2.0 | AT90USB1286 | 46 | [链接](https://www.pjrc.com/teensy/pinout.html#Teensy_2.0) | *Elite C 与 Pro Micro 除将 Micro USB 替换为 USB-C 外其余无差别。 一些主控板专门为手工接线设计,除可直接连接少量开关外还有额外的引脚,但这些通常会更贵一些,也更难掌控。 <img src="https://i.imgur.com/QiA3ta6.jpg" alt="实装的 Postage mini 主控板" width="500"/> | 控制器板 | 控制器方案 | # I/O引脚数 | | :------------ |:-------------:| ------:| | [Swiss helper](https://www.reddit.com/r/MechanicalKeyboards/comments/8jg5d6/hand_wiring_this_might_help/) | ATmega32u4 | 20 | | [Postage 主控板](https://github.com/LifeIsOnTheWire/Postage-Board/)| ATmega32u4| 25 | | [Postage mini 主控板](https://geekhack.org/index.php?topic=101460.0)| ATmega32u4| 25 | ## 矩阵布线 布线方案不是唯一的,要达成的效果是可以正确连接所有的焊点并不会出现预期外的短路。 公开的材料和技术方案: (译注:链接文章及标题恕不翻译) | 技术方案 | 示例 | 优点 | 缺点 | 图片 | :-----------| :------- | :------ | :--- | :--- | 间断开口的线缆 | [Sasha Solomon's Dactyl](https://medium.com/@sachee/building-my-first-keyboard-and-you-can-too-512c0f8a4c5f) 以及 [Cribbit's modern hand wire](https://geekhack.org/index.php?topic=87689.0) | 整洁 | 线缆开口的操作会有些困难 | ![开口的线缆](https://i.imgur.com/0GNIYY0.jpg) | 适宜长度的线缆 | [u/xicolinguada's ortho build](https://www.reddit.com/r/MechanicalKeyboards/comments/c39k4f/my_first_hand_wired_keyboard_its_not_perfect_but/) | 剥线容易 | 较难固定位置 | ![适宜长度的线缆](https://i.imgur.com/mBe5vkL.jpg) | 漆包线 | [fknraiden's custom board](https://geekhack.org/index.php?topic=74223.0) | 可以直接焊接(烧掉绝缘层) | 外观差? | ![漆包线](https://i.imgur.com/b4b7KDb.jpg) | 弯折二极管引脚作为行方向连线 | [Matt3o's Brownfox](https://deskthority.net/viewtopic.php?f=7&t=6050) | 焊点更少 | 绝缘性差 | ![弯折了的二极管引脚](https://i.imgur.com/aTnG8TV.jpg) | 硬线(如铜管) | [u/d_stilgar's invisible hardline](https://www.reddit.com/r/MechanicalKeyboards/comments/8aw5j2/invisible_hardline_keyboard_progress_update_april/) 以及 [u/jonasfasler's first attempt](https://www.reddit.com/r/MechanicalKeyboards/comments/de1jyv/my_first_attempt_at_handwiring_a_keyboard/) | 非常漂亮 | 难度高,没有物理绝缘 | ![手工连接的硬线](https://i.imgur.com/CnASmPo.jpg) | 用绝缘胶带(如高温胶带*)隔离开的裸线 | [Matt3o's 65% on his website](https://matt3o.com/hand-wiring-a-custom-keyboard/) | 简单(不用剥线) | 丑拒 | ![裸线](https://i.imgur.com/AvXZShD.jpg) | 铜箔胶带 | [ManuForm Dactyl](https://github.com/tshort/dactyl-keyboard) | 非常简单 | 只适用于定位板/外壳与开关底部平齐的情况 | ![铜箔胶带](https://i.imgur.com/RFyNMlL.jpg) (*译注:原文是聚酰亚胺胶带,在中国通常叫高温胶带) 以上方案可以结合使用,在焊接前请准备好各种长度的线缆。 ### 分体键盘的注意事项 如果你想制作的是分体键盘(如Dactyl),每一半边都需要一个控制器以及连通两方的通信用线(如TRRS或硬连接线)。更多资料参见[QMK分体键盘文档](zh-cn/feature_split_keyboard.md)。 (译注:TRRS即一种常用的4线耳机线插口,具体信息请查阅维基百科或[这份知乎文章](https://zhuanlan.zhihu.com/p/144233538)) ### 焊接 你可以找到很多焊接指导及技巧,这里列出了最相关及最关键的部分: 要想焊接的牢固需要确保焊料与焊接两端的金属面充分地接触,一个好办法(也不是必须)是上锡前先(将线缆)在针脚上绕一圈或先拧在一起。 <img src="https://i.imgur.com/eHJjmnU.jpg" alt="杆上绕圈" width="200"/> <img src="https://i.imgur.com/8nbxmmr.jpg?1" alt="绕环的二极管引脚" width="200"/> 如果二极管还在包装条上且需要弯折(作为绕圈的起点处或用于连接到邻接处),一个简便的办法是找一个盒子、桌子或尺子的直边上进行弯折。由于弯折统一在二极管一侧,也有助于区分二极管的方向。 <img src="https://i.imgur.com/oITudbX.jpg" alt="弯折二极管引脚" width="200"/> 如果你的电烙铁有温控功能,将其设置在 315ºC(600ºF)。 热起来后,给电烙铁上锡 - 即融化一部分锡料到烙铁头上然后立刻用湿海绵或烙铁头海绵擦掉,这样烙铁头上会有一层光滑明亮的焊料,以防止氧化且有助于焊料的焊接操作。 接下来进行焊接,先将烙铁头在焊接面上接触一会儿进行加热,然后上焊料焊接两侧。加热焊接面的目的是为了确保焊料可以粘附且不会过早冷却下来。 不能让焊料/焊点加热过度,热量会通过接触面烧毁原件(融毁开关外壳等)。并且,由于焊锡中有帮助[“浸润”](https://en.m.wikipedia.org/wiki/Wetting)(即上锡)的助焊剂,加热的越久助焊剂蒸发掉的越多,最终导致焊接点虚焊,除了看起来糟糕外,还有导致电路短路的风险。 #### 焊接二极管 从左上角的那个开关开始,将二极管放到开关上(用镊子,如果有的话)并纵向放直,有黑线的一端朝向你。让二极管间并联(二极管的阴极不应连接到其它二极管的阳极),二极管的阳极应连接到开关的左引脚上,而弯曲的阴极应朝向右边放置,如图: ![soldering-diodes-01.png](https://raw.githubusercontent.com/noroadsleft/qmk_images/master/docs/hand_wire/soldering-diodes-01.png) 在放稳二极管后,拿起焊锡,将其与左轴脚同时接触到电烙铁上 - 在松香的帮助下焊锡会很容易地覆盖在二极管及轴脚上。二极管可能会有些位移,此时你可以抓住二极管另外一端弯折过的引脚,小心地放回到位置上 - 但请留意另一端是会迅速变得烫手的。如果二极管容易乱跑,可以使用尖嘴钳之类的东西在焊接时辅助保持稳固。 松香加热时升起的烟有害,注意保护口鼻,不要熏到眼睛或皮肤。 焊接到位时,可以将焊点升起的烟吹走以免熏脸,也能帮助焊点快速降温。焊点在冷却后会形成沙哑状(无光泽)的表面,但请注意此时它依旧非常烫,需要几分钟时间的冷却才可以触摸,多吹吹有助于快速冷却。 在第一个二极管焊接完毕后,第二个二极管需要焊接轴脚以及上一个二极管弯折的那一端,看起来像这样: ![soldering-diodes-02.png](https://raw.githubusercontent.com/noroadsleft/qmk_images/master/docs/hand_wire/soldering-diodes-02.png) 在焊接完毕一整行后,用剪线钳剪掉二极管上方(绕轴脚后多出的部分),以及这一行最后侧多出来的引脚部分。在每一行焊接完毕后都要记得这一步。 在你完成了所有的二极管的焊接工作后,最好是逐一测试一下以确保焊接牢固稳定 - 再往后不是不能回头修正,但会越来越困难。 #### 纵向上的焊接 这一步你有几个可选项需考虑 - 给横向电缆进行绝缘处理是个好主意(毕竟二极管没有绝缘层),但如果你足够小心,横向电缆裸露着也行 - 但仍旧不建议这么做。如果你用的是单芯线,先将外皮整个褪下来再酌情装回去可能是最好的办法,但会因尺寸及材质原因造成操作困难,你可以将线缆上需要焊接到开关轴的部分裸露出来。 如果你使用多股线/铜绞线,可能最简单的方案就是用不固定长度的小段电线来纵向连接开关。通过融化掉焊接点的外皮的方式来用一整根线不是不可以,但这里不推荐这样做,这种操作会产生更多的有害烟尘,也会毁掉你的电烙铁。 在进行焊接操作前,先预弯折好线缆(如果是单芯线),或至少心中已经规划好焊接路线顺序(特别是你要做的设计是错列的时)。实际上焊接顺序不是特别重要,因为我们是通过焊接方案来确定键映射定义的 - 只要确保一行上的所有按键都有独自的列,且从左到右依次排列。 如果你不做任何的绝缘处理,可以将纵向的线升高一些,焊接在轴脚尖端上 - 如果线缆本身足够稳固,不会短路到连接着二极管的横线线缆上。 ## 连接控制器 在矩阵焊接完成后,可以将其焊接到微控制器板上了。 将微控制器放在预期的位置上,同时要考虑到安装及外壳对齐问题。须记得USB槽的位置是可以与微控制器分开的,只需使用一小段公对母线接驳下即可。 找到微控制器板的引脚定义/文档([链接](#common-microcontroller-boards))并将所有的I/O引脚标出来(留意像teensy这种的控制器,模拟I/O引脚可能是数字I/O引脚的两倍),将线缆连接到这些引脚上。 ---- ### 针对 Teensy 2.0 的特殊说明 Teensy 上的部分引脚有点特殊,像 D6(片上LED),及一些 UART、SPI、I2C或PWM通道,不过只是在你计划着在键盘上还有其它功能设计时才需避免使用。如果你还不是很确定以后会不会增加什么功能上去,引脚应该还是足够充足到可以剩一部分出来的。 那些无论在什么控制器上都不应去使用的引脚,有:GND、VCC、AREF以及RST - 其它所有引脚都是可以用且也能在固件中访问的到的。 ---- 将电线切割为控制器到各行/列上某一点距离的长度。可以焊到各行的任意位置上,只需要确保是在二极管之后 - 焊接到二极管前面(轴脚侧)的话该行将无法正常使用。 这里用排线的话会显得非常整洁,你也可以考虑如何排布线缆以连接到各行/列的近处。 <img src="https://i.imgur.com/z2QlKfB.jpg" alt="排线" width="350"/> 在往控制器上焊接电线时,请记住各引脚连接的是哪一行/列,在后续制作固件时我们需要用到这些信息来定义矩阵。 在你往下继续以前,请确保控制器已装配到位 - 切掉线缆再重新焊接非常麻烦! ## 一些基础的固件配置 至此,在你构建好固件后,键盘就应该能正常工作了。 通过 [Keyboard Firmware Builder](https://kbfirmware.com/) 网站可以轻松地创建一个简单的固件。通过 [Keyboard Layout Editor](https://www.keyboard-layout-editor.com) 可以自己制作配列数据,之后就可以导入进来并重新构建矩阵信息(如果你没有在先前的 [设计矩阵](#planning-the-matrix) 完成的话)。 继续完成剩下的步骤,在逐一配置完所有的按键后就可以编译下载固件了。其中 .hex 文件可以用来直接刷写到键盘上,而 .zip 包中的源代码可以用来添加高级功能并通过 [构建第一个固件](zh-cn/newbs_building_firmware?id=build-your-firmware) 中详述的方法进行本地构建。 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](https://github.com/qmk/qmk_toolbox). ![QMK Toolbox](https://raw.githubusercontent.com/noroadsleft/qmk_images/master/docs/hand_wire/qmk_toolbox.png "QMK Toolbox 0.0.16 on Windows 8.1") 在 “Local File” 栏处定位到你新创建的 .hex 文件,在 “MicroController” 中选择你的控制器板(常见型号[这里](#common-microcontroller-boards)有)。 插上你的键盘后在QMK Toolbox中点击reset(重置)按钮(如果没有重置按钮,短接一下Reset和接地引脚)再点击“Flash”(刷写)按钮。 ## 测试固件 可以用 [QMK配置器的键盘测试器](https://config.qmk.fm/#/test)、[Keyboard Tester](https://www.keyboardtester.com/tester.html) 或 [Keyboard Checker](https://keyboardchecker.com/) 进行测试,也可以打开一个文本编辑器并试着输入 - 你应该能成功输入键映射方案中的所有字符。对每个按键进行测试,并记录下不能正常工作的按键。对这些不能正常工作的按键,这里有一个快速排查指引: 1. 将键盘翻过来,用一段金属物短接一下轴脚 - 这么做可以排除掉需要更换掉的坏轴的可能性。 2. 检查轴脚上的焊点 - 应该是饱满且完整覆盖的。如果你稍加用力就能将其弄下来,那么就是焊接不到位。 3. 检查二极管的焊点 - 如果二极管虚焊了,部分行可以使用,但其它的可能就不行了。 4. 检查连接到各行的焊点 - 如果这里虚焊了,这些行就无法正常使用。 5. 检查 Teensy 两侧的进/出线的焊点 - 两侧的线缆都必须确保已被良好地焊接。 6. 检查 `<project_name>.h` 文件中是否有错误或不当的 `KC_NO` - 如果不确定在哪里,用已有的 k*xy* 变量替换一下。 7. 检查固件文件确实经过编译且正确刷写到Teensy上了。除非你在终端看到了错误消息,或是刷写时出现了弹框,否则一切应该是正常的。 8. 使用万用表实测一下,触发开关时是否成功闭合(按下时可以连通电路)。 如果你完成了上述所有检查,应当留意有时可能是多种因素共同造成了开关的异常,因此最后将其短路掉来排查问题并没有什么害处。 ## 即将完成 在确认键盘可以正常使用后,如果你用的是独立的控制器模块(非手工构建用),须将其固定好。办法有很多,比如热熔胶、双面胶带、3D打印的盒子、电工胶带等。 如果你觉得成就感满满,可以试着增加一些额外的功能,比如 [轴内LED](https://geekhack.org/index.php?topic=94258.0),[轴内RGB](https://www.reddit.com/r/MechanicalKeyboards/comments/5s1l5u/photoskeyboard_science_i_made_a_handwired_rgb/),[RGB背光](https://medium.com/@DavidNZ/hand-wired-custom-keyboard-cdd14429c7b3#.7a1ovebsk) 甚至可以是 [OLED显示屏!](https://www.reddit.com/r/olkb/comments/5zy7og/adding_ssd1306_oled_display_to_your_build/) 固件的潜力非常大 - 阅览 [docs.qmk.fm](https://docs.qmk.fm) 可以看到全部功能的列表,也能深入了解人们是如何使用那些五花八门的键盘的。随时欢迎到 [OLKB subreddit](https://reddit.com/r/olkb) 或 [QMK Discord](https://discord.gg/Uq7gcHh) 上寻求帮助! ## 其它指引链接 - [matt3o 的分步指引 (BrownFox build)](https://deskthority.net/viewtopic.php?f=7&t=6050) 以及他的 [个人站点](https://matt3o.com/hand-wiring-a-custom-keyboard/) 和 [指导视频](https://www.youtube.com/watch?v=LVzpsjFWPP4) - [Cribbit:“现代化的手工搭建指南 - 强大,简洁,友好”](https://geekhack.org/index.php?topic=87689.0) - [Sasha Solomon:“打造我的第一把键盘”](https://medium.com/@sachee/building-my-first-keyboard-and-you-can-too-512c0f8a4c5f) - [RoastPotatoe: “如何手工搭建Planck键盘”](https://blog.roastpotatoes.co/guide/2015/11/04/how-to-handwire-a-planck/) - [Masterzen:“手工搭建键盘记录”](https://www.masterzen.fr/2018/12/16/handwired-keyboard-build-log-part-1/) # 遗留内容 以前本页内还有其它内容,现在我们已经将他们单独分离出去了。以下的内容是一些重定向链接,以供那些从老链接地址过来的人能找到自己要找的内容。 ## 序: 键盘矩阵是如何工作的(以及为什么需要二极管) :id=preamble-how-a-keyboard-matrix-works-and-why-we-need-diodes * [键盘矩阵是如何工作的](zh-cn/how_a_matrix_works.md)