#第六届立创电赛# 基于QMK的自制小键盘（仅软件部分）

注意：本项目因个人原因未完工，仅分享QMK相关内容，硬件内容见后续吧。

其实是主控不慎烧掉了，后面在校有事又没时间...

1、项目功能介绍

基于 QMK 固件的、支持 VIA 软件改键的 DIY 热插拔小键盘。

2、项目属性

本项目为原创，首次公开。

3、开源协议

GPL 3.0

4、软件部分

以下内容为一个 QMK 新手在尝试过程中的一些经验和记录，如有错误望指正。

此部分内容仅记录Rev1设计过程，截图等不代表最终成品！内容仅供参考。

0、QMK简介

QMK (Quantum Mechanical Keyboard) 是一个社区维护的开源软件，包括 QMK 固件，QMK 工具箱，qmk.fm 网站，和这些文档。QMK 固件是一个基于 tmk_keyboard 的键盘固件，它在 Atmel AVR 微控制器实现一些有用的功能。它被移植到使用 ChibiOS 的 ARM 芯片上. 它可以在飞线键盘或定制 PCB 键盘中发挥功能。

1、安装编译环境

本项目采用Windows系统下 QMK MSYS 软件配置编译环境，安装方便简洁。下面介绍安装流程。

如果使用其它系统，请参照官网文档进行相应的环境搭建工作。

首先，进入 QMK MSYS 项目页面，于 Release 中下载最新版软件并安装。

打开，运行 qmk setup 命令，此步骤需要较长时间 会魔法的兄弟忽略这句话就好。直到显示 QMK is ready to go。

2、初编译

qmk setup后，尝试初次编译键盘固件以确认环境搭建成功。（防止丢包、缺失文件导致后面编译出错）

可输入

qmk compile -kb dz60 -km default

以尝试编译 dz60 键盘在默认布局下的固件。（随便选的一个键盘，当然可以选其他的来测试）

如果出现一串 OK 并在最后显示 The firmware size is fine，恭喜你，环境搭建完成，且你已经第一次成功编译了一个QMK键盘固件。

如果报错，请检查命令是否有误，并检查报错信息，补全文件，再次尝试编译。

成功示例（不是第一次编译故 OK 的数量很少）：

3、构建自己的键盘固件

下面来构建自己的键盘固件。

0、了解QMK文件夹的文件结构

• 用户空间结构
  在users文件夹里面的目录是每个用户的目录。这个文件夹里面放的是用户们在不同键盘都能用到的代码。
• 键盘项目结构
  在 keyboards 文件夹和他的子文件夹 handwired 中就是各个键盘的项目了，比如qmk_firmware/keyboards/clueboard。内部结构与如下:
  • keymaps/ : 可以构建的不同布局
  • rules.mk : 用来设置 “make” 命令默认选项的文件。
  • config.h : 用于设置默认编译选项的文件。
  • 在各个布局的文件夹，你能找到以下文件。只有 keymap.c 是必要的, 如果其他文件找不到就会直接选择默认选项。
    • config.h: 配置布局的选项
    • keymap.c: 布局的全部代码, 必要文件
    • rules.mk: 使能的QMK特性
    • readme.md:介绍你的布局,告诉别人怎么使用，附上功能说明。
    • config.h 文件

有三个重要的config.h 位置:

键盘 /keyboards//config.h

用户空间 /users//config.h

布局 /keyboards//keymaps//config.h

了解完毕！虽然自己的工程不必按照官方要求来建立文件。

1、设计键盘布局

进入Keyboard Layout Editor 网站。这是一个可视化键盘布局编辑网站，通过增减键和调整键的位置和定义来生成键盘布局。设计自己的键盘布局后，下载 json 文件。

设置键名如上是为了方便后面添加 VIA 支持，如果不需要可以直接命名成自己所需键的名称，以方便检查。

2、初步生成QMK固件

进入 Keyboard Firmware Builder 网页，将前面的 json文件复制进来。

Wiring界面：编辑键盘连线。

Rows 表示行数，Columns 表示列数，同时可以选中某一个键，调整其行、列号，使其连线确定，同时可以美化走线。

Pins界面：设置行列对应的主控引脚。

注意！本文仅作步骤解释，图示并不完全为正确操作！（如上图，引脚是不同的）

Keymap界面：选择某个键，编辑它在某一层（layer）时的功能。

键码的具体含义请前往 QMK 文档Keycodes部分进行查看。

需要注意的是：当使用到不止一层时，需要添加切层键，具体设置请参照官方文档。

Macros界面：键盘宏相关，作者尚不了解，请参照官方文档。

Quantum界面：大大的警告，不建议更改。

Settings界面：修改键盘名称、容量、WS2812数量、背光亮度等设置。

Compile界面：完成全部设置并下载固件的界面

如果所需功能较简单，经过以上步骤可以直接配置完成的，可以选择直接下载 .hex 文件，烧录之。

如果需要复杂功能（如oled，编码器等），请下载 .zip 文件，里面是该网页自动生成的、未进行编译的 QMK 固件，我们将在其基础上进行修改以满足自己的需求。

3、生成定位板

进入 Plate & Case Builder - swillkb，上传键盘配列的 json 文件，网站将自动生成适用于 CherryMX 系列机械键盘轴体和钢板卫星轴的定位板，下载 dxf 文件即可。此文件可以用于制作各种材质的定位板 你要无钢就当我没说

4、代码部分

以我自己的代码为例。

首先看 rules.mk 文件。

在最下方添加

ENCODER_ENABLE ?= yes
VIA_ENABLE ?= yes

以实现编码器支持和 VIA 支持。（如不需要 VIA 改键请不要开启）

如需其他功能请依照 QMK 官方文档自行添加开启。

其次，nk01.h 文件。如果是由网页生成的初始固件，该文件名为 kb.h。建议将其修改为自己的键盘名称。注意：需要同步修改 kb.c 和 kb.h 文件，并修改各文件中头文件名称。

这个文件定义的是键盘各键的行列序号。理论上无需修改，但请确认与设计稿无出入。

然后是 keymap.c 文件。这个文件定义的是键盘的功能。

5 - 8 行定义的是各层的名称。

10 - 26 行定义的是各层键值，可依据 QMK Keycodes 列表进行自行修改。

29 - 46 行定义的是编码器功能。QMK 文档中有更深解析，如有需求可前往查看。

各种切层方法：

MO(layer)
按下触发层， 可以把 MO(layer) ， 理解成 Fn。 当松开这个键， layer 层会释放并恢复到上一层。若把 MO(layer)设置到一个键位， layer 层中的同一键位必须设置为 KC_TRNS，否则在松开这个按键的时候不会回到上一层。 若把第 0 层的 ESC 设置为 MO(1)， 则在第一层 ESC 的位置只能设置成 KC_TRNS。同时只能把 MO(layer) 这个键设置到 layer 上面的层， 比如可以在第 0 层设置 MO(1)，但是不能在第 1 层设置 M0(0)。

OSL(layer)
临时触发层， 如果把一个键位设置为 OSL(1) ， 点击这个按键后， 只有下一个点击的按键会从层 1 触发。 之后的点击回立即回到层 0 触发。

LT(layer, kc)
可以把 LT(layer, kc) 理解成 MO(layer)+kc 一键两用。 当长按这个键， 键位的功能就是 MO(layer) ，点击这个键， 键位的功能就是 kc。经大佬测试， 这里的 kc 不能设置为 mod(Ctrl，Alt，GUI，Shift 等键)

LM(layer,mod)
可以把 LM(layer, mod) 理解成 MO(layer)+mod 一键两用。 当你长按这个键， 键位的功能就是MO(layer)+ mod 同时生效。这样可以把 mod 键一键两用。

TO(layer)
一键切换到 layer。可以在任意层中设置。例如在层 0 设置了 TO(2) ， 但是要记得最后在层 2 中设置 TO(0)来恢复到默认层。

TG(layer)
类似于 TG(layer)，但是只能在某两层中来回切换。例如在层 0 中 ESC 的位置设置了 TG(5)，按下后会立即跳转到层 5 中， 在层 5 中 ESC 的位置只能设置为 KC_TRNS。 只能把 TG(layer) 这个键设置到 layer 上面的层，比如可以在第 0 层设置 TG(5)，但是不能在第 5 层设置 TG(0) 。

DF(layer)
键盘的默认层是层 0， 此键位的功能是设置默认层为 layer ， 非必要不用改动默认层。

最后来到最复杂的 config.h 文件。

其中主要部分不要改动。

7 - 12 行可自行更改。（如果计划使用VIA请查看VIA部分并修改）

15、16行为行列数量。

19、20行定义行列对应引脚号。

24行定义二极管方向。

50、51、52分别定义编码器分辨率和 A、B 引脚连线。

*5、VIA支持

此部分请自行考虑是否进行，因为大多数使用者并不会频繁出现改键需求。如有需求请前往官网下载VIA软件。（安装包太大了发不上来）

VIA 官网链接：VIA

1. rules.mk 添加

VIA_ENABLE ?= yes

语句，即开启 VIA 支持。
2. 依照 config.h 文件编写 via.json 文件。
以我的项目为例：

格式需完全一致。
保存文档。

• "name"：键盘名，将显示在 VIA 中。
• "vendorId"：即 config.h 文件中的 VENDOR_ID。
• "productId"：即 config.h 文件中的 PRODUCT_ID。
• "lighting"：灯光，因为个人爱好无光键盘故选择 none，若有需求请参照 VIA 官方文档。
• "matrix"：分别输入行、列数量。
• "layouts"：对于固定配列的键盘（即不能更改键长宽位置的），将 KLE 网站下载的 RawData 复制并修改为正确格式即可。若是可变配列型，请参照 VIA 官方文档。

3. 测试 json 文件可行性。
- 打开 VIA 软件，进入 Settings，开启 Design。
- 进入 Design，上传编辑好的 via.json。
- 若成功，将出现如下（或类似）界面。

• 
  * 若不成功或键盘配列怪怪的（键重叠等等），依照报错内容修改 json 文件。
  * 硬件制作完成后可测试改键功能。如下图。
  

以上部分均基于 Rev1。基础功能其实在烧主控之前已经验证了。

6、生成hex文件

打开 QMK MSYS，初始化后，输入

qmk compile -kb nk01 -km default

如果是其他键盘或其他配列请自行更改。

如果顺利，将出现类似界面。

恭喜！键盘固件顺利完成！

5、硬件部分

硬件部分包含 Type-C 输入、USB拓展、MCU主控、控制元件四部分组成。请参照附件查看。

设计选用 ATmega32U4 作键盘主控 废话固件都写好了。轴体采用热插拔轴座固定方式，方便更换轴体。编码器选用EC11。FE8.1 作USB拓展芯片（问就是SL2.1A烧了好多次了）。Rev 1 版本分别在前后侧引出1、2USB接口，其中靠近Type C 接口侧是用来与主键盘连接 这难道不是分体键盘？，如果使用有线鼠标的可以上方2USB下方1USB以方便放线。Rev 2 版本因插件元件受限，只能将剩余两个usb接口放在右侧（但是我是左手小键盘啊喂）。

6、其他工作

焊接

（主控烧了导致无法按时完工）

烧录

1. 烧录 Bootloader。
   选用 Arduino IDE 烧录。方法如下：
   • 打开 Arduino IDE，版型选择为 Leonardo，烧录方法选择为 USBasp。
   • 通过 USBasp 和测试针连接主控，压紧，选择烧录引导程序。
   • 烧写完成。
2. 烧录键盘固件。
   若选用 QMK Toolbox，方法如下：
   1. 打开 QMK Toolbox，选中固件，MCU选择为 ATmega32U4。
   2. 选择键盘和布局，打开自动烧录。
   3. 连接键盘，reset，开始烧录。
   4. 烧录完成。
3. 若选用 avrdudess，方法如下：
   1. 打开 avrdudess，编程器选择为 USBasp，MCU 选择为 ATmega32U4。
   2. 测试针连接主控，尝试连接芯片。
   3. 选择键盘固件，烧录。
   4. 烧录完成。
4. 测试键盘。
   VIA 软件内 KeyTester 一条龙服务。

7、BOM清单

因时间原因未按时完工，截止比赛结束仅分享QMK软件部分，故不包含BOM表。

8、大赛LOGO验证

请上传包含大赛logo的项目图片，logo以丝印形式印刷在PCB上面。