4.3 KiB
QMK Overview
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.
Basic QMK structure
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.
Keyboard project structure
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 specificMakefile
.config.h
: The file that sets the default compile time options. Do not edit this file directly, instead use a keymap specificconfig.h
.
Keymap structure
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 runmake
in your keymap folderreadme.md
: a description of your keymap, how others might use it, and explanations of features- Other files: Some people choose to include an image depicting the layout, and other files that help people to use or understand a particular keymap.
The make
command
The 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.
Simple instructions for building and uploading a keyboard
Most keyboards have more specific instructions in the keyboard specific readme.md file, so please check that first
- Enter the
root
folder - Run
make <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 beez
orinfinity
, and for Planckrev3
orrev4
.- If the keyboard doesn't have a subproject, or if you are happy with the default (defined in
rules.mk
file of thekeyboard
folder), you can leave it out. But remember to also remove the dash (-
) from the command.
- If the keyboard doesn't have a subproject, or if you are happy with the default (defined in
<programmer>
The programmer to use. Most keyboards usedfu
, but some useteensy
. Infinity keyboards usedfu-util
. Check the readme file in the keyboard folder to find out which programmer to use.- If you don't add
-<programmer
to the command line, the firmware will be still be compiled into a hex file, but the upload will be skipped.
- If you don't add
NOTE: Some operating systems will refuse to program unless you run the make command as root for example sudo make clueboard-default-dfu
Make Examples
- Build all Clueboard keymaps:
make clueboard
- Build the default Planck keymap:
make planck-rev4-default
- Build and flash your ergodox-ez:
make ergodox-ez-default-teensy
The config.h
file
There are 2 config.h
locations:
- keyboard (
/keyboards/<keyboard>/
) - keymap (
/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.