这真是愚蠢的教学。写得很详细。只是一个人
翻译/排版/制作：aialra
原始来源：docs.qmk.fm
*未经作者许可请勿商用
目录：QMK教学大纲（建议先从基础开始看，不建议直接跳文章）
本页面通过首先介绍基础知识，并指导您理解想要精通QMK需要了解的所有概念，从而帮助您构建QMK的知识体系。
引言
如果您没有阅读其他内容，那么您应该阅读本节中的文档。在阅读了本教程之后，您应该能够创建一个基本的键映射，编译它，并将其刷写到键盘上。其余的文档将对这些基础知识进行补充。
学习如何使用QMK工具
学习键映射
您可以使用文档提供的的键码的完整列表。请注意，有些可能键码需要进阶的知识。
编程软件（可选）
·Eclipse
·VS Code
中级学习
这些章节将开始深入研究QMK支持的一些功能。您不必阅读所有的文档，但如果跳过其中一些，您就可能无法阅读高级章节部分中的一些文档。
学习如何使用或配置功能
·Lighting 灯光
更进一步学习键映射
·Macros 宏
·Custom Functions and Keycodes 定制功能和键码
高级阶段
下面的一切都需要大量的基础知识。除了能够熟练使用高级功能创建键映射之外，您还应该熟悉使用config.h和rules.mk来配置键盘选项。
·Maintaining Keyboards Within QMK 使用QMK进行键盘维护
·Advanced Features 进阶功能
·Hardware 硬件
·How A Keyboard Matrix Works 键盘矩阵是如何工作的
·Core Development 核心研发
·Compatible Microcontrollers 可兼容的微控制器
·CLI Development 命令行界面开发
·Coding Conventions 编程规范（python）
正式学习部分
序章
什么是QMK固件?
QMK (Quantum Mechanical Keyboard)是一个以开发计算机输入设备为中心的开源社区。社区包含各种输入设备，如键盘、鼠标和MIDI(Musical Instrument Digital Interface乐器数字接口）设备。有一个核心协作者组负责维护QMK固件，QMK配置器，QMK工具箱和QMK网站。这文档可以帮助像你一样的社区成员
开始
对QMK完全陌生?有两种方法可以开始学习:
基础:QMK配置器
·只需从下拉菜单中选择你的键盘，然后为键盘编程。
·你可以看一段介绍视频。
·您还可以阅读一个概述文档。
高级:使用源（source）
·更强大，但更难使用
把它变成你自己的东西
QMK有很多特性需要你去研究，也有很多参考文档需要深入研究。大多数特性可以通过修改你的键值映射和更改键值代码来操作。
需要帮忙吗?
查看支持页面，了解如何获得使用QMK的帮助。
回馈
您可以通过很多方式为QMK社区做出贡献。最简单的方法就是使用它并把它传播给你的朋友。
·在我们的论坛和聊天室:帮助人们
·单击底部的“编辑此页”，为我们的文档做出贡献
·把我们的文件翻译成你们的语言
·报告一个错误
·或者打开一个Pull请求
介绍
完整的QMK萌新指南
你的键盘里面有一个处理器，就像你的电脑里面的一样。该处理器运行的软件负责检测按键的按下，并在按键按下时通知计算机。QMK固件充当软件的角色，检测按下的按键并将信息传递给主机。当您构建自定义的键映射时，您就是为您的键盘创建一个可执行的程序。
QMK试图通过使简单的事情变得简单，使困难的事情变得可能，从而将大量的权利交到你的手中。你不需要知道如何编程来创建强大的键映射—你只需要遵循一些简单的语法规则。
不知道你的键盘是否可以运行QMK?如果是你自己造的机械键盘，有很大可能它可以。我们支持大量的爱好者开发板。如果你当前的键盘不能运行QMK，有很多其他的板子可以选择。
这是给我的指南吗?
这个指南适合所有想要使用源代码构建键盘固件的人。如果您已经是一名程序员，您会发现这个过程非常熟悉，并且更容易遵循。如果你害怕编程，请对着我们文章中的GUI（图形用户界面Graphical User Interface-相当于图片）操作。
概述
本指南有4个主要部分:
·建立开发环境
·构建您的第一个固件
·刷写固件
·测试和调试
本指南主要帮助那些以前从未编译过软件的人，它根据这一特性作出教学的选择和建议。完成这些程序有很多的方法，我们支持大多数的方法。如果你对如何完成任务有疑问，可以向我们寻求指导。
额外的资源
在学习QMK时，除了本指南之外，还有一些有用的资源。你可以去QMK官网的学习资源（ Learning Resources ）页面进行下载
开源
QMK是在GNU通用公共许可证下发布的开源软件。
建立qmk开发环境
在构建键映射之前，你需要安装一些软件并设置构建环境。这只需要做一次，无论你计划为多少键盘编译固件。
1. 下载软件
您需要先下载以下软件：
文本编辑器
你需要一个可以编辑和保存纯文本文件的程序。如果你使用的是Windows系统，你可以使用记事本（Notepad），而在Linux系统中你可以使用gedit。这两个都是简单但功能强大的文本编辑器。在macOS上，要小心使用自带的TextEdit应用程序:它不会保存纯文本文件，除非你在设计（format）菜单中显式地选择使用纯文本（Make plain text）。
您还可以下载并安装专用的文本编辑器，如Sublime text或VS code。这可能是最好的方法，因为不论在什么平台上，这些程序都是专门为编辑代码而设计的。
QMK工具箱
QMK 工具箱是一个可供选择的图形程序，用于Windows和macOS，它既允许您编程也允许您调试您的客制化键盘。您可能会发现它对快捷地刷写键盘固件和查看它的调试消息非常有用。
tips：如不是最新请去官网下载
·用于Windows: qmk_toolbox_install.exe(可移植)或qmk_toolbox_install.exe(安装程序)
·macOS: QMK.Toolbox.app.zip(可移植)或QMK.Toolbox.pkg(安装程序)
类unix系统中的环境建设
Linux和macOS附带unix shell，所以您已经可以直接执行了。您只需要设置您的构建环境。
在Windows上，您需要安装MSYS2或WSL并使用这些环境。下面提供了设置MSYS2的说明。
2. 准备构建环境
我们试图使QMK尽可能容易设置。您只需准备好Linux或Unix环境，然后让QMK自动安装其余的操作。
如果您以前没有使用过Linux/Unix命令行，那么您应该学习一些基本概念和命令。这些资源将教你足够的QMK工作:
Windows
您将需要安装MSYS2、Git和QMK CLI。
按照MSYS2主页上的安装说明操作。安装完成后关闭所有打开的MSYS终端（命令窗口），并打开一个新的MinGW 64位终端。注意:这与安装完成时打开的MSYS终端不同。
然后，运行以下命令:
pacman --needed --noconfirm --disable-download-timeout -S git mingw-w64-x86_64-toolchain mingw-w64-x86_64-python3-pip python3 -m pip install qmk
macOS
你需要安装Homebrew。按照Homebrew主页上的说明操作。
安装Homebrew后运行以下命令:
brew install qmk/qmk/qmk
Linux
您将需要安装Git和Python。很可能你已经有两个，但如果没有，使用以下命令之一安装它们:
·Debian / Ubuntu / Devuan: sudo apt install git python3 python3-pip
·Fedora / Red Hat / CentOS: sudo yum install git python3 python3-pip
·Arch / Manjaro: sudo pacman -S git python python-pip python-setuptools libffi
安装全局CLI（命令行界面command-line interface）以引导您的系统:python3 -m pip install –user qmk
(在基于arch的发行版上，你也可以尝试来自AUR的qmk包(注意:它是被一个社区成员维护的):yay -S qmk)
FreeBSD
您将需要安装Git和Python。有可能你已经有两个，但如果没有，运行以下命令来安装它们:
pkg install git python3
确保 $PATH已经被添加到了$HOME/.local/bin ，确认本地安装Python
只要安装一次，你就可以全局运行qmk：
python3 -m pip install --user qmk
3.运行QMK设置
安装QMK后，您可以使用以下命令进行设置:
qmk setup
在大多数情况下，您希望对所有提示都回答Yes。
*在Debian, Ubuntu和他们的衍生工具上注意:你会可能得到一个错误比如:bash: qmk: command not found。这是由于Debian在其Bash 4.4发行版中有一个bug，该bug从PATH中删除了$HOME/.local/bin。这个bug后来在Debian和Ubuntu上被修复。可惜的是，Ubuntu发现了这个bug，现在还没有修复。幸运的是，修复很容易，以用户身份运行如下即可:
echo ‘PATH=”$HOME/.local/bin:$PATH”‘ >> $HOME/.bashrc && source $HOME/.bashrc
*关于FreeBSD的提示:建议以非root用户的身份开始运行qmk setup，但这可能会识别出需要使用pkg安装到基本系统的包，但是如果以非特权用户的身份运行，安装可能会失败。要手动安装基本依赖项，作为root用户或使用sudo运行./util/qmk_install.sh。完成之后，重新运行qmk setup以完成安装和检查。
*如果您已经知道如何使用GitHub，我们建议您创建自己的fork并使用qmk setup <github_username>/qmk_firmware来克隆您的个人fork。如果您不知道这意味着什么，您可以忽略此信息。
4. 测试您的构建环境
现在QMK构建环境已经设置好，可以为键盘构建固件了。首先尝试构建键盘的默认键映射。你应该能够用这行命令做到:
qmk compile -kb <keyboard> -km default
例如，要为66%配列的键盘创建固件，您将使用:
qmk compile -kb clueboard/66/rev3 -km default
当它完成的时候，你应该有很多类似这样的输出:
Linking: .build/clueboard_66_rev3_default.elf [OK] Creating load file for flashing:.build/clueboard_66_rev3_default.hex
[OK]
Copying clueboard_66_rev3_default.hex to qmk_firmware folder [OK] Checking file size of clueboard_66_rev3_default.hex [OK] * The firmware size is fine - 26356/28672 (2316 bytes free)
5. 配置构建环境(可选)
您可以配置构建环境来设置默认值，使得使用QMK不那么繁琐。现在就开始吧!
大多数QMK新手只有一个键盘。您可以将此键盘设置为您的默认键盘
qmk config user.keyboard=clueboard/66/rev4
您还可以设置默认的键盘密钥映射名称。大多数人在这里使用GitHub用户名，我们建议你也这么做。
qmk config user.keymap=<username>
在这之后，你可以这些像这样使用参数并编译你的键盘:
qmk compile
创建您键值映射表
现在，您可以创建自己的键值映射了!继续为它构建您的第一个固件。
构建您的第一个固件
既然已经安装了构建环境，就可以开始建立定制固件了。对于这指南的这一部分，我们将使用3个程序-你的文件管理器，你的文本编辑器，和你的终端窗口。保证这三个软件是打开的直到您完成令您满意的键盘固件。
创建一个新的键映射
要创建属于自己的键映射，您需要创建默认键映射的副本。如果您在上一章的最后一步配置了您的构建环境，您可以轻松地用QMK CLI完成:
qmk new-keymap
如果您没有配置您的环境，或者您有多个键盘，您可以指定一个键盘名称:
qmk new-keymap -kb <keyboard_name>
命令的输出应该类似这样：
Ψ <github_username> keymap directory created in: /home/me/qmk_firmware/keyboards/clueboard/66/rev3/keymaps/<github_username>
这是你的新keymap.c文件的所在位置
在您喜爱的文本编辑器中打开keymap.c
在文本编辑器中打开keymap.c文件。在这个文件中，你会发现控制键盘表现的架构。在keymap.c的顶部可能有一些定义和例子使键映射的概念更容易被理解。再往下你会发现一条像这样的一行:
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
这一行表示层列表的开始位置。下面你会发现包含LAYOUT的行，这些行条表示一个层的开始。在这一行下面是组成特定层的键的列表。
*编辑键值映射文件时，注意不要添加或删除任何逗号。如果您这样做，您将
使您的固件编译出错，并且找出额外的或缺少的逗号在哪里可能很困难。
根据您的喜好定制配列
如何完成这一步完全取决于您。比如说改变一个你一直不喜欢的配列，或者完全重做一个新的。如果你不需要所有的配列层，你可以删除它们，也可以增加层，总共可以有32个。QMK中有很多功能，请在左侧“使用QMK”的侧边栏中查看完整的列表。为了让你开始这里有比较容易使用的功能介绍:
·量子键码（量子键码比基本键码更容易定制您的键映射，而无需定义自定义操作。
*当你对键映射的工作原理有了一定的了解时，建议你保持每次都进行小幅度修改。较大的更改会让你调试解决任何出现的问题变得更加困难。
建立你的固件
当您完成了对键值映射的更改后，您将需要构建固件。为此，您需要回到您的终端窗口并运行编译命令:
qmk compile
如果您没有配置您的环境，或您有多个键盘，您可以指定键盘或键映射:
qmk compile -kb <keyboard> -km <keymap>
在编译过程中，会有很多输出语句显示在屏幕上，告诉您正在编译的文件信息。它应该以如下所示的输出结束:
Linking: .build/planck_rev5_default.elf [OK]
Creating load file for flashing: .build/planck_rev5_default.hex [OK]
Copying planck_rev5_default.hex to qmk_firmware folder [OK]
Checking file size of planck_rev5_default.hex [OK]
* The firmware size is fine – 27312/28672 (95%, 1360 bytes free)
刷写你的固件
继续学习刷写固件，了解如何将新固件写入键盘。
刷写你的键盘固件
现在您已经构建了一个自定义固件文件，您将需要刷写您的键盘固件。
把你的键盘放入DFU(引导加载器)模式
为了刷写你的自定义固件，你必须首先把你的键盘进入一个特殊的刷写模式。在此模式下，您将无法打字或使用键盘。在编写固件时，不要拔下键盘或中断刷写进程，这一点非常重要。
不同的键盘有不同的方式进入这个特殊模式。如果您的PCB当前运行QMK、TMK或PS2AVRGB (Bootmapper客户端)，并且没有得到具体的指令，请尝试以下操作:
·按住shift键和Pause键
·同时按下shift键和B键
·拔下你的键盘，同时按住空格键和B键，并插上你的键盘，然后在释放这两个键之前等待一秒钟
·拔掉键盘插头，按住左上键或左下键(通常是Escape或left Control键)，然后插入键盘
·按下物理复位按钮，通常位于PCB的底面
·在PCB上定位标为RESET和GND的针脚，并将它们短接在一起
如果你已经尝试了所有的上面都没有效果，主板上的主芯片属于STM32系列，这可能有点复杂。一般来说，你最好的办法是寻求会使用的人的帮助。很可能一些键盘的照片需要被提供——如果你能事先准备好它们，这将有助于快速推动进程!
否则，你应该看到一个黄色的消息，类似于QMK工具箱里面的形式:
*** DFU device connected: Atmel Corp. ATmega32U4 (03EB:2FF4:0000)
这个引导装载器设备也会出现在设备管理器，系统信息，应用程序或lsusb（Linux）中
用QMK工具箱刷写你的键盘固件
最简单的刷 键盘的方法是使用QMK工具箱。
然而，该工具箱目前仅适用于Windows和macOS。如果您正在使用Linux(或者只是希望从命令行刷新固件)，请从命令行部分刷写您的键盘。
将文件加载到QMK工具箱中
首先打开QMK工具箱应用程序。您将希望在Finder或Explorer中找到固件文件。你的键盘固件可能有两种格式.hex或.bin。QMK尝试将键盘所需的相应文件复制到根目录qmk_firmware中。
如果您使用的是Windows或macOS，您可以使用一些命令来轻松地在Explorer或Finder中打开当前文件夹。
Windows：
start
MacOS:
open
固件将遵循以下命名格式：
<keyboard_name>_<keymap_name>.{bin,hex}
例如，拥有default键值的planck/rev5会有这个文件名:
planck_rev5_default.hex
一旦你找到你的固件文件,拖动它到QMK工具箱的“本地文件”框，或点击“打开”并选择你的固件文件存储的位置。
刷写你的固件
单击QMK工具箱中的Flash按钮。您将看到类似如下的输出语句:
*** DFU device connected: Atmel Corp. ATmega32U4 (03EB:2FF4:0000)
*** Attempting to flash, please don’t remove device
>>> dfu-programmer.exe atmega32u4 erase –force
Erasing flash… Success
Checking memory from 0x0 to 0x6FFF… Empty.
>>> dfu-programmer.exe atmega32u4 flash “D:\Git\qmk_firmware\gh60_satan_default.hex”
Checking memory from 0x0 to 0x3F7F… Empty.
0% 100% Programming 0x3F80 bytes…
[>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success
0% 100% Reading 0x7000 bytes…
[>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success
Validating… Success
0x3F80 bytes written into 0x7000 bytes memory (56.70%).
>>> dfu-programmer.exe atmega32u4 reset
*** DFU device disconnected: Atmel Corp: ATmega32U4 (03EB:2FF4:0000)
从命令行刷写你的键盘
与过去相比，这已经变得相当简单了。当你准备编译和刷写你的固件，打开你的终端窗口，运行刷写命令::
qmk flash
您还没有如果在CLI中配置键盘/键映射名称，或者您有多个键盘，您可以指定键盘和键映射:
qmk flash -kb <my_keyboard> -km <my_keymap>
这将检查键盘的配置，然后尝试基于指定的引导加载程序来刷写它。这意味着您不需要知道您的键盘使用的是哪个引导加载程序。只需运行该命令，并让命令来完成繁重的工作。
但是，这取决于于由键盘设置的引导加载程序。如果这个信息没有配置，或者你使用的pcb没有一个支持刷写的目标，你会看到这个错误:
WARNING: This board's bootloader is not specified or is not supported by the ":flash" target at this time.
测试一下!
恭喜!您的自定义固件已被编程到您的键盘!
试一试，确保一切都按照你想要的方式运行。我们已经编写了测试和调试程序来完善这个指南，所以去那里学习如何确认固件和排除自定义功能的故障。
测试和调试
一旦你用自定义固件刷写好你的键盘，你就可以测试了。如果运气好的话，一次就能成功，但如果不是，本文档将帮助您找出问题所在。
测试
测试你的键盘通常很简单。按下每一个键，并确保它发送您期望的键值。您可以使用QMK配置器的测试模式来检查您的键盘，即使它没有运行QMK固件。
调试
如果您的rules.mk中有CONSOLE_ENABLE = yes，那么您的键盘将输出调试信息。默认情况下，输出的内容非常有限，但是您可以打开调试模式来增加调试输出的数量。在键映射中使用调试键码，使用命令功能启用调试模式，或将以下代码添加到键映射中。
void keyboard_post_init_user(void) {
// Customise these values to desired behaviour
debug_enable=true;
debug_matrix=true;
//debug_keyboard=true;
//debug_mouse=true;
}
调试工具
有两种不同的工具可以用来调试键盘。
使用QMK工具箱进行调试
对于兼容的平台，QMK Toolbox可以用于显示来自键盘的调试消息。
用hid_listen调试
发送自己的调试消息
有时候，从自定义代码中打印调试消息是非常有用的。这样做非常简单，只需让文件的顶部包含print.h：
#include <print.h>
在这之后你可以用很多种不同的打印功能：
print(“string”)：打印一个简单的字符串。
uprintf(“%s string”, var)：打印格式化字符串
dprint(“string”)：输出一个简单的字符串，但只在启用调试模式下使用
dprintf(“%s string”, var)：只在启用调试模式时输出格式化字符串
调试案例
这个按键在矩阵的哪个位置?
在移植信息，或者在尝试诊断pcb问题时，了解一个按键被按压时扫描是否正确是很有用的。你需要启用日志记录，请将以下代码添加到你的键值映射中（keymap.c）：
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
// If console is enabled, it will print the matrix position and status of each key pressed
#ifdef CONSOLE_ENABLE
uprintf(“KL: kc: %u, col: %u, row: %u, pressed: %u\n”, keycode, record->event.key.col, record->event.key.row, record->event.pressed);
#endif
return true;
}
输出案例：
Waiting for device:…….
Listening:
KL: kc: 169, col: 0, row: 0, pressed: 1
KL: kc: 169, col: 0, row: 0, pressed: 0
KL: kc: 174, col: 1, row: 0, pressed: 1
KL: kc: 174, col: 1, row: 0, pressed: 0
KL: kc: 172, col: 2, row: 0, pressed: 1
KL: kc: 172, col: 2, row: 0, pressed: 0
扫描一个按键需要多长时间?
在测试性能表现的问题时，了解扫描开关矩阵的频率是很有用的。要在这个场景中启用日志记录，请将以下代码添加到键值映射的 config.h中：
#define DEBUG_MATRIX_SCAN_RATE
输出示例：
> matrix scan frequency: 315
> matrix scan frequency: 313
> matrix scan frequency: 316
> matrix scan frequency: 316
> matrix scan frequency: 316
> matrix scan frequency: 316
寻求帮助
有很多资源可以帮助你学习QMK。
实时聊天
如果你在某些方面需要帮助，得到快速支持的最好地方就是我们的服务器。平时都会有人在哪里为你排异解惑。
OLKB Subreddit
GitHub的问题
你可以在GitHub上直接打开问题。这点在您的问题需要长期讨论或调试时尤其方便。
学习资源
这些资源旨在让QMK社区的新成员对文档中提供的信息有更深层的理解。
QMK资源
命令行资源:
Git资源:
……