summaryrefslogtreecommitdiff
path: root/docs/config_options.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/config_options.md')
-rw-r--r--docs/config_options.md299
1 files changed, 184 insertions, 115 deletions
diff --git a/docs/config_options.md b/docs/config_options.md
index b71dbb8ae9..de67630adc 100644
--- a/docs/config_options.md
+++ b/docs/config_options.md
@@ -1,129 +1,198 @@
1# The `config.h` file 1# Configuring QMK
2
3This 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 (namely keymaps). This file can exist at a couple different levels:
4
5## Keyboard
6 2
7```c 3QMK 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.
8#ifndef CONFIG_H
9#define CONFIG_H
10 4
11#include "config_common.h" 5There 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:
12 6
13// config options 7* QMK Default
8* Keyboard
9* Folders (Up to 5 levels deep)
10* Keymap
14 11
15#endif 12## QMK Default
16```
17 13
18This file contains config options that should apply to the whole keyboard, and won't change in revisions, or most keymaps. The revision block here only applies to keyboards with revisions. 14Every 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.
19 15
20## Revisions 16## Keyboard
21
22```c
23#ifndef <revision>_CONFIG_H
24#define <revision>_CONFIG_H
25
26#include "config_common.h"
27 17
28// config options 18This 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.
29 19
30#endif 20## Folders
31```
32 21
33For keyboards that have revisions, this file contains config options that should apply to only that revisions, and won't change in most keymaps. 22Some 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.
34 23
35## Keymap 24## Keymap
36 25
37```c 26This 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.
38#ifndef CONFIG_USER_H
39#define CONFIG_USER_H
40
41#include "config_common.h"
42
43// config options
44
45#endif
46```
47
48This file 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.
49
50# Config Options
51
52```c
53#define VENDOR_ID 0x1234 // defines your VID, and for most DIY projects, can be whatever you want
54#define PRODUCT_ID 0x5678 // defines your PID, and for most DIY projects, can be whatever you want
55#define DEVICE_VER 0 // defines the device version (often used for revisions)
56
57#define MANUFACTURER Me // generally who/whatever brand produced the board
58#define PRODUCT Board // the name of the keyboard
59#define DESCRIPTION a keyboard // a short description of what the keyboard is
60
61#define MATRIX_ROWS 5 // the number of rows in your keyboard's matrix
62#define MATRIX_COLS 15 // the number of columns in your keyboard's matrix
63
64#define MATRIX_ROW_PINS { D0, D5, B5, B6 } // pins of the rows, from top to bottom
65#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 } // pins of the columns, from left to right
66#define UNUSED_PINS { D1, D2, D3, B1, B2, B3 } // pins unused by the keyboard for reference
67#define MATRIX_HAS_GHOST // define is matrix has ghost (unlikely)
68#define DIODE_DIRECTION COL2ROW // COL2ROW or ROW2COL - how your matrix is configured
69// COL2ROW means the black mark on your diode is facing to the rows, and between the switch and the rows
70 27
71#define AUDIO_VOICES // turns on the alternate audio voices (to cycle through) 28# The `config.h` file
72#define C6_AUDIO // enables audio on pin C6
73#define B5_AUDIO // enables audio on pin B5 (duophony is enable if both are enabled)
74
75#define BACKLIGHT_PIN B7 // pin of the backlight - B5, B6, B7 use PWM, others use softPWM
76#define BACKLIGHT_LEVELS 3 // number of levels your backlight will have (not including off)
77
78#define DEBOUNCING_DELAY 5 // the delay when reading the value of the pin (5 is default)
79
80#define LOCKING_SUPPORT_ENABLE // mechanical locking support. Use KC_LCAP, KC_LNUM or KC_LSCR instead in keymap
81#define LOCKING_RESYNC_ENABLE // tries to keep switch state consistent with keyboard LED state
82
83#define IS_COMMAND() ( \ // key combination that allows the use of magic commands (useful for debugging)
84 keyboard_report->mods == (MOD_BIT(KC_LSHIFT) | MOD_BIT(KC_RSHIFT)) \
85)
86
87// the following options can save on file size at the expense of that feature
88#define NO_DEBUG // disable debuging (saves on file size)
89#define NO_PRINT // disable printing (saves of file size)
90#define NO_ACTION_LAYER // no layers
91#define NO_ACTION_TAPPING // no tapping for layers/mods
92#define NO_ACTION_ONESHOT // no oneshot for layers/mods
93#define NO_ACTION_MACRO // no macros
94#define NO_ACTION_FUNCTION // no functions
95
96#define FORCE_NKRO // NKRO by default requires to be turned on, this forces it to be on always
97
98#define PREVENT_STUCK_MODIFIERS // when switching layers, this will release all mods
99
100#define TAPPING_TERM 200 // how long before a tap becomes a hold
101#define TAPPING_TOGGLE 2 // how many taps before triggering the toggle
102
103#define PERMISSIVE_HOLD // makes tap and hold keys work better for fast typers who don't want tapping term set above 500
104
105#define LEADER_TIMEOUT 300 // how long before the leader key times out
106
107#define ONESHOT_TIMEOUT 300 // how long before oneshot times out
108#define ONESHOT_TAP_TOGGLE 2 // how many taps before oneshot toggle is triggered
109
110#define IGNORE_MOD_TAP_INTERRUPT // makes it possible to do rolling combos (zx) with keys that convert to other keys on hold
111
112// ws2812 options
113#define RGB_DI_PIN D7 // pin the DI on the ws2812 is hooked-up to
114#define RGBLIGHT_ANIMATIONS // run RGB animations
115#define RGBLED_NUM 15 // number of LEDs
116#define RGBLIGHT_HUE_STEP 12 // units to step when in/decreasing hue
117#define RGBLIGHT_SAT_STEP 25 // units to step when in/decresing saturation
118#define RGBLIGHT_VAL_STEP 12 // units to step when in/decreasing value (brightness)
119
120#define RGBW_BB_TWI // bit-bangs twi to EZ RGBW LEDs (only required for Ergodox EZ)
121
122// mousekey options (self-describing)
123#define MOUSEKEY_INTERVAL 20
124#define MOUSEKEY_DELAY 0
125#define MOUSEKEY_TIME_TO_MAX 60
126#define MOUSEKEY_MAX_SPEED 7
127#define MOUSEKEY_WHEEL_DELAY 0
128 29
129``` \ No newline at end of file 30This 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.
31
32## `config.h` Options
33
34### Hardware Options
35* `#define VENDOR_ID 0x1234`
36 * defines your VID, and for most DIY projects, can be whatever you want
37* `#define PRODUCT_ID 0x5678`
38 * defines your PID, and for most DIY projects, can be whatever you want
39* `#define DEVICE_VER 0`
40 * defines the device version (often used for revisions)
41* `#define MANUFACTURER Me`
42 * generally who/whatever brand produced the board
43* `#define PRODUCT Board`
44 * the name of the keyboard
45* `#define DESCRIPTION a keyboard`
46 * a short description of what the keyboard is
47* `#define MATRIX_ROWS 5`
48 * the number of rows in your keyboard's matrix
49* `#define MATRIX_COLS 15`
50 * the number of columns in your keyboard's matrix
51* `#define MATRIX_ROW_PINS { D0, D5, B5, B6 }`
52 * pins of the rows, from top to bottom
53* `#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 }`
54 * pins of the columns, from left to right
55* `#define UNUSED_PINS { D1, D2, D3, B1, B2, B3 }`
56 * pins unused by the keyboard for reference
57* `#define MATRIX_HAS_GHOST`
58 * define is matrix has ghost (unlikely)
59* `#define DIODE_DIRECTION COL2ROW`
60 * 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.
61* `#define AUDIO_VOICES`
62 * turns on the alternate audio voices (to cycle through)
63* `#define C6_AUDIO`
64 * enables audio on pin C6
65* `#define B5_AUDIO`
66 * enables audio on pin B5 (duophony is enable if both are enabled)
67* `#define BACKLIGHT_PIN B7`
68 * pin of the backlight - B5, B6, B7 use PWM, others use softPWM
69* `#define BACKLIGHT_LEVELS 3`
70 * number of levels your backlight will have (not including off)
71* `#define DEBOUNCING_DELAY 5`
72 * the delay when reading the value of the pin (5 is default)
73* `#define LOCKING_SUPPORT_ENABLE`
74 * mechanical locking support. Use KC_LCAP, KC_LNUM or KC_LSCR instead in keymap
75* `#define LOCKING_RESYNC_ENABLE`
76 * tries to keep switch state consistent with keyboard LED state
77* `#define IS_COMMAND() ( keyboard_report->mods == (MOD_BIT(KC_LSHIFT) | MOD_BIT(KC_RSHIFT)) )`
78 * key combination that allows the use of magic commands (useful for debugging)
79
80### Features That Can Be Disabled
81
82If you define these options you will disable the associated feature, which can save on code size.
83
84* `#define NO_DEBUG`
85 * disable debuging
86* `#define NO_PRINT`
87 * disable printing/debugging using hid_listen
88* `#define NO_ACTION_LAYER`
89 * disable layers
90* `#define NO_ACTION_TAPPING`
91 * disable tap dance and other tapping features
92* `#define NO_ACTION_ONESHOT`
93 * disable one-shot modifiers
94* `#define NO_ACTION_MACRO`
95 * disable all macro handling
96* `#define NO_ACTION_FUNCTION`
97 * disable the action function (deprecated)
98
99### Features That Can Be Enabled
100
101If you define these options you will enable the associated feature, which may increase your code size.
102
103* `#define FORCE_NKRO`
104 * 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.
105* `#define PREVENT_STUCK_MODIFIERS`
106 * when switching layers, this will release all mods
107
108### Behaviors That Can Be Configured
109
110* `#define TAPPING_TERM 200`
111 * how long before a tap becomes a hold
112* `#define TAPPING_TOGGLE 2`
113 * how many taps before triggering the toggle
114* `#define PERMISSIVE_HOLD`
115 * makes tap and hold keys work better for fast typers who don't want tapping term set above 500
116* `#define LEADER_TIMEOUT 300`
117 * how long before the leader key times out
118* `#define ONESHOT_TIMEOUT 300`
119 * how long before oneshot times out
120* `#define ONESHOT_TAP_TOGGLE 2`
121 * how many taps before oneshot toggle is triggered
122* `#define IGNORE_MOD_TAP_INTERRUPT`
123 * makes it possible to do rolling combos (zx) with keys that convert to other keys on hold
124
125### RGB Light Configuration
126
127* `#define RGB_DI_PIN D7`
128 * pin the DI on the ws2812 is hooked-up to
129* `#define RGBLIGHT_ANIMATIONS`
130 * run RGB animations
131* `#define RGBLED_NUM 15`
132 * number of LEDs
133* `#define RGBLIGHT_HUE_STEP 12`
134 * units to step when in/decreasing hue
135* `#define RGBLIGHT_SAT_STEP 25`
136 * units to step when in/decresing saturation
137* `#define RGBLIGHT_VAL_STEP 12`
138 * units to step when in/decreasing value (brightness)
139* `#define RGBW_BB_TWI`
140 * bit-bangs twi to EZ RGBW LEDs (only required for Ergodox EZ)
141
142### Mouse Key Options
143
144* `#define MOUSEKEY_INTERVAL 20`
145* `#define MOUSEKEY_DELAY 0`
146* `#define MOUSEKEY_TIME_TO_MAX 60`
147* `#define MOUSEKEY_MAX_SPEED 7`
148* `#define MOUSEKEY_WHEEL_DELAY 0`
149
150# The `rules.mk` File
151
152This 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.
153
154## `rules.mk` options
155
156### Build Options
157
158* `DEFAULT_FOLDER`
159 * Used to specify a default folder when a keyboard has more than one sub-folder.
160* `SRC`
161 * Used to add files to the compilation/linking list.
162* `LAYOUTS`
163 * A list of [layouts](feature_layouts.md) this keyboard supports.
164
165### AVR MCU Options
166* `MCU = atmega32u4`
167* `F_CPU = 16000000`
168* `ARCH = AVR8`
169* `F_USB = $(F_CPU)`
170* `OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT`
171* `OPT_DEFS += -DBOOTLOADER_SIZE=4096`
172
173### Feature Options
174
175Use 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.
176
177* `BOOTMAGIC_ENABLE`
178 * Virtual DIP switch configuration(+1000)
179* `MOUSEKEY_ENABLE`
180 * Mouse keys(+4700)
181* `EXTRAKEY_ENABLE`
182 * Audio control and System control(+450)
183* `CONSOLE_ENABLE`
184 * Console for debug(+400)
185* `COMMAND_ENABLE`
186 * Commands for debug and configuration
187* `NKRO_ENABLE`
188 * USB Nkey Rollover - if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work
189* `AUDIO_ENABLE`
190 * Enable the audio subsystem.
191* `RGBLIGHT_ENABLE`
192 * Enable keyboard underlight functionality
193* `MIDI_ENABLE`
194 * MIDI controls
195* `UNICODE_ENABLE`
196 * Unicode
197* `BLUETOOTH_ENABLE`
198 * Enable Bluetooth with the Adafruit EZ-Key HID
generated by cgit v1.2.3 (git 2.25.1) at 2026-09-03 08:09:22 +0000