config_options.md (24554B)
1 # Configuring QMK 2 3 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. 4 5 There are three main types of configuration files in QMK: 6 7 * `config.h`, which contains various preprocessor directives (`#define`, `#ifdef`) 8 * `rules.mk`, which contains additional variables 9 * `info.json`, which is utilized for [data-driven configuration](data_driven_config) 10 11 This page will only discuss the first two types, `config.h` and `rules.mk`. 12 13 ::: tip 14 While not all settings have data-driven equivalents yet, keyboard makers are encouraged to utilize the `info.json` file to set the metadata for their boards when possible. See the [`info.json` Format](reference_info_json) page for more details. 15 ::: 16 17 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: 18 19 * QMK Default 20 * Keyboard 21 * Folders (Up to 5 levels deep) 22 * Keymap 23 24 ## QMK Default 25 26 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. 27 28 ## Keyboard 29 30 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. 31 32 ## Folders 33 34 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. 35 36 ## Keymap 37 38 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. 39 40 # The `config.h` File 41 42 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. 43 44 ## Hardware Options 45 * `#define VENDOR_ID 0x1234` 46 * defines your VID, and for most DIY projects, can be whatever you want 47 * `#define PRODUCT_ID 0x5678` 48 * defines your PID, and for most DIY projects, can be whatever you want 49 * `#define DEVICE_VER 0x0100` 50 * defines the device version (often used for revisions) 51 * `#define MANUFACTURER "Me"` 52 * generally who/whatever brand produced the board 53 * `#define PRODUCT "Board"` 54 * the name of the keyboard 55 * `#define MATRIX_ROWS 5` 56 * the number of rows in your keyboard's matrix 57 * `#define MATRIX_COLS 15` 58 * the number of columns in your keyboard's matrix 59 * `#define MATRIX_ROW_PINS { D0, D5, B5, B6 }` 60 * pins of the rows, from top to bottom 61 * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions#low-level-matrix-overrides) for more information. 62 * `#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 }` 63 * pins of the columns, from left to right 64 * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions#low-level-matrix-overrides) for more information. 65 * `#define MATRIX_IO_DELAY 30` 66 * the delay in microseconds when between changing matrix pin state and reading values 67 * `#define MATRIX_HAS_GHOST` 68 * define is matrix has ghost (unlikely) 69 * `#define MATRIX_UNSELECT_DRIVE_HIGH` 70 * On un-select of matrix pins, rather than setting pins to input-high, sets them to output-high. 71 * `#define DIODE_DIRECTION COL2ROW` 72 * 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. 73 * `#define DIRECT_PINS { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }` 74 * pins mapped to rows and columns, from left to right. Defines a matrix where each switch is connected to a separate pin and ground. 75 * `#define AUDIO_VOICES` 76 * turns on the alternate audio voices (to cycle through) 77 * `#define C4_AUDIO` 78 * enables audio on pin C4 79 * Deprecated. Use `#define AUDIO_PIN C4` 80 * `#define C5_AUDIO` 81 * enables audio on pin C5 82 * Deprecated. Use `#define AUDIO_PIN C5` 83 * `#define C6_AUDIO` 84 * enables audio on pin C6 85 * Deprecated. Use `#define AUDIO_PIN C6` 86 * `#define B5_AUDIO` 87 * enables audio on pin B5 (duophony is enabled if one of B pins is enabled along with one of C pins) 88 * Deprecated. Use `#define AUDIO_PIN B5`, or use `#define AUDIO_PIN_ALT B5` if a `C` pin is enabled with `AUDIO_PIN` 89 * `#define B6_AUDIO` 90 * enables audio on pin B6 (duophony is enabled if one of B pins is enabled along with one of C pins) 91 * Deprecated. Use `#define AUDIO_PIN B6`, or use `#define AUDIO_PIN_ALT B6` if a `C` pin is enabled with `AUDIO_PIN` 92 * `#define B7_AUDIO` 93 * enables audio on pin B7 (duophony is enabled if one of B pins is enabled along with one of C pins) 94 * Deprecated. Use `#define AUDIO_PIN B7`, or use `#define AUDIO_PIN_ALT B7` if a `C` pin is enabled with `AUDIO_PIN` 95 * `#define BACKLIGHT_PIN B7` 96 * pin of the backlight 97 * `#define BACKLIGHT_LEVELS 3` 98 * number of levels your backlight will have (maximum 31 excluding off) 99 * `#define BACKLIGHT_BREATHING` 100 * enables backlight breathing 101 * `#define BREATHING_PERIOD 6` 102 * the length of one backlight "breath" in seconds 103 * `#define DEBOUNCE 5` 104 * the delay when reading the value of the pin (5 is default) 105 * `#define LOCKING_SUPPORT_ENABLE` 106 * mechanical locking support. Use KC_LCAP, KC_LNUM or KC_LSCR instead in keymap 107 * `#define LOCKING_RESYNC_ENABLE` 108 * tries to keep switch state consistent with keyboard LED state 109 * `#define IS_COMMAND() (get_mods() == MOD_MASK_SHIFT)` 110 * key combination that allows the use of magic commands (useful for debugging) 111 * `#define USB_MAX_POWER_CONSUMPTION 500` 112 * sets the maximum power (in mA) over USB for the device (default: 500) 113 * `#define USB_POLLING_INTERVAL_MS 10` 114 * sets the USB polling rate in milliseconds for the keyboard, mouse, and shared (NKRO/media keys) interfaces 115 * `#define USB_SUSPEND_WAKEUP_DELAY 0` 116 * sets the number of milliseconds to pause after sending a wakeup packet. 117 Disabled by default, you might want to set this to 200 (or higher) if the 118 keyboard does not wake up properly after suspending. 119 * `#define F_SCL 100000L` 120 * 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`. 121 122 ## Features That Can Be Disabled 123 124 If you define these options you will disable the associated feature, which can save on code size. 125 126 * `#define NO_DEBUG` 127 * disable debugging 128 * `#define NO_PRINT` 129 * disable printing/debugging using hid_listen 130 * `#define NO_ACTION_LAYER` 131 * disable layers 132 * `#define NO_ACTION_TAPPING` 133 * disable tap dance and other tapping features 134 * `#define NO_ACTION_ONESHOT` 135 * disable one-shot modifiers 136 137 ## Features That Can Be Enabled 138 139 If you define these options you will enable the associated feature, which may increase your code size. 140 141 * `#define ENABLE_COMPILE_KEYCODE` 142 * Enables the `QK_MAKE` keycode 143 * `#define STRICT_LAYER_RELEASE` 144 * force a key release to be evaluated using the current layer stack instead of remembering which layer it came from (used for advanced cases) 145 146 ## Behaviors That Can Be Configured 147 148 * `#define TAPPING_TERM 200` 149 * how long before a key press becomes a hold 150 * `#define TAPPING_TERM_PER_KEY` 151 * enables handling for per key `TAPPING_TERM` settings 152 * `#define RETRO_TAPPING` 153 * tap anyway, even after `TAPPING_TERM`, if there was no other key interruption between press and release 154 * See [Retro Tapping](tap_hold#retro-tapping) for details 155 * `#define RETRO_TAPPING_PER_KEY` 156 * enables handling for per key `RETRO_TAPPING` settings 157 * `#define TAPPING_TOGGLE 2` 158 * how many taps before triggering the toggle 159 * `#define PERMISSIVE_HOLD` 160 * makes tap and hold keys trigger the hold if another key is pressed before releasing, even if it hasn't hit the `TAPPING_TERM` 161 * See [Permissive Hold](tap_hold#permissive-hold) for details 162 * `#define PERMISSIVE_HOLD_PER_KEY` 163 * enabled handling for per key `PERMISSIVE_HOLD` settings 164 * `#define QUICK_TAP_TERM 100` 165 * tap-then-hold timing to use a dual role key to repeat keycode 166 * See [Quick Tap Term](tap_hold#quick-tap-term) 167 * Changes the timing of Tap Toggle functionality (`TT` or the One Shot Tap Toggle) 168 * Defaults to `TAPPING_TERM` if not defined 169 * `#define QUICK_TAP_TERM_PER_KEY` 170 * enables handling for per key `QUICK_TAP_TERM` settings 171 * `#define HOLD_ON_OTHER_KEY_PRESS` 172 * selects the hold action of a dual-role key as soon as the tap of the dual-role key is interrupted by the press of another key. 173 * See "[hold on other key press](tap_hold#hold-on-other-key-press)" for details 174 * `#define HOLD_ON_OTHER_KEY_PRESS_PER_KEY` 175 * enables handling for per key `HOLD_ON_OTHER_KEY_PRESS` settings 176 * `#define LEADER_TIMEOUT 300` 177 * how long before the leader key times out 178 * 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. 179 * `#define LEADER_PER_KEY_TIMING` 180 * sets the timer for leader key chords to run on each key press rather than overall 181 * `#define LEADER_KEY_STRICT_KEY_PROCESSING` 182 * 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`. 183 * `#define MOUSE_EXTENDED_REPORT` 184 * Enables support for extended reports (-32767 to 32767, instead of -127 to 127), which may allow for smoother reporting, and prevent maxing out of the reports. Applies to both Pointing Device and Mousekeys. 185 * `#define ONESHOT_TIMEOUT 300` 186 * how long before oneshot times out 187 * `#define ONESHOT_TAP_TOGGLE 2` 188 * how many taps before oneshot toggle is triggered 189 * `#define COMBO_TERM 200` 190 * how long for the Combo keys to be detected. Defaults to `TAPPING_TERM` if not defined. 191 * `#define COMBO_MUST_HOLD_MODS` 192 * Flag for enabling extending timeout on Combos containing modifiers 193 * `#define COMBO_MOD_TERM 200` 194 * Allows for extending COMBO_TERM for mod keys while mid-combo. 195 * `#define COMBO_MUST_HOLD_PER_COMBO` 196 * Flag to enable per-combo COMBO_TERM extension and `get_combo_must_hold()` function 197 * `#define COMBO_TERM_PER_COMBO` 198 * Flag to enable per-combo COMBO_TERM extension and `get_combo_term()` function 199 * `#define COMBO_STRICT_TIMER` 200 * Only start the combo timer on the first key press instead of on all key presses. 201 * `#define COMBO_NO_TIMER` 202 * Disable the combo timer completely for relaxed combos. 203 * `#define TAP_CODE_DELAY 100` 204 * 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 and defaults to `0`. 205 * `#define TAP_HOLD_CAPS_DELAY 80` 206 * 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. 207 * `#define KEY_OVERRIDE_REPEAT_DELAY 500` 208 * Sets the key repeat interval for [key overrides](features/key_overrides). 209 * `#define LEGACY_MAGIC_HANDLING` 210 * Enables magic configuration handling for advanced keycodes (such as Mod Tap and Layer Tap) 211 212 213 ## RGB Light Configuration 214 215 * `#define WS2812_DI_PIN D7` 216 * pin the DI on the WS2812 is hooked-up to 217 * `#define RGBLIGHT_LAYERS` 218 * Lets you define [lighting layers](features/rgblight#lighting-layers) that can be toggled on or off. Great for showing the current keyboard layer or caps lock state. 219 * `#define RGBLIGHT_MAX_LAYERS` 220 * Defaults to 8. Can be expanded up to 32 if more [lighting layers](features/rgblight#lighting-layers) are needed. 221 * Note: Increasing the maximum will increase the firmware size and slow sync on split keyboards. 222 * `#define RGBLIGHT_LAYER_BLINK` 223 * Adds ability to [blink](features/rgblight#lighting-layer-blink) a lighting layer for a specified number of milliseconds (e.g. to acknowledge an action). 224 * `#define RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF` 225 * If defined, then [lighting layers](features/rgblight#overriding-rgb-lighting-onoff-status) will be shown even if RGB Light is off. 226 * `#define RGBLIGHT_LED_COUNT 12` 227 * number of LEDs 228 * `#define RGBLIGHT_SPLIT` 229 * 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 230 * `#define RGBLED_SPLIT { 6, 6 }` 231 * number of LEDs connected that are directly wired to the RGB pin on each half of a split keyboard 232 * First value indicates number of LEDs for left half, second value is for the right half 233 * When RGBLED_SPLIT is defined, RGBLIGHT_SPLIT is implicitly defined. 234 * `#define RGBLIGHT_HUE_STEP 12` 235 * units to step when in/decreasing hue 236 * `#define RGBLIGHT_SAT_STEP 25` 237 * units to step when in/decreasing saturation 238 * `#define RGBLIGHT_VAL_STEP 12` 239 * units to step when in/decreasing value (brightness) 240 * `#define WS2812_RGBW` 241 * Enables RGBW LED support 242 243 ## Mouse Key Options 244 245 * `#define MOUSEKEY_INTERVAL 20` 246 * `#define MOUSEKEY_DELAY 0` 247 * `#define MOUSEKEY_TIME_TO_MAX 60` 248 * `#define MOUSEKEY_MAX_SPEED 7` 249 * `#define MOUSEKEY_WHEEL_DELAY 0` 250 251 ## Split Keyboard Options 252 253 Split Keyboard specific options, make sure you have 'SPLIT_KEYBOARD = yes' in your rules.mk 254 255 * `SPLIT_TRANSPORT = custom` 256 * Allows replacing the standard split communication routines with a custom one. ARM based split keyboards must use this at present. 257 258 ### Setting Handedness 259 260 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. 261 262 There are a few different ways to set handedness for split keyboards (listed in order of precedence): 263 264 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 265 2. Set `EE_HANDS` and flash `eeprom-lefthand.eep`/`eeprom-righthand.eep` to each half 266 * For boards with DFU bootloader you can use `:dfu-split-left`/`:dfu-split-right` to flash these EEPROM files 267 * For boards with Caterina bootloader (like stock Pro Micros), use `:avrdude-split-left`/`:avrdude-split-right` 268 * For boards with ARM DFU bootloader (like Proton C), use `:dfu-util-split-left`/`:dfu-util-split-right` 269 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) 270 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 271 272 #### Defines for handedness 273 274 * `#define SPLIT_HAND_PIN B7` 275 * 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. 276 277 * `#define SPLIT_HAND_MATRIX_GRID <out_pin>,<in_pin>` 278 * 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 right. If you define `#define SPLIT_HAND_MATRIX_GRID_LOW_IS_LEFT`, it is determined to be left when the level is low. 279 280 * `#define EE_HANDS` (only works if `SPLIT_HAND_PIN` and `SPLIT_HAND_MATRIX_GRID` are not defined) 281 * Reads the handedness value stored in the EEPROM after `eeprom-lefthand.eep`/`eeprom-righthand.eep` has been flashed to their respective halves. 282 283 * `#define MASTER_RIGHT` 284 * Master half is defined to be the right half. 285 286 ### Other Options 287 288 * `#define USE_I2C` 289 * For using I2C instead of Serial (default is serial; serial transport is supported on ARM -- I2C is AVR-only) 290 291 * `#define SOFT_SERIAL_PIN D0` 292 * When using serial, define this. `D0` or `D1`,`D2`,`D3`,`E6`. 293 294 * `#define MATRIX_ROW_PINS_RIGHT { <row pins> }` 295 * `#define MATRIX_COL_PINS_RIGHT { <col pins> }` 296 * 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. 297 * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions#low-level-matrix-overrides) for more information. 298 299 * `#define DIRECT_PINS_RIGHT { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }` 300 * 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`. 301 302 * `#define RGBLED_SPLIT { 6, 6 }` 303 * See [RGB Light Configuration](#rgb-light-configuration) 304 305 * `#define SELECT_SOFT_SERIAL_SPEED <speed>` (default speed is 1) 306 * Sets the protocol speed when using serial communication 307 * Speeds: 308 * 0: about 189kbps (Experimental only) 309 * 1: about 137kbps (default) 310 * 2: about 75kbps 311 * 3: about 39kbps 312 * 4: about 26kbps 313 * 5: about 20kbps 314 315 * `#define SPLIT_USB_DETECT` 316 * Detect (with timeout) USB connection when delegating master/slave 317 * Default behavior for ARM 318 * Required for AVR Teensy (without hardware mods) 319 320 * `#define SPLIT_USB_TIMEOUT 2000` 321 * Maximum timeout when detecting master/slave when using `SPLIT_USB_DETECT` 322 323 * `#define SPLIT_USB_TIMEOUT_POLL 10` 324 * Poll frequency when detecting master/slave when using `SPLIT_USB_DETECT` 325 326 * `#define SPLIT_WATCHDOG_ENABLE` 327 * Reboot slave if no communication from master within timeout. 328 * Helps resolve issue where both sides detect as slave using `SPLIT_USB_DETECT` 329 330 * `#define SPLIT_WATCHDOG_TIMEOUT 3000` 331 * Maximum slave timeout when waiting for communication from master when using `SPLIT_WATCHDOG_ENABLE` 332 333 * `#define FORCED_SYNC_THROTTLE_MS 100` 334 * Deadline for synchronizing data from master to slave when using the QMK-provided split transport. 335 336 * `#define SPLIT_TRANSPORT_MIRROR` 337 * Mirrors the master-side matrix on the slave when using the QMK-provided split transport. 338 339 * `#define SPLIT_LAYER_STATE_ENABLE` 340 * Ensures the current layer state is available on the slave when using the QMK-provided split transport. 341 342 * `#define SPLIT_LED_STATE_ENABLE` 343 * Ensures the current host indicator state (caps/num/scroll) is available on the slave when using the QMK-provided split transport. 344 345 * `#define SPLIT_MODS_ENABLE` 346 * Ensures the current modifier state (normal, weak, and oneshot) is available on the slave when using the QMK-provided split transport. 347 348 * `#define SPLIT_WPM_ENABLE` 349 * Ensures the current WPM is available on the slave when using the QMK-provided split transport. 350 351 * `#define SPLIT_OLED_ENABLE` 352 * Syncs the on/off state of the OLED between the halves. 353 354 * `#define SPLIT_ST7565_ENABLE` 355 * Syncs the on/off state of the ST7565 screen between the halves. 356 357 * `#define SPLIT_TRANSACTION_IDS_KB .....` 358 * `#define SPLIT_TRANSACTION_IDS_USER .....` 359 * Allows for custom data sync with the slave when using the QMK-provided split transport. See [custom data sync between sides](features/split_keyboard#custom-data-sync) for more information. 360 361 # The `rules.mk` File 362 363 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. 364 365 ## Build Options 366 367 * `FIRMWARE_FORMAT` 368 * Defines which format (bin, hex) is copied to the root `qmk_firmware` folder after building. 369 * `SRC` 370 * Used to add files to the compilation/linking list. 371 * `LIB_SRC` 372 * Used to add files as a library to the compilation/linking list. 373 The files specified by `LIB_SRC` is linked after the files specified by `SRC`. 374 For example, if you specify: 375 ``` 376 SRC += a.c 377 LIB_SRC += lib_b.c 378 SRC += c.c 379 LIB_SRC += lib_d.c 380 ``` 381 The link order is as follows. 382 ``` 383 ... a.o c.o ... lib_b.a lib_d.a ... 384 ``` 385 * `LAYOUTS` 386 * A list of [layouts](feature_layouts) this keyboard supports. 387 * `LTO_ENABLE` 388 * 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). 389 390 ## AVR MCU Options 391 * `MCU = atmega32u4` 392 * `F_CPU = 16000000` 393 * `ARCH = AVR8` 394 * `F_USB = $(F_CPU)` 395 * `OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT` 396 * `BOOTLOADER = atmel-dfu` with the following options: 397 * `atmel-dfu` 398 * `lufa-dfu` 399 * `qmk-dfu` 400 * `qmk-hid` 401 * `halfkay` 402 * `caterina` 403 * `bootloadhid` 404 * `usbasploader` 405 406 ## Feature Options {#feature-options} 407 408 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. 409 410 * `MAGIC_ENABLE` 411 * MAGIC actions (BOOTMAGIC without the boot) 412 * `BOOTMAGIC_ENABLE` 413 * Enable Bootmagic 414 * `MOUSEKEY_ENABLE` 415 * Mouse keys 416 * `EXTRAKEY_ENABLE` 417 * Audio control and System control 418 * `CONSOLE_ENABLE` 419 * Console for debug 420 * `COMMAND_ENABLE` 421 * Commands for debug and configuration 422 * `COMBO_ENABLE` 423 * Key combo feature 424 * `NKRO_ENABLE` 425 * USB N-Key Rollover - if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work 426 * `AUDIO_ENABLE` 427 * Enable the audio subsystem. 428 * `KEY_OVERRIDE_ENABLE` 429 * Enable the key override feature 430 * `RGBLIGHT_ENABLE` 431 * Enable keyboard underlight functionality 432 * `LEADER_ENABLE` 433 * Enable leader key chording 434 * `MIDI_ENABLE` 435 * MIDI controls 436 * `UNICODE_ENABLE` 437 * Unicode 438 * `BLUETOOTH_ENABLE` 439 * Current options are bluefruit_le, rn42 440 * `SPLIT_KEYBOARD` 441 * 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 442 * `CUSTOM_MATRIX` 443 * Allows replacing the standard matrix scanning routine with a custom one. 444 * `DEBOUNCE_TYPE` 445 * Allows replacing the standard key debouncing routine with an alternative or custom one. 446 * `USB_WAIT_FOR_ENUMERATION` 447 * Forces the keyboard to wait for a USB connection to be established before it starts up 448 * `NO_USB_STARTUP_CHECK` 449 * 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. 450 * `DEFERRED_EXEC_ENABLE` 451 * Enables deferred executor support -- timed delays before callbacks are invoked. See [deferred execution](custom_quantum_functions#deferred-execution) for more information. 452 * `DYNAMIC_TAPPING_TERM_ENABLE` 453 * Allows to configure the global tapping term on the fly. 454 455 ## USB Endpoint Limitations 456 457 In order to provide services over USB, QMK has to use USB endpoints. 458 These are a finite resource: each microcontroller has only a certain number. 459 This limits what features can be enabled together. 460 If the available endpoints are exceeded, a build error is thrown. 461 462 The following features can require separate endpoints: 463 464 * `MOUSEKEY_ENABLE` 465 * `EXTRAKEY_ENABLE` 466 * `CONSOLE_ENABLE` 467 * `NKRO_ENABLE` 468 * `MIDI_ENABLE` 469 * `RAW_ENABLE` 470 * `VIRTSER_ENABLE` 471 472 In order to improve utilisation of the endpoints, the HID features can be combined to use a single endpoint. 473 By default, `MOUSEKEY`, `EXTRAKEY`, and `NKRO` are combined into a single endpoint. 474 475 The base keyboard functionality can also be combined into the endpoint, 476 by setting `KEYBOARD_SHARED_EP = yes`. 477 This frees up one more endpoint, 478 but it can prevent the keyboard working in some BIOSes, 479 as they do not implement Boot Keyboard protocol switching. 480 481 Combining the mouse also breaks Boot Mouse compatibility. 482 The mouse can be uncombined by setting `MOUSE_SHARED_EP = no` if this functionality is required.