From 08c682c193f43e5d54df990680ae93fc2e06150a Mon Sep 17 00:00:00 2001 From: Evan Travers Date: Tue, 28 Aug 2018 19:35:24 -0500 Subject: Docs: Add docs for the `LAYOUT_*` macro to layouts (#3772) When moving my planck layout to my let's split, I ran into this issue because I had copied my planck layout from the default layout which just used the `{}` array form for the keymap layers. I checked the docs, but this bit wasn't clear to me. I'm sure @ishtob or @drashna helped me on discord, but this seemed to be the logical place to add a helpful hint. --- docs/feature_layouts.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs') diff --git a/docs/feature_layouts.md b/docs/feature_layouts.md index bfae920440..1ee8b5e35c 100644 --- a/docs/feature_layouts.md +++ b/docs/feature_layouts.md @@ -53,6 +53,8 @@ but the `LAYOUT_` variable must be defined in `.h` as well. ## Tips for Making Layouts Keyboard-Agnostic +### Includes + Instead of using `#include "planck.h"`, you can use this line to include whatever `.h` (`.h` should not be included here) file that is being compiled: #include QMK_KEYBOARD_H @@ -72,3 +74,7 @@ For example: ``` Note that the names are lowercase and match the folder/file names for the keyboard/revision exactly. + +### Keymaps + +In order to support both split and non-split keyboards with the same layout, you need to use the keyboard agnostic `LAYOUT_` macro in your keymap. For instance, in order for a Let's Split and Planck to share the same layout file, you need to use `LAYOUT_ortho_4x12` instead of `LAYOUT_planck_grid` or just `{}` for a C array. -- cgit v1.2.3 From 097f1a299f2d0e0e5afe174b8cfc1eea1b00c7cf Mon Sep 17 00:00:00 2001 From: fauxpark Date: Thu, 30 Aug 2018 11:05:02 +1000 Subject: Mask off keycode/layer/mod where possible in LT(), MT(), etc. (#3430) * Mask off keycode/layer/mod where possible in LT(), MT(), etc. * Don't need these parentheses * Put back parentheses for order of operations --- docs/feature_advanced_keycodes.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md index f93b8033a5..5713234be1 100644 --- a/docs/feature_advanced_keycodes.md +++ b/docs/feature_advanced_keycodes.md @@ -13,9 +13,11 @@ People often define custom names using `#define`. For example: This will allow you to use `FN_CAPS` and `ALT_TAB` in your `KEYMAP()`, keeping it more readable. -### Limits of These Aliases +### Caveats -Currently, the keycodes able to used with these functions are limited to the [Basic Keycodes](keycodes_basic.md), meaning you can't use keycodes like `KC_TILD`, or anything greater than 0xFF. For a full list of the keycodes able to be used see [Basic Keycodes](keycodes_basic.md). +Currently, `LT()` and `MT()` are limited to the [Basic Keycode set](keycodes_basic.md), meaning you can't use keycodes like `LCTL()`, `KC_TILD`, or anything greater than `0xFF`. Modifiers specified as part of a Layer Tap or Mod Tap's keycode will be ignored. + +Additionally, if at least one right-handed modifier is specified in a Mod Tap or Layer Tap, it will cause all modifiers specified to become right-handed, so it is not possible to mix and match the two. # Switching and Toggling Layers @@ -103,10 +105,6 @@ We've added shortcuts to make common modifier/tap (mod-tap) mappings more compac * `LCAG_T(kc)` - is CtrlAltGui when held and *kc* when tapped * `MEH_T(kc)` - is like Hyper, but not as cool -- does not include the Cmd/Win key, so just sends Alt+Ctrl+Shift. -?> 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-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 One shot keys are keys that remain active until the next key is pressed, and then are released. This allows you to type keyboard combinations without pressing more than one key at a time. These keys are usually called "Sticky keys" or "Dead keys". -- cgit v1.2.3 From 4cd4e1ded686f2799cfd87750200fcd6fba445ee Mon Sep 17 00:00:00 2001 From: arlenk <33534303+arlenk@users.noreply.github.com> Date: Wed, 29 Aug 2018 21:20:41 -0400 Subject: Docs: add process_terminal() and update links to other functions (#3778) * add process_terminal() and update links to other functions * convert links to permalinks and add a few missing process_* functions * update links in main text as well --- docs/understanding_qmk.md | 53 ++++++++++++++++++++++++++--------------------- 1 file changed, 29 insertions(+), 24 deletions(-) (limited to 'docs') diff --git a/docs/understanding_qmk.md b/docs/understanding_qmk.md index 4544cb2602..bf695d008d 100644 --- a/docs/understanding_qmk.md +++ b/docs/understanding_qmk.md @@ -12,7 +12,7 @@ You can think of QMK as no different from any other computer program. It is star The reason for this is the different platforms that QMK supports. The most common platform is `lufa`, which runs on AVR processors such at the atmega32u4. We also support `chibios` and `vusb`. -We'll focus on AVR processors for the moment, which use the `lufa` platform. You can find the `main()` function in [tmk_core/protocol/lufa/lufa.c](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/protocol/lufa/lufa.c#L1129). If you browse through that function you'll find that it initializes any hardware that has been configured (including USB to the host) and then it starts the core part of the program with a [`while(1)`](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/protocol/lufa/lufa.c#L1182). This is [The Main Loop](#the_main_loop). +We'll focus on AVR processors for the moment, which use the `lufa` platform. You can find the `main()` function in [tmk_core/protocol/lufa/lufa.c](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/tmk_core/protocol/lufa/lufa.c#L1019). If you browse through that function you'll find that it initializes any hardware that has been configured (including USB to the host) and then it starts the core part of the program with a [`while(1)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/tmk_core/protocol/lufa/lufa.c#L1060). This is [The Main Loop](#the-main-loop). ## The Main Loop @@ -22,7 +22,7 @@ This section of code is called "The Main Loop" because it's responsible for loop keyboard_task(); ``` -This is where all the keyboard specific functionality is dispatched. The source code for `keyboard_task()` can be found in [tmk_core/common/keyboard.c](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/keyboard.c#L154), and it is responsible for detecting changes in the matrix and turning status LED's on and off. +This is where all the keyboard specific functionality is dispatched. The source code for `keyboard_task()` can be found in [tmk_core/common/keyboard.c](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/tmk_core/common/keyboard.c#L206), and it is responsible for detecting changes in the matrix and turning status LED's on and off. Within `keyboard_task()` you'll find code to handle: @@ -77,7 +77,7 @@ At the keyboard level we define a C macro (typically named `KEYMAP()`) which map Notice how the second block of our `KEYMAP()` macro matches the Matrix Scanning array above? This macro is what will map the matrix scanning array to keycodes. However, if you look at a 17 key numpad you'll notice that it has 3 places where the matrix could have a switch but doesn't, due to larger keys. We have populated those spaces with `KC_NO` so that our keymap definition doesn't have to. -You can also use this macro to handle unusual matrix layouts, for example the [Clueboard rev 2](https://github.com/qmk/qmk_firmware/blob/master/keyboards/clueboard/66/rev2/rev2.h). Explaining that is outside the scope of this document. +You can also use this macro to handle unusual matrix layouts, for example the [Clueboard rev 2](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/keyboards/clueboard/66/rev2/rev2.h). Explaining that is outside the scope of this document. ##### Keycode Assignment @@ -129,27 +129,32 @@ Comparing against our keymap we can see that the pressed key is KC_NLCK. From he ##### Process Record - -The `process_record()` function itself is deceptively simple, but hidden within is a gateway to overriding functionality at various levels of QMK. The chain of events is described below, using cluecard whenever we need to look at the keyboard/keymap level functions. - -* [`void process_record(keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/action.c#L128) - * [`bool process_record_quantum(keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/quantum.c#L140) - * [Map this record to a keycode](https://github.com/qmk/qmk_firmware/blob/master/quantum/quantum.c#L143) - * [`bool process_record_kb(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/keyboards/clueboard/card/card.c#L20) - * [`bool process_record_user(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/keyboards/clueboard/card/keymaps/default/keymap.c#L58) - * [`bool process_midi(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_midi.c#L102) - * [`bool process_audio(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_audio.c#L10) - * [`bool process_music(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_music.c#L69) - * [`bool process_tap_dance(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_tap_dance.c#L75) - * [`bool process_leader(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_leader.c#L32) - * [`bool process_chording(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_chording.c#L41) - * [`bool process_combo(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_combo.c#L115) - * [`bool process_unicode(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_unicode.c#L22) - * [`bool process_ucis(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_ucis.c#L91) - * [`bool process_printer(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_printer.c#L77) - * [`bool process_auto_shift(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_auto_shift.c#L47) - * [`bool process_unicode_map(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_unicodemap.c#L47) - * [Identify and process quantum specific keycodes](https://github.com/qmk/qmk_firmware/blob/master/quantum/quantum.c#L211) +The `process_record()` function itself is deceptively simple, but hidden within is a gateway to overriding functionality at various levels of QMK. The chain of events is listed below, using cluecard whenever we need to look at the keyboard/keymap level functions. Depending on options set in rule.mk or elsewhere, only a subset of the functions below will be included in final firmware. + +* [`void process_record(keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/08c682c193f43e5d54df990680ae93fc2e06150a/tmk_core/common/action.c#L172) + * [`bool process_record_quantum(keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/08c682c193f43e5d54df990680ae93fc2e06150a/quantum/quantum.c#L193) + * [Map this record to a keycode](https://github.com/qmk/qmk_firmware/blob/08c682c193f43e5d54df990680ae93fc2e06150a/quantum/quantum.c#L213) + * [`void preprocess_tap_dance(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/08c682c193f43e5d54df990680ae93fc2e06150a/quantum/process_keycode/process_tap_dance.c#L115) + * [`bool process_key_lock(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/08c682c193f43e5d54df990680ae93fc2e06150a/quantum/process_keycode/process_key_lock.c#L62) + * [`bool process_clicky(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/08c682c193f43e5d54df990680ae93fc2e06150a/quantum/process_keycode/process_clicky.c#L44) + * [`bool process_record_kb(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/08c682c193f43e5d54df990680ae93fc2e06150a/keyboards/clueboard/card/card.c#L20) + * [`bool process_record_user(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/08c682c193f43e5d54df990680ae93fc2e06150a/keyboards/clueboard/card/keymaps/default/keymap.c#L58) + * [`bool process_rgb_matrix(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/fdd0f915271f79b104aa5d216566bcc3fd134e85/quantum/rgb_matrix.c#L139) + * [`bool process_midi(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_midi.c#L81) + * [`bool process_audio(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_audio.c#L19) + * [`bool process_steno(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_steno.c#L160) + * [`bool process_music(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_music.c#L114) + * [`bool process_tap_dance(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_tap_dance.c#L136) + * [`bool process_leader(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_leader.c#L38) + * [`bool process_chording(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_chording.c#L41) + * [`bool process_combo(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_combo.c#L115) + * [`bool process_unicode(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_unicode.c#L22) + * [`bool process_ucis(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_ucis.c#L91) + * [`bool process_printer(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_printer.c#L77) + * [`bool process_auto_shift(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_auto_shift.c#L94) + * [`bool process_unicode_map(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_unicodemap.c#L47) + * [`bool process_terminal(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_terminal.c#L264) + * [Identify and process quantum specific keycodes](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/quantum.c#L287) At any step during this chain of events a function (such as `process_record_kb()`) can `return false` to halt all further processing. -- cgit v1.2.3 From 1acaf2b2c22eb6bd77374b93101480207829db04 Mon Sep 17 00:00:00 2001 From: fauxpark Date: Thu, 30 Aug 2018 16:22:29 +1000 Subject: Tweak the wording in "Becoming a QMK Collaborator" --- docs/becoming_a_qmk_collaborator.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/becoming_a_qmk_collaborator.md b/docs/becoming_a_qmk_collaborator.md index 3cac63c97b..16ae0d569e 100644 --- a/docs/becoming_a_qmk_collaborator.md +++ b/docs/becoming_a_qmk_collaborator.md @@ -1,7 +1,9 @@ -A QMK collaborator is a keyboard maker/designer that is interested in helping QMK grow and fully support their keyboard(s), and encouraging their users/customers to submit features, ideas, and keymaps. We're always looking to add more keyboards and collaborators, but we ask that they fulfill these requirements: +# Becoming a QMK Collaborator -* **Have a PCB available for sale** - unfortunately there's just too much variation and complications with handwired keyboards. -* **Maintain the your keyboard's directory** - this may just require an initial setup to get your keyboard working, but it could also include accommodating changes made to QMK's core. -* **Approve and merge your keyboard's keymap pull requests** - we like to encourage users to contribute their keymaps for others to see and work from when creating their own. +A QMK collaborator is a keyboard maker or designer that is interested in helping QMK grow and fully support their keyboard(s), and encouraging their users and customers to submit features, ideas, and keymaps. We're always looking to add more keyboards and collaborators, but we ask that they fulfill these requirements: + +* **Have a PCB available for sale.** Unfortunately there's just too much variation and complications with handwired keyboards. +* **Maintain your keyboard in QMK.** This may just require an initial setup to get your keyboard working, but it could also include accommodating changes made to QMK's core that might break or render any custom code redundant. +* **Approve and merge keymap pull requests for your keyboard.** We like to encourage users to contribute their keymaps for others to see and work from when creating their own. If you feel you meet these requirements, shoot us an email at hello@qmk.fm with an introduction and some links to your keyboard! -- cgit v1.2.3 From ce3ccd3f4a5e8ff8ac391887f3357dd8e985a452 Mon Sep 17 00:00:00 2001 From: fauxpark Date: Fri, 31 Aug 2018 02:37:05 +1000 Subject: Docs: Tabulate Modifier & Mod-Tap keycode listings in advanced keycodes docs (#3799) --- docs/feature_advanced_keycodes.md | 114 ++++++++++++++++++++++---------------- docs/keycodes.md | 4 +- 2 files changed, 69 insertions(+), 49 deletions(-) (limited to 'docs') diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md index 5713234be1..5f30359e0d 100644 --- a/docs/feature_advanced_keycodes.md +++ b/docs/feature_advanced_keycodes.md @@ -57,53 +57,73 @@ Sometimes, you might want to switch between layers in a macro or as part of a ta # Modifier Keys -These functions allow you to combine a mod with a keycode. When pressed the keydown for the mod will be sent first, and then *kc* will be sent. When released the keyup for *kc* will be sent and then the mod will be sent. - -* `LSFT(kc)` or `S(kc)` - applies left Shift to *kc* (keycode) -* `RSFT(kc)` - applies right Shift to *kc* -* `LCTL(kc)` - applies left Control to *kc* -* `RCTL(kc)` - applies right Control to *kc* -* `LALT(kc)` - applies left Alt to *kc* -* `RALT(kc)` - applies right Alt to *kc* -* `LGUI(kc)` - applies left GUI (command/win) to *kc* -* `RGUI(kc)` - applies right GUI (command/win) to *kc* -* `HYPR(kc)` - applies Hyper (all modifiers) to *kc* -* `MEH(kc)` - applies Meh (all modifiers except Win/Cmd) to *kc* -* `LCAG(kc)` - applies CtrlAltGui to *kc* - -You can also chain these, like this: - - LALT(LCTL(KC_DEL)) -- this makes a key that sends Alt, Control, and Delete in a single keypress. - -# Mod Tap - -`MT(mod, kc)` - is *mod* (modifier key - MOD_LCTL, MOD_LSFT) when held, and *kc* when tapped. In other words, you can have a key that sends Esc (or the letter O or whatever) when you tap it, but works as a Control key or a Shift key when you hold it down. - -These are the values you can use for the `mod` in `MT()` and `OSM()`: - - * MOD_LCTL - * MOD_LSFT - * MOD_LALT - * MOD_LGUI - * MOD_RCTL - * MOD_RSFT - * MOD_RALT - * MOD_RGUI - * MOD_HYPR - * MOD_MEH - -These can also be combined like `MOD_LCTL | MOD_LSFT` e.g. `MT(MOD_LCTL | MOD_LSFT, KC_ESC)` which would activate Control and Shift when held, and send Escape when tapped. - -We've added shortcuts to make common modifier/tap (mod-tap) mappings more compact: - - * `CTL_T(kc)` - is LCTL when held and *kc* when tapped - * `SFT_T(kc)` - is LSFT when held and *kc* when tapped - * `ALT_T(kc)` - is LALT when held and *kc* when tapped - * `ALGR_T(kc)` - is AltGr when held and *kc* when tapped - * `GUI_T(kc)` - is LGUI when held and *kc* when tapped - * `ALL_T(kc)` - is Hyper (all mods) when held and *kc* when tapped. To read more about what you can do with a Hyper key, see [this blog post by Brett Terpstra](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/) - * `LCAG_T(kc)` - is CtrlAltGui when held and *kc* when tapped - * `MEH_T(kc)` - is like Hyper, but not as cool -- does not include the Cmd/Win key, so just sends Alt+Ctrl+Shift. +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)`| |Hold Left Control and press `kc` | +|`LSFT(kc)`|`S(kc)` |Hold Left Shift and press `kc` | +|`LALT(kc)`| |Hold Left Alt and press `kc` | +|`LGUI(kc)`|`LCMD(kc)`, `LWIN(kc)`|Hold Left GUI and press `kc` | +|`RCTL(kc)`| |Hold Right Control and press `kc` | +|`RSFT(kc)`| |Hold Right Shift and press `kc` | +|`RALT(kc)`| |Hold Right Alt and press `kc` | +|`RGUI(kc)`|`RCMD(kc)`, `LWIN(kc)`|Hold Right GUI and press `kc` | +|`HYPR(kc)`| |Hold Left Control, Shift, Alt and GUI and press `kc`| +|`MEH(kc)` | |Hold Left Control, Shift and Alt and press `kc` | +|`LCAG(kc)`| |Hold Left Control, Alt and GUI and press `kc` | +|`ALTG(kc)`| |Hold Right Control and Alt and press `kc` | +|`SGUI(kc)`|`SCMD(kc)`, `SWIN(kc)`|Hold Left Shift and GUI and press `kc` | +|`LCA(kc)` | |Hold Left Control and Alt and press `kc` | + +You can also chain them, for example `LCTL(LALT(KC_DEL))` makes a key that sends Control+Alt+Delete with a single keypress. + +# Mod-Tap + +The Mod-Tap key `MT(mod, kc)` acts like a modifier when held, and a regular keycode when tapped. In other words, you can have a key that sends Escape when you tap it, but functions as a Control or Shift key when you hold it down. + +The modifiers this keycode and `OSM()` accept are prefixed with `MOD_`, not `KC_`: + +|Modifier |Description | +|----------|----------------------------------------| +|`MOD_LCTL`|Left Control | +|`MOD_LSFT`|Left Shift | +|`MOD_LALT`|Left Alt | +|`MOD_LGUI`|Left GUI (Windows/Command/Meta key) | +|`MOD_RCTL`|Right Control | +|`MOD_RSFT`|Right Shift | +|`MOD_RALT`|Right Alt | +|`MOD_RGUI`|Right GUI (Windows/Command/Meta key) | +|`MOD_HYPR`|Hyper (Left Control, Shift, Alt and GUI)| +|`MOD_MEH` |Meh (Left Control, Shift, and Alt) | + +You can combine these by ORing them together like so: + +```c +MT(MOD_LCTL | MOD_LSFT, KC_ESC) +``` + +This key would activate Left Control and Left Shift when held, and send Escape when tapped. + +For convenience, QMK includes some Mod-Tap shortcuts to make common combinations more compact in your keymap: + +|Key |Aliases |Description | +|------------|---------------------------------------|-------------------------------------------------------| +|`LCTL_T(kc)`|`CTL_T(kc)` |Left Control when held, `kc` when tapped | +|`RCTL_T(kc)`| |Right Control when held, `kc` when tapped | +|`LSFT_T(kc)`|`SFT_T(kc)` |Left Shift when held, `kc` when tapped | +|`RSFT_T(kc)`| |Right Shift when held, `kc` when tapped | +|`LALT_T(kc)`|`ALT_T(kc)` |Left Alt when held, `kc` when tapped | +|`RALT_T(kc)`|`ALGR_T(kc)` |Right Alt when held, `kc` when tapped | +|`LGUI_T(kc)`|`LCMD_T(kc)`, `RWIN_T(kc)`, `GUI_T(kc)`|Left GUI when held, `kc` when tapped | +|`RGUI_T(kc)`|`RCMD_T(kc)`, `RWIN_T(kc)` |Right GUI when held, `kc` when tapped | +|`C_S_T(kc)` | |Left Control and Shift when held, `kc` when tapped | +|`MEH_T(kc)` | |Left Control, Shift and Alt when held, `kc` when tapped| +|`LCAG_T(kc)`| |Left Control, Alt and GUI when held, `kc` when tapped | +|`RCAG_T(kc)`| |Right Control, Alt and GUI when held, `kc` when tapped | +|`ALL_T(kc)` | |Left Control, Shift, Alt and GUI when held, `kc` when tapped - more info [here](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)| +|`SGUI_T(kc)`|`SCMD_T(kc)`, `SWIN_T(kc)` |Left Shift and GUI when held, `kc` when tapped | +|`LCA_T(kc)` | |Left Control and Alt when held, `kc` when tapped | # One Shot Keys diff --git a/docs/keycodes.md b/docs/keycodes.md index fd3776bb72..c344a75283 100644 --- a/docs/keycodes.md +++ b/docs/keycodes.md @@ -318,7 +318,7 @@ This is a reference only. Each group of keys links to the page documenting their ## [Modifiers](feature_advanced_keycodes.md#modifier-keys) |Key |Aliases |Description | -|----------|---------- |----------------------------------------------------| +|----------|----------------------|----------------------------------------------------| |`KC_HYPR` | |Hold Left Control, Shift, Alt and GUI | |`KC_MEH` | |Hold Left Control, Shift and Alt | |`LCTL(kc)`| |Hold Left Control and press `kc` | @@ -353,7 +353,7 @@ This is a reference only. Each group of keys links to the page documenting their |`LCAG_T(kc)`| |Left Control, Alt and GUI when held, `kc` when tapped | |`RCAG_T(kc)`| |Right Control, Alt and GUI when held, `kc` when tapped | |`ALL_T(kc)` | |Left Control, Shift, Alt and GUI when held, `kc` when tapped - more info [here](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)| -|`SCMD_T(kc)`|`SWIN_T(kc)` |Left Shift and GUI when held, `kc` when tapped | +|`SGUI_T(kc)`|`SCMD_T(kc)`, `SWIN_T(kc)` |Left Shift and GUI when held, `kc` when tapped | |`LCA_T(kc)` | |Left Control and Alt when held, `kc` when tapped | ## [RGB Lighting](feature_rgblight.md) -- cgit v1.2.3 From 73a3399d0ef7e06db70fc2964a3f2a35e9aca25d Mon Sep 17 00:00:00 2001 From: yiancar Date: Fri, 24 Aug 2018 15:38:31 +0300 Subject: Add the ability to disable the USB startup check for Chibios - Added support for NO_USB_STARTUP_CHECK. This allows the keyboard do function and not get stuck in a SUSPENDED state loop in case of no USB connection. - Added support for WAIT_FOR_USB. In LUFA no keyboard has this flag enable therefor no keyboard waits for usb to be active. - Added documentation for both configuration flags as they were missing. --- docs/config_options.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/config_options.md b/docs/config_options.md index e978bcce82..eaaa59872c 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -248,3 +248,7 @@ Use these to enable or disable building certain features. The more you have enab * Enable Bluetooth with the Adafruit EZ-Key HID * `SPLIT_KEYBOARD` * Enables split keyboard support (dual MCU like the let's split and bakingpy's boards) and includes all necessary files located at quantum/split_common +* `WAIT_FOR_USB` + * Forces the keyboard to wait for a USB connection to be established before it starts up +* `NO_USB_STARTUP_CHECK` + * Disables usb suspend check after keyboard startup. Usually the keyboard waits for the host to wake it up before any tasks are performed. This is useful for split keyboards as one half will not get a wakeup call but must send commands to the master. -- cgit v1.2.3 From 6d6d91c834ef3415425e21d895d4ec91c67fd4b8 Mon Sep 17 00:00:00 2001 From: Takeshi ISHII <2170248+mtei@users.noreply.github.com> Date: Fri, 14 Sep 2018 02:24:10 +0900 Subject: rgblight.[ch] more configurable (#3582) * add temporary test code rgblight-macro-test1.[ch] * rgblight.h : mode auto numberring and auto generate mode name symbol No change in build result. * rgblight.c use RGBLIGHT_MODE_xxx symbols No change in build result. * quantum.c use RGBLIGHT_MODE_xxx symbols No change in build result. * fix build break. when RGB_MATRIX_ENABLE defined * add temporary test code rgblight-macro-test2.[ch] * modify rgblight_mode_eeprom_helper() and rgblight_sethsv_eeprom_helper() * modify rgblight_task() * configurable each effect compile on/off in config.h * update docs/feature_rgblight.md * fix conflict. docs/feature_rgblight.md * remove temporary test code rgblight-macro-test*.[ch] * fix comment typo. * remove old mode number from comment * update docs/feature_rgblight.md about effect mode * Revert "update docs/feature_rgblight.md about effect mode" This reverts commit 43890663fcc9dda1899df7a37d382fc38b1a6d6d. * some change docs/feature_rgblight.md * fix typo * docs/feature_rgblight.md update: revise mode number table --- docs/feature_rgblight.md | 42 +++++++++++++++++++++++++++--------------- 1 file changed, 27 insertions(+), 15 deletions(-) (limited to 'docs') diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md index d48941a04f..925dca724b 100644 --- a/docs/feature_rgblight.md +++ b/docs/feature_rgblight.md @@ -79,20 +79,23 @@ Your RGB lighting can be configured by placing these `#define`s in your `config. ## Animations -Not only can this lighting be whatever color you want, if `RGBLIGHT_ANIMATIONS` is defined, you also have a number of animation modes at your disposal: - -|Mode |Description | -|-----|---------------------| -|1 |Solid color | -|2-5 |Solid color breathing| -|6-8 |Cycling rainbow | -|9-14 |Swirling rainbow | -|15-20|Snake | -|21-23|Knight | -|24 |Christmas | -|25-34|Static gradient | -|35 |RGB Test | -|36 |Alternating | + +Not only can this lighting be whatever color you want, +if `RGBLIGHT_EFFECT_xxxx` or `RGBLIGHT_ANIMATIONS` is defined, you also have a number of animation modes at your disposal: + +|Mode number symbol |Additional number |Description | +|-----------------------------|-------------------|---------------------------------------| +|`RGBLIGHT_MODE_STATIC_LIGHT` | *None* |Solid color (this mode is always enabled) | +|`RGBLIGHT_MODE_BREATHING` | 0,1,2,3 |Solid color breathing | +|`RGBLIGHT_MODE_RAINBOW_MOOD` | 0,1,2 |Cycling rainbow | +|`RGBLIGHT_MODE_RAINBOW_SWIRL`| 0,1,2,3,4,5 |Swirling rainbow | +|`RGBLIGHT_MODE_SNAKE` | 0,1,2,3,4,5 |Snake | +|`RGBLIGHT_MODE_KNIGHT` | 0,1,2 |Knight | +|`RGBLIGHT_MODE_CHRISTMAS` | *None* |Christmas | +|`RGBLIGHT_MODE_STATIC_GRADIENT`| 0,1,..,9 |Static gradient | +|`RGBLIGHT_MODE_RGB_TEST` | *None* |RGB Test | +|`RGBLIGHT_MODE_ALTERNATING` | *None* |Alternating | + Check out [this video](https://youtube.com/watch?v=VKrpPAHlisY) for a demonstration. @@ -100,7 +103,16 @@ The following options can be used to tweak the various animations: |Define |Default |Description | |------------------------------------|-------------|-------------------------------------------------------------------------------------| -|`RGBLIGHT_ANIMATIONS` |*Not defined*|If defined, enables additional animation modes | +|`RGBLIGHT_EFFECT_BREATHING` |*Not defined*|If defined, enable breathing animation mode. | +|`RGBLIGHT_EFFECT_RAINBOW_MOOD` |*Not defined*|If defined, enable rainbow mood animation mode. | +|`RGBLIGHT_EFFECT_RAINBOW_SWIRL` |*Not defined*|If defined, enable rainbow swirl animation mode. | +|`RGBLIGHT_EFFECT_SNAKE` |*Not defined*|If defined, enable snake animation mode. | +|`RGBLIGHT_EFFECT_KNIGHT` |*Not defined*|If defined, enable knight animation mode. | +|`RGBLIGHT_EFFECT_CHRISTMAS` |*Not defined*|If defined, enable christmas animation mode. | +|`RGBLIGHT_EFFECT_STATIC_GRADIENT` |*Not defined*|If defined, enable static gradient mode. | +|`RGBLIGHT_EFFECT_RGB_TEST` |*Not defined*|If defined, enable RGB test animation mode. | +|`RGBLIGHT_EFFECT_ALTERNATING` |*Not defined*|If defined, enable alternating animation mode. | +|`RGBLIGHT_ANIMATIONS` |*Not defined*|If defined, enables all additional animation modes | |`RGBLIGHT_EFFECT_BREATHE_CENTER` |`1.85` |Used to calculate the curve for the breathing animation. Valid values are 1.0 to 2.7 | |`RGBLIGHT_EFFECT_BREATHE_MAX` |`255` |The maximum brightness for the breathing mode. Valid values are 1 to 255 | |`RGBLIGHT_EFFECT_SNAKE_LENGTH` |`4` |The number of LEDs to light up for the "Snake" animation | -- cgit v1.2.3 From 170de1273cde78d93b3f955aca133a4d690742b2 Mon Sep 17 00:00:00 2001 From: MechMerlin <30334081+mechmerlin@users.noreply.github.com> Date: Thu, 13 Sep 2018 11:22:05 -0700 Subject: Add an easy way to create new keymaps for your favorite keyboard (#3868) * initial commit of keymap creation script * create default keymap * pass shellcheck * provide a better usage message * change printf string to more accurately reflect the path * make it more easily understood * found another typo * add documentation regarding the new_keymap script * enforce lowercase for userinputs --- docs/newbs_building_firmware.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'docs') diff --git a/docs/newbs_building_firmware.md b/docs/newbs_building_firmware.md index f227d623f0..ac6bff2bc7 100644 --- a/docs/newbs_building_firmware.md +++ b/docs/newbs_building_firmware.md @@ -22,6 +22,20 @@ Start by navigating to the `keymaps` folder for your keyboard. Once you have the `keymaps` folder open you will want to create a copy of the `default` folder. We highly recommend you name your folder the same as your GitHub username, but you can use any name you want as long as it contains only lower case letters, numbers, and the underscore character. +To automate the process, you also have the option to run the `new_keymap.sh` script. + +Navigate to the `qmk_firmware/util` directory and type the following: + +``` +./new_keymap.sh +``` + +For example, for a user named John, trying to make a new keymap for the 1up60hse, they would type in + +``` +./new_keymap.sh 1upkeyboards/1up60hse john +``` + ## Open `keymap.c` In Your Favorite Text Editor Open up your `keymap.c`. Inside this file you'll find the structure that controls how your keyboard behaves. At the top of `keymap.c` there may be some defines and enums that make the keymap easier to read. Farther down you'll find a line that looks like this: -- cgit v1.2.3 From b1f11636c63694f0e94504e5752e963c73f86c3b Mon Sep 17 00:00:00 2001 From: James Laird-Wah Date: Sat, 15 Sep 2018 11:50:12 +1000 Subject: docs/contributing: add `#pragma once` to Coding Conventions This supersedes the older include guard mechanism since all the compilers now support it. It's easier for new users and less prone to error. --- docs/contributing.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/contributing.md b/docs/contributing.md index 8242cc1adc..7ed7cd06a5 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -70,6 +70,7 @@ Most of our style is pretty easy to pick up on, but right now it's not entirely * Do not write obvious comments * If you not sure if a comment is obvious, go ahead and include it. * In general we don't wrap lines, they can be as long as needed. If you do choose to wrap lines please do not wrap any wider than 76 columns. +* We use `#pragma once` at the start of header files rather than old-style include guards (`#ifndef THIS_FILE_H`, `#define THIS_FILE_H`, ..., `#endif`) # General Guidelines -- cgit v1.2.3 From 743449472e58651ec8111e6f70811103fb0a28bd Mon Sep 17 00:00:00 2001 From: Joe Wasson Date: Mon, 17 Sep 2018 10:48:02 -0700 Subject: Make `PREVENT_STUCK_MODIFIERS` the default (#3107) * Remove chording as it is not documented, not used, and needs work. * Make Leader Key an optional feature. * Switch from `PREVENT_STUCK_MODIFIERS` to `STRICT_LAYER_RELEASE` * Remove `#define PREVENT_STUCK_MODIFIERS` from keymaps. --- docs/config_options.md | 4 ++-- docs/feature_leader_key.md | 8 ++++++++ docs/understanding_qmk.md | 2 +- 3 files changed, 11 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/config_options.md b/docs/config_options.md index eaaa59872c..072857727b 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -119,8 +119,8 @@ If you define these options you will enable the associated feature, which may in * `#define FORCE_NKRO` * NKRO by default requires to be turned on, this forces it on during keyboard startup regardless of EEPROM setting. NKRO can still be turned off but will be turned on again if the keyboard reboots. -* `#define PREVENT_STUCK_MODIFIERS` - * stores the layer a key press came from so the same layer is used when the key is released, regardless of which layers are enabled +* `#define STRICT_LAYER_RELEASE` + * force a key release to be evaluated using the current layer stack instead of remembering which layer it came from (used for advanced cases) ## Behaviors That Can Be Configured diff --git a/docs/feature_leader_key.md b/docs/feature_leader_key.md index 46633b2870..0c3f4a1332 100644 --- a/docs/feature_leader_key.md +++ b/docs/feature_leader_key.md @@ -39,3 +39,11 @@ void matrix_scan_user(void) { As you can see, you have a few function. You can use `SEQ_ONE_KEY` for single-key sequences (Leader followed by just one key), and `SEQ_TWO_KEYS`, `SEQ_THREE_KEYS` up to `SEQ_FIVE_KEYS` for longer sequences. Each of these accepts one or more keycodes as arguments. This is an important point: You can use keycodes from **any layer on your keyboard**. That layer would need to be active for the leader macro to fire, obviously. + +## Adding Leader Key Support in the `rules.mk` + +To add support for Leader Key you simply need to add a single line to your keymap's `rules.mk`: + +``` +LEADER_ENABLE = yes +``` diff --git a/docs/understanding_qmk.md b/docs/understanding_qmk.md index bf695d008d..35596cc692 100644 --- a/docs/understanding_qmk.md +++ b/docs/understanding_qmk.md @@ -129,6 +129,7 @@ Comparing against our keymap we can see that the pressed key is KC_NLCK. From he ##### Process Record + The `process_record()` function itself is deceptively simple, but hidden within is a gateway to overriding functionality at various levels of QMK. The chain of events is listed below, using cluecard whenever we need to look at the keyboard/keymap level functions. Depending on options set in rule.mk or elsewhere, only a subset of the functions below will be included in final firmware. * [`void process_record(keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/08c682c193f43e5d54df990680ae93fc2e06150a/tmk_core/common/action.c#L172) @@ -146,7 +147,6 @@ The `process_record()` function itself is deceptively simple, but hidden within * [`bool process_music(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_music.c#L114) * [`bool process_tap_dance(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_tap_dance.c#L136) * [`bool process_leader(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_leader.c#L38) - * [`bool process_chording(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_chording.c#L41) * [`bool process_combo(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_combo.c#L115) * [`bool process_unicode(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_unicode.c#L22) * [`bool process_ucis(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_ucis.c#L91) -- cgit v1.2.3 From 244e1c5a57eecd349c7d88e1af42d1b3467aeafe Mon Sep 17 00:00:00 2001 From: dsissitka Date: Sun, 16 Sep 2018 17:49:20 -0400 Subject: Fix LEADER_KEY docs. LEADER_KEY needs to be set in config.h, not keymap.c. Credit goes to @randywallace for figuring this one out: https://github.com/qmk/qmk_firmware/issues/2514#issuecomment-384847485 --- docs/feature_leader_key.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/feature_leader_key.md b/docs/feature_leader_key.md index 0c3f4a1332..92aebd463d 100644 --- a/docs/feature_leader_key.md +++ b/docs/feature_leader_key.md @@ -5,7 +5,7 @@ If you've ever used Vim, you know what a Leader key is. If not, you're about to That's what `KC_LEAD` does. Here's an example: 1. Pick a key on your keyboard you want to use as the Leader key. Assign it the keycode `KC_LEAD`. This key would be dedicated just for this -- it's a single action key, can't be used for anything else. -2. Include the line `#define LEADER_TIMEOUT 300` somewhere in your keymap.c file, probably near the top. The 300 there is 300ms -- that's how long you have for the sequence of keys following the leader. You can tweak this value for comfort, of course. +2. Include the line `#define LEADER_TIMEOUT 300` in your config.h. The 300 there is 300ms -- that's how long you have for the sequence of keys following the leader. You can tweak this value for comfort, of course. 3. Within your `matrix_scan_user` function, do something like this: ``` -- cgit v1.2.3 From a6d1db2c275f2e33e23135a6e410dbc8d19720a2 Mon Sep 17 00:00:00 2001 From: Joe Wasson Date: Mon, 17 Sep 2018 09:23:43 -0700 Subject: Create AG_TOGG code to toggle Alt/Gui swap. --- docs/feature_bootmagic.md | 1 + docs/keycodes.md | 1 + 2 files changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/feature_bootmagic.md b/docs/feature_bootmagic.md index d6915d3559..586b5d8370 100644 --- a/docs/feature_bootmagic.md +++ b/docs/feature_bootmagic.md @@ -57,6 +57,7 @@ Hold down the Bootmagic key (Space by default) and the desired hotkey while plug |`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_TOGGLE_ALT_GUI` |`AG_TOGG`|Toggle Left Alt and GUI swap | |`MAGIC_SWAP_BACKSLASH_BACKSPACE` | |Swap `\` and Backspace | |`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`| |Unswap `\` and Backspace | |`MAGIC_SWAP_CONTROL_CAPSLOCK` | |Swap Left Control and Caps Lock | diff --git a/docs/keycodes.md b/docs/keycodes.md index c344a75283..6676bb53c9 100644 --- a/docs/keycodes.md +++ b/docs/keycodes.md @@ -271,6 +271,7 @@ This is a reference only. Each group of keys links to the page documenting their |`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`| |Unswap `\` and Backspace | |`MAGIC_UNHOST_NKRO` | |Force NKRO off | |`MAGIC_UNSWAP_ALT_GUI` |`AG_NORM`|Unswap Alt and GUI on both sides | +|`MAGIC_TOGGLE_ALT_GUI` |`AG_TOGG`|Toggle Alt and GUI swap on both sides| |`MAGIC_TOGGLE_NKRO` | |Turn NKRO on or off | ## [Bluetooth](feature_bluetooth.md) -- cgit v1.2.3 From 334e2629df4adb44b0ac0dff3363a6daebc072e7 Mon Sep 17 00:00:00 2001 From: Anthony Wharton Date: Thu, 20 Sep 2018 00:18:15 +0100 Subject: Remove redefinition of `_______` in documentation example (#3924) * Remove redefinition of `_______` in documentation example * Slight rewording to include purpose of defintions * Update include to newer macro --- docs/keymap.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/keymap.md b/docs/keymap.md index b28d21a21d..382a0e911b 100644 --- a/docs/keymap.md +++ b/docs/keymap.md @@ -89,11 +89,15 @@ There are 3 main sections of a `keymap.c` file you'll want to concern yourself w At the top of the file you'll find this: - #include "clueboard.h" + #include QMK_KEYBOARD_H // Helpful defines #define GRAVE_MODS (MOD_BIT(KC_LSHIFT)|MOD_BIT(KC_RSHIFT)|MOD_BIT(KC_LGUI)|MOD_BIT(KC_RGUI)|MOD_BIT(KC_LALT)|MOD_BIT(KC_RALT)) - #define _______ KC_TRNS + + /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * You can use _______ in place for KC_TRNS (transparent) * + * Or you can use XXXXXXX for KC_NO (NOOP) * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ // Each layer gets a name for readability. // The underscores don't mean anything - you can @@ -105,7 +109,9 @@ At the top of the file you'll find this: #define _FL 1 #define _CL 2 -These are some handy definitions we can use when building our keymap and our custom function. The `GRAVE_MODS` definition will be used later in our custom function. The `_______` define makes it easier to see what keys a layer is overriding, while the `_BL`, `_FL`, and `_CL` defines make it easier to refer to each of our layers. +These are some handy definitions we can use when building our keymap and our custom function. The `GRAVE_MODS` definition will be used later in our custom function, and the following `_BL`, `_FL`, and `_CL` defines make it easier to refer to each of our layers. + +Note: You may also find some older keymap files may also have a define(s) for `_______` and/or `XXXXXXX`. These can be used in place for `KC_TRNS` and `KC_NO` respectively, making it easier to see what keys a layer is overriding. These definitions are now unecessary, as they are included by default. ### Layers and Keymaps -- cgit v1.2.3 From 58b9b22670c2c36e8502826349d8f752d8b3ab37 Mon Sep 17 00:00:00 2001 From: Luca Date: Sun, 23 Sep 2018 22:49:17 +0200 Subject: Circuitry sample for PS/2 Mouse (#3959) Added a sample circuitry for handling the connection of a PS/2 Mouse. Even if it's written that a circuitry is needed, there're a lot of other things and the information gets lost really fast. A really simple sample helps to remember who wants to implement the functionality about the circuitry. --- docs/feature_ps2_mouse.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'docs') diff --git a/docs/feature_ps2_mouse.md b/docs/feature_ps2_mouse.md index 909406e7d2..01e2cc63db 100644 --- a/docs/feature_ps2_mouse.md +++ b/docs/feature_ps2_mouse.md @@ -6,6 +6,24 @@ To hook up a Trackpoint, you need to obtain a Trackpoint module (i.e. harvest fr There are three available modes for hooking up PS/2 devices: USART (best), interrupts (better) or busywait (not recommended). +### The Cirtuitry between Trackpoint and Controller + +To get the things working, a 4.7K drag is needed between the two lines DATA and CLK and the line 5+. + +``` + + DATA ----------+--------- PIN + | + 4.7K + | +MODULE 5+ --------+--+--------- PWR CONTROLLER + | + 4.7K + | + CLK ------+------------ PIN +``` + + ### Busywait Version Note: This is not recommended, you may encounter jerky movement or unsent inputs. Please use interrupt or USART version if possible. -- cgit v1.2.3 From e72e4b6920299176a322a2862f930b7ee5f73dff Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Tue, 8 May 2018 18:46:29 -0700 Subject: Store Clicky status in EEPROM --- docs/feature_audio.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/feature_audio.md b/docs/feature_audio.md index 039c62cdf1..fe210c09b9 100644 --- a/docs/feature_audio.md +++ b/docs/feature_audio.md @@ -128,13 +128,11 @@ This adds a click sound each time you hit a button, to simulate click sounds fro * `CK_UP` - Increases the frequency of the clicks * `CK_DOWN` - Decreases the frequency of the clicks + The feature is disabled by default, to save space. To enable it, add this to your `config.h`: #define AUDIO_CLICKY -Additionally, even when enabled, the feature is not enabled by default, so you would need to turn it on first. And since we don't use EEPROM to store the setting (yet), you can default this to on by adding this to your `config.h`: - - #define AUDIO_CLICKY_ON You can configure the default, min and max frequencies, the stepping and built in randomness by defining these values: -- cgit v1.2.3 From a0309db983150fd0197eb620a6ba552d90d29f93 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Fri, 1 Jun 2018 13:29:52 -0700 Subject: Add On/Off keycodes --- docs/feature_audio.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/feature_audio.md b/docs/feature_audio.md index fe210c09b9..82e0ed9503 100644 --- a/docs/feature_audio.md +++ b/docs/feature_audio.md @@ -119,14 +119,16 @@ You can completely disable Music Mode as well. This is useful, if you're pressed #define NO_MUSIC_MODE -## Faux Click +## Audio Click This adds a click sound each time you hit a button, to simulate click sounds from the keyboard. And the sounds are slightly different for each keypress, so it doesn't sound like a single long note, if you type rapidly. * `CK_TOGG` - Toggles the status (will play sound if enabled) -* `CK_RST` - Resets the frequency to the default state -* `CK_UP` - Increases the frequency of the clicks -* `CK_DOWN` - Decreases the frequency of the clicks +* `CK_ON` - Turns on Audio Click (plays sound) +* `CK_OFF` - Turns off Audio Click (doesn't play sound) +* `CK_RST` - Resets the frequency to the default state (plays sound at default frequency) +* `CK_UP` - Increases the frequency of the clicks (plays sound at new frequency) +* `CK_DOWN` - Decreases the frequency of the clicks (plays sound at new frequency) The feature is disabled by default, to save space. To enable it, add this to your `config.h`: @@ -142,7 +144,7 @@ You can configure the default, min and max frequencies, the stepping and built i | `AUDIO_CLICKY_FREQ_MIN` | 65.0f | Sets the lowest frequency (under 60f are a bit buggy). | | `AUDIO_CLICKY_FREQ_MAX` | 1500.0f | Sets the the highest frequency. Too high may result in coworkers attacking you. | | `AUDIO_CLICKY_FREQ_FACTOR` | 1.18921f| Sets the stepping of UP/DOWN key codes. | -| `AUDIO_CLICKY_FREQ_RANDOMNESS` | 0.05f | Sets a factor of randomness for the clicks, Setting this to `0f` will make each click identical. | +| `AUDIO_CLICKY_FREQ_RANDOMNESS` | 0.05f | Sets a factor of randomness for the clicks, Setting this to `0f` will make each click identical, and `1.0f` will make this sound much like the 90's computer screen scrolling/typing effect. | -- cgit v1.2.3 From baebbc096702c3ecc0ee89b4fbf5749e79f02375 Mon Sep 17 00:00:00 2001 From: Takeshi ISHII <2170248+mtei@users.noreply.github.com> Date: Fri, 28 Sep 2018 11:02:12 +0900 Subject: add 'mavrdude' target into tmk_core/avr.mk (#3986) * add 'mavrdude' target into tmk_core/avr.mk I made it a little convenient when writing the same binary to multiple Pro Micro. * rename target name 'mavrdude' to 'avrdude-loop' * modify docs/flashing.md about avrdude-loop * mdify docs/flashing.md again * modifi docs/flashing.md 3rd --- docs/flashing.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs') diff --git a/docs/flashing.md b/docs/flashing.md index e5fe59f8f0..66c08a3610 100644 --- a/docs/flashing.md +++ b/docs/flashing.md @@ -78,6 +78,12 @@ or make ::avrdude +or if you want to flash multiple boards, use the following command + + make ::avrdude-loop + +When you're done flashing boards, you'll need to hit Ctrl + C or whatever the correct keystroke is for your operating system to break the loop. + ## Halfkay Halfkay is a super-slim protocol developed by PJRC that uses HID, and come on all Teensys (namely the 2.0). -- cgit v1.2.3 From 8454fa5e9faab3a969168447d42369828f8ade91 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Fri, 28 Sep 2018 09:04:30 -0700 Subject: Update Document Templates to reflect newer wording and URLs (#4006) * Add pragma once info to contributing guidelines * Fix links in readme template to match doc site * Revert changes to contributing doc as somebody already changed it --- docs/documentation_templates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/documentation_templates.md b/docs/documentation_templates.md index 18829ed0f0..ba3830b64c 100644 --- a/docs/documentation_templates.md +++ b/docs/documentation_templates.md @@ -36,7 +36,7 @@ Make example for this keyboard (after setting up your build environment): make planck/rev4:default -See [build environment setup](https://docs.qmk.fm/build_environment_setup.html) then the [make instructions](https://docs.qmk.fm/make_instructions.html) for more information. +See the [build environment setup](https://docs.qmk.fm/#/getting_started_build_tools) and the [make instructions](https://docs.qmk.fm/#/getting_started_make_guide) for more information. Brand new to QMK? Start with our [Complete Newbs Guide](https://docs.qmk.fm/#/newbs). ``` There needs to be two spaces at the end of the `Keyboard Maintainer` and `Hardware Supported` lines for it to render correctly with Markdown. -- cgit v1.2.3 From fa47f5fb15cca3bea9ab4de1001fcfecd43dac19 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Fri, 28 Sep 2018 09:27:51 -0700 Subject: Update to the Userspace documentation (#4005) * Overhaul to Userspace Documentation * Formatting issues * Additionaly formatting fixes * Add Readme info * Additionaly Readme info * Formatting fixes --- docs/feature_userspace.md | 178 ++++++++++++++++++++++++++++++++++------------ 1 file changed, 133 insertions(+), 45 deletions(-) (limited to 'docs') diff --git a/docs/feature_userspace.md b/docs/feature_userspace.md index 5f7c05b83b..b7fc9d8099 100644 --- a/docs/feature_userspace.md +++ b/docs/feature_userspace.md @@ -5,15 +5,12 @@ If you use more than one keyboard with a similar keymap, you might see the benef * `/users//` (added to the path automatically) * `readme.md` (optional, recommended) * `rules.mk` (included automatically) + * `config.h` (included automatically) * `.h` (optional) * `.c` (optional) - * `config.h` (optional) + * `cool_rgb_stuff.c` (optional) + * `cool_rgb_stuff.h` (optional) -`.c` will need to be added to the SRC in `rules.mk` like this: - - SRC += .c - -Additional files may be added in the same way - it's recommended you have one named ``.c/.h though. All this only happens when you build a keymap named ``, like this: @@ -23,82 +20,179 @@ For example, make planck:jack -Will include the `/users/jack/` folder in the path, along with `/users/jack/rules.mk`. +Will include the `/users/jack/` folder in the path, along with `/users/jack/rules.mk`. -Additionally, `config.h` here will be processed like the same file in your keymap folder. This is handled separately from the `.h` file. +!> This `name` can be [overridden](#override-default-userspace), if needed. -The reason for this, is that `.h` won't be added in time to add settings (such as `#define TAPPING_TERM 100`), and including the `` file in any `config.h` files will result in compile issues. +## `Rules.mk` + +The `rules.mk` is one of the two files that gets processed automatically. This is how you add additional source files (such as `.c`) will be added when compiling. -So you should use the `config.h` for QMK settings, and the `.h` file for user or keymap specific settings. +It's highly recommended that you use `.c` as the default source file to be added. And to add it, you need to add it the SRC in `rules.mk` like this: -`/users//rules.mk` will be included in the build _after_ the `rules.mk` from your keymap. This allows you to have features in your userspace `rules.mk` that depend on individual QMK features that may or may not be available on a specific keyboard. For example, if you have RGB control features shared between all your keyboards that support RGB lighting, you can `define RGB_ENABLE` in your keymap `rules.mk` and then check for the variable in your userspace `rules.mk` like this: + SRC += .c + +Additional files may be added in the same way - it's recommended you have one named ``.c/.h to start off with, though. + +The `/users//rules.mk` file will be included in the build _after_ the `rules.mk` from your keymap. This allows you to have features in your userspace `rules.mk` that depend on individual QMK features that may or may not be available on a specific keyboard. + +For example, if you have RGB control features shared between all your keyboards that support RGB lighting, you can add support for that if the RGBLIGHT feature is enabled: ```make -ifdef RGB_ENABLE - # Include my fancy rgb functions source here +ifeq ($(strip $(RGBLIGHT_ENABLE)), yes) + # Include my fancy rgb functions source here + SRC += cool_rgb_stuff.c endif ``` -Because of this, any time you turn on QMK features in your `users//rules.mk`, you should conditionally enable them only if the flag isn't already defined, like this: + +Alternatively, you can `define RGB_ENABLE` in your keymap's `rules.mk` and then check for the variable in your userspace's `rules.mk` like this: ```make -ifndef TAP_DANCE_ENABLE - TAP_DANCE_ENABLE = yes +ifdef RGB_ENABLE + # Include my fancy rgb functions source here + SRC += cool_rgb_stuff.c endif ``` -This will ensure that you can explicitly turn off features for an individual keymap. -## Readme +### Override default userspace + +By default the userspace used will be the same as the keymap name. In some situations this isn't desirable. For instance, if you use the [layout](feature_layouts.md) feature you can't use the same name for different keymaps (e.g. ANSI and ISO). You can name your layouts `mylayout-ansi` and `mylayout-iso` and add the following line to your layout's `rules.mk`: + +``` +USER_NAME := mylayout +``` + +This is also useful if you have multiple different keyboards with different features physically present on the board (such as one with RGB Lights, and one with Audio, or different number of LEDs, or connected to a different PIN on the controller). + +## Configuration Options (`config.h`) + +Additionally, `config.h` here will be processed like the same file in your keymap folder. This is handled separately from the `.h` file. + +The reason for this, is that `.h` won't be added in time to add settings (such as `#define TAPPING_TERM 100`), and including the `` file in any `config.h` files will result in compile issues. + +!>You should use the `config.h` for [configuration options](config_options.md), and the `.h` file for user or keymap specific settings (such as the enum for layer or keycodes) + + +## Readme (`readme.md`) Please include authorship (your name, github username, email), and optionally [a license that's GPL compatible](https://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses). -## `Config.h` +You can use this as a template: +``` +Copyright @ + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation, either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see . +``` + +You'd want to replace the year, name, email and g