From c570b696d1bbd99a17e4ab5a4e7c90fd701ece91 Mon Sep 17 00:00:00 2001 From: Seth Milliken Date: Wed, 4 Oct 2023 14:26:28 -0700 Subject: [PATCH 1/2] feat(docs): add new recipes section Recipes document distinct functionality provided by novel use of existing config, features, and behaviors. n.b. All pages are currently only placeholders. All names are tentative. --- docs/docs/recipes/adjust-layer.md | 12 ++++++++++++ docs/docs/recipes/callum-mods.md | 12 ++++++++++++ docs/docs/recipes/home-row-mods.md | 12 ++++++++++++ docs/docs/recipes/multiple-base-layers.md | 12 ++++++++++++ docs/docs/recipes/os-profile-layer.md | 12 ++++++++++++ docs/sidebars.js | 7 +++++++ 6 files changed, 67 insertions(+) create mode 100644 docs/docs/recipes/adjust-layer.md create mode 100644 docs/docs/recipes/callum-mods.md create mode 100644 docs/docs/recipes/home-row-mods.md create mode 100644 docs/docs/recipes/multiple-base-layers.md create mode 100644 docs/docs/recipes/os-profile-layer.md diff --git a/docs/docs/recipes/adjust-layer.md b/docs/docs/recipes/adjust-layer.md new file mode 100644 index 00000000..275e3b60 --- /dev/null +++ b/docs/docs/recipes/adjust-layer.md @@ -0,0 +1,12 @@ +--- +title: Adjust Layer +sidebar_label: Adjust Layer +--- + +## Summary + +Recipe summary + +## Implementation + +Recipe implementation diff --git a/docs/docs/recipes/callum-mods.md b/docs/docs/recipes/callum-mods.md new file mode 100644 index 00000000..0aebacf8 --- /dev/null +++ b/docs/docs/recipes/callum-mods.md @@ -0,0 +1,12 @@ +--- +title: Callum Mods +sidebar_label: Callum Mods +--- + +## Summary + +Recipe summary + +## Implementation + +Recipe implementation diff --git a/docs/docs/recipes/home-row-mods.md b/docs/docs/recipes/home-row-mods.md new file mode 100644 index 00000000..6b78b9a2 --- /dev/null +++ b/docs/docs/recipes/home-row-mods.md @@ -0,0 +1,12 @@ +--- +title: Home Row Mods +sidebar_label: Home Row Mods +--- + +## Summary + +Recipe summary + +## Implementation + +Recipe implementation diff --git a/docs/docs/recipes/multiple-base-layers.md b/docs/docs/recipes/multiple-base-layers.md new file mode 100644 index 00000000..aa69a2e6 --- /dev/null +++ b/docs/docs/recipes/multiple-base-layers.md @@ -0,0 +1,12 @@ +--- +title: Multiple Base Layers +sidebar_label: Multiple Base Layers +--- + +## Summary + +Recipe summary + +## Implementation + +Recipe implementation diff --git a/docs/docs/recipes/os-profile-layer.md b/docs/docs/recipes/os-profile-layer.md new file mode 100644 index 00000000..1dbc2c08 --- /dev/null +++ b/docs/docs/recipes/os-profile-layer.md @@ -0,0 +1,12 @@ +--- +title: OS Profile Layer +sidebar_label: OS Profile Layer +--- + +## Summary + +Recipe summary + +## Implementation + +Recipe implementation diff --git a/docs/sidebars.js b/docs/sidebars.js index 43f17b41..266b6931 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -43,6 +43,13 @@ module.exports = { "behaviors/backlight", "behaviors/power", ], + Recipes: [ + "recipes/adjust-layer", + "recipes/callum-mods", + "recipes/home-row-mods", + "recipes/multiple-base-layers", + "recipes/os-profile-layer", + ], Codes: [ "codes/index", "codes/keyboard-keypad", From 061a3b81fda07017ac1d1a5bddb266834fa42e77 Mon Sep 17 00:00:00 2001 From: Seth Milliken Date: Thu, 5 Oct 2023 02:48:58 -0700 Subject: [PATCH 2/2] wip: rough draft of the home row mods recipe A first stab at the potential structure of a recipe, while starting to flesh out some of the details of the home row mods recipe. --- docs/docs/recipes/home-row-mods.md | 74 +++++++++++++++++++++++++++++- 1 file changed, 72 insertions(+), 2 deletions(-) diff --git a/docs/docs/recipes/home-row-mods.md b/docs/docs/recipes/home-row-mods.md index 6b78b9a2..e6bf9542 100644 --- a/docs/docs/recipes/home-row-mods.md +++ b/docs/docs/recipes/home-row-mods.md @@ -5,8 +5,78 @@ sidebar_label: Home Row Mods ## Summary -Recipe summary +Home Row Mods assigns a [modifier key](../../docs/codes/modifiers) to the 'hold' binding of a [hold-tap](../../docs/behaviors/hold-tap) for each key under your fingers when your hands rest naturally on the home row. The 'tap' binding of each hold-tap is the same as the original key. On a QWERTY layout, these keys would be: `A`, `S`, `D`, `F` (left hand) and `J`, `K`, `L`, `;` (right hand). + +### Benefits + +- Reduced finger movement +- Reduced load on pinky +- Smaller key count + +### Difficulties + +- Adoption period +- Rolls +- Inadvertent triggers +- Potentially reduced typing speed ## Implementation -Recipe implementation +### Ingredients + +- [Hold-Tap](../../docs/behaviors/mod-tap) +- Configuration + +### Steps + +Add a new home row mods `hold-tap` to your keymap: + +``` +hrm: home-row-mods { + compatible = "zmk,behavior-hold-tap"; + label = "HOME_ROW_MODS"; + #binding-cells = <2>; + flavor = "tap-preferred"; + tapping-term-ms = <200>; + quick-tap-ms = <125>; + global-quick-tap; + bindings = <&kp>, <&kp>; +}; +``` + +Decide what order you want to for the modifiers. `GUI`, `ALT`, `CTRL`, `SHIFT` is a commonly used one. There are reasons for different orderings, and ultimate this is a matter of preference. + +Use the new hold-tap to assign modifiers as the 'hold' binding for home row keys in your default layer, and the original key as the 'tap' binding. Mirror the hold-tap 'hold' bindings for the other hand. Example of the [Corne keymap](https://github.com/zmkfirmware/zmk/blob/main/app/boards/shields/corne/corne.keymap#L22-L25) with this applied: +``` + &kp TAB &kp Q &kp W &kp E &kp R &kp T &kp Y &kp U &kp I &kp O &kp P &kp BSPC + &kp LCTRL &hrm LGUI A &hrm LALT S &hrm LCTL D &hrm LSHFT F &kp G &kp H &hrm RSHFT J &hrm RCTL K &hrm RALT L &hrm RGUI SEMI &kp SQT + &kp LSHFT &kp Z &kp X &kp C &kp V &kp B &kp N &kp M &kp COMMA &kp DOT &kp FSLH &kp ESC + &kp LGUI &mo 1 &kp SPACE &kp RET &mo 2 &kp RALT +``` + +The bindings should be symmetrical for each hand. (TODO: explain why?) + +### Troubleshooting +Try typing using this modified keymap. You may notice misfires caused by inadvertently rolling home row mod hold-tap keys, or other timing issues. + +- Adjust the 'tapping-term-ms' value (under what circumstances?) +- Adjust the 'quick-tap-ms' value (under what circumstances?) +- Remove the 'global-quick-tap' setting (under what circumstances?) + +## Variations + +### Bottom Row Mods + +Move the hold-tap bindings one row lower. This is a good alternative if no timing or other configuration adjustments succeed at preventing misfires. + +### Different order for mods + +Change the order of modifiers so that your stronger fingers are associated with the modifiers that _you_ use most frequently. + +### Exclude same-hand key combinations + +Configure the hold-tap so that a hold is not considered a hold if the next key is one assigned to the same hand. This can help reduce problems misfires from rolls. + +### Avoid `RALT` due to unusual Windows behavior. + +On Windows, the right Alt key operates differently from the left, and so if you are a Windows user you may want to use `LALT` for both hands.