This page attempts to explain the basic information you need to know to work with the QMK project. It assumes that you are familiar with navigating a UNIX shell, but does not assume you are familiar with C or with compiling using make.
QMK is a fork of @tmk's tmk_keyboard project. The original TMK code, with modifications, can be found in the tmk
folder. The QMK additions to the project may be found in the quantum
folder. Keyboard projects may be found in the handwired
and keyboard
folders.
Within the handwired
and keyboard
folders is a directory for each keyboard project, for example qmk_firmware/keyboards/clueboard
. Within you'll find the following structure:
keymaps/
: Different keymaps that can be builtrules.mk
: The file that sets the default "make" options. Do not edit this file directly, instead use a keymap specific Makefile
.config.h
: The file that sets the default compile time options. Do not edit this file directly, instead use a keymap specific config.h
.In every keymap folder, the following files may be found. Only keymap.c
is required, if the rest of the files are not found the default options will be chosen.
config.h
: the options to configure your keymapkeymap.c
: all of your keymap code, requiredMakefile
: the features of QMK that are enabled, required to run make
in your keymap folderreadme.md
: a description of your keymap, how others might use it, and explanations of featuresmake
commandThe make
command is how you compile the firmware into a .hex file, which can be loaded by a dfu programmer (like dfu-progammer via make dfu
) or the Teensy loader (only used with Teensys). It it recommended that you always run make from within the root
folder.
NOTE: To abort a make command press Ctrl-c
For more details on the QMK build process see Make Instructions.
Most keyboards have more specific instructions in the keyboard specific readme.md file, so please check that first
root
foldermake <keyboard>-<subproject>-<keymap>-<programmer>
In the above commands, replace:
<keyboard>
with the name of your keyboard<keymap>
with the name of your keymap<subproject>
with the name of the subproject (revision or sub-model of your keyboard). For example, for Ergodox it can be ez
or infinity
, and for Planck rev3
or rev4
.
rules.mk
file of the keyboard
folder), you can leave it out. But remember to also remove the dash (-
) from the command.<programmer>
The programmer to use. Most keyboards use dfu
, but some use teensy
. Infinity keyboards use dfu-util
. Check the readme file in the keyboard folder to find out which programmer to use.
-<programmer
to the command line, the firmware will be still be compiled into a hex file, but the upload will be skipped.NOTE: Some operating systems will refuse to program unless you run the make command as root for example sudo make clueboard-default-dfu
make clueboard
make planck-rev4-default
make ergodox-ez-default-teensy
config.h
fileThere are 2 config.h
locations:
/keyboards/<keyboard>/
)/keyboards/<keyboard>/keymaps/<keymap>/
)The keyboard config.h
is included only if the keymap one doesn't exist. The format to use for your custom one is here. If you want to override a setting from the parent config.h
file, you need to do this:
#undef MY_SETTING
#define MY_SETTING 4
For a value of 4
for this imaginary setting. So we undef
it first, then define
it.
You can then override any settings, rather than having to copy and paste the whole thing.