QMK is nearly infinitely configurable. Wherever possible we err on the side of allowing users to customize their keyboard, even at the expense of code size. That level of flexibility makes for a daunting configuration experience, however.
There are two main types of configuration files in QMK- `config.h` and `rules.mk`. These files exist at various levels in QMK and all files of the same type are combined to build the final configuration. The levels, from lowest priority to highest priority, are:
* QMK Default
* Keyboard
* Folders (Up to 5 levels deep)
* Keymap
## QMK Default
Every available setting in QMK has a default. If that setting is not set at the Keyboard, Folder, or Keymap level this is the setting that will be used.
## Keyboard
This level contains config options that should apply to the whole keyboard. Some settings won't change in revisions, or most keymaps. Other settings are merely defaults for this keyboard and can be overridden by folders and/or keymaps.
## Folders
Some keyboards have folders and sub-folders to allow for different hardware configurations. Most keyboards only go 1 folder deep, but QMK supports structures up to 5 folders deep. Each folder can have its own `config.h` and `rules.mk` files that are incorporated into the final configuration.
## Keymap
This level contains all of the options for that particular keymap. If you wish to override a previous declaration, you can use `#undef <variable>` to undefine it, where you can then redefine it without an error.
# The `config.h` File
This is a C header file that is one of the first things included, and will persist over the whole project (if included). Lots of variables can be set here and accessed elsewhere. The `config.h` file shouldn't be including other `config.h` files, or anything besides this:
* may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information.
* may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information.
* COL2ROW or ROW2COL - how your matrix is configured. COL2ROW means the black mark on your diode is facing to the rows, and between the switch and the rows.
* sets the I2C clock rate speed for keyboards using I2C. The default is `400000L`, except for keyboards using `split_common`, where the default is `100000L`.
## Features That Can Be Disabled
If you define these options you will disable the associated feature, which can save on code size.
*`#define NO_DEBUG`
* disable debugging
*`#define NO_PRINT`
* disable printing/debugging using hid_listen
*`#define NO_ACTION_LAYER`
* disable layers
*`#define NO_ACTION_TAPPING`
* disable tap dance and other tapping features
*`#define NO_ACTION_ONESHOT`
* disable one-shot modifiers
## Features That Can Be Enabled
If you define these options you will enable the associated feature, which may increase your code size.
* NKRO by default requires to be turned on, this forces it on during keyboard startup regardless of EEPROM setting. NKRO can still be turned off but will be turned on again if the keyboard reboots.
*`#define STRICT_LAYER_RELEASE`
* force a key release to be evaluated using the current layer stack instead of remembering which layer it came from (used for advanced cases)
## Behaviors That Can Be Configured
*`#define TAPPING_TERM 200`
* how long before a tap becomes a hold, if set above 500, a key tapped during the tapping term will turn it into a hold too
*`#define TAPPING_TERM_PER_KEY`
* enables handling for per key `TAPPING_TERM` settings
*`#define RETRO_TAPPING`
* tap anyway, even after TAPPING_TERM, if there was no other key interruption between press and release
* See [Retro Tapping](tap_hold.md#retro-tapping) for details
* makes tap and hold keys trigger the hold if another key is pressed before releasing, even if it hasn't hit the `TAPPING_TERM`
* See [Permissive Hold](tap_hold.md#permissive-hold) for details
*`#define PERMISSIVE_HOLD_PER_KEY`
* enabled handling for per key `PERMISSIVE_HOLD` settings
*`#define IGNORE_MOD_TAP_INTERRUPT`
* makes it possible to do rolling combos (zx) with keys that convert to other keys on hold, by enforcing the `TAPPING_TERM` for both keys.
* See [Ignore Mod Tap Interrupt](tap_hold.md#ignore-mod-tap-interrupt) for details
*`#define IGNORE_MOD_TAP_INTERRUPT_PER_KEY`
* enables handling for per key `IGNORE_MOD_TAP_INTERRUPT` settings
*`#define TAPPING_FORCE_HOLD`
* makes it possible to use a dual role key as modifier shortly after having been tapped
* See [Tapping Force Hold](tap_hold.md#tapping-force-hold)
* Breaks any Tap Toggle functionality (`TT` or the One Shot Tap Toggle)
*`#define TAPPING_FORCE_HOLD_PER_KEY`
* enables handling for per key `TAPPING_FORCE_HOLD` settings
*`#define LEADER_TIMEOUT 300`
* how long before the leader key times out
* If you're having issues finishing the sequence before it times out, you may need to increase the timeout setting. Or you may want to enable the `LEADER_PER_KEY_TIMING` option, which resets the timeout after each key is tapped.
*`#define LEADER_PER_KEY_TIMING`
* sets the timer for leader key chords to run on each key press rather than overall
*`#define LEADER_KEY_STRICT_KEY_PROCESSING`
* Disables keycode filtering for Mod-Tap and Layer-Tap keycodes. Eg, if you enable this, you would need to specify `MT(MOD_CTL, KC_A)` if you want to use `KC_A`.
*`#define ONESHOT_TIMEOUT 300`
* how long before oneshot times out
*`#define ONESHOT_TAP_TOGGLE 2`
* how many taps before oneshot toggle is triggered
*`#define QMK_KEYS_PER_SCAN 4`
* Allows sending more than one key per scan. By default, only one key event gets
sent via `process_record()` per scan. This has little impact on most typing, but
if you're doing a lot of chords, or your scan rate is slow to begin with, you can
have some delay in processing key events. Each press and release is a separate
event. For a keyboard with 1ms or so scan times, even a very fast typist isn't
going to produce the 500 keystrokes a second needed to actually get more than a
few ms of delay from this. But if you're doing chording on something with 3-4ms
* Set this to the number of combos that you're using in the [Combo](feature_combo.md) feature. Or leave it undefined and programmatically set the count.
* Sets the delay between `register_code` and `unregister_code`, if you're having issues with it registering properly (common on VUSB boards). The value is in milliseconds.
* Sets the delay for Tap Hold keys (`LT`, `MT`) when using `KC_CAPS_LOCK` keycode, as this has some special handling on MacOS. The value is in milliseconds, and defaults to 80 ms if not defined. For macOS, you may want to set this to 200 or higher.
* Lets you define [lighting layers](feature_rgblight.md?id=lighting-layers) that can be toggled on or off. Great for showing the current keyboard layer or caps lock state.
*`#define RGBLIGHT_MAX_LAYERS`
* Defaults to 8. Can be expanded up to 32 if more [lighting layers](feature_rgblight.md?id=lighting-layers) are needed.
* Note: Increasing the maximum will increase the firmware size and slow sync on split keyboards.
*`#define RGBLIGHT_LAYER_BLINK`
* Adds ability to [blink](feature_rgblight.md?id=lighting-layer-blink) a lighting layer for a specified number of milliseconds (e.g. to acknowledge an action).
*`#define RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF`
* If defined, then [lighting layers](feature_rgblight?id=overriding-rgb-lighting-onoff-status) will be shown even if RGB Light is off.
*`#define RGBLED_NUM 12`
* number of LEDs
*`#define RGBLIGHT_SPLIT`
* Needed if both halves of the board have RGB LEDs wired directly to the RGB output pin on the controllers instead of passing the output of the left half to the input of the right half
*`#define RGBLED_SPLIT { 6, 6 }`
* number of LEDs connected that are directly wired to `RGB_DI_PIN` on each half of a split keyboard
* First value indicates number of LEDs for left half, second value is for the right half
* When RGBLED_SPLIT is defined, RGBLIGHT_SPLIT is implicitly defined.
*`#define RGBLIGHT_HUE_STEP 12`
* units to step when in/decreasing hue
*`#define RGBLIGHT_SAT_STEP 25`
* units to step when in/decreasing saturation
*`#define RGBLIGHT_VAL_STEP 12`
* units to step when in/decreasing value (brightness)
*`#define RGBW`
* Enables RGBW LED support
## Mouse Key Options
*`#define MOUSEKEY_INTERVAL 20`
*`#define MOUSEKEY_DELAY 0`
*`#define MOUSEKEY_TIME_TO_MAX 60`
*`#define MOUSEKEY_MAX_SPEED 7`
*`#define MOUSEKEY_WHEEL_DELAY 0`
## Split Keyboard Options
Split Keyboard specific options, make sure you have 'SPLIT_KEYBOARD = yes' in your rules.mk
*`SPLIT_TRANSPORT = custom`
* Allows replacing the standard split communication routines with a custom one. ARM based split keyboards must use this at present.
### Setting Handedness
One thing to remember, the side that the USB port is plugged into is always the master half. The side not plugged into USB is the slave.
There are a few different ways to set handedness for split keyboards (listed in order of precedence):
1. Set `SPLIT_HAND_PIN`: Reads a pin to determine handedness. If pin is high, it's the left side, if low, the half is determined to be the right side
2. Set `EE_HANDS` and flash `eeprom-lefthand.eep`/`eeprom-righthand.eep` to each half
* For boards with DFU bootloader you can use `:dfu-split-left`/`:dfu-split-right` to flash these EEPROM files
* For boards with Caterina bootloader (like stock Pro Micros), use `:avrdude-split-left`/`:avrdude-split-right`
* For boards with ARM DFU bootloader (like Proton C), use `:dfu-util-split-left`/`:dfu-util-split-right`
3. Set `MASTER_RIGHT`: Half that is plugged into the USB port is determined to be the master and right half (inverse of the default)
4. Default: The side that is plugged into the USB port is the master half and is assumed to be the left half. The slave side is the right half
#### Defines for handedness
*`#define SPLIT_HAND_PIN B7`
* For using high/low pin to determine handedness, low = right hand, high = left hand. Replace `B7` with the pin you are using. This is optional, and if you leave `SPLIT_HAND_PIN` undefined, then you can still use the EE_HANDS method or MASTER_LEFT / MASTER_RIGHT defines like the stock Let's Split uses.
* The handedness is determined by using the intersection of the keyswitches in the key matrix, which does not exist. Normally, when this intersection is shorted (level low), it is considered left. If you define `#define SPLIT_HAND_MATRIX_GRID_LOW_IS_RIGHT`, it is determined to be right when the level is low.
*`#define EE_HANDS` (only works if `SPLIT_HAND_PIN` and `SPLIT_HAND_MATRIX_GRID` are not defined)
* Reads the handedness value stored in the EEPROM after `eeprom-lefthand.eep`/`eeprom-righthand.eep` has been flashed to their respective halves.
* When using serial, define this. `D0` or `D1`,`D2`,`D3`,`E6`.
*`#define MATRIX_ROW_PINS_RIGHT { <row pins> }`
*`#define MATRIX_COL_PINS_RIGHT { <col pins> }`
* If you want to specify a different pinout for the right half than the left half, you can define `MATRIX_ROW_PINS_RIGHT`/`MATRIX_COL_PINS_RIGHT`. Currently, the size of `MATRIX_ROW_PINS` must be the same as `MATRIX_ROW_PINS_RIGHT` and likewise for the definition of columns.
* may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information.
* If you want to specify a different direct pinout for the right half than the left half, you can define `DIRECT_PINS_RIGHT`. Currently, the size of `DIRECT_PINS` must be the same as `DIRECT_PINS_RIGHT`.
*`#define RGBLED_SPLIT { 6, 6 }`
* See [RGB Light Configuration](#rgb-light-configuration)
*`#define SELECT_SOFT_SERIAL_SPEED <speed>` (default speed is 1)
* Sets the protocol speed when using serial communication
* Speeds:
* 0: about 189kbps (Experimental only)
* 1: about 137kbps (default)
* 2: about 75kbps
* 3: about 39kbps
* 4: about 26kbps
* 5: about 20kbps
*`#define SPLIT_USB_DETECT`
* Detect (with timeout) USB connection when delegating master/slave
* Deadline for synchronizing data from master to slave when using the QMK-provided split transport.
*`#define SPLIT_TRANSPORT_MIRROR`
* Mirrors the master-side matrix on the slave when using the QMK-provided split transport.
*`#define SPLIT_LAYER_STATE_ENABLE`
* Ensures the current layer state is available on the slave when using the QMK-provided split transport.
*`#define SPLIT_LED_STATE_ENABLE`
* Ensures the current host indicator state (caps/num/scroll) is available on the slave when using the QMK-provided split transport.
*`#define SPLIT_MODS_ENABLE`
* Ensures the current modifier state (normal, weak, and oneshot) is available on the slave when using the QMK-provided split transport.
*`#define SPLIT_WPM_ENABLE`
* Ensures the current WPM is available on the slave when using the QMK-provided split transport.
*`#define SPLIT_OLED_ENABLE`
* Syncs the on/off state of the OLED between the halves.
*`#define SPLIT_ST7565_ENABLE`
* Syncs the on/off state of the ST7565 screen between the halves.
*`#define SPLIT_TRANSACTION_IDS_KB .....`
*`#define SPLIT_TRANSACTION_IDS_USER .....`
* Allows for custom data sync with the slave when using the QMK-provided split transport. See [custom data sync between sides](feature_split_keyboard.md#custom-data-sync) for more information.
This is a [make](https://www.gnu.org/software/make/manual/make.html) file that is included by the top-level `Makefile`. It is used to set some information about the MCU that we will be compiling for as well as enabling and disabling certain features.
## Build Options
*`DEFAULT_FOLDER`
* Used to specify a default folder when a keyboard has more than one sub-folder.
*`FIRMWARE_FORMAT`
* Defines which format (bin, hex) is copied to the root `qmk_firmware` folder after building.
*`SRC`
* Used to add files to the compilation/linking list.
*`LIB_SRC`
* Used to add files as a library to the compilation/linking list.
The files specified by `LIB_SRC` is linked after the files specified by `SRC`.
For example, if you specify:
```
SRC += a.c
LIB_SRC += lib_b.c
SRC += c.c
LIB_SRC += lib_d.c
```
The link order is as follows.
```
... a.o c.o ... lib_b.a lib_d.a ...
```
*`LAYOUTS`
* A list of [layouts](feature_layouts.md) this keyboard supports.
*`LTO_ENABLE`
* Enables Link Time Optimization (LTO) when compiling the keyboard. This makes the process take longer, but it can significantly reduce the compiled size (and since the firmware is small, the added time is not noticeable).
## AVR MCU Options
*`MCU = atmega32u4`
*`F_CPU = 16000000`
*`ARCH = AVR8`
*`F_USB = $(F_CPU)`
*`OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT`
*`BOOTLOADER = atmel-dfu` with the following options:
Use these to enable or disable building certain features. The more you have enabled the bigger your firmware will be, and you run the risk of building a firmware too large for your MCU.
* Enables split keyboard support (dual MCU like the let's split and bakingpy's boards) and includes all necessary files located at quantum/split_common
*`CUSTOM_MATRIX`
* Allows replacing the standard matrix scanning routine with a custom one.
*`DEBOUNCE_TYPE`
* Allows replacing the standard key debouncing routine with an alternative or custom one.
*`WAIT_FOR_USB`
* Forces the keyboard to wait for a USB connection to be established before it starts up
*`NO_USB_STARTUP_CHECK`
* Disables usb suspend check after keyboard startup. Usually the keyboard waits for the host to wake it up before any tasks are performed. This is useful for split keyboards as one half will not get a wakeup call but must send commands to the master.
* Enables deferred executor support -- timed delays before callbacks are invoked. See [deferred execution](custom_quantum_functions.md#deferred-execution) for more information.
*`DYNAMIC_TAPPING_TERM_ENABLE`
* Allows to configure the global tapping term on the fly.
