首页 > 装备展示厅

初级QMK编译入门教程

by 拆哪 2020.3.3

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

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


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


如果您并没有QMK固件的制作经验,强烈建议先去看下我之前的那篇《改装路透社小键盘,超详细图文讲解QMK刷机教程》,网址:https://www.zfrontier.com/post/detail/18546

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


下手之前还是先到处搜索相关的教程帖子,发现国内关于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三行代码是修改设备品牌、名称和描述的,无关痛痒,只是连接电脑后显示的设备名。

3132行是设置键盘按键的行列数,这个20键的小键盘是5行4列。

3637行是设置行和列对应的开发板针脚,第50行是设置二极管的方向是行到列还是列到行。这些跟我们之前在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行不用动。

后面的几行,在图中注释了。


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


需要注意的是,在设置针脚的时候,不要占用D1和D2针脚,因为这两个针脚除了可以当做普通针脚以外,还是开发板的通讯针脚,要留给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安装好以后还要配置下开发环境,具体教程可以参阅:https://post.smzdm.com/p/az50xgpo/

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



配置好以后,打开MSYS2,输入cd空格/c/qmk回车,然后再输入make空格mak01: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


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



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


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

最后编辑于 2020.5.28
27 举报帖子
最早回复
  • 最早回复
  • 最新回复
  • 最热回复
拆这
2020.3.2
#1

一楼沙发~!耶耶耶~!

王侃by
2020.3.2
#2
大神请收下我的膝盖
  • 拆哪
    2020.3.5
    能折现么?
  • 月饼
    2020.3.2
    #3
    必须顶啊,辛苦了
  • 拆哪
    2020.3.3
    为人民服务
  • 一愚
    2020.3.2
    #4
    42?
  • 拆哪
    2020.3.3
    啥?
  • 可以的
    Dendrobium
    2020.3.3
    #6

    支持一下,感觉写的相当浅显易懂了,不熟悉C或C++的应该也能看得差不多

  • 拆哪
    2020.3.4

    可惜这种主题关注的人不太多……哈哈哈

  • 劉仝
    2020.3.6
    #7

    在zF甚至可以学习编程!

  • 拆哪
    2020.3.7

    不算什么编程啦……你可以看成是在文本编辑器里调节各种选项……

  • 隐言静默
    2020.3.8
    #8
    希望早点出硬件部分的搭建,详细的步骤
    samkk
    2020.3.30
    #10

    make[1]: 进入目录“/c/qmk” tmk_core/protocol/lufa.mk:14: lib/lufa/LUFA/makefile: No such file or directory make[1]: *** 没有规则可制作目标“lib/lufa/LUFA/makefile”。 停止。 make[1]: 离开目录“/c/qmk” Make finished with errors make: *** [Makefile:579:9key:default] 错误 1

  • monkeychou🔰
    2020.4.7
    兄弟,你去github的qmk里,找到lufa这个文件夹,单独下载这个文件夹,放进去就行了
  • 旋风dg
    2020.4.16

    兄弟,你这个问题解决了吗

  • samkk
    2020.3.30
    #11
    老师可以帮我写个代码,支持4个编码器的吗
  • 拆哪
    2020.3.31
    等我练练的……现在还不会……我也是刚入门……
  • 用户8526
    2020.3.31
    #12

    还有一些我没玩过的 早有这样的帖子就能让我少走很多弯路

  • samkk
    2020.3.31

    老师编译出现/bin/sh: avr-gcc: 未找到命令,怎么解决 win764系统配置的环境

  • 这是之前的环境没装上 , 那个下载很容易中断 ,建议用别的方式下载安装 ,我记得好像装了很多次

  • 今天终于环境搭建好了,可以成功编译了,编码器针脚怎么接线啊,地线,5v,还有AB脚怎么接线,尝试了很多种都不行

  • samkk samkk
    2020.3.31

    终于搞定了。这个编码器不能接D1 D2 针脚。现在就是不自动怎么接4个编码器,难道要没个编码器接两个端口吗,4个编码器不是要8个端口了

  • cijianbian
    2020.3.31
    #15
    大……大佬
  • 拆哪
    2020.4.1
    不大……就会这些……全写出来了……抛砖引玉
  • samkk
    2020.4.6
    #16
    大哥,什么时候写一篇midi键盘教程啊,最近迷上diy了,看了好多关于diy midi的教程都没看懂,看了一下代码和 你这一篇文章差不多,没有你将的通俗易懂,弯路走很多,最后还是没成功
  • 拆哪
    2020.4.6
    额……完全没接触过midi……
  • 这以后
    2020.4.16
    #17

    收藏

    27