docs/config_options.md

   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 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:
   6
   7 * QMK Default
   8 * Keyboard
   9 * Folders (Up to 5 levels deep)
  10 * Keymap
  11
  12 ## QMK Default
  13
  14 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.
  15
  16 ## Keyboard
  17
  18 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.
  19
  20 ## Folders
  21
  22 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.
  23
  24 ## Keymap
  25
  26 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.
  27
  28 # The `config.h` File
  29
  30 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:
  31
  32     #include "config_common.h"
  33
  34
  35 ## Hardware Options
  36 * `#define VENDOR_ID 0x1234`
  37   * defines your VID, and for most DIY projects, can be whatever you want
  38 * `#define PRODUCT_ID 0x5678`
  39   * defines your PID, and for most DIY projects, can be whatever you want
  40 * `#define DEVICE_VER 0`
  41   * defines the device version (often used for revisions)
  42 * `#define MANUFACTURER Me`
  43   * generally who/whatever brand produced the board
  44 * `#define PRODUCT Board`
  45   * the name of the keyboard
  46 * `#define DESCRIPTION a keyboard`
  47   * a short description of what the keyboard is
  48 * `#define MATRIX_ROWS 5`
  49   * the number of rows in your keyboard's matrix
  50 * `#define MATRIX_COLS 15`
  51   * the number of columns in your keyboard's matrix
  52 * `#define MATRIX_ROW_PINS { D0, D5, B5, B6 }`
  53   * pins of the rows, from top to bottom
  54 * `#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 }`
  55   * pins of the columns, from left to right
  56 * `#define UNUSED_PINS { D1, D2, D3, B1, B2, B3 }`
  57   * pins unused by the keyboard for reference
  58 * `#define MATRIX_HAS_GHOST`
  59   * define is matrix has ghost (unlikely)
  60 * `#define DIODE_DIRECTION COL2ROW`
  61   * 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.
  62 * `#define AUDIO_VOICES`
  63   * turns on the alternate audio voices (to cycle through)
  64 * `#define C4_AUDIO`
  65   * enables audio on pin C4
  66 * `#define C5_AUDIO`
  67   * enables audio on pin C5
  68 * `#define C6_AUDIO`
  69   * enables audio on pin C6
  70 * `#define B5_AUDIO`
  71   * enables audio on pin B5 (duophony is enables if one of B[5-7]_AUDIO is enabled along with one of C[4-6]_AUDIO)
  72 * `#define B6_AUDIO`
  73   * enables audio on pin B6 (duophony is enables if one of B[5-7]_AUDIO is enabled along with one of C[4-6]_AUDIO)
  74 * `#define B7_AUDIO`
  75   * enables audio on pin B7 (duophony is enables if one of B[5-7]_AUDIO is enabled along with one of C[4-6]_AUDIO)
  76 * `#define BACKLIGHT_PIN B7`
  77   * pin of the backlight - B5, B6, B7 use PWM, others use softPWM
  78 * `#define BACKLIGHT_LEVELS 3`
  79   * number of levels your backlight will have (maximum 15 excluding off)
  80 * `#define BACKLIGHT_BREATHING`
  81   * enables backlight breathing (only works with backlight pins B5, B6 and B7)
  82 * `#define BREATHING_PERIOD 6`
  83   * the length of one backlight "breath" in seconds
  84 * `#define DEBOUNCING_DELAY 5`
  85   * the delay when reading the value of the pin (5 is default)
  86 * `#define LOCKING_SUPPORT_ENABLE`
  87   * mechanical locking support. Use KC_LCAP, KC_LNUM or KC_LSCR instead in keymap
  88 * `#define LOCKING_RESYNC_ENABLE`
  89   * tries to keep switch state consistent with keyboard LED state
  90 * `#define IS_COMMAND() ( keyboard_report->mods == (MOD_BIT(KC_LSHIFT) | MOD_BIT(KC_RSHIFT)) )`
  91   * key combination that allows the use of magic commands (useful for debugging)
  92 * `#define USB_MAX_POWER_CONSUMPTION`
  93   * sets the maximum power (in mA) over USB for the device (default: 500)
  94 * `#define SCL_CLOCK 100000L`
  95   * sets the SCL_CLOCK speed for split keyboards. The default is `100000L` but some boards can be set to `400000L`.
  96
  97 ## Features That Can Be Disabled
  98
  99 If you define these options you will disable the associated feature, which can save on code size.
 100
 101 * `#define NO_DEBUG`
 102   * disable debugging
 103 * `#define NO_PRINT`
 104   * disable printing/debugging using hid_listen
 105 * `#define NO_ACTION_LAYER`
 106   * disable layers
 107 * `#define NO_ACTION_TAPPING`
 108   * disable tap dance and other tapping features
 109 * `#define NO_ACTION_ONESHOT`
 110   * disable one-shot modifiers
 111 * `#define NO_ACTION_MACRO`
 112   * disable all macro handling
 113 * `#define NO_ACTION_FUNCTION`
 114   * disable the action function (deprecated)
 115
 116 ## Features That Can Be Enabled
 117
 118 If you define these options you will enable the associated feature, which may increase your code size.
 119
 120 * `#define FORCE_NKRO`
 121   * 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.
 122 * `#define PREVENT_STUCK_MODIFIERS`
 123   * stores the layer a key press came from so the same layer is used when the key is released, regardless of which layers are enabled
 124
 125 ## Behaviors That Can Be Configured
 126
 127 * `#define TAPPING_TERM 200`
 128   * 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
 129 * `#define RETRO_TAPPING`
 130   * tap anyway, even after TAPPING_TERM, if there was no other key interruption between press and release
 131   * See [Retro Tapping](feature_advanced_keycodes.md#retro-tapping) for details
 132 * `#define TAPPING_TOGGLE 2`
 133   * how many taps before triggering the toggle
 134 * `#define PERMISSIVE_HOLD`
 135   * makes tap and hold keys work better for fast typers who don't want tapping term set above 500
 136   * See [Permissive Hold](feature_advanced_keycodes.md#permissive-hold) for details
 137 * `#define IGNORE_MOD_TAP_INTERRUPT`
 138   * makes it possible to do rolling combos (zx) with keys that convert to other keys on hold
 139   * See [Mod tap interrupt](feature_advanced_keycodes.md#mod-tap-interrupt) for details
 140 * `#define TAPPING_FORCE_HOLD`
 141   * makes it possible to use a dual role key as modifier shortly after having been tapped
 142   * See [Hold after tap](feature_advanced_keycodes.md#hold-after-tap)
 143 * `#define LEADER_TIMEOUT 300`
 144   * how long before the leader key times out
 145 * `#define ONESHOT_TIMEOUT 300`
 146   * how long before oneshot times out
 147 * `#define ONESHOT_TAP_TOGGLE 2`
 148   * how many taps before oneshot toggle is triggered
 149 * `#define QMK_KEYS_PER_SCAN 4`
 150   * Allows sending more than one key per scan. By default, only one key event gets
 151     sent via `process_record()` per scan. This has little impact on most typing, but
 152     if you're doing a lot of chords, or your scan rate is slow to begin with, you can
 153     have some delay in processing key events. Each press and release is a separate
 154     event. For a keyboard with 1ms or so scan times, even a very fast typist isn't
 155     going to produce the 500 keystrokes a second needed to actually get more than a
 156     few ms of delay from this. But if you're doing chording on something with 3-4ms
 157     scan times? You probably want this.
 158
 159 ## RGB Light Configuration
 160
 161 * `#define RGB_DI_PIN D7`
 162   * pin the DI on the ws2812 is hooked-up to
 163 * `#define RGBLIGHT_ANIMATIONS`
 164   * run RGB animations
 165 * `#define RGBLED_NUM 15`
 166   * number of LEDs
 167 * `#define RGBLIGHT_HUE_STEP 12`
 168   * units to step when in/decreasing hue
 169 * `#define RGBLIGHT_SAT_STEP 25`
 170   * units to step when in/decreasing saturation
 171 * `#define RGBLIGHT_VAL_STEP 12`
 172   * units to step when in/decreasing value (brightness)
 173 * `#define RGBW_BB_TWI`
 174   * bit-bangs TWI to EZ RGBW LEDs (only required for Ergodox EZ)
 175
 176 ## Mouse Key Options
 177
 178 * `#define MOUSEKEY_INTERVAL 20`
 179 * `#define MOUSEKEY_DELAY 0`
 180 * `#define MOUSEKEY_TIME_TO_MAX 60`
 181 * `#define MOUSEKEY_MAX_SPEED 7`
 182 * `#define MOUSEKEY_WHEEL_DELAY 0`
 183
 184 ## Split Keyboard Options
 185
 186 Split Keyboard specific options, make sure you have 'SPLIT_KEYBOARD = yes' in your rules.mk
 187
 188 * `#define SPLIT_HAND_PIN B7`
 189   * 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 you can still use the EEHANDS method or MASTER_LEFT / MASTER_RIGHT defines like the stock Let's Split uses.
 190
 191 * `#define USE_I2C`
 192   * For using I2C instead of Serial (defaults to serial)
 193
 194 # The `rules.mk` File
 195
 196 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.
 197
 198 ## Build Options
 199
 200 * `DEFAULT_FOLDER`
 201   * Used to specify a default folder when a keyboard has more than one sub-folder.
 202 * `FIRMWARE_FORMAT`
 203   * Defines which format (bin, hex) is copied to the root `qmk_firmware` folder after building.
 204 * `SRC`
 205   * Used to add files to the compilation/linking list.
 206 * `LAYOUTS`
 207   * A list of [layouts](feature_layouts.md) this keyboard supports.
 208
 209 ## AVR MCU Options
 210 * `MCU = atmega32u4`
 211 * `F_CPU = 16000000`
 212 * `ARCH = AVR8`
 213 * `F_USB = $(F_CPU)`
 214 * `OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT`
 215 * `BOOTLOADER = atmel-dfu` with the following options:
 216   * `atmel-dfu`
 217   * `lufa-dfu`
 218   * `qmk-dfu`
 219   * `halfkay`
 220   * `caterina`
 221   * `bootloadHID`
 222
 223 ## Feature Options
 224
 225 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.
 226
 227 * `BOOTMAGIC_ENABLE`
 228   * Virtual DIP switch configuration(+1000)
 229 * `MOUSEKEY_ENABLE`
 230   * Mouse keys(+4700)
 231 * `EXTRAKEY_ENABLE`
 232   * Audio control and System control(+450)
 233 * `CONSOLE_ENABLE`
 234   * Console for debug(+400)
 235 * `COMMAND_ENABLE`
 236   * Commands for debug and configuration
 237 * `NKRO_ENABLE`
 238   * USB N-Key Rollover - if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work
 239 * `AUDIO_ENABLE`
 240   * Enable the audio subsystem.
 241 * `RGBLIGHT_ENABLE`
 242   * Enable keyboard underlight functionality
 243 * `MIDI_ENABLE`
 244   * MIDI controls
 245 * `UNICODE_ENABLE`
 246   * Unicode
 247 * `BLUETOOTH_ENABLE`
 248   * Enable Bluetooth with the Adafruit EZ-Key HID
 249 * `SPLIT_KEYBOARD`
 250   * 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