初级QMK编译入门教程

如果只是做常规键盘的话，用我之前文章里提到的QMK固件制作方法就足够了。

但是人的欲望总是无尽的，当看到那些客制化键盘上的OLED屏、旋钮、分体键盘等等的时候，我的内心又有一个声音对我说：我全都要……

于是这个问题就变得复杂了……之前的编辑方法显然不足以满足这些需求了。于是就要对QMK固件进行代码级的编辑。看上去很炫酷有没有？！？！

如果您并没有QMK固件的制作经验，强烈建议先去看下我之前的那篇《改装路透社小键盘，超详细图文讲解QMK刷机教程》

如果能照着做一遍就更好了，因为这篇文章里涉及的很多问题，其实就是将一些之前可视化的编程还原回代码化了。

下手之前还是先到处搜索相关的教程帖子，发现国内关于QMK固件编辑的教程少的可怜，加之祖传的英语渣渣，只能在网页翻译插件的帮助下，强行硬啃QMK主页的官方教程了。其实现在想想还是挺有收获的，有些问题当时可能不太理解，但是大概看一眼，没事念念不忘一下，没准什么时候就必有回响了……

QMK官方说明网址：https://docs.qmk.fm/#/

言归正传，把我经过各种路子学到的一点凤毛麟角的固件编辑知识分享给大家。其实也谈不上教程，因为我本身也是边摸索边写的，如有不规范或者疏漏，还往大神轻拍指正。

文中涉及的软件：

ATOM：代码编辑器。可以去atom主页免费下载使用，地址：https://atom.io/

MSYS2：把代码文件整合编译成HEX格式的固件文件。也是免费的，官网地址：https://www.msys2.org/

首先，去到QMK的GAYHUB（GAYHUB不是笔误，你懂的。）主页：https://github.com/qmk/qmk_firmware

点击页面右偏上角的绿色按钮，在弹出的菜单中选择Download ZIP。

得到qmk_firmware-master.zip，解压缩成文件夹，然后把文件夹名字改为QMK，其实不改也行，主要是为了后面方便记忆，同时也可以少敲点字……然后把QMK文件夹放到C盘根目录，原因同上……懒癌晚期就这样……

下一步是要找到一个合适自己的键盘源文件，QMK自带的键盘固件源文件都在keyboards文件夹中。对于小白来说，如果在keyboards里面能找到适合自己的键盘当然是很幸运的。

如何确定这些各种各样的名称的键盘，哪一个是自己想要的哪？对于我这种英文不好的人来说，我的办法是看找键字，比如首先肯定知道自己想要什么配列的键盘，比如60%，那就搜索60，一般在给键盘命名的时候都会体现出按键数量或者比例。

如果很不幸，示例文件中没有合适的布局，也可以通过去各种网站论坛上寻找接近的键盘，然后进行个性化的修改。当然，前提是你看上的这款键盘的作者大发慈悲的分享了他的源文件……

通过寻找QMK自带的键盘示例，并没有发现满足我需求的键盘。所以只能通过寻找相近的案例文件，再进行修改了，毕竟我是小白……让我独自写一个完整的键盘固件，我还是有点力不从心的……

不过不管有没有在QMK文件夹中找到自己满意的键盘文件，都不要删除它！后面还有用！

很幸运的是，最近在thingiverse上，有一位ID为soapsrx的大神，分享了一款小键盘，有6个按键，一块OLED 和一个旋钮，这与我之前的需求很接近了。功能方面，我只需要在他的基础上增加一些按键和rgb灯光就好了。外观的话，借着3D打印机的淫威，基本都不是问题。

打开https://www.thingiverse.com/thing:4134988

点击右上角蓝色按钮。下载得到+Mechanical+Keyboard+-+SiCK-68+Encoder+Oled+Display.zip。解压缩。

在解压后的文件夹内，打开files->mak01->mak01文件夹。

然后我们看到的这些文件，就是制作QMK固件的最基本的文件构成了。

QMK固件构成文件简单介绍：

keymaps->default->keymap.c 负责键位、键层设置，旋钮功能设置，oeld功能设置等等

rules.mk 相当于总开关，使用什么开发板，键盘开启和关闭什么功能，都要在这个文件中设置。

config.h 可以设置键盘的设备名称等相关信息，还有针脚设置，RGB灯光设置等等。

mak01.h 这个文件中的键值配列要与keymap.c中的对应。一般情况下，只要不改变配列，只是修改按键定义的话，就不用动这个文件了。

mak01.c 这个我也不知道干什么的，但是要保证里面的内容指向同名的.h文件。一般不修改这个文件。

readme.md 说明文件，不用理会。

除了这些最基本的文件，对于一些功能复杂的键盘来说，他的文件会多出很多其他文件，但是万变不离其中，对于我这种初学者来说，多看看其他键盘的示例文件也可以学到很多东西。

这些文件分工不同，相互关联，所以很多修改往往要涉及到几个文件的编辑。

比如增加旋钮（编码器）功能：

首先要在rules.mk中开启旋钮功能

然后在config,h中设置旋钮连接的针脚以及灵敏度等

最后在keymap.c设置旋钮的功能

打开rules.mk。

用atom文件打开以后，就是下图这种画风的，炸一看全是字，感觉比较高深，其实主要原因我觉得是因为全是英文……如果英语比较好，或者耐下心来翻译一下的话，也就没那么难了。其实这些文件用WIN自带的记事本也可以编辑，用编辑软件的好处就是，软件会根据代码的格式，自动将功能相同的内容统一成一个颜色，同时还会在每行的前面加一个行数，方便查找。

如下图，红字是代码的功能名称，白字是可以修改的选项，灰字是注释文字。

注释文字的头尾都会有特定的符号，用这些符号开头或者夹在这些符号中的文字，就会被识别为注释文字。注释文字的作用是方便记忆，并且支持中文。

可以看到，这个文件的编辑者有一个很好的习惯，就是将开启和关闭的功能，分为两组。其实QMK对这些代码的行顺序是没有强制要求的，而且默认的代码的顺序也不是这样严格区分的，按照何种方式归类完全根据个人喜好。

第2行是设置开发板芯片型号的，我这里使用的是Teensy2.0开发板，所以芯片型号改成ATmega32U4。

第12行，根据开发板的型号，修改启动类型，Teensy2.0对应的是halfkay。

第34行是rgb灯光开关，复制到上面，改成yes。

保存，关闭。

如果有命令不知道是干什么用的，可以去QMK官网搜索。

网址：https://docs.qmk.fm/#/

打开网页以后，点击左上角的Search，然后把搞不懂的代码粘贴上去，搜索一下，一般就能找到说明了。

比如搜索：COMMAND_ENABLE，然后就会找到跟这条代码相关的所有内容，英文不好的话，用浏览器插件翻译一下，大概就能知道这个代码的作用了。

就像前面说的，rules.mk文件只相当于一个总开关，这几个功能虽然开启了，但是具体如何使用，就要在config.h中进行设置了。PS一句，rules.mk中并不是将QMK所有的功能都列在其中了，没写入进去的就默认为关闭了。不过，为什么不把代码里面标记为NO的都删除了哪？我也不知道……尽量还是不要大改动了，以免出现超出自己解决能力的错误……

打开config.h。

还是一行行的代码，还是要静下心一条条的看……

26、27、28三行代码是修改设备品牌、名称和描述的，无关痛痒，只是连接电脑后显示的设备名。

第31和32行是设置键盘按键的行列数，这个20键的小键盘是5行4列。

36和37行是设置行和列对应的开发板针脚，第42行是设置二极管的方向是行到列还是列到行。这些跟我们之前在kbfirmware.com上做的其实是一个原理，只不过KBF上将这一过程可视化了。

与rules.mk文件中的工整相比，config.h文件的编写明显偷懒了……原作一个2*3的6键配列，文件中竟然是5*19的配列……反正我都要改成5*4，顺手就改了吧。同时对应的针脚数量也要与行列数对应。

插播一下，由于改变了原本的配列，所以要对mak01.h进行编辑，将里面的键值也改成5*4的，也就是每行保留4个键值，一共5行。两个键层都要这样。当然，如果只是修改按键功能，不改变配列的话，就可以省略这一步了。

回到config.h文件接着往下看，下图中：

第47行，修改延迟的，由于按键开关的物理特性，在按下去的过程中，都会产生一些很细微的颤抖，如果不增加一个容错时间，很可能感觉是按了一下，但是在极短的时间内，按键已经经历了多次开关的过程，这样就容易造成误触。但是这个容错时间又不能太长，太长的话，按键就会延迟过长了，影响输入。QMK的默认值是5，也就是0.005秒，一般情况下这个数值不用修改。

第50行和第52行不用动。

后面的几行，在图中注释了。（RGB灯光效果的代码是从QMK官网瞎抄的……很可能不管用……）

在keymaps->default文件夹中，还有一个config.h文件，里面是旋钮编码器的针脚设置，一般来说，这个代码写在前面那个config.h就可以。出于一个新手的小心谨慎，还是不要把这两个文件合并到一起吧……

需要注意的是，在设置所有针脚的时候，都不要占用D0和D1针脚，因为这两个针脚除了可以当做普通针脚以外，还是开发板的通讯针脚，要留给OLED 屏幕使用。

打开keymaps->default文件夹中的keymap.c文件，如下图。

与修改config.h时候看到的行列数一样，keymap.c文件中设置的果然5*19的配列……并且有两个键层（LAYOUT），根据需要，按照QMK的键值表，进行修改。但是在修改的时候一定要注意保持原有代码结构，只修改橙色的键值即可，一个标点符号的格式千万不要变。而且要特别留神那些标点符号！比如每行键值的最后都有一个逗号，但是最后一行键值的结尾却没有……如果编辑的时候不小心也打上逗号，就会编译失败了……就是这么的严谨……

QMK键值地址：https://docs.qmk.fm/#/keycodes_basic

根据我自己的用途调整好的按键设置如下图，在小键盘上增加了退格键，是为了方便使用计算器的时候删除数字。右上角的按键是播放暂停键，对应到编码器的按键功能上，这样按下编码器就可以控制播放器了。左下角TO的键值是切换键层用的，两个键层要可以相互切换才行。

再往下的一段代码是关于OLED的，其中绿色的代码为最终将要显示在OLED上的文字，不支持汉字……QMK默认的OLED为128*32分辨率的，这段设置中，将OLED分为四行显示：

第一行为Layer：，后面的文字根据激活的键层显示，BASE键层是显示Default，FUNCTION键层时显示PhonoShop。

第二行是“-------”分割线。

第三行是Stats：

第四行跟键盘LED的功能相同，显示NUM和CAP时表示激活小键盘和大写，反之同理。

QMK默认开启的OLED屏幕分辨率为128*32，也可以支持128*64的OLED，需要额外加一条代码声明一下。

最后一段代码是旋钮，也就是编码器功能的设置，本着挑看得懂的改的原则，将正转和反转的键值设定为音量大小调节。

官方提供的编码器范例代码是对应两个编码器，自己在编辑的时候去掉一个编码器的代码就行了。删除代码的时候要注意大括号的对应关系，保证大括号都是成对出现的。

至此，按键不多，却包含了比较流行的元素的键盘固件源文件就基本写好了，下一步就要把这些文件编译成固件文件了。

还记得文章一开始提到的QMK文件夹么？将刚才编译的那些文件所在的MAK01文件夹拷贝到C->QMK->keyboards文件夹中。

MSYS2安装好以后还要配置下开发环境，具体教程可以参阅：

自编译QMK入门篇——开发环境搭建与编译前言之前写过使用kbfirmware编译QMK的教程，一些人不满足于简单的QMK固件，总想加个蓝牙或者RGB背光灯之类的特性。这次开个系列详细说说怎么编译出功能复杂一点的QMK固件。教程会从开发环境搭建，配列修改，蓝牙或背光等附加特性都详细说说，喜欢的可以关注一下。搭建自己编译QMK固件，需要搭建Aqianseyue| 赞9 评论3 收藏34查看详情

特别感谢一下这篇文章的作者qianseyue，网上比较容易找到的几篇关于QMK的文章都是qianseyue老师写的。

配置好以后，打开MSYS2，输入cd空格/c/qmk回车，然后再输入make空格sunumpad20:default回车，没有意外的话，就会像下图这样，一路OK。

当然，一路OK的情况在编译当中并不是一下子就能得到的，正常情况下都会有点错误，这个时候就要冷静分析原因了。好在QMK很贴心的提示了编译失败的原因。

比如下图这种错误，我们可以看到熟悉的文件名keymap.c，后面的C：39：5，是错误出现在代码的第39行的第5个字。再往下提示出错误的具体位置，是括号和逗号出问题了。

于是回到编辑器，查看keymap.c的代码，找到第39行，发现括号和逗号并没有问题，但是查看附近的代码，通过上下两个键层的对比，可以看出，第一键层的最后一个按键后面比第二键层多了一个逗号，这就是导致报错的原因，删除这个逗号，保存文件，再次编译，问题就解决了。

最后，去到QMK文件夹下的,build文件里，找到一个hex格式的文件，就是我们做好的固件了。

将固件文件刷入开发板，TEENSY 2.0的刷固件方法可以看我另一篇文章《3D打印机械键盘制作-附超详细Teensy 2.0主控制作教程》地址：https://www.zfrontier.com/post/detail/18651

刷好固件以后，系统就会识别出键盘了，虽然只是一个没有连接任何零件的开发板。

看了下文章长度，好像有点长……于是就在主控刷好固件这里告一段落，下一篇着重说键盘硬件部分的搭建。

最最后说一句，这里说到的某些代码可能会在后面实际测试以后发现错误，如果有这种情况我会在后面的文章中指出更正。