* enables handling for per key `TAPPING_TERM` settings
* `#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
+ * See [Retro Tapping](#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
+ * See [Permissive Hold](#permissive-hold) for details
* `#define PERMISSIVE_HOLD_PER_KEY`
* enabled handling for per key `PERMISSIVE_HOLD` settings
* `#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
+ * See [Mod tap interrupt](#ignore-mod-tap-interrupt) for details
* `#define IGNORE_MOD_TAP_INTERRUPT_PER_KEY`
* enables handling for per key `IGNORE_MOD_TAP_INTERRUPT` settings
* `#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)
+ * See [Hold after tap](#tapping-force-hold)
* Breaks any Tap Toggle functionality (`TT` or the One Shot Tap Toggle)
* `#define TAPPING_FORCE_HOLD_PER_KEY`
* enables handling for per key `TAPPING_FORCE_HOLD` settings
* `bootloadHID`
* `USBasp`
-## Feature Options
+## Feature Options :id=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.
};
```
-### Previewing the Documentation
+### Previewing the Documentation :id=previewing-the-documentation
Before opening a pull request, you can preview your changes if you have set up the development environment by running this command from the `qmk_firmware/` folder:
This page does not assume any special knowledge about QMK, but reading [Understanding QMK](understanding_qmk.md) will help you understand what is going on at a more fundamental level.
-## A Word on Core vs Keyboards vs Keymap
+## A Word on Core vs Keyboards vs Keymap :id=a-word-on-core-vs-keyboards-vs-keymap
We have structured QMK as a hierarchy:
};
```
-## Programming the Behavior of Any Keycode
+## Programming the Behavior of Any Keycode :id=programming-the-behavior-of-any-keycode
When you want to override the behavior of an existing key, or define the behavior for a new key, you should use the `process_record_kb()` and `process_record_user()` functions. These are called by QMK during key processing before the actual key event is handled. If these functions return `true` QMK will process the keycodes as usual. That can be handy for extending the functionality of a key rather than replacing it. If these functions return `false` QMK will skip the normal key handling, and it will be up to you to send any key up or down events that are required.
* Keyboard/Revision: `void suspend_power_down_kb(void)` and `void suspend_wakeup_init_user(void)`
* Keymap: `void suspend_power_down_kb(void)` and `void suspend_wakeup_init_user(void)`
-# Layer Change Code
+# Layer Change Code :id=layer-change-code
This runs code every time that the layers get changed. This can be useful for layer indication, or custom layer handling.
* [Macros](de/feature_macros.md)
* [Mouse Keys](de/feature_mouse_keys.md)
* [OLED Driver](de/feature_oled_driver.md)
- * [One Shot Keys](de/feature_advanced_keycodes.md#one-shot-keys)
+ * [One Shot Keys](de/one_shot_keys.md)
* [Pointing Device](de/feature_pointing_device.md)
* [PS/2 Mouse](de/feature_ps2_mouse.md)
* [RGB Lighting](de/feature_rgblight.md)
This page documents the templates you should use when submitting new Keymaps and Keyboards to QMK.
-## Keymap `readme.md` Template
+## Keymap `readme.md` Template :id=keyboard-readmemd-template
Most keymaps have an image depicting the layout. You can use [Keyboard Layout Editor](http://keyboard-layout-editor.com) to create an image. Upload it to [Imgur](http://imgur.com) or another hosting service, please do not include images in your Pull Request.
* [Macros](es/feature_macros.md)
* [Teclas del ratón](es/feature_mouse_keys.md)
* [Driver OLED](es/feature_oled_driver.md)
- * [Teclas One Shot](es/feature_advanced_keycodes.md#one-shot-keys)
+ * [Teclas One Shot](es/one_shot_keys.md)
* [Dispositivo de apuntado](es/feature_pointing_device.md)
* [Ratón PS/2](es/feature_ps2_mouse.md)
* [Iluminación RGB](es/feature_rgblight.md)
-# Switching and Toggling Layers
+# Switching and Toggling Layers :id=switching-and-toggling-layers
These functions allow you to activate layers in various ways. Note that layers are not generally independent layouts -- multiple layers can be activated at once, and it's typical for layers to use `KC_TRNS` to allow keypresses to pass through to lower layers. For a detailed explanation of layers, see [Keymap Overview](keymap.md#keymap-and-layers). When using momentary layer switching with MO(), LM(), TT(), or LT(), make sure to leave the key on the above layers transparent or it may not work as intended.
* `MO(layer)` - momentarily activates *layer*. As soon as you let go of the key, the layer is deactivated.
* `LM(layer, mod)` - Momentarily activates *layer* (like `MO`), but with modifier(s) *mod* active. Only supports layers 0-15 and the left modifiers: `MOD_LCTL`, `MOD_LSFT`, `MOD_LALT`, `MOD_LGUI` (note the use of `MOD_` constants instead of `KC_`). These modifiers can be combined using bitwise OR, e.g. `LM(_RAISE, MOD_LCTL | MOD_LALT)`.
* `LT(layer, kc)` - momentarily activates *layer* when held, and sends *kc* when tapped. Only supports layers 0-15.
-* `OSL(layer)` - momentarily activates *layer* until the next key is pressed. See [One Shot Keys](#one-shot-keys) for details and additional functionality.
+* `OSL(layer)` - momentarily activates *layer* until the next key is pressed. See [One Shot Keys](one_shot_keys.md) for details and additional functionality.
* `TG(layer)` - toggles *layer*, activating it if it's inactive and vice versa
* `TO(layer)` - activates *layer* and de-activates all other layers (except your default layer). This function is special, because instead of just adding/removing one layer to your active layer stack, it will completely replace your current active layers, uniquely allowing you to replace higher layers with a lower one. This is activated on keydown (as soon as the key is pressed).
* `TT(layer)` - Layer Tap-Toggle. If you hold the key down, *layer* is activated, and then is de-activated when you let go (like `MO`). If you repeatedly tap it, the layer will be toggled on or off (like `TG`). It needs 5 taps by default, but you can change this by defining `TAPPING_TOGGLE` -- for example, `#define TAPPING_TOGGLE 2` to toggle on just two taps.
Sometimes, you might want to switch between layers in a macro or as part of a tap dance routine. `layer_on` activates a layer, and `layer_off` deactivates it. More layer-related functions can be found in [action_layer.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/action_layer.h).
-# Modifier Keys
+# Modifier Keys :id=modifier-keys
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.
|`BACKLIGHT_PWM_CHANNEL` |`3` |The PWM channel to use, see ST datasheets for pin to PWM channel mapping. Unless you are designing your own keyboard, you shouldn't need to change this|
|`BACKLIGHT_PAL_MODE` |`2` |The pin alternative function to use, see ST datasheets for pin AF mapping. Unless you are designing your own keyboard, you shouldn't need to change this|
-## Software PWM Driver
+## Software PWM Driver :id=software-pwm-driver
Emulation of PWM while running other keyboard tasks, it offers maximum hardware compatibility without extra platform configuration. The tradeoff is the backlight might jitter when the keyboard is busy. To enable, add this to your rules.mk:
```makefile
|`6` |Make layer 6 the default layer |
|`7` |Make layer 7 the default layer |
-## Keycodes
+## Keycodes :id=keycodes
|Key |Aliases |Description |
|----------------------------------|---------|--------------------------------------------------------------------------|
|`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 |
-# Bootmagic Lite
+# Bootmagic Lite :id=bootmagic-lite
In addition to the full blown Bootmagic feature, is the Bootmagic Lite feature that only handles jumping into the bootloader. This is great for boards that don't have a physical reset button but you need a way to jump into the bootloader, and don't want to deal with the headache that Bootmagic can cause.
## Caveats
-Key Lock is only able to hold standard action keys and [One Shot modifier](feature_advanced_keycodes.md#one-shot-keys) keys (for example, if you have your Shift defined as `OSM(KC_LSFT)`).
+Key Lock is only able to hold standard action keys and [One Shot modifier](one_shot_keys.md) 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.
## Strict Key Processing
-By default, the Leader Key feature will filter the keycode out of [`Mod-Tap`](feature_advanced_keycodes.md#mod-tap) and [`Layer Tap`](feature_advanced_keycodes.md#switching-and-toggling-layers) functions when checking for the Leader sequences. That means if you're using `LT(3, KC_A)`, it will pick this up as `KC_A` for the sequence, rather than `LT(3, KC_A)`, giving a more expected behavior for newer users.
+By default, the Leader Key feature will filter the keycode out of [`Mod-Tap`](mod_tap.md) and [`Layer Tap`](feature_advanced_keycodes.md#switching-and-toggling-layers) functions when checking for the Leader sequences. That means if you're using `LT(3, KC_A)`, it will pick this up as `KC_A` for the sequence, rather than `LT(3, KC_A)`, giving a more expected behavior for newer users.
While, this may be fine for most, if you want to specify the whole keycode (eg, `LT(3, KC_A)` from the example above) in the sequence, you can enable this by added `#define LEADER_KEY_STRICT_KEY_PROCESSING` to your `config.h` file. This well then disable the filtering, and you'll need to specify the whole keycode.
> In this configuration "hold" takes place **after** tap dance timeout (see `ACTION_TAP_DANCE_FN_ADVANCED_TIME`). To achieve instant hold, remove `state->interrupted` checks in conditions. As a result you may use comfortable longer tapping periods to have more time for taps and not to wait too long for holds (try starting with doubled `TAPPING_TERM`).
-### Example 5: Using tap dance for advanced mod-tap and layer-tap keys
+### Example 5: Using tap dance for advanced mod-tap and layer-tap keys :id=example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys
Tap dance can be used to emulate `MT()` and `LT()` behavior when the tapped code is not a basic keycode. This is useful to send tapped keycodes that normally require `Shift`, such as parentheses or curly braces—or other modified keycodes, such as `Control + X`.
* [Macros](fr-fr/feature_macros.md)
* [Boutons de souris](fr-fr/feature_mouse_keys.md)
* [Pilotes / Drivers OLED](fr-fr/feature_oled_driver.md)
- * [Touche one-shot](fr-fr/feature_advanced_keycodes.md#one-shot-keys)
+ * [Touche one-shot](fr-fr/one_shot_keys.md)
* [Périphériques de pointage](fr-fr/feature_pointing_device.md)
* [Souris PS/2](fr-fr/feature_ps2_mouse.md)
* [Éclairage RGB](fr-fr/feature_rgblight.md)
* [Macros](he-il/feature_macros.md)
* [Mouse Keys](he-il/feature_mouse_keys.md)
* [OLED Driver](he-il/feature_oled_driver.md)
- * [One Shot Keys](he-il/feature_advanced_keycodes.md#one-shot-keys)
+ * [One Shot Keys](he-il/one_shot_keys.md)
* [Pointing Device](he-il/feature_pointing_device.md)
* [PS/2 Mouse](he-il/feature_ps2_mouse.md)
* [RGB Lighting](he-il/feature_rgblight.md)
* [マクロ](ja/feature_macros.md)
* [マウスキー](ja/feature_mouse_keys.md)
* [OLED ドライバ](ja/feature_oled_driver.md)
- * [One Shot Keys](ja/feature_advanced_keycodes.md#one-shot-keys)
+ * [One Shot Keys](ja/one_shot_keys.md)
* [ポインティング デバイス](ja/feature_pointing_device.md)
* [PS/2 マウス](ja/feature_ps2_mouse.md)
* [RGB ライト](ja/feature_rgblight.md)
|----------------|----------------------------------------------------------------------------------|
|`DF(layer)` |Set the base (default) layer |
|`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](feature_advanced_keycodes#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](feature_advanced_keycodes#mod-tap). Example Implementation: `LM(LAYER_1, MOD_LALT)`|
+|`OSL(layer)` |Momentarily activates `layer` until a key is pressed. See [One Shot Keys](one_shot_keys.md) 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.md). 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 |
|`TO(layer)` |Turns on `layer` and turns off all other layers, except the default layer |
|`KC_MEH` | |Left Control, Shift and Alt |
|`KC_HYPR` | |Left Control, Shift, Alt and GUI |
-## [Mod-Tap Keys](feature_advanced_keycodes.md#mod-tap)
+## [Mod-Tap Keys](mod_tap.md)
|Key |Aliases |Description |
|-------------|-----------------------------------------------------------------|-------------------------------------------------------|
|`KC_RIGHT_ANGLE_BRACKET`|`KC_RABK`, `KC_GT` |`>` |
|`KC_QUESTION` |`KC_QUES` |`?` |
-## [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys)
+## [One Shot Keys](one_shot_keys.md)
|Key |Description |
|------------|----------------------------------|
QMK keymaps are defined inside a C source file. The data structure is an array of arrays. The outer array is a list of layer arrays while the inner layer array is a list of keys. Most keyboards define a `LAYOUT()` macro to help you create this array of arrays.
-## Keymap and Layers
+## Keymap and Layers :id=keymap-and-layers
In QMK, **`const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS]`** holds multiple **layers** of keymap information in **16 bit** data holding the **action code**. You can define **32 layers** at most.
For trivial key definitions, the higher 8 bits of the **action code** are all 0 and the lower 8 bits holds the USB HID usage code generated by the key as **keycode**.
Sometimes, the action code stored in keymap may be referred as keycode in some documents due to the TMK history.
-### Keymap Layer Status
+### Keymap Layer Status :id=keymap-layer-status
+
The state of the Keymap layer is determined by two 32 bit parameters:
* **`default_layer_state`** indicates a base keymap layer (0-31) which is always valid and to be referred (the default layer).
?> While you get a feel for how keymaps work, keep each change small. Bigger changes make it harder to debug any problems that arise.
-## Build Your Firmware
+## Build Your Firmware :id=build-your-firmware
When your changes to the keymap are complete you will need to build the firmware. To do so go back to your terminal window and run the compile command:
The simplest way to flash your keyboard will be with the [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases).
-However, the QMK Toolbox is only available for Windows and macOS currently. If you're using Linux (or just wish to flash the firmware from the command line), proceed down to [Flash Your Keyboard From The Command Line](newbs_flashing.md#flash-your-keyboard-from-the-command-line).
+However, the QMK Toolbox is only available for Windows and macOS currently. If you're using Linux (or just wish to flash the firmware from the command line), proceed down to [Flash Your Keyboard From The Command Line](#flash-your-keyboard-from-the-command-line).
### Load The File Into QMK Toolbox
On Windows you will need to install MSYS2 or WSL and use those environments. Instructions for setting up MSYS2 are provided below.
-## 2. Prepare Your Build Environment
+## 2. Prepare Your Build Environment :id=set-up-your-environment
We've tried to make QMK as easy to set up as possible. You only have to prepare your Linux or Unix environment, then let QMK install the rest.
* Fedora / Red Hat / CentOS: `yum install git python3 && python3 -m pip install qmk`
* Arch: `pacman -S qmk`
-## 3. Run QMK Setup
+## 3. Run QMK Setup :id=set-up-qmk
After installing QMK you can set it up with this command:
This switches you to your `master` branch, retrieves the refs from the QMK repo, downloads the current QMK `master` branch to your computer, and then uploads it to your fork.
-## Making Changes
+## Making Changes :id=making-changes
To make changes, create a new branch by entering:
Testing your keyboard is usually pretty straightforward. Press every single key and make sure it sends the keys you expect. You can use [QMK Configurator](https://config.qmk.fm/#/test/)'s test mode to check your keyboard, even if it doesn't run QMK.
-## Debugging
+## Debugging :id=debugging
Your keyboard will output debug information if you have `CONSOLE_ENABLE = yes` in your `rules.mk`. By default the output is very limited, but you can turn on debug mode to increase the amount of debug output. Use the `DEBUG` keycode in your keymap, use the [Command](feature_command.md) feature to enable debug mode, or add the following code to your keymap.
# Prerequisites
## Build Environment
-Before starting, you must have followed the [Getting Started](README.md#getting-started) section corresponding to your system. In particular, you must have been able to build the firmware with [the `make` command](../#the-make-command).
+Before starting, you must have followed the [Getting Started](news_getting_started.md) section of the Tutorial. In particular, you must have been able to build the firmware with [the `qmk compile` command](news_building_firmware#build-your-firmware).
## Java
Eclipse is a Java application, so you will need to install Java 8 or more recent to be able to run it. You may choose between the JRE or the JDK, the latter being useful if you intend to do Java development.
8. Double-click the build target you created to trigger a build.
9. Select the <kbd>Console</kbd> view at the bottom to view the running build.
- [1]: https://en.wikipedia.org/wiki/Eclipse_(software)
\ No newline at end of file
+ [1]: https://en.wikipedia.org/wiki/Eclipse_(software)
* [Macros](pt-br/feature_macros.md)
* [Mouse Keys](pt-br/feature_mouse_keys.md)
* [OLED Driver](pt-br/feature_oled_driver.md)
- * [One Shot Keys](pt-br/feature_advanced_keycodes.md#one-shot-keys)
+ * [One Shot Keys](pt-br/one_shot_keys.md)
* [Pointing Device](pt-br/feature_pointing_device.md)
* [PS/2 Mouse](pt-br/feature_ps2_mouse.md)
* [RGB Lighting](pt-br/feature_rgblight.md)
On this page we have documented keycodes between `0x00FF` and `0xFFFF` which are used to implement advanced quantum features. If you define your own custom keycodes they will be put into this range as well.
-## QMK Keycodes
+## QMK Keycodes :id=qmk-keycodes
|Key |Aliases |Description |
|--------------|---------|-------------------------------------------------------|
There are a lot of hidden functions in QMK that are incredible useful, or may add a bit of functionality that you've been wanting. Functions that are specific to certain features are not included here, as those will be on their respective feature page.
-## (OLKB) Tri Layers
+## (OLKB) Tri Layers :id=olkb-tri-layers
There are actually separate functions that you can use there, depending on what you're after.
* [Macros](ru-ru/feature_macros.md)
* [Mouse Keys](ru-ru/feature_mouse_keys.md)
* [OLED Driver](ru-ru/feature_oled_driver.md)
- * [One Shot Keys](ru-ru/feature_advanced_keycodes.md#one-shot-keys)
+ * [One Shot Keys](ru-ru/one_shot_keys.md)
* [Pointing Device](ru-ru/feature_pointing_device.md)
* [PS/2 Mouse](ru-ru/feature_ps2_mouse.md)
* [RGB Lighting](ru-ru/feature_rgblight.md)
In that model you would emulate the input, and expect a certain output from the emulated keyboard.
-# Tracing Variables
+# Tracing Variables :id=tracing-variables
Sometimes you might wonder why a variable gets changed and where, and this can be quite tricky to track down without having a debugger. It's of course possible to manually add print statements to track it, but you can also enable the variable trace feature. This works for both for variables that are changed by the code, and when the variable is changed by some memory corruption.
* [宏指令](zh-cn/feature_macros.md)
* [鼠标键](zh-cn/feature_mouse_keys.md)
* [OLED驱动](zh-cn/feature_oled_driver.md)
- * [一键功能](zh-cn/feature_advanced_keycodes.md#one-shot-keys)
+ * [一键功能](zh-cn/one_shot_keys.md)
* [指针设备](zh-cn/feature_pointing_device.md)
* [PS/2鼠标](zh-cn/feature_ps2_mouse.md)
* [RGB灯光](zh-cn/feature_rgblight.md)
HCoop / jackhill / qmk / firmware.git / commitdiff