diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 9a4d98b9c2..d5d8b01de5 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,10 +1,10 @@ # Code Of Conduct -QMK strives to be an inclusive and tolerant community. We welcome participation from anyone regardless of age, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, political belief, race, religion, or sexual identity and orientation. +QMK strives to be an inclusive, tolerant, and welcoming community. We encourage participation from anyone regardless of age, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, political belief, race, religion, or sexual identity and orientation. -> “A gentle word turns away wrath, but a harsh word stirs up anger.” +> “A gentle word turns away wrath, but a harsh word stirs up anger." -Our users, contributors, and collaborators are expected to treat each other with respect, to assume good intentions, and to gently correct, where possible, rather than react with escalation. Some examples of behavior we will not tolerate include, but is not limited to: +Our users, contributors, and collaborators are expected to treat each other with kindness and respect, to assume good intentions, and to gently correct, where possible, rather than react with escalation. While our goal is to be as accurate as possible, kindness and understanding are more valuable than correctness. Some examples of behavior we will not tolerate include, but is not limited to: * The use of sexualized language or imagery * Unwelcome advances, sexual or otherwise diff --git a/docs/_sidebar.md b/docs/_sidebar.md index a4216122a2..6c56bb2e51 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -44,8 +44,8 @@ * [PS/2 Mouse](feature_ps2_mouse.md) * [RGB Lighting](feature_rgblight.md) * [RGB Matrix](feature_rgb_matrix.md) - * [Space Cadet Shift](feature_space_cadet.md) - * [Space Cadet Shift Enter](feature_space_shift_cadet.md) + * [Space Cadet Shift](feature_space_cadet_shift.md) + * [Space Cadet Shift Enter](feature_space_cadet_shift_enter.md) * [Stenography](feature_stenography.md) * [Swap Hands](feature_swap_hands.md) * [Tap Dance](feature_tap_dance.md) diff --git a/docs/_summary.md b/docs/_summary.md index a4216122a2..6c56bb2e51 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -44,8 +44,8 @@ * [PS/2 Mouse](feature_ps2_mouse.md) * [RGB Lighting](feature_rgblight.md) * [RGB Matrix](feature_rgb_matrix.md) - * [Space Cadet Shift](feature_space_cadet.md) - * [Space Cadet Shift Enter](feature_space_shift_cadet.md) + * [Space Cadet Shift](feature_space_cadet_shift.md) + * [Space Cadet Shift Enter](feature_space_cadet_shift_enter.md) * [Stenography](feature_stenography.md) * [Swap Hands](feature_swap_hands.md) * [Tap Dance](feature_tap_dance.md) diff --git a/docs/faq_keymap.md b/docs/faq_keymap.md index 674d207aa9..447b892262 100644 --- a/docs/faq_keymap.md +++ b/docs/faq_keymap.md @@ -87,14 +87,14 @@ On **Xorg** you can use `compose` key, instead. And see this for **Unicode** input. * http://en.wikipedia.org/wiki/Unicode_input +## `Fn` Key on macOS -## Apple/Mac Keyboard `Fn` -Not supported. +Unlike most Fn keys, the one on Apple keyboards actually has its own keycode... sort of. It takes the place of the sixth keycode in a basic 6KRO HID report -- so an Apple keyboard is in fact only 5KRO. -Apple/Mac keyboard sends keycode for Fn unlike most of other keyboards. -I think you can send Apple Fn key using Apple venter specific Page 0xff01 and usage 0x0003. But you have to change HID Report Descriptor for this, of course. +It is technically possible to get QMK to send this key. However, doing so requires modification of the report format to add the state of the Fn key. +Even worse, it is not recognized unless the keyboard's VID and PID match that of a real Apple keyboard. The legal issues that official QMK support for this feature may create mean it is unlikely to happen. -https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/AppleHIDUsageTables.h +See [this issue](https://github.com/qmk/qmk_firmware/issues/2179) for detailed information. ## Media Control Keys in Mac OSX diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md index f03a7121c4..493a99fd73 100644 --- a/docs/feature_advanced_keycodes.md +++ b/docs/feature_advanced_keycodes.md @@ -133,7 +133,7 @@ We've added shortcuts to make common modifier/tap (mod-tap) mappings more compac ?> Due to the way that keycodes are structured, any modifiers specified as part of `kc`, such as `LCTL()` or `KC_LPRN`, will only activate when held instead of tapped. -?> Additionally, if there is at least one right modifier, any other modifiers will turn into their right equivalents, so it is not possible to "mix and match" the two. +?> Additionally, if there is at least one right-handed modifier, any other modifiers in a chain of functions will turn into their right-handed equivalents, so it is not possible to "mix and match" the two. # One Shot Keys diff --git a/docs/feature_backlight.md b/docs/feature_backlight.md index 5336e85266..6140e6a0ab 100644 --- a/docs/feature_backlight.md +++ b/docs/feature_backlight.md @@ -1,10 +1,20 @@ # Backlighting - +Many keyboards support backlit keys by way of individual LEDs placed through or underneath the keyswitches. QMK is able to control the brightness of these LEDs by switching them on and off rapidly in a certain ratio, a technique known as *Pulse Width Modulation*, or PWM. By altering the duty cycle of the PWM signal, it creates the illusion of dimming. -## Backlight Keycodes +The MCU can only supply so much current to its GPIO pins. Instead of powering the backlight directly from the MCU, the backlight pin is connected to a transistor or MOSFET that switches the power to the LEDs. -These keycodes control the backlight. Most keyboards use this for single color in-switch lighting. +## Usage + +Most keyboards have backlighting enabled by default if they support it, but if it is not working for you, check that your `rules.mk` includes the following: + +```make +BACKLIGHT_ENABLE = yes +``` + +You should then be able to use the keycodes below to change the backlight level. + +## Keycodes |Key |Description | |---------|------------------------------------------| @@ -16,24 +26,28 @@ These keycodes control the backlight. Most keyboards use this for single color i |`BL_DEC` |Decrease the backlight level | |`BL_BRTG`|Toggle backlight breathing | -Note that for backlight breathing, you need to have `#define BACKLIGHT_BREATHING` in your config.h. +## Caveats + +This feature is distinct from both the [RGB underglow](feature_rgblight.md) and [RGB matrix](feature_rgb_matrix.md) features as it usually allows for only a single colour per switch, though you can obviously use multiple different coloured LEDs on a keyboard. + +Hardware PWM is only supported on certain pins of the MCU, so if the backlighting is not connected to one of them, a software implementation will be used, and backlight breathing will not be available. Currently the supported pins are `B5`, `B6`, `B7`, and `C6`. + +## Configuration -## Configuration Options in `config.h` +To change the behaviour of the backlighting, `#define` these in your `config.h`: -* `BACKLIGHT_PIN B7` defines the pin that controlls the LEDs. Unless you design your own keyboard, you don't need to set this. -* `BACKLIGHT_LEVELS 3` defines the number of brightness levels (maximum 15 excluding off). -* `BACKLIGHT_BREATHING` if defined, enables backlight breathing. Note that this is only available if `BACKLIGHT_PIN` is B5, B6 or B7. -* `BREATHING_PERIOD 6` defines the length of one backlight "breath" in seconds. +|Define |Default |Description | +|---------------------|-------------|-------------------------------------------------------------------------------------------------------------| +|`BACKLIGHT_PIN` |`B7` |The pin that controls the LEDs. Unless you are designing your own keyboard, you shouldn't need to change this| +|`BACKLIGHT_LEVELS` |`3` |The number of brightness levels (maximum 15 excluding off) | +|`BACKLIGHT_BREATHING`|*Not defined*|Enable backlight breathing, if hardware PWM is used | +|`BREATHING_PERIOD` |`6` |The length of one backlight "breath" in seconds | -## Notes on Implementation +## Hardware PWM Implementation -To change the brightness when using pins B5, B6 or B7, the PWM (Pulse Width Modulation) functionality of the on-chip timer is used. -The timer is a counter that counts up to a certain TOP value (`0xFFFF` set in ICR1) before resetting to 0. -We also set an OCR1x register. -When the counter reaches the value stored in that register, the PWM pin drops to low. -The PWM pin is pulled high again when the counter resets to 0. -Therefore, OCR1x basically sets the duty cycle of the LEDs and as such the brightness where `0` is the darkest and `0xFFFF` the brightest setting. +When using the supported pins for backlighting, QMK will use a hardware timer configured to output a PWM signal. This timer will count up to `ICRx` (by default `0xFFFF`) before resetting to 0. +The desired brightness is calculated and stored in the `OCRxx` register. When the counter reaches this value, the backlight pin will go low, and is pulled high again when the counter resets. +In this way `OCRxx` essentially controls the duty cycle of the LEDs, and thus the brightness, where `0x0000` is completely off and `0xFFFF` is completely on. -To enable the breathing effect, we register an interrupt handler to be called whenever the counter resets (with `ISR(TIMER1_OVF_vect)`). -In this handler, which gets called roughly 244 times per second, we compute the desired brightness using a precomputed brightness curve. -To disable breathing, we can just disable the respective interrupt vector and reset the brightness to the desired level. +The breathing effect is achieved by registering an interrupt handler for `TIMER1_OVF_vect` that is called whenever the counter resets, roughly 244 times per second. +In this handler, the value of an incrementing counter is mapped onto a precomputed brightness curve. To turn off breathing, the interrupt handler is simply disabled, and the brightness reset to the level stored in EEPROM. diff --git a/docs/feature_bootmagic.md b/docs/feature_bootmagic.md index beef6c467e..d6915d3559 100644 --- a/docs/feature_bootmagic.md +++ b/docs/feature_bootmagic.md @@ -1,89 +1,100 @@ -# Bootmagic and Magic Keycodes +# Bootmagic -There are 3 separate but related features that allow you to change the behavior of your keyboard without reflashing. While each of them have similar functionality you access that functionality in different ways depending on how your keyboard is configured. +There are three separate but related features that allow you to change the behavior of your keyboard without reflashing. While each of them have similar functionality, it is accessed in different ways depending on how your keyboard is configured. -Bootmagic is a system for configuring your keyboard while it initializes. To trigger a Bootmagic command you hold down the bootmagic key (`KC_SPACE` on most keyboards) and one or more command keys. +**Bootmagic** is a system for configuring your keyboard while it initializes. To trigger a Bootmagic command, hold down the Bootmagic key and one or more command keys. -Bootmagic Keycodes allow you to access the Bootmagic functionality after your keyboard has initialized. To use Bootmagic Keycodes you assign keycodes starting with `MAGIC_`, much in the same way you define any other key. +**Bootmagic Keycodes** are prefixed with `MAGIC_`, and allow you to access the Bootmagic functionality *after* your keyboard has initialized. To use the keycodes, assign them to your keymap as you would any other keycode. -Command is a feature that allows you to control different aspects of your keyboard. Command used to be called Magic. Command is typically accessed by holding Left and Right Shift at the same time, although that can be customized. While it shares some functionality with Bootmagic it also allows you to access functionality that Bootmagic does not. For more information see the [Command](feature_command.md) documentation page. +**Command**, formerly known as **Magic**, is another feature that allows you to control different aspects of your keyboard. While it shares some functionality with Bootmagic, it also allows you to do things that Bootmagic does not, such as printing version information to the console. For more information, see [Command](feature_command.md). -## Enabling Bootmagic +On some keyboards Bootmagic is disabled by default. If this is the case, it must be explicitly enabled in your `rules.mk` with: -Bootmagic is disabled by default. To use Bootmagic you need to enable it in your `rules.mk` file: +```make +BOOTMAGIC_ENABLE = yes +``` - BOOTMAGIC_ENABLE = yes +## Hotkeys -## Bootmagic Hotkeys and Keycodes +Hold down the Bootmagic key (Space by default) and the desired hotkey while plugging in your keyboard. For example, holding Space+`B` should cause it to enter the bootloader. -This table describes the default Hotkeys for Bootmagic and the Keycodes for Magic. These may be overriden at the Keyboard or Keymap level. Some functionality is not available in both methods. +|Hotkey |Description | +|------------------|---------------------------------------------| +|Escape |Ignore Bootmagic configuration in EEPROM | +|`B` |Enter the bootloader | +|`D` |Toggle debugging over serial | +|`X` |Toggle key matrix debugging | +|`K` |Toggle keyboard debugging | +|`M` |Toggle mouse debugging | +|Backspace |Clear the EEPROM | +|Caps Lock |Toggle treating Caps Lock as Left Control | +|Left Control |Toggle swapping Caps Lock and Left Control | +|Left Alt |Toggle swapping Left Alt and Left GUI | +|Right Alt |Toggle swapping Right Alt and Right GUI | +|Left GUI |Toggle the GUI keys (useful when gaming) | +|`|Toggle swapping ` and Escape| +|`\` |Toggle swapping `\` and Backspace | +|`N` |Toggle N-Key Rollover (NKRO) | +|`0` |Make layer 0 the default layer | +|`1` |Make layer 1 the default layer | +|`2` |Make layer 2 the default layer | +|`3` |Make layer 3 the default layer | +|`4` |Make layer 4 the default layer | +|`5` |Make layer 5 the default layer | +|`6` |Make layer 6 the default layer | +|`7` |Make layer 7 the default layer | -To use the Hotkey hold down `BOOTMAGIC_KEY_SALT` (`KC_SPACE` by default) and the Hotkey while plugging in your keyboard. To use the Keycode assign that keycode to a layer. For example, if you hold down Space+B while plugging in most keyboards, you will enter bootloader mode. +## Keycodes -|Hotkey |Keycode |Description | -|-----------|----------------------------------|--------------------------------------------------------| -|`ESC` | |Skip bootmagic and saved eeprom configuration | -|`B` |`RESET` |Enter bootloader instead of firmware | -|`D` |`DEBUG` |Enable debugging (writes messages to serial) | -|`X` | |Enable matrix debugging | -|`K` | |Enable keyboard debugging | -|`M` | |Enable mouse debugging | -|`BACKSPACE`| |Clear the saved settings from flash | -|`CAPSLOCK` |`MAGIC_CAPSLOCK_TO_CONTROL` |Treat `Capslock` as `Control` | -| |`MAGIC_UNCAPSLOCK_TO_CONTROL` |Stop treating CapsLock as Control | -|`LCTRL` |`MAGIC_SWAP_CONTROL_CAPSLOCK` |Swap `Control` and `Capslock` | -| |`MAGIC_UNSWAP_CONTROL_CAPSLOCK` |Unswap Left Control and Caps Lock | -| |`MAGIC_SWAP_ALT_GUI` |Swap Alt and GUI on both sides | -| |`MAGIC_UNSWAP_ALT_GUI` |Unswap Left Alt and GUI | -|`LALT` |`MAGIC_SWAP_LALT_LGUI` |Swap Left `Alt` and `GUI`, e.g. for OSX Opt and Cmd | -| |`MAGIC_UNSWAP_LALT_LGUI` |Unswap Left Alt and GUI | -|`RALT` |`MAGIC_SWAP_RALT_RGUI` |Swap Right `Alt` and `GUI` | -| |`MAGIC_UNSWAP_RALT_RGUI` |Unswap Right Alt and GUI | -|`LGUI` |`MAGIC_NO_GUI` |Disable GUI key - e.g. disable Windows key during gaming| -| |`MAGIC_UNNO_GUI` |Enable the GUI key | -|`GRAVE` |`MAGIC_SWAP_GRAVE_ESC` |Swap `\`~` and `ESC` | -| |`MAGIC_UNSWAP_GRAVE_ESC` |Unswap `\`~` and Escape | -|`BACKSLASH`|`MAGIC_SWAP_BACKSLASH_BACKSPACE` |Swap Blackslash and Backspace | -| |`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|Unswap Backslash and Backspace | -|`N` |`MAGIC_HOST_NKRO` |Force N-Key Rollover (NKRO) on | -| |`MAGIC_UNHOST_NKRO` |Force NKRO off | -| |`MAGIC_TOGGLE_NKRO` |Toggle NKRO on or off | -|`0` |`DF(0)` |Make Layer 0 the default layer at bootup | -|`1` |`DF(1)` |Make Layer 1 the default layer at bootup | -|`2` |`DF(2)` |Make Layer 2 the default layer at bootup | -|`3` |`DF(3)` |Make Layer 3 the default layer at bootup | -|`4` |`DF(4)` |Make Layer 4 the default layer at bootup | -|`5` |`DF(5)` |Make Layer 5 the default layer at bootup | -|`6` |`DF(6)` |Make Layer 6 the default layer at bootup | -|`7` |`DF(7)` |Make Layer 7 the default layer at bootup | +|Keycode |Aliases |Description | +|----------------------------------|---------|------------------------------------------| +|`MAGIC_CAPSLOCK_TO_CONTROL` | |Treat Caps Lock as Left Control | +|`MAGIC_UNCAPSLOCK_TO_CONTROL` | |Stop treating Caps Lock as Left Control | +|`MAGIC_HOST_NKRO` | |Force N-Key Rollover (NKRO) on | +|`MAGIC_UNHOST_NKRO` | |Force NKRO off | +|`MAGIC_TOGGLE_NKRO` | |Turn NKRO on or off | +|`MAGIC_NO_GUI` | |Disable the GUI keys (useful when gaming) | +|`MAGIC_UNNO_GUI` | |Enable the GUI keys | +|`MAGIC_SWAP_ALT_GUI` |`AG_SWAP`|Swap Alt and GUI on both sides (for macOS)| +|`MAGIC_UNSWAP_ALT_GUI` |`AG_NORM`|Unswap Left Alt and Left GUI | +|`MAGIC_SWAP_BACKSLASH_BACKSPACE` | |Swap `\` and Backspace | +|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`| |Unswap `\` and Backspace | +|`MAGIC_SWAP_CONTROL_CAPSLOCK` | |Swap Left Control and Caps Lock | +|`MAGIC_UNSWAP_CONTROL_CAPSLOCK` | |Unswap Left Control and Caps Lock | +|`MAGIC_SWAP_GRAVE_ESC` | |Swap ` and Escape | +|`MAGIC_UNSWAP_GRAVE_ESC` | |Unswap ` and Escape | +|`MAGIC_SWAP_LALT_LGUI` | |Swap Left Alt and Left GUI | +|`MAGIC_UNSWAP_LALT_LGUI` | |Unswap Left Alt and Left GUI | +|`MAGIC_SWAP_RALT_RGUI` | |Swap Right Alt and Right GUI | +|`MAGIC_UNSWAP_RALT_RGUI` | |Unswap Right Alt and Right GUI | -## Bootmagic Configuration +## Configuration -When setting up your keyboard and/or keymap there are a number of `#define`s that control the behavior of Bootmagic. To use these put them in your `config.h`, either at the keyboard or keymap level. +If you would like to change the hotkey assignments for Bootmagic, `#define` these in your `config.h` at either the keyboard or keymap level. -|Define |Default|Description | -|-------|-------|------------| -|`BOOTMAGIC_KEY_SALT`|`KC_SPACE`|The key to hold down to trigger Bootmagic during initialization.| -|`BOOTMAGIC_KEY_SKIP`|`KC_ESC`|The Hotkey to ignore saved eeprom configuration.| -|`BOOTMAGIC_KEY_EEPROM_CLEAR`|`KC_BSPACE`|The hotkey to clear the saved eeprom configuration.| -|`BOOTMAGIC_KEY_BOOTLOADER`|`KC_B`|The hotkey to enter the bootloader.| -|`BOOTMAGIC_KEY_DEBUG_ENABLE`|`KC_D`|The hotkey to enable debug mode.| -|`BOOTMAGIC_KEY_DEBUG_MATRIX`|`KC_X`|The hotkey to enable matrix debugging mode.| -|`BOOTMAGIC_KEY_DEBUG_KEYBOARD`|`KC_K`|The hotkey to enable keyboard debugging mode.| -|`BOOTMAGIC_KEY_DEBUG_MOUSE`|`KC_M`|The hotkey to enable mouse debugging mode.| -|`BOOTMAGIC_KEY_SWAP_CONTROL_CAPSLOCK`|`KC_LCTRL`|| -|`BOOTMAGIC_KEY_CAPSLOCK_TO_CONTROL`|`KC_CAPSLOCK`|| -|`BOOTMAGIC_KEY_SWAP_LALT_LGUI`|`KC_LALT`|| -|`BOOTMAGIC_KEY_SWAP_RALT_RGUI`|`KC_RALT`|| -|`BOOTMAGIC_KEY_NO_GUI`|`KC_LGUI`|| -|`BOOTMAGIC_KEY_SWAP_GRAVE_ESC`|`KC_GRAVE`|| -|`BOOTMAGIC_KEY_SWAP_BACKSLASH_BACKSPACE`|`KC_BSLASH`|| -|`BOOTMAGIC_HOST_NKRO`|`KC_N`|| -|`BOOTMAGIC_KEY_DEFAULT_LAYER_0`|`KC_0`|Hotkey to set Layer 0 as the default layer| -|`BOOTMAGIC_KEY_DEFAULT_LAYER_1`|`KC_1`|Hotkey to set Layer 1 as the default layer| -|`BOOTMAGIC_KEY_DEFAULT_LAYER_2`|`KC_2`|Hotkey to set Layer 2 as the default layer| -|`BOOTMAGIC_KEY_DEFAULT_LAYER_3`|`KC_3`|Hotkey to set Layer 3 as the default layer| -|`BOOTMAGIC_KEY_DEFAULT_LAYER_4`|`KC_4`|Hotkey to set Layer 4 as the default layer| -|`BOOTMAGIC_KEY_DEFAULT_LAYER_5`|`KC_5`|Hotkey to set Layer 5 as the default layer| -|`BOOTMAGIC_KEY_DEFAULT_LAYER_6`|`KC_6`|Hotkey to set Layer 6 as the default layer| -|`BOOTMAGIC_KEY_DEFAULT_LAYER_7`|`KC_7`|Hotkey to set Layer 7 as the default layer| +|Define |Default |Description | +|----------------------------------------|-------------|---------------------------------------------------| +|`BOOTMAGIC_KEY_SALT` |`KC_SPACE` |The Bootmagic key | +|`BOOTMAGIC_KEY_SKIP` |`KC_ESC` |Ignore Bootmagic configuration in EEPROM | +|`BOOTMAGIC_KEY_EEPROM_CLEAR` |`KC_BSPACE` |Clear the EEPROM configuration | +|`BOOTMAGIC_KEY_BOOTLOADER` |`KC_B` |Enter the bootloader | +|`BOOTMAGIC_KEY_DEBUG_ENABLE` |`KC_D` |Toggle debugging over serial | +|`BOOTMAGIC_KEY_DEBUG_MATRIX` |`KC_X` |Toggle matrix debugging | +|`BOOTMAGIC_KEY_DEBUG_KEYBOARD` |`KC_K` |Toggle keyboard debugging | +|`BOOTMAGIC_KEY_DEBUG_MOUSE` |`KC_M` |Toggle mouse debugging | +|`BOOTMAGIC_KEY_SWAP_CONTROL_CAPSLOCK` |`KC_LCTRL` |Swap Left Control and Caps Lock | +|`BOOTMAGIC_KEY_CAPSLOCK_TO_CONTROL` |`KC_CAPSLOCK`|Toggle treating Caps Lock as Left Control | +|`BOOTMAGIC_KEY_SWAP_LALT_LGUI` |`KC_LALT` |Toggle swapping Left Alt and Left GUI (for macOS) | +|`BOOTMAGIC_KEY_SWAP_RALT_RGUI` |`KC_RALT` |Toggle swapping Right Alt and Right GUI (for macOS)| +|`BOOTMAGIC_KEY_NO_GUI` |`KC_LGUI` |Toggle the GUI keys (useful when gaming) | +|`BOOTMAGIC_KEY_SWAP_GRAVE_ESC` |`KC_GRAVE` |Toggle swapping ` and Escape | +|`BOOTMAGIC_KEY_SWAP_BACKSLASH_BACKSPACE`|`KC_BSLASH` |Toggle swapping `\` and Backspace | +|`BOOTMAGIC_HOST_NKRO` |`KC_N` |Toggle N-Key Rollover (NKRO) | +|`BOOTMAGIC_KEY_DEFAULT_LAYER_0` |`KC_0` |Make layer 0 the default layer | +|`BOOTMAGIC_KEY_DEFAULT_LAYER_1` |`KC_1` |Make layer 1 the default layer | +|`BOOTMAGIC_KEY_DEFAULT_LAYER_2` |`KC_2` |Make layer 2 the default layer | +|`BOOTMAGIC_KEY_DEFAULT_LAYER_3` |`KC_3` |Make layer 3 the default layer | +|`BOOTMAGIC_KEY_DEFAULT_LAYER_4` |`KC_4` |Make layer 4 the default layer | +|`BOOTMAGIC_KEY_DEFAULT_LAYER_5` |`KC_5` |Make layer 5 the default layer | +|`BOOTMAGIC_KEY_DEFAULT_LAYER_6` |`KC_6` |Make layer 6 the default layer | +|`BOOTMAGIC_KEY_DEFAULT_LAYER_7` |`KC_7` |Make layer 7 the default layer | diff --git a/docs/feature_command.md b/docs/feature_command.md index ad987aaf60..ca2ecce0da 100644 --- a/docs/feature_command.md +++ b/docs/feature_command.md @@ -1,52 +1,50 @@ -# Command (Formerly known as Magic) +# Command -Command is a way to change your keyboard's behavior without having to flash or unplug it to use [Bootmagic](feature_bootmagic.md). There is a lot of overlap between this functionality and the [Bootmagic Keycodes](feature_bootmagic.md). Whenever possible we encourage you to use that functionality instead of Command. +Command, formerly known as Magic, is a way to change your keyboard's behavior without having to flash or unplug it to use [Bootmagic](feature_bootmagic.md). There is a lot of overlap between this functionality and the [Bootmagic Keycodes](feature_bootmagic.md#keycodes). Wherever possible we encourage you to use that feature instead of Command. -## Enabling Command +On some keyboards Command is disabled by default. If this is the case, it must be explicitly enabled in your `rules.mk`: -By default Command is disabled. You can enable it in your `rules.mk` file: - - COMMAND_ENABLE = yes +```make +COMMAND_ENABLE = yes +``` ## Usage -To use Command you hold down the key combination defined by `IS_COMMAND`. By default that combination is both shift keys. While holding the key combination press the key corresponding to the command you want. - -For example, to write the current QMK version to the QMK Toolbox console, you can press `Left Shift`+`Right Shift`+`V`. +To use Command, hold down the key combination defined by the `IS_COMMAND()` macro. By default this is Left Shift+Right Shift. Then, press the key corresponding to the command you want. For example, to output the current QMK version to the QMK Toolbox console, press Left Shift+Right Shift+`V`. ## Configuration -The following values can be defined in `config.h` to control the behavior of Command. - -|Define |Default | Description | -|-------|--------|-------------| -|`IS_COMMAND()` |`(keyboard_report->mods == (MOD_BIT(KC_LSHIFT) | MOD_BIT(KC_RSHIFT)))`|Key combination to activate Command| -|`MAGIC_KEY_SWITCH_LAYER_WITH_FKEYS` |`true` |Do layer switching with Function row| -|`MAGIC_KEY_SWITCH_LAYER_WITH_NKEYS` |`true` |Do layer switching with number keys.| -|`MAGIC_KEY_SWITCH_LAYER_WITH_CUSTOM`|`false` |Do layer switching with custom keys (`MAGIC_KEY_LAYER0..9` below.)| -|`MAGIC_KEY_HELP1` |`H` |Show help.| -|`MAGIC_KEY_HELP2` |`SLASH` |Show help.| -|`MAGIC_KEY_DEBUG` |`D` |Turn on debug mode.| -|`MAGIC_KEY_DEBUG_MATRIX` |`X` |Turn on matrix debugging.| -|`MAGIC_KEY_DEBUG_KBD` |`K` |Turn on keyboard debugging.| -|`MAGIC_KEY_DEBUG_MOUSE` |`M` |Turn on mouse debugging.| -|`MAGIC_KEY_VERSION` |`V` |Write the QMK version to the console| -|`MAGIC_KEY_STATUS` |`S` |Show the current keyboard status| -|`MAGIC_KEY_CONSOLE` |`C` |Enable the Command Console| -|`MAGIC_KEY_LAYER0_ALT1` |`ESC` |Alternate access to layer 0| -|`MAGIC_KEY_LAYER0_ALT2` |`GRAVE` |Alternate access to layer 0| -|`MAGIC_KEY_LAYER0` |`0` |Change default layer to 0| -|`MAGIC_KEY_LAYER1` |`1` |Change default layer to 1| -|`MAGIC_KEY_LAYER2` |`2` |Change default layer to 2| -|`MAGIC_KEY_LAYER3` |`3` |Change default layer to 3| -|`MAGIC_KEY_LAYER4` |`4` |Change default layer to 4| -|`MAGIC_KEY_LAYER5` |`5` |Change default layer to 5| -|`MAGIC_KEY_LAYER6` |`6` |Change default layer to 6| -|`MAGIC_KEY_LAYER7` |`7` |Change default layer to 7| -|`MAGIC_KEY_LAYER8` |`8` |Change default layer to 8| -|`MAGIC_KEY_LAYER9` |`9` |Change default layer to 9| -|`MAGIC_KEY_BOOTLOADER` |`PAUSE` |Exit keyboard and enter bootloader| -|`MAGIC_KEY_LOCK` |`CAPS` |Lock the keyboard so nothing can be typed| -|`MAGIC_KEY_EEPROM` |`E` |Erase EEPROM settings| -|`MAGIC_KEY_NKRO` |`N` |Toggle NKRO on/off| -|`MAGIC_KEY_SLEEP_LED` |`Z` |Toggle LED when computer is sleeping on/off| +If you would like to change the key assignments for Command, `#define` these in your `config.h` at either the keyboard or keymap level. All keycode assignments here must omit the `KC_` prefix. + +|Define |Default |Description | +|------------------------------------|--------------------------------------------------------------------------------------|------------------------------------------------| +|`IS_COMMAND()` |(keyboard_report->mods == (MOD_BIT(KC_LSHIFT) | MOD_BIT(KC_RSHIFT)))|The key combination to activate Command | +|`MAGIC_KEY_SWITCH_LAYER_WITH_FKEYS` |`true` |Set default layer with the Function row | +|`MAGIC_KEY_SWITCH_LAYER_WITH_NKEYS` |`true` |Set default layer with the number keys | +|`MAGIC_KEY_SWITCH_LAYER_WITH_CUSTOM`|`false` |Set default layer with `MAGIC_KEY_LAYER0..9` | +|`MAGIC_KEY_DEBUG` |`D` |Toggle debugging over serial | +|`MAGIC_KEY_DEBUG_MATRIX` |`X` |Toggle key matrix debugging | +|`MAGIC_KEY_DEBUG_KBD` |`K` |Toggle keyboard debugging | +|`MAGIC_KEY_DEBUG_MOUSE` |`M` |Toggle mouse debugging | +|`MAGIC_KEY_CONSOLE` |`C` |Enable the Command console | +|`MAGIC_KEY_VERSION` |`V` |Print the running QMK version to the console | +|`MAGIC_KEY_STATUS` |`S` |Print the current keyboard status to the console| +|`MAGIC_KEY_HELP1` |`H` |Print Command help to the console | +|`MAGIC_KEY_HELP2` |`SLASH` |Print Command help to the console (alternate) | +|`MAGIC_KEY_LAYER0` |`0` |Make layer 0 the default layer | +|`MAGIC_KEY_LAYER1` |`1` |Make layer 1 the default layer | +|`MAGIC_KEY_LAYER2` |`2` |Make layer 2 the default layer | +|`MAGIC_KEY_LAYER3` |`3` |Make layer 3 the default layer | +|`MAGIC_KEY_LAYER4` |`4` |Make layer 4 the default layer | +|`MAGIC_KEY_LAYER5` |`5` |Make layer 5 the default layer | +|`MAGIC_KEY_LAYER6` |`6` |Make layer 6 the default layer | +|`MAGIC_KEY_LAYER7` |`7` |Make layer 7 the default layer | +|`MAGIC_KEY_LAYER8` |`8` |Make layer 8 the default layer | +|`MAGIC_KEY_LAYER9` |`9` |Make layer 9 the default layer | +|`MAGIC_KEY_LAYER0_ALT1` |`ESC` |Make layer 0 the default layer (alternate) | +|`MAGIC_KEY_LAYER0_ALT2` |`GRAVE` |Make layer 0 the default layer (alternate) | +|`MAGIC_KEY_BOOTLOADER` |`PAUSE` |Enter the bootloader | +|`MAGIC_KEY_LOCK` |`CAPS` |Lock the keyboard so nothing can be typed | +|`MAGIC_KEY_EEPROM` |`E` |Clear the EEPROM | +|`MAGIC_KEY_NKRO` |`N` |Toggle N-Key Rollover (NKRO) | +|`MAGIC_KEY_SLEEP_LED` |`Z` |Toggle LED when computer is sleeping | diff --git a/docs/feature_dynamic_macros.md b/docs/feature_dynamic_macros.md index 9803557e9e..0d11a28641 100644 --- a/docs/feature_dynamic_macros.md +++ b/docs/feature_dynamic_macros.md @@ -4,10 +4,10 @@ QMK supports temporary macros created on the fly. We call these Dynamic Macros. You can store one or two macros and they may have a combined total of 128 keypresses. You can increase this size at the cost of RAM. -To enable them, first add a new element to the `planck_keycodes` enum — `DYNAMIC_MACRO_RANGE`: +To enable them, first add a new element to the end of your `keycodes` enum — `DYNAMIC_MACRO_RANGE`: ```c -enum planck_keycodes { +enum keycodes { QWERTY = SAFE_RANGE, COLEMAK, DVORAK, @@ -20,7 +20,7 @@ enum planck_keycodes { }; ``` -It must be the last element because `dynamic_macros.h` will add some more keycodes after it. +Your `keycodes` enum may have a slightly different name. You must add `DYNAMIC_MACRO_RANGE` as the last element because `dynamic_macros.h` will add some more keycodes after it. Below it, include the `dynamic_macro.h` header: diff --git a/docs/feature_grave_esc.md b/docs/feature_grave_esc.md index a8e45f3a9a..c6fa160221 100644 --- a/docs/feature_grave_esc.md +++ b/docs/feature_grave_esc.md @@ -1,17 +1,24 @@ # Grave Escape -Grave Escape is a feature that allows you to share the grave key (` and `~`) on the same key as Escape. When `KC_GESC` is used it will act as `KC_ESC`, unless Shift or GUI is pressed, in which case it will act as `KC_GRAVE`. +If you're using a 60% keyboard, or any other layout with no F-row, you will have noticed that there is no dedicated Escape key. Grave Escape is a feature that allows you to share the grave key (` and `~`) with Escape. +## Usage + +Replace the `KC_GRAVE` key in your keymap (usually to the left of the `1` key) with `KC_GESC`. When pressed it will behave like `KC_ESC`, but with Shift or GUI held it will send `KC_GRAVE`. + +## Keycodes |Key |Aliases |Description | |---------|-----------|------------------------------------------------------------------| |`KC_GESC`|`GRAVE_ESC`|Escape when pressed, ` when Shift or GUI are held| -There are several possible key combinations this will break, among them Ctrl+Shift+Esc on Windows and Cmd+Opt+Esc on macOS. You can use these options in your `config.h` to work around this: +## Configuration + +There are several possible key combinations this will break, among them Control+Shift+Escape on Windows and Command+Option+Escape on macOS. To work around this, you can `#define` these options in your `config.h`: -| Option | Description | -|--------|-------------| -| `GRAVE_ESC_ALT_OVERRIDE` | Always send Escape if Alt is pressed. | -| `GRAVE_ESC_CTRL_OVERRIDE` | Always send Escape if Ctrl is pressed. | -| `GRAVE_ESC_GUI_OVERRIDE` | Always send Escape if GUI is pressed. | -| `GRAVE_ESC_SHIFT_OVERRIDE` | Always send Escape if SHIFT is pressed. | +|Define |Description | +|--------------------------|-----------------------------------------| +|`GRAVE_ESC_ALT_OVERRIDE` |Always send Escape if Alt is pressed | +|`GRAVE_ESC_CTRL_OVERRIDE` |Always send Escape if Control is pressed | +|`GRAVE_ESC_GUI_OVERRIDE` |Always send Escape if GUI is pressed | +|`GRAVE_ESC_SHIFT_OVERRIDE`|Always send Escape if Shift is pressed | diff --git a/docs/feature_key_lock.md b/docs/feature_key_lock.md index 225e7136ff..718d9c5bd1 100644 --- a/docs/feature_key_lock.md +++ b/docs/feature_key_lock.md @@ -1,11 +1,22 @@ -## Key Lock: Holding Down Keys for You +# Key Lock -Sometimes, you need to hold down a specific key for a long period of time. Whether this is while typing in ALL CAPS, or playing a video game that hasn't implemented auto-run, Key Lock is here to help. Key Lock adds a new keycode, `KC_LOCK`, that will hold down the next key you hit for you. The key is released when you hit it again. Here's an example: let's say you need to type in all caps for a few sentences. You hit KC_LOCK, and then shift. Now, shift will be considered held until you hit it again. You can think of key lock as caps lock, but supercharged. +Sometimes you may find yourself needing to hold down a specific key for a long period of time. Key Lock holds down the next key you press for you. Press it again, and it will be released. -Here's how to use it: +Let's say you need to type in ALL CAPS for a few sentences. Hit `KC_LOCK`, and then Shift. Now, Shift will be considered held until you tap it again. You can think of Key Lock as Caps Lock, but supercharged. -1. Pick a key on your keyboard. This will be the key lock key. Assign it the keycode `KC_LOCK`. This will be a single-action key: you won't be able to use it for anything else. -2. Enable key lock by including `KEY_LOCK_ENABLE = yes` in your Makefile. -3. That's it! +## Usage -Important: switching layers does not cancel the key lock. Additionally, key lock is only able to hold standard action keys and One Shot modifier keys (for example, if you have your shift defined as `OSM(KC_LSFT)`; see [One Shot Keys](quantum_keycodes.md#one-shot-keys)). This does not include any of the QMK special functions (except One Shot modifiers), or shifted versions of keys such as KC_LPRN. If it's in the [Basic Keycodes](keycodes_basic.md) list, it can be held. If it's not, then it can't be. +First, enable Key Lock by setting `KEY_LOCK_ENABLE = yes` in your `rules.mk`. Then pick a key in your keymap and assign it the keycode `KC_LOCK`. + +## Keycodes + +|Keycode |Description | +|---------|--------------------------------------------------------------| +|`KC_LOCK`|Hold down the next key pressed, until the key is pressed again| + +## Caveats + +Key Lock is only able to hold standard action keys and [One Shot modifier](quantum_keycodes.md#one-shot-keys) keys (for example, if you have your Shift defined as `OSM(KC_LSFT)`). +This does not include any of the QMK special functions (except One Shot modifiers), or shifted versions of keys such as `KC_LPRN`. If it's in the [Basic Keycodes](keycodes_basic.md) list, it can be held. + +Switching layers will not cancel the Key Lock. diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index cb7aa666cf..ed33c7ea4e 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -80,7 +80,7 @@ All RGB keycodes are currently shared with the RGBLIGHT system: These are the effects that are currently available: enum rgb_matrix_effects { - RGB_MATRIX_SOLID_COLOR = 1, + RGB_MATRIX_SOLID_COLOR = 1, RGB_MATRIX_ALPHAS_MODS, RGB_MATRIX_DUAL_BEACON, RGB_MATRIX_GRADIENT_UP_DOWN, @@ -93,7 +93,7 @@ These are the effects that are currently available: RGB_MATRIX_RAINBOW_MOVING_CHEVRON, RGB_MATRIX_JELLYBEAN_RAINDROPS, #ifdef RGB_MATRIX_KEYPRESSES - RGB_MATRIX_SOLID_REACTIVE, + RGB_MATRIX_SOLID_REACTIVE, RGB_MATRIX_SPLASH, RGB_MATRIX_MULTISPLASH, RGB_MATRIX_SOLID_SPLASH, @@ -107,7 +107,7 @@ These are the effects that are currently available: Custom layer effects can be done by defining this in your `.c`: void rgb_matrix_indicators_kb(void) { - // rgb_matrix_set_color(index, red, green, blue); + rgb_matrix_set_color(index, red, green, blue); } A similar function works in the keymap as `rgb_matrix_indicators_user`. diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md index e0918d11bd..d48941a04f 100644 --- a/docs/feature_rgblight.md +++ b/docs/feature_rgblight.md @@ -1,131 +1,46 @@ # RGB Lighting -If you've installed addressable RGB lights on your keyboard you can control them with QMK. Currently we support the following addressable LEDs on Atmel AVR processors: +QMK has the ability to control RGB LEDs attached to your keyboard. This is commonly called *underglow*, due to the LEDs often being mounted on the bottom of the keyboard, producing a nice diffused effect when combined with a translucent case. -* WS2811 and variants (WS2812, WS2812B, WS2812C, etc) -* SK6812RGBW - -Some keyboards come with RGB LEDs pre-installed. Others have to have LEDs installed after the fact. See below for information on modifying your keyboard. - -## Selecting Colors - -QMK uses Hue, Saturation, and Value to set color rather than using RGB. You can use the color wheel below to see how this works. Changing the Hue will cycle around the circle. Saturation will affect the intensity of the color, which you can see as you move from the inner part to the outer part of the wheel. Value sets the overall brightness. - -HSV Color Wheel - -If you would like to learn more about HSV you can start with the [Wikipedia article](https://en.wikipedia.org/wiki/HSL_and_HSV). +![Planck with RGB Underglow](https://raw.githubusercontent.com/qmk/qmk_firmware/3774a7fcdab5544fc787f4c200be05fcd417e31f/keyboards/planck/keymaps/yang/planck-with-rgb-underglow.jpg) -## Configuration +Some keyboards come with RGB LEDs preinstalled. Others must have them installed after the fact. See the [Hardware Modification](#hardware-modification) section for information on adding RGB lighting to your keyboard. -Before RGB Lighting can be used you have to enable it in `rules.mk`: +Currently QMK supports the following addressable LEDs on AVR microcontrollers (however, the white LED in RGBW variants is not supported): - RGBLIGHT_ENABLE = yes + * WS2811, WS2812, WS2812B, WS2812C, etc. + * SK6812, SK6812MINI, SK6805 -You can configure the behavior of the RGB lighting by defining values inside `config.h`. +These LEDs are called "addressable" because instead of using a wire per color, each LED contains a small microchip that understands a special protocol sent over a single wire. The chip passes on the remaining data to the next LED, allowing them to be chained together. In this way, you can easily control the color of the individual LEDs. -### Required Configuration +## Usage -At minimum you have to define the pin your LED strip is connected to and the number of LEDs connected. +On keyboards with onboard RGB LEDs, it is usually enabled by default. If it is not working for you, check that your `rules.mk` includes the following: -```c -#define RGB_DI_PIN D7 // The pin the LED strip is connected to -#define RGBLED_NUM 14 // Number of LEDs in your strip +```make +RGBLIGHT_ENABLE = yes ``` -### Optional Configuration - -You can change the behavior of the RGB Lighting by setting these configuration values. Use `#define