aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/drivers/ws2812.md20
-rw-r--r--docs/feature_advanced_keycodes.md60
-rw-r--r--docs/hardware_keyboard_guidelines.md70
-rw-r--r--docs/keycodes.md113
-rw-r--r--docs/mod_tap.md6
-rw-r--r--docs/one_shot_keys.md48
6 files changed, 195 insertions, 122 deletions
diff --git a/docs/drivers/ws2812.md b/docs/drivers/ws2812.md
index 4d1e727928..0c26ec6248 100644
--- a/docs/drivers/ws2812.md
+++ b/docs/drivers/ws2812.md
@@ -144,18 +144,30 @@ The following defines apply only to ARM devices:
|`WS2812_T1L`|`(WS2812_TIMING - WS2812_T1H)`|The length of a "1" bit's low phase in nanoseconds (bitbang and PIO drivers only)|
|`WS2812_T0L`|`(WS2812_TIMING - WS2812_T0H)`|The length of a "0" bit's low phase in nanoseconds (bitbang and PIO drivers only)|
-### Push-Pull and Open Drain {#push-pull-open-drain}
+### Logic Levels {#logic-levels}
-By default, the GPIO used for data transmission is configured as a *push-pull* output, meaning the pin is effectively always driven either to VCC or to ground.
+WS2812 LEDs usually operate at 5V, but some microcontrollers, particularly ARM-based ones, run on 3.3V. This can pose an issue when driving the LED chain as the logic level voltage is lower than the power supply voltage, leading to unreliable data transmission. There are two main workarounds:
-For situations where the logic level voltage is lower than the power supply voltage, however, this can pose an issue. The solution is to configure the pin for *open drain* mode instead, and use a pullup resistor between the DI pin and VCC. In this mode, the MCU can only pull the GPIO *low*, or leave it floating. The pullup resistor is then responsible for pulling the line high, when the MCU is not driving the GPIO.
+#### 1. Open Drain Circuit {#open-drain-circuit}
-To configure the DI pin for open drain configuration, add the following to your `config.h`:
+By default, `WS2812_DI_PIN` is configured as a *push-pull* output, meaning the pin is effectively always driven either to VCC or to ground; however, it can be configured in *open drain* mode instead.
+
+In this mode, the MCU will only pull the GPIO *low*, and leaves it floating otherwise. A pullup resistor (typically around 10kΩ) between DI and 5V is then responsible for pulling the line high when the MCU is not driving the GPIO.
+
+To use the DI pin in open drain configuration, add the following to your `config.h`:
```c
#define WS2812_EXTERNAL_PULLUP
```
+::: warning
+Because the GPIO is being pulled to 5V in this situation rather than VCC (3.3V), **it must be a 5V tolerant pin**. Consult your MCU's datasheet first – if there are no eligible pins, you must use a level shifter instead.
+:::
+
+#### 2. Level Shifter {#level-shifter}
+
+A level shifter IC, such as the SN74LV1T34, can be placed between the GPIO and the first LED's DI pin to convert the 3.3V logic to 5V. This requires no additional configuration in the firmware, nor a 5V tolerant GPIO, but may be more expensive and is generally less handwire-friendly.
+
### SPI Driver {#arm-spi-driver}
Depending on the ChibiOS board configuration, you may need to enable SPI at the keyboard level. For STM32, this would look like:
diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md
index b21accd367..a6f8bc8372 100644
--- a/docs/feature_advanced_keycodes.md
+++ b/docs/feature_advanced_keycodes.md
@@ -2,36 +2,36 @@
These allow you to combine a modifier with a keycode. When pressed, the keydown event for the modifier, then `kc` will be sent. On release, the keyup event for `kc`, then the modifier will be sent.
-|Key |Aliases |Description |
-|----------|----------------------------------|-------------------------------------------------------------------------------|
-|`LCTL(kc)`|`C(kc)` |Hold Left Control and press `kc` |
-|`LSFT(kc)`|`S(kc)` |Hold Left Shift and press `kc` |
-|`LALT(kc)`|`A(kc)`, `LOPT(kc)` |Hold Left Alt and press `kc` |
-|`LGUI(kc)`|`G(kc)`, `LCMD(kc)`, `LWIN(kc)` |Hold Left GUI and press `kc` |
-|`LCS(kc)` | |Hold Left Control and Left Shift and press `kc` |
-|`LCA(kc)` | |Hold Left Control and Left Alt and press `kc` |
-|`LCG(kc)` | |Hold Left Control and Left GUI and press `kc` |
-|`LSA(kc)` | |Hold Left Shift and Left Alt and press `kc` |
-|`LSG(kc)` |`SGUI(kc)`, `SCMD(kc)`, `SWIN(kc)`|Hold Left Shift and Left GUI and press `kc` |
-|`LAG(kc)` | |Hold Left Alt and Left GUI and press `kc` |
-|`LCSG(kc)`| |Hold Left Control, Left Shift and Left GUI and press `kc` |
-|`LCAG(kc)`| |Hold Left Control, Left Alt and Left GUI and press `kc` |
-|`LSAG(kc)`| |Hold Left Shift, Left Alt and Left GUI and press `kc` |
-|`RCTL(kc)`| |Hold Right Control and press `kc` |
-|`RSFT(kc)`| |Hold Right Shift and press `kc` |
-|`RALT(kc)`|`ROPT(kc)`, `ALGR(kc)` |Hold Right Alt and press `kc` |
-|`RGUI(kc)`|`RCMD(kc)`, `RWIN(kc)` |Hold Right GUI and press `kc` |
-|`RCA(kc)` | |Hold Right Control and Right Alt and press `kc` |
-|`RCS(kc)` | |Hold Right Control and Right Shift and press `kc` |
-|`RCG(kc)` | |Hold Right Control and Right GUI and press `kc` |
-|`RSA(kc)` |`SAGR(kc)` |Hold Right Shift and Right Alt and press `kc` |
-|`RSG(kc)` | |Hold Right Shift and Right GUI and press `kc` |
-|`RAG(kc)` | |Hold Right Alt and Right GUI and press `kc` |
-|`RCSG(kc)`| |Hold Right Control, Right Shift and Right GUI and press `kc` |
-|`RCAG(kc)`| |Hold Right Control, Right Alt and Right GUI and press `kc` |
-|`RSAG(kc)`| |Hold Right Shift, Right Alt and Right GUI and press `kc` |
-|`MEH(kc)` | |Hold Left Control, Left Shift and Left Alt and press `kc` |
-|`HYPR(kc)`| |Hold Left Control, Left Shift, Left Alt and Left GUI and press `kc`<sup>1</sup>|
+|Key |Aliases |Description |
+|----------|-------------------------------|-------------------------------------------------------------------------------|
+|`LCTL(kc)`|`C(kc)` |Hold Left Control and press `kc` |
+|`LSFT(kc)`|`S(kc)` |Hold Left Shift and press `kc` |
+|`LALT(kc)`|`A(kc)`, `LOPT(kc)` |Hold Left Alt and press `kc` |
+|`LGUI(kc)`|`G(kc)`, `LCMD(kc)`, `LWIN(kc)`|Hold Left GUI and press `kc` |
+|`LCS(kc)` | |Hold Left Control and Left Shift and press `kc` |
+|`LCA(kc)` | |Hold Left Control and Left Alt and press `kc` |
+|`LCG(kc)` | |Hold Left Control and Left GUI and press `kc` |
+|`LSA(kc)` | |Hold Left Shift and Left Alt and press `kc` |
+|`LSG(kc)` | |Hold Left Shift and Left GUI and press `kc` |
+|`LAG(kc)` | |Hold Left Alt and Left GUI and press `kc` |
+|`LCSG(kc)`| |Hold Left Control, Left Shift and Left GUI and press `kc` |
+|`LCAG(kc)`| |Hold Left Control, Left Alt and Left GUI and press `kc` |
+|`LSAG(kc)`| |Hold Left Shift, Left Alt and Left GUI and press `kc` |
+|`RCTL(kc)`| |Hold Right Control and press `kc` |
+|`RSFT(kc)`| |Hold Right Shift and press `kc` |
+|`RALT(kc)`|`ROPT(kc)`, `ALGR(kc)` |Hold Right Alt and press `kc` |
+|`RGUI(kc)`|`RCMD(kc)`, `RWIN(kc)` |Hold Right GUI and press `kc` |
+|`RCA(kc)` | |Hold Right Control and Right Alt and press `kc` |
+|`RCS(kc)` | |Hold Right Control and Right Shift and press `kc` |
+|`RCG(kc)` | |Hold Right Control and Right GUI and press `kc` |
+|`RSA(kc)` | |Hold Right Shift and Right Alt and press `kc` |
+|`RSG(kc)` | |Hold Right Shift and Right GUI and press `kc` |
+|`RAG(kc)` | |Hold Right Alt and Right GUI and press `kc` |
+|`RCSG(kc)`| |Hold Right Control, Right Shift and Right GUI and press `kc` |
+|`RCAG(kc)`| |Hold Right Control, Right Alt and Right GUI and press `kc` |
+|`RSAG(kc)`| |Hold Right Shift, Right Alt and Right GUI and press `kc` |
+|`MEH(kc)` | |Hold Left Control, Left Shift and Left Alt and press `kc` |
+|`HYPR(kc)`| |Hold Left Control, Left Shift, Left Alt and Left GUI and press `kc`<sup>1</sup>|
<sup>1. More information on the Hyper key can be found on [this blog post by Brett Terpstra](https://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/).</sup>
diff --git a/docs/hardware_keyboard_guidelines.md b/docs/hardware_keyboard_guidelines.md
index 7f17c46748..7e88ff231d 100644
--- a/docs/hardware_keyboard_guidelines.md
+++ b/docs/hardware_keyboard_guidelines.md
@@ -44,7 +44,11 @@ QMK uses sub-folders both for organization and to share code between revisions o
qmk_firmware/keyboards/top_folder/sub_1/sub_2/sub_3/sub_4
```
-If a sub-folder has a `rules.mk` file it will be considered a compilable keyboard. It will be available in QMK Configurator and tested with `make all`. If you are using a folder to organize several keyboards from the same maker you should not have a `rules.mk` file.
+If a sub-folder has a `keyboard.json` file it will be considered a compilable keyboard. It will be available in QMK Configurator and tested with `make all`. If you are using a folder to organize several keyboards from the same maker you should not have a `keyboard.json` file.
+
+::: tip
+When configuring a keyboard with multiple revisions (like the `clueboard/66` example below), an `info.json` file at the top keyboard level (eg. `clueboard/66`) should be used for configuration shared between revisions. Then `keyboard.json` in each revision directory containing revision-specific configuration, and indicating a buildable keyboard.
+:::
Example:
@@ -52,19 +56,19 @@ Clueboard uses sub-folders for both purposes, organization and keyboard revision
* [`qmk_firmware`](https://github.com/qmk/qmk_firmware/tree/master)
* [`keyboards`](https://github.com/qmk/qmk_firmware/tree/master/keyboards)
- * [`clueboard`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard) &larr; This is the organization folder, there's no `rules.mk` file
- * [`60`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/60) &larr; This is a compilable keyboard, it has a `rules.mk` file
- * [`66`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66) &larr; This is also compilable- it uses `DEFAULT_FOLDER` to specify `rev3` as the default revision
+ * [`clueboard`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard) &larr; This is the organization folder, there's no `keyboard.json` file
+ * [`60`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/60) &larr; This is a compilable keyboard - it has a `keyboard.json` file
+ * [`66`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66) &larr; This is not a compilable keyboard - a revision must be specified
* [`rev1`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev1) &larr; compilable: `make clueboard/66/rev1`
* [`rev2`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev2) &larr; compilable: `make clueboard/66/rev2`
- * [`rev3`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev3) &larr; compilable: `make clueboard/66/rev3` or `make clueboard/66`
+ * [`rev3`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev3) &larr; compilable: `make clueboard/66/rev3`
## Keyboard Folder Structure
-Your keyboard should be located in `qmk_firmware/keyboards/` and the folder name should be your keyboard's name as described in the previous section. Inside this folder should be several files:
+Your keyboard should be located in `qmk_firmware/keyboards/` and the folder name should be your keyboard's name as described in the previous section. Inside this folder should be several files, some of which are optional:
* `readme.md`
-* `info.json`
+* `keyboard.json` (or `info.json`)
* `config.h`
* `rules.mk`
* `<keyboard_name>.c`
@@ -74,13 +78,27 @@ Your keyboard should be located in `qmk_firmware/keyboards/` and the folder name
All projects need to have a `readme.md` file that explains what the keyboard is, who made it and where it's available. If applicable, it should also contain links to more information, such as the maker's website. Please follow the [published template](documentation_templates#keyboard-readmemd-template).
-### `info.json`
+### `keyboard.json`/`info.json`
+
+The `keyboard.json` file is necessary for your keyboard (or keyboard revision) to be considered a buildable keyboard. The same content is valid in both `info.json` and `keyboard.json`. For the available configuration options of this file, see the [reference page](reference_info_json). This file is also used by the [QMK API](https://github.com/qmk/qmk_api), and by the [QMK Configurator](https://config.qmk.fm/) to display a representation of the available layouts of your keyboard.
+
+Additionally, this is where layouts available on your keyboard are defined. If you only have a single layout, it should be named `LAYOUT`. When defining multiple layouts, you should have a base layout, named `LAYOUT_all`, that supports all possible switch positions in your matrix, even if that layout is impossible to build physically. This is the layout that should be used in the `default` keymap. You should then have additional keymaps named `default_<layout>` that configure keymaps for the other layouts. Layout macro names are entirely lowercase, except for the prefix of `LAYOUT`.
-This file is used by the [QMK API](https://github.com/qmk/qmk_api). It contains the information [QMK Configurator](https://config.qmk.fm/) needs to display a representation of your keyboard. You can also set metadata here. For more information see the [reference page](reference_info_json).
+As an example, if you have a 60% PCB that supports ANSI and ISO, you might define the following layouts and keymaps:
+
+| Layout Name | Keymap Name | Description |
+|-------------|--------------|------------------------------------------|
+| LAYOUT_all | default | A layout that supports both ISO and ANSI |
+| LAYOUT_ansi | default_ansi | An ANSI layout |
+| LAYOUT_iso | default_iso | An ISO layout |
+
+::: tip
+Providing only `LAYOUT_all` is invalid, as is providing a `LAYOUT` when multiple layouts are present.
+:::
### `config.h`
-All projects need to have a `config.h` file that sets things like the matrix size, product name, USB VID/PID, description and other settings. In general, use this file to set essential information and defaults for your keyboard that will always work.
+Some projects will need to have a `config.h` that configures parameters that are not possible to be set in `keyboard.json`. This is not a required file.
The `config.h` files can also be placed in sub-folders, and the order in which they are read is as follows:
@@ -138,7 +156,7 @@ If you define options using `post_config.h` as in the above example, you should
### `rules.mk`
-The presence of this file means that the folder is a keyboard target and can be used in `make` commands. This is where you setup the build environment for your keyboard and configure the default set of features.
+This file is typically used to configure hardware drivers (eg. pointing device), or to include additional C files in compilation. This is not a required file.
The `rules.mk` file can also be placed in a sub-folder, and its reading order is as follows:
@@ -187,7 +205,7 @@ See `build_keyboard.mk` and `common_features.mk` for more details.
### `<keyboard_name.c>`
-This is where you will write custom code for your keyboard. Typically you will write code to initialize and interface with the hardware in your keyboard. If your keyboard consists of only a key matrix with no LEDs, speakers, or other auxiliary hardware this file can be blank.
+This file should contain C code required for the functionality of your keyboard, for example hardware initialisation code, OLED display code, and so on. This file should only contain code necessary for the keyboard to work, and *not* things that should be left to the end user to configure in their keymap. This file is automatically included in compilation if it exists. This is not a required file.
The following functions are typically defined in this file:
@@ -198,31 +216,11 @@ The following functions are typically defined in this file:
### `<keyboard_name.h>`
-This file is used to define the matrix for your keyboard. You should define at least one C macro which translates an array into a matrix representing the physical switch matrix for your keyboard. If it's possible to build your keyboard with multiple layouts you should define additional macros.
-
-If you have only a single layout you should call this macro `LAYOUT`.
-
-When defining multiple layouts you should have a base layout, named `LAYOUT_all`, that supports all possible switch positions on your matrix, even if that layout is impossible to build physically. This is the macro you should use in your `default` keymap. You should then have additional keymaps named `default_<layout>` that use your other layout macros. This will make it easier for people to use the layouts you define.
-
-Layout macro names are entirely lowercase, except for the word `LAYOUT` at the front.
-
-As an example, if you have a 60% PCB that supports ANSI and ISO you might define the following layouts and keymaps:
-
-| Layout Name | Keymap Name | Description |
-|-------------|-------------|-------------|
-| LAYOUT_all | default | A layout that supports both ISO and ANSI |
-| LAYOUT_ansi | default_ansi | An ANSI layout |
-| LAYOUT_iso | default_iso | An ISO layout |
-
-::: tip
-Providing only `LAYOUT_all` is invalid - especially when implementing the additional layouts within 3rd party tooling.
-:::
+This file can contain function prototypes for custom functions and other header file code utilised by `<keyboard_name>.c`. The `<keyboard_name>.c` file should include this file. This is not a required file.
## Image/Hardware Files
-In an effort to keep the repo size down we're no longer accepting binary files of any format, with few exceptions. Hosting them elsewhere (such as <https://imgur.com>) and linking them in the `readme.md` is preferred.
-
-Hardware files (such as plates, cases, pcb) can be contributed to the [qmk.fm repo](https://github.com/qmk/qmk.fm) and they will be made available on [qmk.fm](https://qmk.fm). Downloadable files are stored in `/<keyboard>/` (name follows the same format as above) which are served at `https://qmk.fm/<keyboard>/`, and pages are generated from `/_pages/<keyboard>/` which are served at the same location (.md files are generated into .html files through Jekyll). Check out the `lets_split` folder for an example.
+In an effort to keep the repo size down we do not accept binary files of any format, with few exceptions. Hosting them elsewhere (such as <https://imgur.com>) and linking them in the `readme.md` is preferred. Hardware files such as plates, cases, and PCBs can be published in a personal repository or elsewhere, and linked to by your keyboard's `readme.md` file.
## Keyboard Defaults
@@ -232,8 +230,6 @@ Given the amount of functionality that QMK exposes it's very easy to confuse new
[Magic Keycodes](keycodes_magic) and [Command](features/command) are two related features that allow a user to control their keyboard in non-obvious ways. We recommend you think long and hard about if you're going to enable either feature, and how you will expose this functionality. Keep in mind that users who want this functionality can enable it in their personal keymaps without affecting all the novice users who may be using your keyboard as their first programmable board.
-By far the most common problem new users encounter is accidentally triggering Bootmagic while they're plugging in their keyboard. They're holding the keyboard by the bottom, unknowingly pressing in alt and spacebar, and then they find that these keys have been swapped on them. We recommend leaving this feature disabled by default, but if you do turn it on consider setting `BOOTMAGIC_KEY_SALT` to a key that is hard to press while plugging your keyboard in.
-
If your keyboard does not have 2 shift keys you should provide a working default for `IS_COMMAND`, even when you have set `COMMAND_ENABLE = no`. This will give your users a default to conform to if they do enable Command.
## Custom Keyboard Programming
@@ -242,7 +238,7 @@ As documented on [Customizing Functionality](custom_quantum_functions) you can d
## Non-Production/Handwired Projects
-We're happy to accept any project that uses QMK, including prototypes and handwired ones, but we have a separate `/keyboards/handwired/` folder for them, so the main `/keyboards/` folder doesn't get overcrowded. If a prototype project becomes a production project at some point in the future, we'd be happy to move it to the main `/keyboards/` folder!
+We're happy to accept any project that uses QMK, including handwired ones, but we have a separate `/keyboards/handwired/` folder for them, so the main `/keyboards/` folder doesn't get overcrowded. If a prototype project becomes a production project at some point in the future, we'd be happy to move it to the main `/keyboards/` folder!
## Warnings as Errors
diff --git a/docs/keycodes.md b/docs/keycodes.md
index 5d983e347e..e569e87431 100644
--- a/docs/keycodes.md
+++ b/docs/keycodes.md
@@ -404,7 +404,6 @@ See also: [Layer Switching](feature_layers#switching-and-toggling-layers)
|`DF(layer)` |Set the base (default) layer until the keyboard loses power |
|`PDF(layer)` |Set the base (default) layer in EEPROM |
|`MO(layer)` |Momentarily turn on `layer` when pressed (requires `KC_TRNS` on destination layer)|
-|`OSL(layer)` |Momentarily activates `layer` until a key is pressed. See [One Shot Keys](one_shot_keys) for details. |
|`LM(layer, mod)`|Momentarily turn on `layer` (like MO) with `mod` active as well. Where `mod` is a mods_bit. Mods can be viewed [here](mod_tap). Example Implementation: `LM(LAYER_1, MOD_LALT)`|
|`LT(layer, kc)` |Turn on `layer` when held, `kc` when tapped |
|`TG(layer)` |Toggle `layer` on or off |
@@ -658,38 +657,38 @@ See also: [Mouse Keys](features/mouse_keys)
See also: [Modifier Keys](feature_advanced_keycodes#modifier-keys)
-|Key |Aliases |Description |
-|----------|----------------------------------|-------------------------------------------------------------------|
-|`LCTL(kc)`|`C(kc)` |Hold Left Control and press `kc` |
-|`LSFT(kc)`|`S(kc)` |Hold Left Shift and press `kc` |
-|`LALT(kc)`|`A(kc)`, `LOPT(kc)` |Hold Left Alt and press `kc` |
-|`LGUI(kc)`|`G(kc)`, `LCMD(kc)`, `LWIN(kc)` |Hold Left GUI and press `kc` |
-|`LCS(kc)` | |Hold Left Control and Left Shift and press `kc` |
-|`LCA(kc)` | |Hold Left Control and Left Alt and press `kc` |
-|`LCG(kc)` | |Hold Left Control and Left GUI and press `kc` |
-|`LSA(kc)` | |Hold Left Shift and Left Alt and press `kc` |
-|`LSG(kc)` |`SGUI(kc)`, `SCMD(kc)`, `SWIN(kc)`|Hold Left Shift and Left GUI and press `kc` |
-|`LAG(kc)` | |Hold Left Alt and Left GUI and press `kc` |
-|`LCSG(kc)`| |Hold Left Control, Left Shift and Left GUI and press `kc` |
-|`LCAG(kc)`| |Hold Left Control, Left Alt and Left GUI and press `kc` |
-|`LSAG(kc)`| |Hold Left Shift, Left Alt and Left GUI and press `kc` |
-|`RCTL(kc)`| |Hold Right Control and press `kc` |
-|`RSFT(kc)`| |Hold Right Shift and press `kc` |
-|`RALT(kc)`|`ROPT(kc)`, `ALGR(kc)` |Hold Right Alt and press `kc` |
-|`RGUI(kc)`|`RCMD(kc)`, `RWIN(kc)` |Hold Right GUI and press `kc` |
-|`RCS(kc)` | |Hold Right Control and Right Shift and press `kc` |
-|`RCA(kc)` | |Hold Right Control and Right Alt and press `kc` |
-|`RCG(kc)` | |Hold Right Control and Right GUI and press `kc` |
-|`RSA(kc)` |`SAGR(kc)` |Hold Right Shift and Right Alt and press `kc` |
-|`RSG(kc)` | |Hold Right Shift and Right GUI and press `kc` |
-|`RAG(kc)` | |Hold Right Alt and Right GUI and press `kc` |
-|`RCSG(kc)`| |Hold Right Control, Right Shift and Right GUI and press `kc` |
-|`RCAG(kc)`| |Hold Right Control, Right Alt and Right GUI and press `kc` |
-|`RSAG(kc)`| |Hold Right Shift, Right Alt and Right GUI and press `kc` |
-|`MEH(kc)` | |Hold Left Control, Left Shift and Left Alt and press `kc` |
-|`HYPR(kc)`| |Hold Left Control, Left Shift, Left Alt and Left GUI and press `kc`|
-|`KC_MEH` | |Left Control, Left Shift and Left Alt |
-|`KC_HYPR` | |Left Control, Left Shift, Left Alt and Left GUI |
+|Key |Aliases |Description |
+|----------|-------------------------------|-------------------------------------------------------------------|
+|`LCTL(kc)`|`C(kc)` |Hold Left Control and press `kc` |
+|`LSFT(kc)`|`S(kc)` |Hold Left Shift and press `kc` |
+|`LALT(kc)`|`A(kc)`, `LOPT(kc)` |Hold Left Alt and press `kc` |
+|`LGUI(kc)`|`G(kc)`, `LCMD(kc)`, `LWIN(kc)`|Hold Left GUI and press `kc` |
+|`LCS(kc)` | |Hold Left Control and Left Shift and press `kc` |
+|`LCA(kc)` | |Hold Left Control and Left Alt and press `kc` |
+|`LCG(kc)` | |Hold Left Control and Left GUI and press `kc` |
+|`LSA(kc)` | |Hold Left Shift and Left Alt and press `kc` |
+|`LSG(kc)` | |Hold Left Shift and Left GUI and press `kc` |
+|`LAG(kc)` | |Hold Left Alt and Left GUI and press `kc` |
+|`LCSG(kc)`| |Hold Left Control, Left Shift and Left GUI and press `kc` |
+|`LCAG(kc)`| |Hold Left Control, Left Alt and Left GUI and press `kc` |
+|`LSAG(kc)`| |Hold Left Shift, Left Alt and Left GUI and press `kc` |
+|`RCTL(kc)`| |Hold Right Control and press `kc` |
+|`RSFT(kc)`| |Hold Right Shift and press `kc` |
+|`RALT(kc)`|`ROPT(kc)`, `ALGR(kc)` |Hold Right Alt and press `kc` |
+|`RGUI(kc)`|`RCMD(kc)`, `RWIN(kc)` |Hold Right GUI and press `kc` |
+|`RCS(kc)` | |Hold Right Control and Right Shift and press `kc` |
+|`RCA(kc)` | |Hold Right Control and Right Alt and press `kc` |
+|`RCG(kc)` | |Hold Right Control and Right GUI and press `kc` |
+|`RSA(kc)` | |Hold Right Shift and Right Alt and press `kc` |
+|`RSG(kc)` | |Hold Right Shift and Right GUI and press `kc` |
+|`RAG(kc)` | |Hold Right Alt and Right GUI and press `kc` |
+|`RCSG(kc)`| |Hold Right Control, Right Shift and Right GUI and press `kc` |
+|`RCAG(kc)`| |Hold Right Control, Right Alt and Right GUI and press `kc` |
+|`RSAG(kc)`| |Hold Right Shift, Right Alt and Right GUI and press `kc` |
+|`MEH(kc)` | |Hold Left Control, Left Shift and Left Alt and press `kc` |
+|`HYPR(kc)`| |Hold Left Control, Left Shift, Left Alt and Left GUI and press `kc`|
+|`KC_MEH` | |Left Control, Left Shift and Left Alt |
+|`KC_HYPR` | |Left Control, Left Shift, Left Alt and Left GUI |
## Mod-Tap Keys {#mod-tap-keys}
@@ -706,7 +705,7 @@ See also: [Mod-Tap](mod_tap)
|`LCA_T(kc)` | |Left Control and Left Alt when held, `kc` when tapped |
|`LCG_T(kc)` | |Left Control and Left GUI when held, `kc` when tapped |
|`LSA_T(kc)` | |Left Shift and Left Alt when held, `kc` when tapped |
-|`LSG_T(kc)` |`SGUI_T(kc)`, `SCMD_T(kc)`, `SWIN_T(kc)` |Left Shift and Left GUI when held, `kc` when tapped |
+|`LSG_T(kc)` | |Left Shift and Left GUI when held, `kc` when tapped |
|`LAG_T(kc)` | |Left Alt and Left GUI when held, `kc` when tapped |
|`LCSG_T(kc)` | |Left Control, Left Shift and Left GUI when held, `kc` when tapped |
|`LCAG_T(kc)` | |Left Control, Left Alt and Left GUI when held, `kc` when tapped |
@@ -718,14 +717,14 @@ See also: [Mod-Tap](mod_tap)
|`RCS_T(kc)` | |Right Control and Right Shift when held, `kc` when tapped |
|`RCA_T(kc)` | |Right Control and Right Alt when held, `kc` when tapped |
|`RCG_T(kc)` | |Right Control and Right GUI when held, `kc` when tapped |
-|`RSA_T(kc)` |`SAGR_T(kc)` |Right Shift and Right Alt when held, `kc` when tapped |
+|`RSA_T(kc)` | |Right Shift and Right Alt when held, `kc` when tapped |
|`RSG_T(kc)` | |Right Shift and Right GUI when held, `kc` when tapped |
|`RAG_T(kc)` | |Right Alt and Right GUI when held, `kc` when tapped |
|`RCSG_T(kc)` | |Right Control, Right Shift and Right GUI when held, `kc` when tapped |
|`RCAG_T(kc)` | |Right Control, Right Alt and Right GUI when held, `kc` when tapped |
|`RSAG_T(kc)` | |Right Shift, Right Alt and Right GUI when held, `kc` when tapped |
|`MEH_T(kc)` | |Left Control, Left Shift and Left Alt when held, `kc` when tapped |
-|`HYPR_T(kc)` |`ALL_T(kc)` |Left Control, Left Shift, Left Alt and Left GUI when held, `kc` when tapped|
+|`HYPR_T(kc)` | |Left Control, Left Shift, Left Alt and Left GUI when held, `kc` when tapped|
## Tapping Term Keys {#tapping-term-keys}
@@ -817,13 +816,41 @@ See also: [US ANSI Shifted Symbols](keycodes_us_ansi_shifted)
See also: [One Shot Keys](one_shot_keys)
-|Key |Aliases |Description |
-|--------------------|---------|----------------------------------|
-|`OSM(mod)` | |Hold `mod` for one keypress |
-|`OSL(layer)` | |Switch to `layer` for one keypress|
-|`QK_ONE_SHOT_TOGGLE`|`OS_TOGG`|Toggles One Shot keys status |
-|`QK_ONE_SHOT_ON` |`OS_ON` |Turns One Shot keys on |
-|`QK_ONE_SHOT_OFF` |`OS_OFF` |Turns One Shot keys off |
+|Key |Aliases |Description |
+|--------------------|---------|---------------------------------------------------------------------|
+|`QK_ONE_SHOT_TOGGLE`|`OS_TOGG`|Toggles One Shot keys status |
+|`QK_ONE_SHOT_ON` |`OS_ON` |Turns One Shot keys on |
+|`QK_ONE_SHOT_OFF` |`OS_OFF` |Turns One Shot keys off |
+|`OSL(layer)` | |Switch to `layer` for one keypress |
+|`OSM(mod)` | |Hold `mod` for one keypress |
+|`OS_LCTL` | |Hold Left Control for one keypress |
+|`OS_LSFT` | |Hold Left Shift for one keypress |
+|`OS_LALT` | |Hold Left Alt for one keypress |
+|`OS_LGUI` | |Hold Left GUI for one keypress |
+|`OS_LCS` | |Hold Left Control and Left Shift for one keypress |
+|`OS_LCA` | |Hold Left Control and left Alt for one keypress |
+|`OS_LCG` | |Hold Left Control and Left GUI for one keypress |
+|`OS_LSA` | |Hold Left Shift and Left Alt for one keypress |
+|`OS_LSG` | |Hold Left Shift and Left GUI for one keypress |
+|`OS_LAG` | |Hold Left Alt and Left GUI for one keypress |
+|`OS_LCSG` | |Hold Left Control, Left Shift and Left GUI for one keypress |
+|`OS_LCAG` | |Hold Left Control, Left Alt and Left GUI for one keypress |
+|`OS_LSAG` | |Hold Left Shift, Left Alt and Left GUI for one keypress |
+|`OS_RCTL` | |Hold Right Control for one keypress |
+|`OS_RSFT` | |Hold Right Shift for one keypress |
+|`OS_RALT` | |Hold Right Alt for one keypress |
+|`OS_RGUI` | |Hold Right GUI for one keypress |
+|`OS_RCS` | |Hold Right Control and Right Shift for one keypress |
+|`OS_RCA` | |Hold Right Control and Right Alt for one keypress |
+|`OS_RCG` | |Hold Right Control and Right GUI for one keypress |
+|`OS_RSA` | |Hold Right Shift and Right Alt for one keypress |
+|`OS_RSG` | |Hold Right Shift and Right GUI for one keypress |
+|`OS_RAG` | |Hold Right Alt and Right GUI for one keypress |
+|`OS_RCSG` | |Hold Right Control, Right Shift and Right GUI for one keypress |
+|`OS_RCAG` | |Hold Right Control, Right Alt and Right GUI for one keypress |
+|`OS_RSAG` | |Hold Right Shift, Right Alt and Right GUI for one keypress |
+|`OS_MEH` | |Hold Left Control, Left Shift and Left Alt for one keypress |
+|`OS_HYPR` | |Hold Left Control, Left Shift, Left Alt and Left GUI for one keypress|
## Programmable Button Support {#programmable-button}
diff --git a/docs/mod_tap.md b/docs/mod_tap.md
index ebf79adb7f..67922c0915 100644
--- a/docs/mod_tap.md
+++ b/docs/mod_tap.md
@@ -37,7 +37,7 @@ For convenience, QMK includes some Mod-Tap shortcuts to make common combinations
|`LCA_T(kc)` | |Left Control and Left Alt when held, `kc` when tapped |
|`LCG_T(kc)` | |Left Control and Left GUI when held, `kc` when tapped |
|`LSA_T(kc)` | |Left Shift and Left Alt when held, `kc` when tapped |
-|`LSG_T(kc)` |`SGUI_T(kc)`, `SCMD_T(kc)`, `SWIN_T(kc)` |Left Shift and Left GUI when held, `kc` when tapped |
+|`LSG_T(kc)` | |Left Shift and Left GUI when held, `kc` when tapped |
|`LAG_T(kc)` | |Left Alt and Left GUI when held, `kc` when tapped |
|`LCSG_T(kc)`| |Left Control, Left Shift and Left GUI when held, `kc` when tapped |
|`LCAG_T(kc)`| |Left Control, Left Alt and Left GUI when held, `kc` when tapped |
@@ -49,14 +49,14 @@ For convenience, QMK includes some Mod-Tap shortcuts to make common combinations
|`RCS_T(kc)` | |Right Control and Right Shift when held, `kc` when tapped |
|`RCA_T(kc)` | |Right Control and Right Alt when held, `kc` when tapped |
|`RCG_T(kc)` | |Right Control and Right GUI when held, `kc` when tapped |
-|`RSA_T(kc)` |`SAGR_T(kc)` |Right Shift and Right Alt when held, `kc` when tapped |
+|`RSA_T(kc)` | |Right Shift and Right Alt when held, `kc` when tapped |
|`RSG_T(kc)` | |Right Shift and Right GUI when held, `kc` when tapped |
|`RAG_T(kc)` | |Right Alt and Right GUI when held, `kc` when tapped |
|`RCSG_T(kc)`| |Right Control, Right Shift and Right GUI when held, `kc` when tapped |
|`RCAG_T(kc)`| |Right Control, Right Alt and Right GUI when held, `kc` when tapped |
|`RSAG_T(kc)`| |Right Shift, Right Alt and Right GUI when held, `kc` when tapped |
|`MEH_T(kc)` | |Left Control, Left Shift and Left Alt when held, `kc` when tapped |
-|`HYPR_T(kc)`|`ALL_T(kc)` |Left Control, Left Shift, Left Alt and Left GUI when held, `kc` when tapped<sup>1</sup>|
+|`HYPR_T(kc)`| |Left Control, Left Shift, Left Alt and Left GUI when held, `kc` when tapped<sup>1</sup>|
<sup>1. More information on the Hyper key can be found on [this blog post by Brett Terpstra](https://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/).</sup>
diff --git a/docs/one_shot_keys.md b/docs/one_shot_keys.md
index 140c8de475..c4d8e3a4bc 100644
--- a/docs/one_shot_keys.md
+++ b/docs/one_shot_keys.md
@@ -15,11 +15,49 @@ You can control the behavior of one shot keys by defining these in `config.h`:
#define ONESHOT_TIMEOUT 5000 /* Time (in ms) before the one shot key is released */
```
-* `OSM(mod)` - Momentarily hold down *mod*. You must use the `MOD_*` keycodes as shown in [Mod Tap](mod_tap), not the `KC_*` codes.
-* `OSL(layer)` - momentary switch to *layer*.
-* `OS_ON` - Turns on One Shot keys.
-* `OS_OFF` - Turns off One Shot keys. OSM act as regular mod keys, OSL act like `MO`.
-* `OS_TOGG` - Toggles the one shot key status.
+## Keycodes {#keycodes}
+
+|Key |Aliases |Description |
+|--------------------|---------|---------------------------------------------------------------------|
+|`QK_ONE_SHOT_TOGGLE`|`OS_TOGG`|Toggles One Shot keys status |
+|`QK_ONE_SHOT_ON` |`OS_ON` |Turns One Shot keys on |
+|`QK_ONE_SHOT_OFF` |`OS_OFF` |Turns One Shot keys off |
+|`OSL(layer)` | |Switch to `layer` for one keypress |
+|`OSM(mod)` | |Hold `mod` for one keypress |
+|`OS_LCTL` | |Hold Left Control for one keypress |
+|`OS_LSFT` | |Hold Left Shift for one keypress |
+|`OS_LALT` | |Hold Left Alt for one keypress |
+|`OS_LGUI` | |Hold Left GUI for one keypress |
+|`OS_LCS` | |Hold Left Control and Left Shift for one keypress |
+|`OS_LCA` | |Hold Left Control and left Alt for one keypress |
+|`OS_LCG` | |Hold Left Control and Left GUI for one keypress |
+|`OS_LSA` | |Hold Left Shift and Left Alt for one keypress |
+|`OS_LSG` | |Hold Left Shift and Left GUI for one keypress |
+|`OS_LAG` | |Hold Left Alt and Left GUI for one keypress |
+|`OS_LCSG` | |Hold Left Control, Left Shift and Left GUI for one keypress |
+|`OS_LCAG` | |Hold Left Control, Left Alt and Left GUI for one keypress |
+|`OS_LSAG` | |Hold Left Shift, Left Alt and Left GUI for one keypress |
+|`OS_RCTL` | |Hold Right Control for one keypress |
+|`OS_RSFT` | |Hold Right Shift for one keypress |
+|`OS_RALT` | |Hold Right Alt for one keypress |
+|`OS_RGUI` | |Hold Right GUI for one keypress |
+|`OS_RCS` | |Hold Right Control and Right Shift for one keypress |
+|`OS_RCA` | |Hold Right Control and Right Alt for one keypress |
+|`OS_RCG` | |Hold Right Control and Right GUI for one keypress |
+|`OS_RSA` | |Hold Right Shift and Right Alt for one keypress |
+|`OS_RSG` | |Hold Right Shift and Right GUI for one keypress |
+|`OS_RAG` | |Hold Right Alt and Right GUI for one keypress |
+|`OS_RCSG` | |Hold Right Control, Right Shift and Right GUI for one keypress |
+|`OS_RCAG` | |Hold Right Control, Right Alt and Right GUI for one keypress |
+|`OS_RSAG` | |Hold Right Shift, Right Alt and Right GUI for one keypress |
+|`OS_MEH` | |Hold Left Control, Left Shift and Left Alt for one keypress |
+|`OS_HYPR` | |Hold Left Control, Left Shift, Left Alt and Left GUI for one keypress|
+
+When One Shot keys are turned off, `OSM()` and `OSL()` will behave like normal modifier keys and `MO()`, respectively.
+
+::: info
+The `mod` parameter to the `OSM()` keycode must use the `MOD_*` prefix, rather than `KC_*`, eg. `OSM(MOD_LCTL | MOD_LSFT)`.
+:::
Sometimes, you want to activate a one-shot key as part of a macro or tap dance routine.