ficd/zmk
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

run formatters

Browse source
This commit is contained in:
urob 2024-04-08 21:55:45 -04:00
parent 3aed3a0bd6
commit c7107524a3
6 changed files with 304 additions and 296 deletions
Download patch file Download diff file Expand all files Collapse all files

284
readme.md
View file

@ -1,8 +1,8 @@
# urob's zmk-config
This is my personal [ZMK firmware](https://github.com/zmkfirmware/zmk/) configuration.
It consists of a 34-keys base layout that is re-used for various boards, including my
Corneish Zen and my Planck.
This is my personal [ZMK firmware](https://github.com/zmkfirmware/zmk/)
configuration. It consists of a 34-keys base layout that is re-used for various
boards, including my Corneish Zen and my Planck.
This branch is updated for the latest ZMK using Zephyr 3.5. A legacy version
compatible with Zephyr 3.0 is available
@ -15,16 +15,19 @@ compatible with Zephyr 3.0 is available
- 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)
- ["timeless" homerow mods](#timeless-homerow-mods)
- combos replacing the symbol layer
- smart numbers and smart mouse layers that automatically toggle off when done
- sticky shift on right thumb, double-tap (or shift + tap)[^1] activates caps-word
- sticky shift on right thumb, double-tap (or shift + tap)[^1] activates
caps-word
- arrow-cluster doubles as <kbd>home</kbd>, <kbd>end</kbd>, <kbd>begin/end of
document</kbd> on long-press
- more intuitive shift-actions: <kbd>, ;</kbd>, <kbd>. :</kbd> and <kbd>? !</kbd>
- more intuitive shift-actions: <kbd>, ;</kbd>, <kbd>. :</kbd> and <kbd>?
!</kbd>
- <kbd>shift</kbd> + <kbd>space</kbd> morphs into <kbd>dot</kbd> →
<kbd>space</kbd> → <kbd>sticky-shift</kbd>
- "Greek" layer for mathematical typesetting (activated as sticky-layer via a combo)
- "Greek" layer for mathematical typesetting (activated as sticky-layer via a
combo)
- modified Github Actions workflow that recognizes git-submodules
- automated
[build-scripts](https://github.com/urob/zmk-config/tree/main/scripts#readme)
@ -34,13 +37,13 @@ compatible with Zephyr 3.0 is available
## Timeless homerow mods
[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]
[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]
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
@ -50,54 +53,53 @@ 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 my favorite
ZMK features:
* To address the first problem, I use ZMK's `balanced` flavor, which produces a
the press of a key and the time it appears on the screen.[^3] Enter two my
favorite ZMK features:
- 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 `require-prior-idle-ms` property, which
immediately resolves a HRM as "tap" when it is pressed shortly *after*
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 `require-prior-idle-ms` property,
which 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 great but there are still a few rough edges:
* When rolling keys, I sometimes unintentionally end up with "nested" key
- When rolling keys, I sometimes unintentionally end up with "nested" key
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. By default, positional-hold-tap
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 the `hold-trigger-on-release` setting, which delays the
positional-hold-tap decision until the next key's *release*. With the setting,
multiple mods can be combined when held, while I still get the benefit from
positional-hold-tap when keys are tapped.
* So far, nothing of the configuration depends on the duration of
"tap" when the _next_ key is on the same side of the keyboard. Problem solved.
- ... or at least almost. By default, positional-hold-tap 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 the
`hold-trigger-on-release` setting, which delays the positional-hold-tap
decision until the next key's _release_. With the setting, multiple mods can
be combined when held, while I still get the benefit from positional-hold-tap
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
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 like sticky-shift
on a home-thumb). This is because shifting alphas is the one scenario where
pressing a mod may conflict with `require-prior-idle-ms`, 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
are not necessary):
Here's my configuration (I use a bunch of
[helper macros](https://github.com/urob/zmk-nodefree-config) to simplify the
syntax, but they are not necessary):
```C++
/* use helper macros to define left and right hand keys */
@ -131,57 +133,61 @@ ZMK_BEHAVIOR(hmr, hold_tap,
### Required firmware
After a recent round of patches, the above configuration now works with
upstream ZMK.
After a recent round of patches, the above configuration now works with upstream
ZMK.
Other parts of my configuration still require a few PRs that aren't yet in
upstream ZMK. My personal [ZMK fork](https://github.com/urob/zmk) includes all
PRs needed to compile my configuration. 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.
with a custom selection of PRs, you might find this
[ZMK-centric introduction to Git](https://gist.github.com/urob/68a1e206b2356a01b876ed02d3f542c7)
helpful.
### Troubleshooting
Hopefully, the above configuration "just works". If it doesn't, here's a
few smaller (and larger) things to try.
Hopefully, the above configuration "just works". If it doesn't, here's a few
smaller (and larger) things to try.
* **Noticeable delay when tapping HRMs:** Increase `require-prior-idle-ms`. As a rule of thumb,
you want to set it to at least `10500/x` where `x` is your (relaxed) WPM for English prose.[^4]
* **False negatives (same-hand):** Reduce `tapping-term-ms` (or disable
- **Noticeable delay when tapping HRMs:** Increase `require-prior-idle-ms`. As a
rule of thumb, you want to set it to at least `10500/x` where `x` is your
(relaxed) WPM for English prose.[^4]
- **False negatives (same-hand):** Reduce `tapping-term-ms` (or disable
`hold-trigger-key-positions`)
* **False negatives (cross-hand):** Reduce `require-prior-idle-ms` (or set flavor
to `hold-preferred` -- to continue using `hold-trigger-on-release`, you must
also [patch
ZMK](https://github.com/celejewski/zmk/commit/d7a8482712d87963e59b74238667346221199293)
- **False negatives (cross-hand):** Reduce `require-prior-idle-ms` (or set
flavor to `hold-preferred` -- to continue using `hold-trigger-on-release`, you
must also
[patch ZMK](https://github.com/celejewski/zmk/commit/d7a8482712d87963e59b74238667346221199293)
or use [an already patched branch](https://github.com/urob/zmk))
* **False positives (same-hand):** Increase `tapping-term-ms`
* **False positives (cross-hand):** Increase `require-prior-idle-ms` (or set
- **False positives (same-hand):** Increase `tapping-term-ms`
- **False positives (cross-hand):** Increase `require-prior-idle-ms` (or set
flavor to `tap-preferred`, which requires holding HRMs past tapping term to
activate)
## Using combos instead of a symbol layer
I am a big fan of combos for all sort of things. In terms of comfort, I much prefer them
over accessing layers that involve lateral thumb movements to be activated, especially
when switching between different layers in rapid succession.
I am a big fan of combos for all sort of things. In terms of comfort, I much
prefer them over accessing layers that involve lateral thumb movements to be
activated, especially when switching between different layers in rapid
succession.
One common concern about overloading the layout with combos is that they lead to
misfires. Fortunately, the above-mentioned `require-prior-idle-ms` option also works
for combos, which in my experience all but completely eliminates the problem -- even
when rolling keys on the home row!
misfires. Fortunately, the above-mentioned `require-prior-idle-ms` option also
works for combos, which in my experience all but completely eliminates the
problem -- even when rolling keys on the home row!
My combo layout aims to place the most used symbols in easy-to-access
locations while also making them easy to remember. Specifically:
My combo layout aims to place 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 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 with `<`,
`>`, `{` and `}` being accessed from the Navigation layer (or when combined with `Shift`)
- left-hand side combos for `tap`, `esc`, `enter`, `cut` (on <kbd>X</kbd> + <kbd>D</kbd>),
`copy` and `paste` that go well with right-handed mouse usage
- parenthesis, braces, brackets are set up symmetrically as horizontal combos
with `<`, `>`, `{` and `}` being accessed from the Navigation layer (or when
combined with `Shift`)
- left-hand side combos for `tap`, `esc`, `enter`, `cut` (on <kbd>X</kbd> +
<kbd>D</kbd>), `copy` and `paste` that go well with right-handed mouse usage
- <kbd>L</kbd> + <kbd>Y</kbd> switches to the Greek layer for a single key
press, <kbd>L</kbd> + <kbd>U</kbd> + <kbd>Y</kbd> activates one-shot shift in
addition
@ -193,49 +199,51 @@ locations while also making them easy to remember. Specifically:
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 "Smart-Num". Numword continues to be activated as long as I
type numbers, and deactivates automatically on any other keypress (holding it activates
a non-sticky num layer).
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 "Smart-Num". Numword continues to be activated as
long as I type numbers, and deactivates automatically on any other keypress
(holding it activates a non-sticky num layer).
After using Numword for more than a year now, I have been overall very happy with it. When
typing single digits, it effectively is a sticky-layer but with the added advantage that
I can also use it to type multiple digits.
The main downside is that if a sequence of numbers is *immediately* followed by any of the
letters on which my numpad is located (WFPRSTXCD), then the automatic deactivation won't
work. But this is rare -- most number sequences are terminated by `space`, `return` or some form
of punctuation/delimination. To deal with the rare cases where they aren't, there is a
`CANCEL` key on the navigation-layer that deactivates Numword, Capsword and Smart-mouse.
(It also toggles off when pressing `Numword` again, but I find it cognitively easier to
have a dedicated "off-switch" than keeping track of which modes are currently active.)
After using Numword for more than a year now, I have been overall very happy
with it. When typing single digits, it effectively is a sticky-layer but with
the added advantage that I can also use it to type multiple digits.
The main downside is that if a sequence of numbers is _immediately_ followed by
any of the letters on which my numpad is located (WFPRSTXCD), then the automatic
deactivation won't work. But this is rare -- most number sequences are
terminated by `space`, `return` or some form of punctuation/delimination. To
deal with the rare cases where they aren't, there is a `CANCEL` key on the
navigation-layer that deactivates Numword, Capsword and Smart-mouse. (It also
toggles off when pressing `Numword` again, but I find it cognitively easier to
have a dedicated "off-switch" than keeping track of which modes are currently
active.)
##### Smart-Mouse
Similarly to Numword, I have a smart-mouse layer (activated by comboing
<kbd>W</kbd> + <kbd>P</kbd>), which replaces the navigation cluster with
scroll and mouse-movements, and replaces the right thumbs with mouse buttons.
Pressing any other key automatically deactivates the layer.
<kbd>W</kbd> + <kbd>P</kbd>), which replaces the navigation cluster with scroll
and mouse-movements, and replaces the right thumbs with mouse buttons. Pressing
any other key automatically deactivates the layer.
##### Capsword
My right thumb triggers three variations of shift: Tapping yields
sticky-shift (used to capitalize alphas), holding activates a regular shift, and
My right thumb triggers three variations of shift: Tapping yields sticky-shift
(used to capitalize alphas), holding activates a regular shift, and
double-tapping (or equivalently shift + tap) activates ZMK's Caps-word behavior.
One minor technical detail: While it would be possible to implement the double-tap functionality
as a tap-dance, this would add a delay when using single taps. To avoid the delays, I
instead implemented the double-tap functionality as a mod-morph.
One minor technical detail: While it would be possible to implement the
double-tap functionality as a tap-dance, this would add a delay when using
single taps. To avoid the delays, I instead implemented the double-tap
functionality as a mod-morph.
##### Multi-purpose Navigation cluster
To economize on keys, I am using hold-taps on my navigation cluster, which yield `home`, `end`,
`begin/end of document`, and `delete word forward/backward` on long-presses. The exact
implementation is tweaked so that `Ctrl` is silently absorbed in combination with `home` and `end`
to avoid accidental document-wide operations (which are accessible via the dedicated `begin/end
document keys`.)
To economize on keys, I am using hold-taps on my navigation cluster, which yield
`home`, `end`, `begin/end of document`, and `delete word forward/backward` on
long-presses. The exact implementation is tweaked so that `Ctrl` is silently
absorbed in combination with `home` and `end` to avoid accidental document-wide
operations (which are accessible via the dedicated `begin/end document keys`.)
##### Swapper
@ -245,19 +253,20 @@ one-handed Alt-Tab switcher (`PWin` and `NWin`).
##### Repeat
I recently switched to 25g-chocs on one of my keyboards. I already was very happy with
my combos prior to that (even with heavy-ish MX-switches). But with the light chocs, I
find that I can now even use them for regular typing. While I haven't yet tried
placing alphas on combos, I am currently experimenting with a `repeat` combo on
my home row that I use to reduce SFUs when typing double-letter words.
I recently switched to 25g-chocs on one of my keyboards. I already was very
happy with my combos prior to that (even with heavy-ish MX-switches). But with
the light chocs, I find that I can now even use them for regular typing. While I
haven't yet tried placing alphas on combos, I am currently experimenting with a
`repeat` combo on my home row that I use to reduce SFUs when typing
double-letter words.
## 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 require complex user-space implementations in QMK). Below
are a few remaining issues:
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)), requiring a brief
@ -267,8 +276,8 @@ are a few remaining issues:
dynamically adding/removing mods doesn't work well). Having a native solution
akin to QMK's "COMBO_MUST_TAP" property would be fantastic.
- Another item on my wishlist are adaptive keys
([#1624](https://github.com/zmkfirmware/zmk/issues/1624)). This would open
the door for things like <kbd>space</kbd><kbd>space</kbd> becoming
([#1624](https://github.com/zmkfirmware/zmk/issues/1624)). This would open the
door for things like <kbd>space</kbd><kbd>space</kbd> becoming
<kbd>.</kbd><kbd>space</kbd><kbd>sticky-shift</kbd>. (Using tap-dance isn't
really an option here due to the delay it adds)
- A minor thing is that ZMK doesn't yet support any keys on the
@ -278,29 +287,34 @@ are a few remaining issues:
- Very minor: `&bootloader` doesn't work with stm32 boards like the Planck
([#1086](https://github.com/zmkfirmware/zmk/issues/1086))
[^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
homerow-mod shift on my left index-finger and then pressing my right home-thumb, which
is my new preferred way. Or, (2) double-tapping the right home-thumb, which also works
because the first tap yields sticky-shift, activating the mod-morph upon the second
tap. But even when only activating via double-tapping, this implementation is advantageous
compared to using tap-dance as it does not create any delay when single-tapping the key.
[^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
homerow-mod shift on my left index-finger and then pressing my right
home-thumb, which is my new preferred way. Or, (2) double-tapping the right
home-thumb, which also works because the first tap yields sticky-shift,
activating the mod-morph upon the second tap. But even when only activating
via double-tapping, this implementation is advantageous compared to using
tap-dance as it does not create any delay when single-tapping the key.
[^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
`require-prior-idle` timeout. However, with both a large tapping-term and
positional-hold-taps, the behavior is *not* actually sensitive to the
`require-prior-idle` timing: All it does is reduce the delay in typing; i.e., variations
in typing speed won't affect *what* is being typed but merely *how fast* it appears on
the screen.
[^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
`require-prior-idle` timeout. However, with both a large tapping-term and
positional-hold-taps, the behavior is _not_ actually sensitive to the
`require-prior-idle` timing: All it does is reduce the delay in typing;
i.e., variations in typing speed won't affect _what_ is being typed but
merely _how fast_ it appears on the screen.
[^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.
[^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.
[^4]: E.g, if your WPM is 70 or larger, then the default of 150ms (=10500/70)
[^4]:
E.g, if your WPM is 70 or larger, then the default of 150ms (=10500/70)
should work well. The rule of thumb is based on an average character length
of 4.7 for English words. Taking into account 1 extra tap for `space`, this
yields a minimum `require-prior-idle-ms` of (60 * 1000) / (5.7 * x) ≈ 10500 / x
milliseconds. The approximation errs on the safe side,
as in practice home row taps tend to be faster than average.
yields a minimum `require-prior-idle-ms` of (60 _ 1000) / (5.7 _ x) ≈ 10500
/ x milliseconds. The approximation errs on the safe side, as in practice
home row taps tend to be faster than average.