You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
qmk_firmware/docs/config_options.md

338 lines
16 KiB

# Configuring QMK
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:
#include "config_common.h"
## Hardware Options
* `#define VENDOR_ID 0x1234`
* defines your VID, and for most DIY projects, can be whatever you want
* `#define PRODUCT_ID 0x5678`
* defines your PID, and for most DIY projects, can be whatever you want
* `#define DEVICE_VER 0`
* defines the device version (often used for revisions)
* `#define MANUFACTURER Me`
* generally who/whatever brand produced the board
* `#define PRODUCT Board`
* the name of the keyboard
* `#define DESCRIPTION a keyboard`
* a short description of what the keyboard is
* `#define MATRIX_ROWS 5`
* the number of rows in your keyboard's matrix
* `#define MATRIX_COLS 15`
* the number of columns in your keyboard's matrix
* `#define MATRIX_ROW_PINS { D0, D5, B5, B6 }`
* pins of the rows, from top to bottom
* `#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 }`
* pins of the columns, from left to right
* `#define UNUSED_PINS { D1, D2, D3, B1, B2, B3 }`
* pins unused by the keyboard for reference
* `#define MATRIX_HAS_GHOST`
* define is matrix has ghost (unlikely)
* `#define DIODE_DIRECTION COL2ROW`
* 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.
* `#define AUDIO_VOICES`
* turns on the alternate audio voices (to cycle through)
* `#define C4_AUDIO`
* enables audio on pin C4
* `#define C5_AUDIO`
* enables audio on pin C5
* `#define C6_AUDIO`
* enables audio on pin C6
* `#define B5_AUDIO`
* 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)
* `#define B6_AUDIO`
* 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)
* `#define B7_AUDIO`
* 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)
* `#define BACKLIGHT_PIN B7`
* pin of the backlight - B5, B6, B7 use PWM, others use softPWM
* `#define BACKLIGHT_LEVELS 3`
* number of levels your backlight will have (maximum 15 excluding off)
* `#define BACKLIGHT_BREATHING`
* enables backlight breathing (only works with backlight pins B5, B6 and B7)
* `#define BREATHING_PERIOD 6`
* the length of one backlight "breath" in seconds
* `#define DEBOUNCING_DELAY 5`
* the delay when reading the value of the pin (5 is default)
* `#define LOCKING_SUPPORT_ENABLE`
* mechanical locking support. Use KC_LCAP, KC_LNUM or KC_LSCR instead in keymap
* `#define LOCKING_RESYNC_ENABLE`
* tries to keep switch state consistent with keyboard LED state
* `#define IS_COMMAND() ( keyboard_report->mods == (MOD_BIT(KC_LSHIFT) | MOD_BIT(KC_RSHIFT)) )`
* key combination that allows the use of magic commands (useful for debugging)
* `#define USB_MAX_POWER_CONSUMPTION`
* sets the maximum power (in mA) over USB for the device (default: 500)
* `#define SCL_CLOCK 100000L`
* sets the SCL_CLOCK speed for split keyboards. The default is `100000L` but some boards can be set to `400000L`.
## 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
* `#define NO_ACTION_MACRO`
* disable all macro handling
* `#define NO_ACTION_FUNCTION`
* disable the action function (deprecated)
## Features That Can Be Enabled
If you define these options you will enable the associated feature, which may increase your code size.
* `#define FORCE_NKRO`
* 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 RETRO_TAPPING`
* tap anyway, even after TAPPING_TERM, if there was no other key interruption between press and release
* See [Retro Tapping](feature_advanced_keycodes.md#retro-tapping) for details
* `#define TAPPING_TOGGLE 2`
* how many taps before triggering the toggle
* `#define PERMISSIVE_HOLD`
* 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](feature_advanced_keycodes.md#permissive-hold) for details
* `#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 [Mod tap interrupt](feature_advanced_keycodes.md#ignore-mod-tap-interrupt) for details
* `#define TAPPING_FORCE_HOLD`
* makes it possible to use a dual role key as modifier shortly after having been tapped
* See [Hold after tap](feature_advanced_keycodes.md#tapping-force-hold)
* Breaks any Tap Toggle functionality (`TT` or the One Shot Tap Toggle)
* `#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
scan times? You probably want this.
* `#define COMBO_COUNT 2`
* Set this to the number of combos that you're using in the [Combo](feature_combo.md) feature.
* `#define COMBO_TERM 200`
* how long for the Combo keys to be detected. Defaults to `TAPPING_TERM` if not defined.
* `#define TAP_CODE_DELAY 100`
* 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.
## RGB Light Configuration
* `#define RGB_DI_PIN D7`
* pin the DI on the ws2812 is hooked-up to
* `#define RGBLIGHT_ANIMATIONS`
* run RGB animations
* `#define RGBLED_NUM 15`
* number of LEDs
* `#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_BB_TWI`
* bit-bangs TWI to EZ RGBW LEDs (only required for Ergodox EZ)
## 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`
Lets split eh (#3120) * Line ending stuff again * Added Let's Split Eh? Files and updated #USE_IC2 checks to also include th EH revision (can only be used in I2C) * Added personal keymap, updated some of the EH files * Created new keyboard file for testing "lets_split_eh" will merge into lets_split once fully functional * Added split code from lets_split, removed pro micro imports and LED code THIS IS WORKING CODE, WITHOUT RGB AND BACKLIGHT * Took back original Lets Slit files for the lets_split keyboard, working in the lets_split_eh folder for now * Updated eh.c * More rework of the I2C code, added global flags for split boards. * Introduced RGB over I2C, having weird edge case issues at the moment though * Fixed weird I2C edgecase with RGB, although still would like to track down route cause.. * Changed RGB keycodes (static ones) to activate on key-up instead of key-down to elimate weird ghosting issue over I2C * Lots of changes, mainly externalized the Split keyboard code and added logic for only including when needed. - Added makefile option "SPLIT_KEYBOARD" that when = yes will include the split keyboard files and custom matrix - Split keyboard files placed into quantum/split_common/ - Added define option for config files "SPLIT_HAND_PIN" FOr using high/low pin to determine handedness, low = right hand, high = left hand - Cleaned up split logic for RGB and Backlight so it is only exectuted / included when needed * Updated documentation for the new makefile options and #defines specific to split keyboards * Added a bit more info to docs, so people aren't confused * Modifed Let's Split to use externalized code, also added left and right hand eeprom files to the split_common folder * Removed some debugging from eh.c * Small changes to keyboard configs. Also added a default keymap (just a copy of my that_canadian keymap). * Added a README file to the Let's Split Eh? * Changed it so RGB static updates are done on key-up ONLY for split boards rather than all boards. Also fixed leftover un-used variable in rgblight.c * Updated default keymap and my keymap for Let's Split Eh? Updated the comments so it reflects RGB control, and removed audio functions. * Fixed lets_split_eh not having a default version * Removed "eh" references from lets_split folder for now * Took lets_split folder from master to fix travis build errors, weird my local was overriding. * Changed LAYOUT_ortho_4x12_kc -> LAYOUT_kc_ortho_4x12 to match bakingpy and others * Removed rules.mk from my lets_split keymap, not needed * Updated the config_options doc to better explain the usage of "#define SPLIT_HAND_PIN"
6 years ago
## Split Keyboard Options
Split Keyboard specific options, make sure you have 'SPLIT_KEYBOARD = yes' in your rules.mk
### 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
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
* `#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.
* `#define EE_HANDS` (only works if `SPLIT_HAND_PIN` is not defined)
* Reads the handedness value stored in the EEPROM after `eeprom-lefthand.eep`/`eeprom-righthand.eep` has been flashed to their respective halves.
* `#define MASTER_RIGHT`
* Master half is defined to be the right half.
### Other Options
Lets split eh (#3120) * Line ending stuff again * Added Let's Split Eh? Files and updated #USE_IC2 checks to also include th EH revision (can only be used in I2C) * Added personal keymap, updated some of the EH files * Created new keyboard file for testing "lets_split_eh" will merge into lets_split once fully functional * Added split code from lets_split, removed pro micro imports and LED code THIS IS WORKING CODE, WITHOUT RGB AND BACKLIGHT * Took back original Lets Slit files for the lets_split keyboard, working in the lets_split_eh folder for now * Updated eh.c * More rework of the I2C code, added global flags for split boards. * Introduced RGB over I2C, having weird edge case issues at the moment though * Fixed weird I2C edgecase with RGB, although still would like to track down route cause.. * Changed RGB keycodes (static ones) to activate on key-up instead of key-down to elimate weird ghosting issue over I2C * Lots of changes, mainly externalized the Split keyboard code and added logic for only including when needed. - Added makefile option "SPLIT_KEYBOARD" that when = yes will include the split keyboard files and custom matrix - Split keyboard files placed into quantum/split_common/ - Added define option for config files "SPLIT_HAND_PIN" FOr using high/low pin to determine handedness, low = right hand, high = left hand - Cleaned up split logic for RGB and Backlight so it is only exectuted / included when needed * Updated documentation for the new makefile options and #defines specific to split keyboards * Added a bit more info to docs, so people aren't confused * Modifed Let's Split to use externalized code, also added left and right hand eeprom files to the split_common folder * Removed some debugging from eh.c * Small changes to keyboard configs. Also added a default keymap (just a copy of my that_canadian keymap). * Added a README file to the Let's Split Eh? * Changed it so RGB static updates are done on key-up ONLY for split boards rather than all boards. Also fixed leftover un-used variable in rgblight.c * Updated default keymap and my keymap for Let's Split Eh? Updated the comments so it reflects RGB control, and removed audio functions. * Fixed lets_split_eh not having a default version * Removed "eh" references from lets_split folder for now * Took lets_split folder from master to fix travis build errors, weird my local was overriding. * Changed LAYOUT_ortho_4x12_kc -> LAYOUT_kc_ortho_4x12 to match bakingpy and others * Removed rules.mk from my lets_split keymap, not needed * Updated the config_options doc to better explain the usage of "#define SPLIT_HAND_PIN"
6 years ago
* `#define USE_I2C`
* For using I2C instead of Serial (defaults to serial)
Make quantum/split_common/serial.[ch] configurable (#4419) * add temporary compile test shell script * add 'CONFIG_H += serial_backward_compatibility.h' into common_features.mk:SPLIT_KEYBOARD block * add quantum/split_common/serial_backward_compatibility.h SERIAL_PIN_PORT and other PIN define move to serial_backward_compatibility.h SERIAL_BACKLIT_START move to split_util.h * quantum/split_common/serial.c change to helix-serial.c style serial configuration * add temporary file quantum/split_common/split-keyboards-list.txt * add '#define SOFT_SERIAL_PIN D0' to keyboards/6lit/config.h * add '#define SOFT_SERIAL_PIN D0' to keyboards/divergetm2/config.h * add '#define SOFT_SERIAL_PIN D0' to keyboards/ergotravel/rev1/config.h * add '#define SOFT_SERIAL_PIN D0' to keyboards/foobar/config.h * add '#define SOFT_SERIAL_PIN D0' to keyboards/handwired/dactyl_manuform/config.h * add '#define SOFT_SERIAL_PIN D0' to keyboards/handwired/qc60/config.h * add '//#define SOFT_SERIAL_PIN D0' to keyboards/handwired/xealous/config.h * add '#define SOFT_SERIAL_PIN D0' to keyboards/iris/rev*/config.h * add '//#define SOFT_SERIAL_PIN D0' to keyboards/lets_split_eh/config.h * add '#define SOFT_SERIAL_PIN D0' to keyboards/levinson/rev*/config.h * add '#define SOFT_SERIAL_PIN D0' to keyboards/miniaxe/config.h * add '#define SOFT_SERIAL_PIN D0' to keyboards/nyquist/rev?/config.h * add '#define SOFT_SERIAL_PIN D0' to keyboards/quefrency/rev1/config.h * add '#define SOFT_SERIAL_PIN D0' to keyboards/qwertyydox/config.h,keyboards/qwertyydox/rev1/config.h * add '#define SOFT_SERIAL_PIN D0' to keyboards/redox/rev1/config.h * add '#define SOFT_SERIAL_PIN D0' to keyboards/rorschach/rev1/config.h * remove '#define SOFT_SERIAL_PIN D0' from quantum/split_common/serial_backward_compatibility.h * remove temporary file quantum/split_common/split-keyboards-list.txt * remove temporary compile test shell script * Revert "remove temporary compile test shell script" This reverts commit 15b0021b4092127b8d8a21f572642ad3702b46d4. * update quantum/split_common/compile_split_test.sh for new keyboard test * add '#define SOFT_SERIAL_PIN D0' to keyboards/diverge3/config.h * add '#define SOFT_SERIAL_PIN D0' to keyboards/40percentclub/25/config.h * remove temporary compile test shell script * update docs/config_options.md, quantum/template/avr/config.h * fix quantum/template/avr/config.h * fix typo docs/config_options.md
6 years ago
* `#define SOFT_SERIAL_PIN D0`
* 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.
* `#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
# The `rules.mk` File
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.
* `LAYOUTS`
* A list of [layouts](feature_layouts.md) this keyboard supports.
## 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:
* `atmel-dfu`
* `lufa-dfu`
* `qmk-dfu`
* `halfkay`
* `caterina`
* `bootloadHID`
## Feature 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.
* `BOOTMAGIC_ENABLE`
* Virtual DIP switch configuration(+1000)
* `MOUSEKEY_ENABLE`
* Mouse keys(+4700)
* `EXTRAKEY_ENABLE`
* Audio control and System control(+450)
* `CONSOLE_ENABLE`
* Console for debug(+400)
* `COMMAND_ENABLE`
* Commands for debug and configuration
* `COMBO_ENABLE`
* Key combo feature
* `NKRO_ENABLE`
* USB N-Key Rollover - if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work
* `AUDIO_ENABLE`
* Enable the audio subsystem.
* `RGBLIGHT_ENABLE`
* Enable keyboard underlight functionality
* `LEADER_ENABLE`
* Enable leader key chording
* `MIDI_ENABLE`
* MIDI controls
* `UNICODE_ENABLE`
* Unicode
* `BLUETOOTH_ENABLE`
* Legacy option to Enable Bluetooth with the Adafruit EZ-Key HID. See BLUETOOTH
* `BLUETOOTH`
* Current options are AdafruitEzKey, AdafruitBLE, RN42
Lets split eh (#3120) * Line ending stuff again * Added Let's Split Eh? Files and updated #USE_IC2 checks to also include th EH revision (can only be used in I2C) * Added personal keymap, updated some of the EH files * Created new keyboard file for testing "lets_split_eh" will merge into lets_split once fully functional * Added split code from lets_split, removed pro micro imports and LED code THIS IS WORKING CODE, WITHOUT RGB AND BACKLIGHT * Took back original Lets Slit files for the lets_split keyboard, working in the lets_split_eh folder for now * Updated eh.c * More rework of the I2C code, added global flags for split boards. * Introduced RGB over I2C, having weird edge case issues at the moment though * Fixed weird I2C edgecase with RGB, although still would like to track down route cause.. * Changed RGB keycodes (static ones) to activate on key-up instead of key-down to elimate weird ghosting issue over I2C * Lots of changes, mainly externalized the Split keyboard code and added logic for only including when needed. - Added makefile option "SPLIT_KEYBOARD" that when = yes will include the split keyboard files and custom matrix - Split keyboard files placed into quantum/split_common/ - Added define option for config files "SPLIT_HAND_PIN" FOr using high/low pin to determine handedness, low = right hand, high = left hand - Cleaned up split logic for RGB and Backlight so it is only exectuted / included when needed * Updated documentation for the new makefile options and #defines specific to split keyboards * Added a bit more info to docs, so people aren't confused * Modifed Let's Split to use externalized code, also added left and right hand eeprom files to the split_common folder * Removed some debugging from eh.c * Small changes to keyboard configs. Also added a default keymap (just a copy of my that_canadian keymap). * Added a README file to the Let's Split Eh? * Changed it so RGB static updates are done on key-up ONLY for split boards rather than all boards. Also fixed leftover un-used variable in rgblight.c * Updated default keymap and my keymap for Let's Split Eh? Updated the comments so it reflects RGB control, and removed audio functions. * Fixed lets_split_eh not having a default version * Removed "eh" references from lets_split folder for now * Took lets_split folder from master to fix travis build errors, weird my local was overriding. * Changed LAYOUT_ortho_4x12_kc -> LAYOUT_kc_ortho_4x12 to match bakingpy and others * Removed rules.mk from my lets_split keymap, not needed * Updated the config_options doc to better explain the usage of "#define SPLIT_HAND_PIN"
6 years ago
* `SPLIT_KEYBOARD`
* 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
* `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.
Use a single endpoint for HID reports (#3951) * Unify multiple HID interfaces into one This reduces the number of USB endpoints required, which frees them up for other things. NKRO and EXTRAKEY always use the shared endpoint. By default, MOUSEKEY also uses it. This means it won't work as a Boot Procotol mouse in some BIOSes, etc. If you really think your keyboard needs to work as a mouse in your BIOS, set MOUSE_SHARED_EP = no in your rules.mk. By default, the core keyboard does not use the shared endpoint, as not all BIOSes are standards compliant and that's one place you don't want to find out your keyboard doesn't work.. If you are really confident, you can set KEYBOARD_SHARED_EP = yes to use the shared endpoint here too. * unify endpoints: ChibiOS protocol implementation * fixup: missing #ifdef EXTRAKEY_ENABLEs broke build on AVR with EXTRAKEY disabled * endpoints: restore error when too many endpoints required * lufa: wait up to 10ms to send keyboard input This avoids packets being dropped when two reports are sent in quick succession (eg. releasing a dual role key). * endpoints: fix compile on ARM_ATSAM * endpoint: ARM_ATSAM fixes No longer use wrong or unexpected endpoint IDs * endpoints: accommodate VUSB protocol V-USB has its own, understandably simple ideas about the report formats. It already blasts the mouse and extrakeys through one endpoint with report IDs. We just stay out of its way. * endpoints: document new endpoint configuration options * endpoints: respect keyboard_report->mods in NKRO The caller(s) of host_keyboard_send expect to be able to just drop modifiers in the mods field and not worry about whether NKRO is in use. This is a good thing. So we just shift it over if needs be. * endpoints: report.c: update for new keyboard_report format
6 years ago
## USB Endpoint Limitations
In order to provide services over USB, QMK has to use USB endpoints.
These are a finite resource: each microcontroller has only a certain number.
This limits what features can be enabled together.
If the available endpoints are exceeded, a build error is thrown.
The following features can require separate endpoints:
* `MOUSEKEY_ENABLE`
* `EXTRAKEY_ENABLE`
* `CONSOLE_ENABLE`
* `NKRO_ENABLE`
* `MIDI_ENABLE`
* `RAW_ENABLE`
* `VIRTSER_ENABLE`
In order to improve utilisation of the endpoints, the HID features can be combined to use a single endpoint.
By default, `MOUSEKEY`, `EXTRAKEY`, and `NKRO` are combined into a single endpoint.
The base keyboard functionality can also be combined into the endpoint,
by setting `KEYBOARD_SHARED_EP = yes`.
This frees up one more endpoint,
but it can prevent the keyboard working in some BIOSes,
as they do not implement Boot Keyboard protocol switching.
Combining the mouse also breaks Boot Mouse compatibility.
The mouse can be uncombined by setting `MOUSE_SHARED_EP = no` if this functionality is required.