From 637def5655eeb69d33e7ac9869e0f8c3a04822af Mon Sep 17 00:00:00 2001 From: urob <978080+urob@users.noreply.github.com> Date: Sun, 12 Feb 2023 22:07:39 -0500 Subject: [PATCH] Polish timer-less writeup --- readme.md | 254 +++++++++++++++++++++++++++++------------------------- 1 file changed, 137 insertions(+), 117 deletions(-) diff --git a/readme.md b/readme.md index a4e26f6..acc8099 100644 --- a/readme.md +++ b/readme.md @@ -4,85 +4,100 @@ This is my personal [ZMK firmware](https://github.com/zmkfirmware/zmk/) configur It consists of a 34-keys base layout that is re-used for various boards, including my Corneish Zen and an Advantage 360 pro. -## Key features +## *Key* features - clean keymap + unicode setup using helper macros from [zmk-nodefree-config](https://github.com/urob/zmk-nodefree-config) -- modified Github Actions workflow that recognizes git-submodules -- the base keymap and combo setup are independent of the physical location of keys and - are re-used for multiple keyboards. The configuration is fit onto larger boards by - padding it via a modular structure of "extra keys" -- ["timeless" homerow mods](#timeless-homerow-mods) on the base layer; sticky mods on - other layers -- num-word: a zmk version of smart-layers that automatically de-activate for non-numbers +- the base keymap and combo setup are independent of the physical location of + keys and are re-used for multiple keyboards. The configuration is fit onto + larger boards by padding it via a modular structure of "extra keys" +- ["timer-less" homerow mods](#timeless-homerow-mods) - combos replacing the symbol layer -- arrow-cluster doubles as home/end/etc on long-press, - bspc/del delete words on long-press -- sticky shift on right thumb, double-tap (or shift + tap)[^1] activates caps-word -- shift + , morphs into ; and shift + - . morphs into ; (freeing up the right pinky for - repeat) -- shift + ctrl + - , morphs into < and shift + ctrl + - . morphs into > -- shift + space morphs into dot → space → - sticky-shift +- a smart-layer implementation for ZMK that automatically toggles the numbers + layer +- long-pressing the arrow-cluster yields home, end, begin/end of document, and + fwd/bwd-delete words +- sticky shift on right thumb, double-tap (or shift + tap)[^1] activates + caps-word +- shift + , morphs into ; and + shift + . morphs into ; (freeing up the + right pinky for ? / !) +- shift + ctrl + , morphs into < + and shift + ctrl + . morphs into + > +- shift + space morphs into dot → + space → sticky-shift - "Greek" layer for mathematical typesetting (activated via sticky-layer combo) +- modified Github Actions workflow that recognizes git-submodules +- automated + [build-scripts](https://github.com/urob/zmk-config/tree/main/scripts#readme) + for local and Docker-based building (independently of VS Code) ![](img/keymap.png) ## Timeless homerow mods -Homerow mods [are great](https://precondition.github.io/home-row-mods). But they can -require some finicky timing: In its most naive implementation, in order to produce a "mod", -they must be held *longer* than `tapping-term-ms`. In order to produce -a "tap", they must be held *less* than `tapping-term-ms`. This requires very consistent -typing speeds that, alas, I do not possess. Hence my quest for a "timeless" HRM -setup.[^2] +[Homerow mods](https://precondition.github.io/home-row-mods) (aka "HRMs") can +be a game changer -- at least in theory. In practice, they require some finicky +timing: In its most naive implementation, in order to produce a "mod", they +must be held *longer* than `tapping-term-ms`. In order to produce a "tap", they +must be held *less* than `tapping-term-ms`. This requires very consistent +typing speeds that, alas, I do not possess. Hence my quest for a "timer-less" +HRM setup.[^2] -Here's what I have ended up with: A "timeless" HRM setup with virtually no misfires and -yet a fluent typing experience with mostly no delays. +After months of tweaking, I eventually ended up with a HRM setup that is +essentially timer-less, resulting in virtually no misfires. Yet it provides a +fluent typing experience with mostly no delays. -Let's suppose for a moment we set `tapping-term-ms` to something ridiculously large, say -5 seconds. This makes the configuration "timeless". But it also creates two -problems: (1) In order to get a "mod" we now have to hold the HRM keys for -what feels like eternity. (2) In normal typing, when tapping keys, there can be -long delays between the press of a key and the time it appears on the screen. Enter my -two favorite configuration options: -* To address the first problem, I use ZMK's `balanced` flavor, which produces - a "hold" if another key is both pressed and released within the tapping-term. Because - that is exactly what I normally do with HRMs, there is virtually never a need to wait - past my long tapping term (see below for two exceptions). +Let's suppose for a moment we set `tapping-term-ms` to something ridiculously +large, say 5 seconds. This makes the configuration timer-less of sorts. But it +has two problems: (1) To activate a mod we will have to hold the HRM keys for +what feels like eternity. (2) During regular typing, there are delays between +the press of a key and the time it appears on the screen.[^3] Enter two of +ZMK's best configuration options: +* To address the first problem, I use ZMK's `balanced` flavor, which produces a + "hold" if another key is both pressed and released within the tapping-term. + Because that is exactly what I normally do with HRMs, there is virtually + never a need to wait past my long tapping term (see below for two + exceptions). * To address the typing delay, I use ZMK's `global-quick-tap` property, which - immediately resolves a HRM as "tap" when it is pressed shortly *after* another key - has been tapped.[^3] This all but completely eliminates the delay when typing. + immediately resolves a HRM as "tap" when it is pressed shortly *after* + another key has been tapped. This all but completely eliminates the delay. -This is almost perfect, but there's still a few rough edges: +This is great but there are still a few rough edges: * When rolling keys, I sometimes unintentionally end up with "nested" key - sequences: `key 1` down, `key 2` down and up, `key 1` up. Given the `balanced` flavor, - this would falsely register `key 1` as a mod. To prevent this, I use ZMK's "positional - hold-tap" feature to force HRMs to always resolve as "tap" when the *next* key is on - the same side of the keyboard. Problem solved. -* ... or at least almost. The official ZMK version for positional-hold-taps performs the - positional check when the next key is *pressed*. This is not ideal, because it - prevents combining multiple modifiers on the same hand. To fix this, I use a small - patch that delays the positional-hold-tap decision until the next key's *release* ([PR - #1423](https://github.com/zmkfirmware/zmk/pull/1423)). With the patch, multiple mods - can be combined when held, while I still get the benefit from positional-hold-taps - when keys are tapped. -* So far, nothing of the configuration depends on the duration of `tapping-term-ms`. In - practice, there are two reasons why I don't set it to infinity: - 1. Sometimes, in rare circumstances, I want to combine a mod with a alpha-key *on - the same hand* (e.g., when using the mouse with the other hand). My positional - hold-tap configuration prevents this *within* the tapping term. By setting the - tapping term to something large but not crazy large (I use 280ms), I can still - use same-hand `mod` + `alpha` shortcuts by holding the mod for just a little while - before tapping the alpha-key. - 2. Sometimes, I want to press a modifier without another key (e.g., on Windows, - tapping `Win` opens the search menu). Because the `balanced` flavour only - kicks in when another key is pressed, this also requires waiting past - `tapping-term-ms`. + sequences: `key 1` down, `key 2` down and up, `key 1` up. Because of the + `balanced` flavor, this would falsely register `key 1` as a mod. As a remedy, + I use ZMK's "positional hold-tap" feature to force HRMs to always resolve as + "tap" when the *next* key is on the same side of the keyboard. Problem + solved. +* ... or at least almost. The official ZMK version for positional-hold-taps + performs the positional check when the next key is *pressed*. This is not + ideal, because it prevents combining multiple modifiers on the same hand. To + fix this, I use a small patch that delays the positional-hold-tap decision + until the next key's *release* ([PR + #1423](https://github.com/zmkfirmware/zmk/pull/1423)). With the patch, + multiple mods can be combined when held, while I still get the benefit from + positional-hold-taps when keys are tapped. +* So far, nothing of the configuration depends on the duration of + `tapping-term-ms`. In practice, there are two reasons why I don't set it to + infinity: + 1. Sometimes, in rare circumstances, I want to combine a mod with a + alpha-key *on the same hand* (e.g., when using the mouse with the other + hand). My positional hold-tap configuration prevents this *within* the + tapping term. By setting the tapping term to something large but not crazy + large (I use 280ms), I can still use same-hand `mod` + `alpha` shortcuts by + holding the mod for just a little while before tapping the alpha-key. + 2. Sometimes, I want to press a modifier without another key (e.g., on + Windows, tapping `Win` opens the search menu). Because the `balanced` + flavour only kicks in when another key is pressed, this also requires + waiting past `tapping-term-ms`. +* Finally, it is worth noting that this setup works best in combination with a + dedicated shift for capitalization during normal typing (I am a big fan of + sticky-shift on a home-thumb). This is because shifting alphas is the + one scenario where pressing a mod may conflict with `global-quick-tap`, which + may result in false negatives when typing fast. Here's my configuration (I use a bunch of [helper macros](https://github.com/urob/zmk-nodefree-config) to simplify the syntax, but they @@ -117,79 +132,85 @@ ZMK_BEHAVIOR(hmr, hold_tap, hold-trigger-on-release; // requires PR #1423 ) ``` -One last note, the configuration above uses some syntactic sugar introduced in [PR + +Final note: the config above uses syntax introduced in [PR #1387](https://github.com/zmkfirmware/zmk/pull/1387), which decouples the -`quick-tap-ms` timeout from the `global-quick-tap-ms` timeout. Without the PR, one -can replace `global-quick-tap-ms = <150>` with `global-quick-tap` for a -similar effect (`global-quick-tap` will use the regular `quick-tap-ms` timeout in this -case). +`quick-tap-ms` timeout from the `global-quick-tap-ms` timeout. Without the PR, +one can replace `global-quick-tap-ms = <150>` with `global-quick-tap` for a +similar effect (`global-quick-tap` will use the regular `quick-tap-ms` timeout +in this case). My personal [ZMK fork](https://github.com/urob/zmk) includes both the -global-quick-tap-ms PR and the hold-trigger-on-release PR (along with a few other PRs). -If you are looking for a ZMK-centric introduction to maintaining your own fork with a -custom selection of PRs, you might find my ["cookbook -approach"](https://gist.github.com/urob/68a1e206b2356a01b876ed02d3f542c7) helpful. +global-quick-tap-ms PR and the hold-trigger-on-release PR (along with a few +other PRs). If you prefer to maintain your own fork with a custom selection of +PRs, you might find this [ZMK-centric introduction to +Git](https://gist.github.com/urob/68a1e206b2356a01b876ed02d3f542c7) helpful. ## Combo setup -I make heavy use of combos to replace the usual symbol layer. The combo layout aims to -put the most used symbols in easy-to-access locations and also make them easy to -remember. Specifically: +My layout makes heavy use of combos. Thanks to `global-quick-tap` for combos +(introduced in above mentioned PR #1387), combo misfires are rare, even when +rolling keys. Most of my combos are bind to symbols, replacing the usual +symbols layer seen on many sub-40 keyboard layouts. The combos are designed so +as to put the most used symbols in easy-to-access locations while also making +them easy to remember. Specifically: -- the top vertical-combo row matches the symbols on a standard numbers row (except `+` - and `&` being swapped) -- the bottom vertical-combo row aims for symmetry with the top row (subscript `_` aligns - with superscript `^`; minus `-` aligns with `+`; division `/` aligns with - multiplication `*`; logical-or `|` aligns with logical-and `&`) -- parenthesis, braces, brackets, `!` and `?` are set up symmetrically in prime locations -- numlock (on `W + P`), cut (on `X + D`), copy, and paste are on the left side for - one-handed mouse use -- `L + Y` activates Greek layer for next key, `L + U + Y` activates shifted Greek layer - for next key +- the top vertical-combo row matches the symbols on a standard numbers row + (except `+` and `&` being swapped) +- the bottom vertical-combo row is symmetric to the top row (subscript `_` + aligns with superscript `^`; minus `-` aligns with `+`; division `/` aligns + with multiplication `*`; logical-or `|` aligns with logical-and `&`) +- parenthesis, braces, brackets are set up symmetrically as horizontal combos +- cut (on `X + D`), copy, and paste are on the left side for one-handed mouse + use +- `L + Y` activates Greek layer for the next key press, `L + U + Y` activates the shifted + Greek layer the next key +- `tap`, `esc`, `enter` are on horizontal combos ## Experimental changes -- I recently reduced my core layout to 34 keys. Backspace, Delete and Tap are now all on -my Navigation-layer. To make room for these keys, I have added hold-taps to the arrow -cluster, which now double as Home/End and Beginning/End of document. I really like the -new navigation cluster and will likely keep it in one way or another +- I recently reduced my core layout to 34 keys. Backspace and Delete are now on + my Navigation-layer. To make room for these keys, I have added hold-taps to + the arrow cluster, which now double as Home/End and Beginning/End of + document. I really like the new navigation cluster and will likely keep it in + one way or another - Inspired by Jonas Hietala's [Numword](https://www.jonashietala.se/blog/2021/06/03/the-t-34-keyboard-layout/#where-are-the-digits) for QMK, I implemented my own version of [Smart-layers for - ZMK](https://github.com/zmkfirmware/zmk/pull/1451). It is triggered via a single tap - on my Num-key (holding the key will activate the num layer as usual without - triggering Numword). Similar to Capsword, Numword continues to be activated as long - as I type numbers, and deactivates automatically on any other keypress. I found that - I use Numword for most of my numbers typing. For single digits, it effectively is a - sticky-layer, but importantly I can also use it for multiple digits. The only case - where it doesn't deactivate automatically is where immediately after a digit I would - type any of the letters on which my numpad is located (WFPRSTXCD), which is rare, - but does happen. For these cases I have a CANCEL key on my Nav layer that cancels - both Numword and Capsword. -- Since the switch to 34 keys, I freed up the tap-position on my left-most thumb key. - For now I added a secondary Bspc, but I am still searching for a better use. (I tried - adding Repeat here but I found that it doesn't work well adjacent to space) + ZMK](https://github.com/zmkfirmware/zmk/pull/1451). It is triggered via a + single tap on my Num-key (holding the key will activate the num layer as + usual without triggering Numword). Similar to Capsword, Numword continues + to be activated as long as I type numbers, and deactivates automatically on + any other keypress. I found that I use Numword for most of my numbers + typing. For single digits, it effectively is a sticky-layer, but + importantly I can also use it for multiple digits. The only case where it + doesn't deactivate automatically is where immediately after a digit I would + type any of the letters on which my numpad is located (WFPRSTXCD), which is + rare, but does happen. For these cases I have a CANCEL key on my Nav layer + that cancels both Numword and Capsword. +- Since the switch to 34 keys, I freed up the tap-position on my left-most + thumb key. For now I added a secondary Bspc, but I am still searching for a + better use. (I tried adding Repeat here but I found that it doesn't work well + adjacent to space, which requires to much lateral thumb-movements) ## Issues and workarounds -Since I switched from QMK to ZMK I have been very impressed with how easy it is to set -up relatively complex layouts in ZMK. For the most parts I don't miss any functionality -(to the contrary, I found that ZMK supports many features natively that would complex -user-space implementations in QMK). Below are a few remaining issues: +Since I switched from QMK to ZMK I have been very impressed with how easy it is +to set up relatively complex layouts in ZMK. For the most parts I don't miss +any functionality (to the contrary, I found that ZMK supports many features +natively that would require complex user-space implementations in QMK). Below +are a few remaining issues: - ZMK does not yet support tap-only combos ([#544](https://github.com/zmkfirmware/zmk/issues/544)). Workaround: pause briefly when chording multiple HRMs together on positions that otherwise would trigger a combo. +- OS sleep is not yet implemented ([#1077](https://github.com/zmkfirmware/zmk/issues/1077)). + Workaround: use sleep-macro instead. - `&bootloader` doesn't work with Planck_rev6 ([#1086](https://github.com/zmkfirmware/zmk/issues/1086)). Workaround: Manually press reset-button. -- "sticky-hold" swallows OS shift when typing quickly. Workaround: use sticky-tap for now. -- Sleep is not yet implemented ([#1077](https://github.com/zmkfirmware/zmk/issues/1077)). - Workaround: use sleep-macro instead. -- Invalid DFU suffix signature warning when flashing with dfu-util. No problem for now - but may cause issues with future versions of dfu-util. [^1]: Really what's happening is that `Shift` + my right home-thumb morph into caps-word. This gives me two separate ways of activating it: (1) Holding the @@ -198,7 +219,7 @@ user-space implementations in QMK). Below are a few remaining issues: because the first tap yields sticky-shift, activating the mod-morph upon the second tap. -[^2]: I call it "timeless", because the large tapping-term makes the behavior +[^2]: I call it "timer-less", because the large tapping-term makes the behavior insensitive to the precise timings. One may say that there is still the `global-quick-tap` timeout. However, with both a large tapping-term and positional-hold-taps, the behavior is *not* actually sensitive to the @@ -206,8 +227,7 @@ user-space implementations in QMK). Below are a few remaining issues: in typing speed won't affect *what* is being typed but merly *how fast* it appears on the screen. -[^3]: One potential downside of `global-quick-tap` is that it prevents using modifiers - *immediately* after another key press. Arguably, this is only problematic for shift, - which is not a problem for me, because I have a dedicated "sticky shift" on my right - thumb. If you rely on homerow mods for regular capitalization, you may want to reduce - the `global-quick-tap` term for just the two shift-mods to about 75-100ms. +[^3]: The delay is determined by how quickly a key is released and is not + directly related to the tapping-term. But regardless of its length, most + people still find it noticable and disruptive. +