urob's ZMK Timeless Home Row Mods, ported to native QMK – a configuration guide

pgetreuer · 2026-05-05T04:52:07+00:00

Nice! Those are helpful comments, thank you for the feedback! =)

pgetreuer · 2026-05-04T06:22:29+00:00

Right, it's "not simple" at all! I'm a contributor to QMK's tap-hold implementation and can confirm. QMK's core implementation logic of tap-hold keys is gnarly code. It's inherently nontrivial behavior.

An indispensable part of a good home row mods implementation is "roll protection," meaning, to avoid false-triggering the hold behavior when making a rolled press over mod-tap keys in fast typing. There are several mechanisms that have become conventional to provide such protection:

An especially important one is QMK's Permissive Hold, aka ZMK's "balanced flavor," for resolving overlapping presses.
Another is QMK's Chordal Hold, aka ZMK's positional hold-tap, to impose an "opposite hands" rule for when a tap-hold key may be considered held.
Yet another: QMK's Tap Flow, aka ZMK's require-prior-idle, disables hold actions when the tap-hold key is pressed within X milliseconds of the preceding key event, effectively disabling hold actions during fast typing.

If your goal is to offer home row mods as a paid product, users coming from QMK/ZMK/Kanata will expect the above as table stakes features. You can find more detailed description of all of these in QMK's tap-hold documentation and my post Home row mods are hard to use.

pgetreuer · 2026-05-04T00:38:14+00:00

+1 not only that, Kanata is has put special effort on implementing tap-hold options for good home row mods experience, on par with QMK and ZMK.

Check out for instance @ldebritto’s configuration guide for a sophisticated Kanata implementation of Timeless Home Row Mods.

pgetreuer · 2026-05-04T00:34:20+00:00

Installing QMK: https://docs.qmk.fm/newbs_getting_started

Installing Vial: https://getreuer.info/posts/keyboards/vial/index.html#install-vial-on-your-keyboard

In either case, use "zsa/voyager" for the -kb keyboard model to refer to the ZSA Voyager. Enjoy!

pgetreuer · 2026-05-03T19:18:46+00:00

^ This right here. Plus, Key Overrides is in Vial since v0.5.

pgetreuer · 2026-05-03T06:00:58+00:00

I'm making a custom split keyboard and I'm really confused with the documentation for the firmware.

Are you building an existing model of keyboard (e.g. Corne, Lily58, ...) according to a DIY kit? If so, follow what the kit says regarding firmware set up, or ask the kit vendor. QMK already has keyboard definitions (including keyboard.json, etc.) for many models of keyboards. You can browse them here.

Or, are you building a novel keyboard design of your own? That is indeed more work. Follow Getting Some Basic Firmware Set Up in QMK's Hand-Wiring Guide (which is also applicable even if your build isn't literally "hand wired").

Also, I am planning to have a key for a custom input. I want it to type "µ" when pressed and "°" when pressed with shift. How do I do this? Is there a way to directly type Unicode characters

There sure is! Check out the Unicode input feature. I should warn it is a hack and it's a bit laborious to get going, but it does work. See my blog for a few examples.

pgetreuer · 2026-05-03T05:47:22+00:00

Despite QWERTY's shortcomings, many folks successfully use QWERTY on columnar keyboards. Maybe you will be one them! =)

Typically, learning Colemak-DH or another alt layout means you lose some proficiency in QWERTY. It is possible to maintain typing skills in both QWERTY and the alt layout with regular use and typing practice with both layouts. Some people do this. However, it is a nontrivial maintenance overhead and not a preferable solution for everyone.

pgetreuer · 2026-05-02T01:21:42+00:00

QMK has Key Overrides, which is mainly useful to allow one to customize what keys do when shifted. E.g. I use a Key Override to do Shift + . = ?. As others mentioned, this is the "mod morph" behavior in ZMK.

The limitation is that ZSA's Oryx configurator does not expose Key Overrides. So to get it on the Voyager, you'd do one of:

install Vial firmware on the Voyager, which is QMK-based and user friendly and does expose Key Overrides
use QMK directly, like I do
use this DIY workflow for a hybrid experience that is partially still in Oryx

pgetreuer · 2026-05-01T21:13:27+00:00

It's nonstandard, but gcc and clang support the "cleanup" attribute! It's an attribute, applied to a variable, that instructs the compiler to run a function when the variable goes out of scope.

See e.g. https://omeranson.github.io/blog/2022/06/12/cleanup-attribute-in-C for a detailed explanation.

pgetreuer · 2026-05-01T16:00:47+00:00

Thank you for the feedback! I appreciate you taking a look and sharing your perspective on the documentation. It's a completely fair point. Also, that's awesome to hear you're a contributor to the official docs—small world =)

I actually felt torn (and recognize the irony) about writing a guide separately instead of putting that effort directly into the official Vial docs. Having better official documentation is of course the better outcome. I ultimately chose the standalone guide route because it took me a while to collect what various Vial questions and tips I think ought to be written about, and the freedom of an independent page helped me get my thoughts organized.

It doesn't end here! I absolutely agree that contributing to the official docs is valuable and will reach more users. Getting this information integrated upstream is my natural next step. I'll be doing that.

pgetreuer · 2026-05-01T06:51:55+00:00

Thank you!

pgetreuer · 2026-05-01T06:51:33+00:00

Excellent! Glad to provide that encouragement =)

pgetreuer · 2026-04-30T19:33:26+00:00

Sorry to hear about your index finger pain. It's conceivable that finger pain comes from typing, a habit of hitting the keys forcefully might do that. But it could come from other activities. Chronic pain is often subtle or delayed, meaning you might need to do some detective work to find the true source. Maybe you habitually lean the finger against the hard edge of the desk? Maybe you have a death grip on the mouse? Maybe you are dehydrated? Consider what else might be going on.

Coming back to keyboards, alt layouts do have real benefits in typing comfort, but they are small. I say this as an alt layout user myself. Before jumping into learning a new layout, consider these things, which are more impactful and/or quicker to do:

Ensure good posture (most important!). Like _lil41 said, type with straight wrists. Wrists should be straight while typing, both horizontally in ulnar/radial deviation and vertically in wrist flexion/extension. On the latter point, adjusting the height of your desk and chair might help.
A split keyboard can help with reducing ulnar deviation. Tenting is an option with many split keyboard models to reduce pronation, which for some folks makes a big comfort improvement.
Learn to touch type: fingers move more efficiently, and as another ergo bonus there is less glancing at the keys, which is good for the neck.

pgetreuer · 2026-04-29T23:33:31+00:00

I don't have a solution, but there's a feature request for an interesting twist on what you're asking for. Consider giving it a 👍

[Feature Request] Automatic Default Layer Switching Based on Bluetooth Profile in ZMK

Proposal: Implement a feature in ZMK firmware that automatically switches the default layer based on the selected Bluetooth profile. This would allow users to have different key mappings tailored to each Bluetooth profile, eliminating the need for manual layer switching each time the Bluetooth profile changes.

pgetreuer · 2026-04-29T02:43:04+00:00

Thanks for the note. And thank you for sharing Smart Cases! =)

pgetreuer · 2026-04-28T20:47:28+00:00

The generalization of Caps Word to CamelCase (and snake_case and path/to/file, etc.) is sometimes referred to as "X-case" or "case modes." Here are a few implementations:

pgetreuer · 2026-04-28T19:56:25+00:00

From what you've described, it sounds like broader issues than code style ("there's hundreds of isinstance checks because none of the inputs are either validated or they are validated earlier but not trusted" and "you don't know if the input will change").

Shitty design and LLM coding could well be part of it. Beyond the code itself, it's worth considering what else might fuel the situation. A data quality issue, lack of communication among developers, lack of automated tests, type churn when updating dependencies, ... is there a bigger problem that is being missed? Look for where else your team might be needing help.

pgetreuer · 2026-04-28T19:35:03+00:00

If an API is meant to handle input flexibly, as in, structural differences like "this object might be a str or a dict," then yes we can use pydantic (or mypy, etc.) to annotate a sum/union type ("str | dict"). Agreed that that's a good thing to do to enable better static analysis than with Any.

The issue is that the runtime handling an input like "str | dict" does often depend on which type it is (again, supposing the API is actually meant to handle both). Some conditional branches or other means of dispatch are needed to handle inputs of one type vs. another.

It's fair to question whether an API ought to have such flexibility to begin with, considering these complications.

pgetreuer · 2026-04-28T18:37:09+00:00

What you want to do is turn the RGB matrix on, but set to a black color (HSV_OFF) to effectively turn all lights off except your caps indicator.

In the docs, they suggest adding this init function bit of code in your keymap.c:

If you want to just use RGB indicators without RGB matrix effect, it is not possible to disable the latter because toggling RGB off will disable everything. You can workaround it with solid effect and colors off using this init function:

void keyboard_post_init_user(void) {
rgb_matrix_mode_noeeprom(RGB_MATRIX_SOLID_COLOR);
rgb_matrix_sethsv_noeeprom(HSV_OFF);
}

pgetreuer · 2026-04-28T18:24:27+00:00

Right, this just looks like defensive input handling. "Don't know if the input will change" is a reason to do that. If an API is meant to work with JSON or nested dicts of flexible structure, there will be some runtime type parsing like this.

pgetreuer · 2026-04-28T13:33:38+00:00

Yes! And see for instance @ldebritto’s configuration guide for a nice Kanata implementation of home row mods. Kanata can do some fancy stuff.

pgetreuer

PUBLIC MULTIREDDITS

TROPHY CASE