diff options
Diffstat (limited to 'docs/config_options.md')
| -rw-r--r-- | docs/config_options.md | 109 |
1 files changed, 99 insertions, 10 deletions
diff --git a/docs/config_options.md b/docs/config_options.md index afc29fae9c..085ab3ee58 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -119,8 +119,8 @@ If you define these options you will enable the associated feature, which may in * `#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 PREVENT_STUCK_MODIFIERS` - * 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 +* `#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 @@ -132,16 +132,22 @@ If you define these options you will enable the associated feature, which may in * `#define TAPPING_TOGGLE 2` * how many taps before triggering the toggle * `#define PERMISSIVE_HOLD` - * makes tap and hold keys work better for fast typers who don't want tapping term set above 500 + * 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 - * See [Mod tap interrupt](feature_advanced_keycodes.md#mod-tap-interrupt) for details + * 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#hold-after-tap) + * 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` @@ -155,6 +161,12 @@ If you define these options you will enable the associated feature, which may in 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 @@ -185,12 +197,48 @@ If you define these options you will enable the associated feature, which may in Split Keyboard specific options, make sure you have 'SPLIT_KEYBOARD = yes' in your rules.mk -* `#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 you can still use the EEHANDS method or MASTER_LEFT / MASTER_RIGHT defines like the stock Let's Split uses. - +### 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 + * `#define USE_I2C` * For using I2C instead of Serial (defaults to serial) +* `#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. @@ -199,6 +247,8 @@ This is a [make](https://www.gnu.org/software/make/manual/make.html) file that i * `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` @@ -232,17 +282,56 @@ Use these to enable or disable building certain features. The more you have enab * 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` - * Enable Bluetooth with the Adafruit EZ-Key HID + * Legacy option to Enable Bluetooth with the Adafruit EZ-Key HID. See BLUETOOTH +* `BLUETOOTH` + * Current options are AdafruitEzKey, AdafruitBLE, RN42 * `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. + +## 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. |