qmk

QMK Firmware
git clone git://git.z3bra.org/qmk.git
Log | Files | Refs | Submodules | LICENSE

config_options.md (18508B)


      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 DIRECT_PINS { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }`
     63   * pins mapped to rows and columns, from left to right. Defines a matrix where each switch is connected to a separate pin and ground.
     64 * `#define AUDIO_VOICES`
     65   * turns on the alternate audio voices (to cycle through)
     66 * `#define C4_AUDIO`
     67   * enables audio on pin C4
     68 * `#define C5_AUDIO`
     69   * enables audio on pin C5
     70 * `#define C6_AUDIO`
     71   * enables audio on pin C6
     72 * `#define B5_AUDIO`
     73   * 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)
     74 * `#define B6_AUDIO`
     75   * 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)
     76 * `#define B7_AUDIO`
     77   * 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)
     78 * `#define BACKLIGHT_PIN B7`
     79   * pin of the backlight
     80 * `#define BACKLIGHT_LEVELS 3`
     81   * number of levels your backlight will have (maximum 15 excluding off)
     82 * `#define BACKLIGHT_BREATHING`
     83   * enables backlight breathing
     84 * `#define BREATHING_PERIOD 6`
     85   * the length of one backlight "breath" in seconds
     86 * `#define DEBOUNCE 5`
     87   * the delay when reading the value of the pin (5 is default)
     88 * `#define LOCKING_SUPPORT_ENABLE`
     89   * mechanical locking support. Use KC_LCAP, KC_LNUM or KC_LSCR instead in keymap
     90 * `#define LOCKING_RESYNC_ENABLE`
     91   * tries to keep switch state consistent with keyboard LED state
     92 * `#define IS_COMMAND() (get_mods() == MOD_MASK_SHIFT)`
     93   * key combination that allows the use of magic commands (useful for debugging)
     94 * `#define USB_MAX_POWER_CONSUMPTION`
     95   * sets the maximum power (in mA) over USB for the device (default: 500)
     96 * `#define F_SCL 100000L`
     97   * 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`.
     98 
     99 ## Features That Can Be Disabled
    100 
    101 If you define these options you will disable the associated feature, which can save on code size.
    102 
    103 * `#define NO_DEBUG`
    104   * disable debugging
    105 * `#define NO_PRINT`
    106   * disable printing/debugging using hid_listen
    107 * `#define NO_ACTION_LAYER`
    108   * disable layers
    109 * `#define NO_ACTION_TAPPING`
    110   * disable tap dance and other tapping features
    111 * `#define NO_ACTION_ONESHOT`
    112   * disable one-shot modifiers
    113 * `#define NO_ACTION_MACRO`
    114   * disable old style macro handling: MACRO() & action_get_macro
    115 * `#define NO_ACTION_FUNCTION`
    116   * disable calling of action_function() from the fn_actions array (deprecated)
    117 
    118 ## Features That Can Be Enabled
    119 
    120 If you define these options you will enable the associated feature, which may increase your code size.
    121 
    122 * `#define FORCE_NKRO`
    123   * 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.
    124 * `#define STRICT_LAYER_RELEASE`
    125   * force a key release to be evaluated using the current layer stack instead of remembering which layer it came from (used for advanced cases)
    126 
    127 ## Behaviors That Can Be Configured
    128 
    129 * `#define TAPPING_TERM 200`
    130   * 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
    131 * `#define TAPPING_TERM_PER_KEY`
    132   * enables handling for per key `TAPPING_TERM` settings
    133 * `#define RETRO_TAPPING`
    134   * tap anyway, even after TAPPING_TERM, if there was no other key interruption between press and release
    135   * See [Retro Tapping](feature_advanced_keycodes.md#retro-tapping) for details
    136 * `#define TAPPING_TOGGLE 2`
    137   * how many taps before triggering the toggle
    138 * `#define PERMISSIVE_HOLD`
    139   * makes tap and hold keys trigger the hold if another key is pressed before releasing, even if it hasn't hit the `TAPPING_TERM`
    140   * See [Permissive Hold](feature_advanced_keycodes.md#permissive-hold) for details
    141 * `#define IGNORE_MOD_TAP_INTERRUPT`
    142   * 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.
    143   * See [Mod tap interrupt](feature_advanced_keycodes.md#ignore-mod-tap-interrupt) for details
    144 * `#define TAPPING_FORCE_HOLD`
    145   * makes it possible to use a dual role key as modifier shortly after having been tapped
    146   * See [Hold after tap](feature_advanced_keycodes.md#tapping-force-hold)
    147   * Breaks any Tap Toggle functionality (`TT` or the One Shot Tap Toggle)
    148 * `#define LEADER_TIMEOUT 300`
    149   * how long before the leader key times out
    150     * 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.
    151 * `#define LEADER_PER_KEY_TIMING`
    152   * sets the timer for leader key chords to run on each key press rather than overall
    153 * `#define LEADER_KEY_STRICT_KEY_PROCESSING`
    154   * 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`.
    155 * `#define ONESHOT_TIMEOUT 300`
    156   * how long before oneshot times out
    157 * `#define ONESHOT_TAP_TOGGLE 2`
    158   * how many taps before oneshot toggle is triggered
    159 * `#define QMK_KEYS_PER_SCAN 4`
    160   * Allows sending more than one key per scan. By default, only one key event gets
    161     sent via `process_record()` per scan. This has little impact on most typing, but
    162     if you're doing a lot of chords, or your scan rate is slow to begin with, you can
    163     have some delay in processing key events. Each press and release is a separate
    164     event. For a keyboard with 1ms or so scan times, even a very fast typist isn't
    165     going to produce the 500 keystrokes a second needed to actually get more than a
    166     few ms of delay from this. But if you're doing chording on something with 3-4ms
    167     scan times? You probably want this.
    168 * `#define COMBO_COUNT 2`
    169   * Set this to the number of combos that you're using in the [Combo](feature_combo.md) feature.
    170 * `#define COMBO_TERM 200`
    171   * how long for the Combo keys to be detected. Defaults to `TAPPING_TERM` if not defined.
    172 * `#define TAP_CODE_DELAY 100`
    173   * 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.
    174 * `#define TAP_HOLD_CAPS_DELAY 80`
    175   * Sets the delay for Tap Hold keys (`LT`, `MT`) when using `KC_CAPSLOCK` 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.
    176 
    177 ## RGB Light Configuration
    178 
    179 * `#define RGB_DI_PIN D7`
    180   * pin the DI on the WS2812 is hooked-up to
    181 * `#define RGBLIGHT_ANIMATIONS`
    182   * run RGB animations
    183 * `#define RGBLED_NUM 12`
    184   * number of LEDs
    185 * `#define RGBLIGHT_SPLIT`
    186   * 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
    187 * `#define RGBLED_SPLIT { 6, 6 }`
    188   * number of LEDs connected that are directly wired to `RGB_DI_PIN` on each half of a split keyboard
    189   * First value indicates number of LEDs for left half, second value is for the right half
    190   * When RGBLED_SPLIT is defined, RGBLIGHT_SPLIT is implicitly defined.
    191 * `#define RGBLIGHT_HUE_STEP 12`
    192   * units to step when in/decreasing hue
    193 * `#define RGBLIGHT_SAT_STEP 25`
    194   * units to step when in/decreasing saturation
    195 * `#define RGBLIGHT_VAL_STEP 12`
    196   * units to step when in/decreasing value (brightness)
    197 * `#define RGBW_BB_TWI`
    198   * bit-bangs TWI to EZ RGBW LEDs (only required for Ergodox EZ)
    199 
    200 ## Mouse Key Options
    201 
    202 * `#define MOUSEKEY_INTERVAL 20`
    203 * `#define MOUSEKEY_DELAY 0`
    204 * `#define MOUSEKEY_TIME_TO_MAX 60`
    205 * `#define MOUSEKEY_MAX_SPEED 7`
    206 * `#define MOUSEKEY_WHEEL_DELAY 0`
    207 
    208 ## Split Keyboard Options
    209 
    210 Split Keyboard specific options, make sure you have 'SPLIT_KEYBOARD = yes' in your rules.mk
    211 
    212 * `SPLIT_TRANSPORT = custom`
    213   * Allows replacing the standard split communication routines with a custom one. ARM based split keyboards must use this at present.
    214 
    215 ### Setting Handedness
    216 
    217 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.
    218 
    219 There are a few different ways to set handedness for split keyboards (listed in order of precedence):
    220 
    221 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
    222 2. Set `EE_HANDS` and flash `eeprom-lefthand.eep`/`eeprom-righthand.eep` to each half
    223    * For boards with DFU bootloader you can use `:dfu-split-left`/`:dfu-split-right` to flash these EEPROM files
    224    * For boards with Caterina bootloader (like stock Pro Micros), use `:avrdude-split-left`/`:avrdude-split-right`
    225 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)
    226 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
    227 
    228 #### Defines for handedness
    229 
    230 * `#define SPLIT_HAND_PIN B7`
    231   * 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.
    232 
    233 * `#define EE_HANDS` (only works if `SPLIT_HAND_PIN` is not defined)
    234   * Reads the handedness value stored in the EEPROM after `eeprom-lefthand.eep`/`eeprom-righthand.eep` has been flashed to their respective halves.
    235 
    236 * `#define MASTER_RIGHT`
    237   * Master half is defined to be the right half.
    238 
    239 ### Other Options
    240 
    241 * `#define USE_I2C`
    242   * For using I2C instead of Serial (defaults to serial)
    243 
    244 * `#define SOFT_SERIAL_PIN D0`
    245   * When using serial, define this. `D0` or `D1`,`D2`,`D3`,`E6`.
    246 
    247 * `#define MATRIX_ROW_PINS_RIGHT { <row pins> }`
    248 * `#define MATRIX_COL_PINS_RIGHT { <col pins> }`
    249   * 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.
    250 
    251 * `#define DIRECT_PINS_RIGHT { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }`
    252   * 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`.
    253 
    254 * `#define RGBLED_SPLIT { 6, 6 }`
    255   * See [RGB Light Configuration](#rgb-light-configuration)
    256 
    257 * `#define SELECT_SOFT_SERIAL_SPEED <speed>` (default speed is 1)
    258   * Sets the protocol speed when using serial communication
    259   * Speeds:
    260     * 0: about 189kbps (Experimental only)
    261     * 1: about 137kbps (default)
    262     * 2: about 75kbps
    263     * 3: about 39kbps
    264     * 4: about 26kbps
    265     * 5: about 20kbps
    266 
    267 # The `rules.mk` File
    268 
    269 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.
    270 
    271 ## Build Options
    272 
    273 * `DEFAULT_FOLDER`
    274   * Used to specify a default folder when a keyboard has more than one sub-folder.
    275 * `FIRMWARE_FORMAT`
    276   * Defines which format (bin, hex) is copied to the root `qmk_firmware` folder after building.
    277 * `SRC`
    278   * Used to add files to the compilation/linking list.
    279 * `LAYOUTS`
    280   * A list of [layouts](feature_layouts.md) this keyboard supports.
    281 
    282 ## AVR MCU Options
    283 * `MCU = atmega32u4`
    284 * `F_CPU = 16000000`
    285 * `ARCH = AVR8`
    286 * `F_USB = $(F_CPU)`
    287 * `OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT`
    288 * `BOOTLOADER = atmel-dfu` with the following options:
    289   * `atmel-dfu`
    290   * `lufa-dfu`
    291   * `qmk-dfu`
    292   * `halfkay`
    293   * `caterina`
    294   * `bootloadHID`
    295   * `USBasp`
    296 
    297 ## Feature Options
    298 
    299 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.
    300 
    301 * `BOOTMAGIC_ENABLE`
    302   * Virtual DIP switch configuration(+1000)
    303 * `MOUSEKEY_ENABLE`
    304   * Mouse keys(+4700)
    305 * `EXTRAKEY_ENABLE`
    306   * Audio control and System control(+450)
    307 * `CONSOLE_ENABLE`
    308   * Console for debug(+400)
    309 * `COMMAND_ENABLE`
    310   * Commands for debug and configuration
    311 * `COMBO_ENABLE`
    312   * Key combo feature
    313 * `NKRO_ENABLE`
    314   * USB N-Key Rollover - if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work
    315 * `AUDIO_ENABLE`
    316   * Enable the audio subsystem.
    317 * `RGBLIGHT_ENABLE`
    318   * Enable keyboard underlight functionality
    319 * `LEADER_ENABLE`
    320   * Enable leader key chording
    321 * `MIDI_ENABLE`
    322   * MIDI controls
    323 * `UNICODE_ENABLE`
    324   * Unicode
    325 * `BLUETOOTH_ENABLE`
    326   * Legacy option to Enable Bluetooth with the Adafruit EZ-Key HID. See BLUETOOTH
    327 * `BLUETOOTH`
    328   * Current options are AdafruitEzKey, AdafruitBLE, RN42
    329 * `SPLIT_KEYBOARD`
    330   * 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
    331 * `CUSTOM_MATRIX`
    332   * Allows replacing the standard matrix scanning routine with a custom one.
    333 * `DEBOUNCE_TYPE`
    334   * Allows replacing the standard key debouncing routine with an alternative or custom one.
    335 * `WAIT_FOR_USB`
    336   * Forces the keyboard to wait for a USB connection to be established before it starts up
    337 * `NO_USB_STARTUP_CHECK`
    338   * 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.
    339 * `LINK_TIME_OPTIMIZATION_ENABLE`
    340   = Enables Link Time Optimization (`LTO`) when compiling the keyboard.  This makes the process take longer, but can significantly reduce the compiled size (and since the firmware is small, the added time is not noticable).  However, this will automatically disable the old Macros and Functions features automatically, as these break when `LTO` is enabled.  It does this by automatically defining `NO_ACTION_MACRO` and `NO_ACTION_FUNCTION` 
    341 
    342 ## USB Endpoint Limitations
    343 
    344 In order to provide services over USB, QMK has to use USB endpoints.
    345 These are a finite resource: each microcontroller has only a certain number.
    346 This limits what features can be enabled together.
    347 If the available endpoints are exceeded, a build error is thrown.
    348 
    349 The following features can require separate endpoints:
    350 
    351 * `MOUSEKEY_ENABLE`
    352 * `EXTRAKEY_ENABLE`
    353 * `CONSOLE_ENABLE`
    354 * `NKRO_ENABLE`
    355 * `MIDI_ENABLE`
    356 * `RAW_ENABLE`
    357 * `VIRTSER_ENABLE`
    358 
    359 In order to improve utilisation of the endpoints, the HID features can be combined to use a single endpoint.
    360 By default, `MOUSEKEY`, `EXTRAKEY`, and `NKRO` are combined into a single endpoint.
    361 
    362 The base keyboard functionality can also be combined into the endpoint,
    363 by setting `KEYBOARD_SHARED_EP = yes`.
    364 This frees up one more endpoint,
    365 but it can prevent the keyboard working in some BIOSes,
    366 as they do not implement Boot Keyboard protocol switching.
    367 
    368 Combining the mouse also breaks Boot Mouse compatibility.
    369 The mouse can be uncombined by setting `MOUSE_SHARED_EP = no` if this functionality is required.