My configuration: Getting rid of bound key combinations

Firngrod · January 24, 2026, 8:09pm

Motivation

At some point a year or so ago, I started getting the beginnings of discomfort in my hands after long days of coding. I guess age catches up to us all. I thought about it, and my conclusion was that the issue was mainly to do with the awkwardness of reaching key combinations, and so I had to find a solution for that.

The wrong solution

The first one to present itself, and the most obvious one with a fully programmable keyboard like the UHK, was of course to map the awkward key combinations to various combo/macro keys on alternative layers and then use those, but that has a couple of big disadvantages:

Now I need to remember where I put all of those key combinations, without any indication in UI where they are. Sure, the program tells me to hit Ctrl+Shift+Alt+~, but where is that in my keymap?
New key combos require overhead of setting them up.
Old key combinations which have fallen out of use need to be cleaned up every so often.

All in all not a road I wanted to continue down.

The good solution

Move the keys around so the combos are not awkward anymore!

So I set out to make a layout not only without keys and macros dedicated to key combos, but without any NEED for such things. But how to do that?

Dealing with mods

First and foremost, I had to move the mods somewhere where I could activate any combination of them and still be able to press any key without ending up in an awkward hand position. Ideally, the non-mod keys should all still be accessible with their usual finger while mods were being held.
Since I had a lot of mods, this was hard. Shift, Ctrl, Alt, AltGr, Gui, Mod. I wanted to access all of those, or any combination thereof, without contorting my hands and without blocking the key I wanted to combo them with.

At first, I came up with the following key arrangement which worked reasonably well. I could make any combination of those three keys with my left thumb only.

I could do a similar thing with the right thumb, only this is still pretty awkward, and I needed that thumb to use the mouse, potentially while holding mods. I had to find something even better!

This is when I finally tried to use Home Row Mods (HRM). Unfortunately, I found the UHK offerings in this regard to be lacking. I simply could not get used to typing with HRMs with the Secondary role configuration options available on the UHK without false triggering every few letters. This turned into a whole other epic which has been documented here. The conclusion of that venture is that the UHK now has very solid support for HRMs, in my own humble and completely unbiased opinion.

Gathering data on key usage

The next issue was that even with better combo placements, frankly, the QWERTY layout is not good for fast and comfortable typing, sort of by design. I also wanted all keys to be available without moving my hands from the wrist rest, and without stretching my fingers into any awkward positions. In order to achieve this, I was already in for a considerable redesign of the key layout. So why not, as with the HRM implementation mentioned above, go all in?

First, I wrote a keylogger which collected statistics on everything I did on my keyboard for several weeks. The following information was gathered relating to each key:

How many times it was reached for (repeat presses were disregarded)
Which keys it was closely related to, that is to say which key preceded and succeeded the key

The reason for disregarding repeat presses is that otherwise something like navigation keys, go to next result keys, or other keys which are pressed repeatedly with no ergonomic cost, will be vastly over represented compared to how much it’s actually reached for while typing.

This data is generally available for any language you would care to mention, but for a bilingual software developer writing a combination of various programming and human languages, this gives me real world data on my own actual usage.

Deciding where to put keys

I also sat down and determined the following for each key on the keyboard:

Which finger is most comfortable for reaching that key
How comfortable it is to actually reach the key

The resulting data was a map of which finger was used to press a key, and whether the key was comfortable or not to reach for repeatedly

The layout was then constructed, with the following considerations in mind:

Most used typing keys on the home row, obviously
Less used keys at less comfortable places obviously
Try to spread the keys such that fingers get a sort of even amount of usage. Fingers with more keys get less frequent keys, except the pinky gets it easy
Try to avoid keys with close ties on the same fingers - H was a pain in this regard
Try to let closely related keys be on adjacent fingers to allow rolling
Keep all keys which have a logical connection grouped together on the same layer. Mostly, this meant keeping the alpha keys and punctuation on the main layer, and other keys on the mod layer, even though some letters are used less frequently than a number of keys on the mod layer.
Try to keep the Vim navigation keys somewhat sanely located - H was a pain because of how many keys it was closely related to (ph, th, wh, sh, gh, …), and J since my data showed that it got very little use in typing, but was central for navigation. I think the resulting location made some logical sense at least, and fit with the other criteria. I matched the arrow keys relative locations to go easy on my sanity, and PgUp, PgDown, Home and End accordingly. Anyone wishing to try this layout who doesn’t care about Vim navigation keys can relocate the arrow keys and the PgUp, PgDown, Home and End according to their desires, and probably swap L and W.

Describing the resulting layout

The result can be seen on Yuzu, or in the config, or in the images below

I have thankfully managed to keep all of the main keys within my comfortable zone. F1-12 are on stretch keys, but they aren’t used in typing, so I can live with stretching for them when I need them.

I was surprised to find that I could actually fit all of the keys within the comfortable keys on just two layers, with keys to spare. I used the leftover keys to duplicate keys from the main layer on the secondary layer. These are keys which are commonly used when typing number sequences (punctuation, space, enter, tab, backspace, delete). This is to avoid too much mod-dancing while typing numbers.

The locations of space, backspace, enter, tab, escape and delete are somewhat arbitrary. I placed space and backspace when I was still playing with the thumb mod idea, and then they got kinda stuck. I guess they would technically be better placed on thumbs according to most people’s preferences, but I actually find not using my thumbs for taps while typing more comfortable. I find the comfy keys on my not-thumbs more comfortable to use than the thumbs for taps.

Using HRMs, I have made all mods available on both hands so that any key combination can be made comfortably without any stretching. On the flip side, HRMs come with two disadvantages:

False activations of the unintended role. This has been largely solved with the recent additions to the firmware in that area. Most people should be able to find some combination of the available parameters which enables them to type reliably without false activations.
Typing in all-caps is annoying as one needs to change which hand holds Shift all the time. However, it turns out that the ancients before us had a solution to that already: Caps Lock is at a reachable location, and is then disabled through macros on Space, Enter and Tab, as well as via Escape. So when I need to type a word in all-caps, I just hit Caps Lock, type the word and on space, it’s disabled automatically.

The location of the HRMs could be switched, and in hindsight, I think I should have put shift on the middle finger instead of the index, but there’s no way I’m relearning that now!

Various tidbits

I use runtime macros via the three keys on the right. When the Record Macro key is pressed, recording starts when the next key is pressed, like it’s done in Vim. Recording stops when the record button is pressed again. Play works in the same way, with pressing the play key first, then a button with a recorded macro, again like it’s done in Vim. This way, I don’t have to have more than three dedicated buttons to access a practically unlimited amount of macros. The keyboard also lights up the keys on which macros have been recorded, making it easier to remember, and making at least some use of the LEDs I have painstakingly soldered onto the board.

Very recently, I have started playing with a home-made mod which doubles all key presses while held, available on the F and H keys (and corresponding mod layer keys). I’m trying to learn to use it, but muscle memory is hard to beat when there’s no punishment for not using it and just double tapping instead.

Apparently, my left pinky is pretty slow to release, because I get by far my most false activations of HRMs from that key. For that reason, I have made a macro to specifically increase the minimum hold time of that key to trigger secondary.

The chassis key mod on the right half is used more or less exclusively for scrolling with the right hand alone when I’m reading long documents. I press it with my thumb and scroll with my index.

I’m also working on my own wrist rests. I have made a set which is considerably thicker than the original ones, raising my palms by a centimeter or two. This, I find, gives a more comfortable typing experience, as some other ergo keyboards will agree. I will share images of those separately once I am done oiling them. Tung oil takes forever to dry, even in a warm room with plenty of air circulation, and needs many layers to get to the finish I want.

Firngrod · January 24, 2026, 9:00pm

Woops, that stray L at the top was used for testing a bug.

maexxx · January 25, 2026, 12:59pm

Thanks for sharing your setup!

Yes, I have hrm shift on my middle fingers.
My order is: lalt ralt lshift lctrl lgui / rgui rctrl rshift ralt lalt
lgui and rgui are a lateral stretch for the index finger. That’s OK, I don’t need that often.

Those Yuzu caps are pretty, btw!

pcooke9 · January 25, 2026, 2:16pm

I wish I had the patience to use HRM. I just don’t have the discipline to rewire my brain away from QWERTY.

Firngrod · January 25, 2026, 2:23pm

You can try just a HRM shift, with QWERTY.

Also, the Yuzu is outdated. I will fix it up later, with the proper colors as well.

pcooke9 · January 25, 2026, 2:54pm

If someone could find the time to whip up a very basic userConfig with all the necessary settings (esp. typing behavior stuff) and a simple keymap/layer template, I’d love to try it . (A dumbed-down tutorial wouldn’t hurt either.) I’m sure it would be easier for me to wrap my head around it if I could see everything mapped out in Agent. If I have to read through the docs first, I’m gonna give up before I even start .

Firngrod · January 25, 2026, 5:50pm

Well, I would recommend the settings from the User Guide, more or less.

set secondaryRole.defaultStrategy advanced
set secondaryRole.advanced.triggeringEvent release
set secondaryRole.advanced.timeout 300
set secondaryRole.advanced.timeoutAction secondary
set secondaryRole.advanced.doubletapToPrimary 1
set secondaryRole.advanced.safetyMargin -50
set secondaryRole.advanced.triggerByMouse 1
set secondaryRole.advanced.minimumHoldTime 130
set secondaryRole.advanced.acceptTriggersFromSameHalf 0

Then just add secondary role Shift on your home row middle fingers, or index fingers, and you should be off to the races. If you tap the key, it’s the normal key, but if you hold it while pressing another button, it’s a shift key. If you don’t like it, you can remove it again.

You need to do it on the same finger on either hand, and with the above settings, the keys will only work as shifts key for keys from the other half of the keyboard.

pcooke9 · January 27, 2026, 12:08am

Ok, seems simple enough. Most of the examples I’ve seen in the past were way too complex for me. Of course most people that use HRMs also seem to use alternate layouts, so that makes it even harder to follow.

I’ve been trying it out, and I think I can probably dip my toes into HRM with just shifts on my base layer for now. I’d eventually like to set up a better system for punctuation, but one step at a time, I guess. I tried adding the other mods for about an hour, and… YIKES!!! Using HRMs has revealed just how terrible my typing really is . I wish I’d known about this stuff a couple of decades ago, because I think I’m getting too old for new tricks .

Thanks, btw!

Does this mean that if I have LShift secondary role on d, that holding d and tapping f on same half should not produce F? Because it shifts to uppercase for me regardless of set secondaryRole.advanced.acceptTriggersFromSameHalf true or false.

I’m on UHK80 with release FW v16.1.1.

Firngrod · January 27, 2026, 5:22am

I suspect, then, that you held the key for a while first, or that you have already typed another letter which turned the key into a shift.

When you press a dual role key, it waits to see if it should become a primary, in your case D, or a secondary, in your case lShift.

With the settings above, it will turn into a shift if it held for more than 300ms (timeout), or if another key is pressed and released while holding the key.

Once the key is either primary or secondary, it will stay that way until release. This means that even when ignoring same half for triggering, for instance, once it has been triggered as secondary, it will still be a shift key for keys on the same half.

That is the basic premise. The configuration options are parameters which can be tuned to match your typing style to allow you to reduce the number of times that the key became the other role that you intended.

I think in your case, if you were testing the feature, you might have run into the timeout and it becamelShift. You can increase timeout if this is undesired. I have a PR open for adding another option to make timeouts more advanced, including the possibility of effectively disabling it.

pcooke9 · January 27, 2026, 6:22am

Ok, I kinda figured it was something like that, but that macro’s name looks like it’s disabling secondaries on same-half altogether. I thought that would be an odd option, because it would make it impossible to do multiple mods on the same half.

Anyway, I’m definitely gonna have to keep tweaking timings because I overlap keypresses a lot. I tend to think in chord-like chunks, and apparently my typing comes out that way as well. Something I didn’t realize until trying HRM .

All these timing tweaks kinda feels like I’m setting up the mic placements and gain staging for recording a band full of percussionists .

maexxx · January 27, 2026, 8:57am

I think @Firngrod explained the hrm role switch really well.

The whole idea is that you can have some overlap between key presses and still activate the primary function as long as:

you don’t hold down the dual-roles key too long (that’s where the timeout triggers, and it becomes a secondary role)
you release the keys in an order that makes it clear that you intended the primary role, e.g. when you finger-roll over multiple keys, but you also let go of them in order.

Here’s an example. We’re assuming a is a dual-role key and its secondary role is mod. All press and release is quick enough so we don’t hit any timeouts.

Press a
Press b // the decision what a should become is currently held back
Release a // ok, a is primary, so it will produce a tap of a followed by press of b
Release b // b released

vs.

Press a
Press b // the decision what a should become is currently held back
Release b // ok, a is secondary and will trigger tap of mod-b
Release a // mod is released again

Now, timeout example:

Press a and hold until the secondary role timeout expires
// a becomes secondary and produces mod
Press b // produces press of mod-b
// at this point it doesn’t really matter in which order the keys are released
Release a // mod is released again
Release b // b released again

pcooke9 · January 27, 2026, 11:44am

Thanks guys, I now clearly notice the effect of acceptTriggersFromSameHalf after paying more attention to the release order and increasing set secondaryRole.advanced.timeout a bit.