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 built
rules.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.

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 keymap
keymap.c: all of your keymap code, required
Makefile: the features of QMK that are enabled, required to run make in your keymap folder
readme.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 be ez or infinity, and for Planck rev3 or rev4.
- If the keyboard doesn't have a subproject, or if you are happy with the default (defined in 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.
- 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.

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.

4.2 KiB Raw Blame History