timseriakov / zmk-config-knucklehead

👊 Knucklehead keyboard layout

👊 Knucklehead

Knucklehead is a mnemonic, macOS-optimized, 42¹ key ergo columnar keyboard layout, designed² to ease the transition [back-and-forth] between corne-style and Apple-style keyboards.

---

Warning

Under active development, expect changes. Scarce/incomplete documentation. Use at your own risk.

Note

This layout was primarily designed for Colemak-DH and influenced by decades of muscle memory using ANSI Apple keyboards.

By request I've started working on other alpha layouts, such as:

• QWERTY
• Colemak

But keep in mind that while many of the mnemonic affordances will work well regardless of layout, many others will be "lost in translation".

---

Drawn with Keymap Drawer

Legend

Symbol	Key Name
⌃	Control
⌥	Option
⌘	Command
⇧	Shift
⇪	Caps Lock
▲	⌃⌥⇧ at once (a.k.a. "Meh")
⌫	Backspace
⌦	Delete
⏎	Return
⇥	Tab
␣	Space
w	Smart word behavior
×	Exit smart word behavior
L1	Layer 1
L2	Layer 2
Fn	Function Layer

Features

Mnemonic Affordances

Important

These are in the context of the (default) Colemak-DH layout. Many will be lost in translation when using other alpha layouts.

Key	Cue	Mnemonic Affordance(s)
⌘	C or ,	Command, Command
⌥	X	shape similarity
⌃	A	shape similarity, proximity
^	A + Z	(Caret) shape similarity, proximity
⇥	␣ or ⌘	space multiplier, proximity; also near ⌘ which is combined with for app switching
` ~	H, ⇥ or ⌘	~ a.k.a. "home" directory on 'nix systems; proximity. Same position, opposite hand as ⇥, typically found near each other on Apple keyboards; also near ⌘ which is combined with for window switching
- _	N + L	Negative, Low
= +	E + U	Equals, Up (+)
[ {	N + H	proximity; used to define a New Hash table/map on many programming languages; adjacent to ] }
] }	E + ,	proximity; used to End hash tables/maps on many programming languages; , is also typically used to delimit items within hash tables/maps; adjacent to [ {
\ |	I + . or / ?	shape similarity, proximity; logical OR — same position, opposite hand as & (logical AND)
&	R + X	shape similarity; logical AND — same position, opposite hand as | (logical OR)
*	S + C	Star, wild Card
⇪	⇧	same position as ⇧ (shift), but on Fn layer
! @ # $ % ^ & * ( )	1 2 3 4 5 6 7 8 9 0	symbols maintain their standard ANSI association with numbers as laid-out on L2, replicated as combos on L1 and L2
-_ =+ [{ ]} |\	Apple ANSI position	this key cluster retains their order/position relative to each other on Apple keyboards, but is to vertical combos more easily accessible to stronger fingers.
Fn ⌃ ⌥ ⌘ ⌘ ⌥ ⌃ Fn	Apple ANSI position	Fn and modifiers cluster retains their familiar Apple keyboard lower left corner (mirrored on the right) relative position and order

---

Smart word Behaviors

A smart word behavior is one where, to perform an action for which you would normally hold a key, you're only required to tap it at the beginning of a sequence to "enter" that special mode, and you remain in that mode until you press a key not in the defined "continue-list" (a "break-word" key, like ␣ [space]), or until you explicitly "exit" that mode.

The most common example of this type of behavior is ZMK's &caps_word (or QMK's).

This layout uses 2 smart word behaviors (marked with the w symbol):

Important

Both of these were taken from @urob's fantastic layout, and use his ZMK fork which include a couple of (popular, but yet-to-be-merged) PRs to ZMK necessary for this to work.

Smart Shift

The right hand middle thumb ⇧ (shift) key will act as follows:

Action	Effect
hold	Normal "shift" behavior.
tap	Sticky "shift" behavior (i.e. will apply a "shift" modification to the next key pressed within 1s). Useful when capitalizing words at the beginning of sentences without holding the key (for example).
double-tap	&caps_word, i.e. retains "shift" behavior until a character not in the "continue-list" is pressed. Useful for ALL_CAPS word sequences, like conventional constant names on some programming languages.
Fn + tap	⇪ (CAPS LOCK).

Smart L2 Layer

Both inner thumbs (marked as L2 on L1) will act as follows:

Action	Effect
hold	Normal &mo "momentary layer" behavior.
tap	Sticky layer behavior, i.e. will switch to L2 until the next key pressed (within 1s), and immediately exit back to L1. Useful to use single-handed sticky modifiers, entering a single number, single arrow movements, single media key actions, etc.
double-tap	Stays on L2 while numbers, arrows, , . / - _ + = *, ⌫ or ⌦ are pressed. Useful when entering longer numeric sequences, math operations, repetitive arrow navigation, etc.

Exiting Smart word Behaviors

Sometimes you may enter a smart behavior by accident, or may need to cancel it to accommodate special use cases. For these situations there are special "cancel" keys, marked with an x:

On L1 the right-most x key (top row, right hand) — and since on L2 that key position is "transparent", it's essentially the same key on that layer — will cancel any smart word behavior (i.e. it will exit &caps_word, and/or exit L2's smart layer behavior and bump you back to L1). It's positioned to mirror the traditional ESC key since it's another type of "escape".

On L2 the same thumb keys you use to summon it will act as follows:

Action	Effect
tap	Will exit the smart layer behavior and bump you back to L1. (It will also cancel &caps_word, so it can be used for that as well; from L1 this would technically be a triple-tap, so the top-right x key is more convenient)
hold	Will also exit the smart layer behavior, but will immediately enter the normal &mo "momentary layer" behavior as well and remain on L2, so as long as you keep holding it you shouldn't see a difference, but as soon as you let go you'll be bumped back to L1. I implemented this to account for accidental "muscle memory" hold actions, making it more forgiving and less confusing.

---

Non-Stacking Upper Layers

One of ZMK's great features is its stacking layers system. These can be amazing for things like multiple "active" base layers for different alphas layouts and such, while sharing a common set of "momentary" layers. However, unless you really understand this behavior and explicitly wish to use it, it may become really confusing very quickly, and make you feel lost in a layer maze.

Since the aim of this keymap is to meet newcomers half-way (specifically those transitioning from Apple keyboards), and make it as intuitive as possible, this behavior is specifically avoided in a few ways:

Note

If this all sounds like gibberish to you here's all you need to understand: L1 should always be the layer behind L2 or Fn. If that's not the case, please report it as a bug.

Single Base Layer

L1 is the one true base layer. There is no way to permanently activate any other layer, only momentary (&mo), sticky (&sl), and smart layer behaviors are used.

Upper Layer Swapping

Additionally, in order to prevent even momentary layer stacking, a "cancel" (x) event is triggered in some circumstances prior to switching to a layer, so that you're first bumped back down to L1 before switching to the desired layer. This all happens transparently without delay, so from your perspective you just "swapped" upper layers, instead of stacking them. This ensures any transparent keys in that upper layer will fall through to L1, and sticky timeouts will bump you back to L1 immediately, as you would expect. These special cases are marked with the same x symbol.

Without this behavior, for example, it might've been confusing if you pressed the Fn key while on L2's smart layer mode, and pressed a transparent key expecting an L1 keycode when instead you get an L2.

Static Key Placement

This layout also aims to keep keys in the same place across layers. Layers may change/enhance that key's functionality, or replace it with another key, but that key itself won't move to a different location. On upper layers unused keys are "transparent", so events flow down to (and are activated on) the base layer.

Together with the single base layer and upper layer swapping, static key placement aims to make layers more intuitive and predictable.

---

Other Features

Keys are repositioned in clusters to either "familiar" relative positions, or otherwise logical ones, using ANSI Apple keyboards as a reference, e.g.

• ;: is accessible as a combo on a stronger finger, but retains its own relative position to the '" key.
• 1–5 numbers retain their familiar "left, upper-row" position on Layer 2
• 6–0 are right below 1–5 on Layer 2's left hand home-row. This not only feels natural for single handed numeric typing, but also moves the most used symbols [for programming] to more accessible positions.
• Fn, Control, Option and Command keep their relative Apple keyboard positions, but are moved to "mod-tap" keys on Layer 1, and on the same position but as "sticky keys" on Layer 2. This allows for easy 2 handed or 1 handed shortcuts.
• Arrow keys are moved to Layer 2 on traditional VIM positions.
• ⇥ and `~ are moved to inner thumbs on each hand, where their proximity to the Command key makes typical App/Window switching a more comfortable, symmetrical "pinch" 🤏 motion.
• Fn key is duplicated on the right/bottom corner, and it activates the Fn layer, which has all F keys organized in the same position as their corresponding numbers on Layer 2 (plus 2 extra ones which go where you imagine they would).
• Bluetooth profile selectors can also be found on the Fn layer, as combos aligned with their corresponding numeric positions.
• Media keys retain almost their relative position, except they're re-arranged a bit so:
  • volume up / down align with + / - and Up / Down arrows, and U ("up") and L ("low") keys.
  • back / forward align with Left / Right arrows.

A 4th Meh modifier is added to the cluster which corresponds to pressing Control, Option and Shift but with a single key, instead of 3. This makes complex shortcuts significantly more comfortable (works great for window managers, app launchers, etc.).

---

F.A.Q.s

Why "Knucklehead"?

While searching for mnemonic-related names I saw the primary image on the Wikipedia article for "mnemonic" (a representation of the Knuckle mnemonic), and it occurred to me it'd be a relevant and funny name (like a slightly more rude version of "a layout for dummies"). The fact that the combos kind of resemble knuckles is just another happy coincidence. Ehrm… I mean, totally planned.

Why no "home row mods"?

• I wanted to keep them in the same position across layers without dictating the position of nor interfering with other typically held keys (e.g. arrows).
• I wanted to diminish their interference with normal/fast typing without over-complicating their implementation, timing configuration, etc. Putting them on "less used" keys helps.
• Decades of muscle memory for I don't know how many shortcuts across who knows how many apps had me unconsciously reaching for those positions anyway.
• I feel like the deliberate, paused, "non-rolly" way I tend to use mods makes home position unnecessary.
• While they don't eliminate hand movement like HMRs, on this new position they still greatly minimize movement/effort, improve comfort when compared to their traditional Apple keyboard position, with the added benefit of leveraging some of your muscle memory.

---

Resources

• ZMK Firmware GitHub
• ZMK Documentation
• ZMK Discord Server
• @caksoylar's Keymap Drawer, ZMK config and Display improvements for Corne-ish Zen
• @urob's ZMK config
• "Callum-style Mods"
• Colemak-DH and the Effort Grid
• Darryl's amazing Corne-ish Zen

---

Important

Content below was inherited from the default Corne-ish Zen ZMK configuration repository, which is where this repo was forked from. It still needs to be updated, but leaving it here for now because it's still relevant.

Customization Instructions

1. Edit the keymap file(s):
   • Change the keymap file to edit keycodes, add new layers etc.
   • Change the conf file to edit configuration settings like changing the deep sleep timeout
2. Commit and push. GitHub Actions will start building a new version of the firmware with the updated keymap and drawing.

Firmware Files

To locate your firmware files...

1. Click "Actions" in the main navigation, and in the left navigation click the "Build" link.
2. Select the desired workflow run in the centre area of the page (based on date and time of the build you wish to use). You can also start a new build from this page by clicking the "Run workflow" button.
3. After clicking the desired workflow run, you should be presented with a section at the bottom of the page called "Artifacts". This section contains the results of your build, in a file called "firmware.zip"
4. Download the firmware zip archive and extract the two .uf2 files. They are named according to which side they need to be flashed to.
5. Flash the firmware to your keyboard by double-clicking the reset button to put the it in bootloader mode. A window should pop up showing the contents of the storage on the keyboard. Drag and drop the correct .uf2 file into the window. When the upload is complete the window will close and the keyboard will exit bootloader mode.
   • If you only changed the keymap file you only need to flash the left side firmware to the left side.
   • If you changed the conf file you should flash both sides their respective files.

Your keyboard is now ready to use.

Footnotes

1. Currently 42 keys because that's what I use, but honestly sometimes I feels like I have a few keys I don't know what to do with; though I often go back to re-adding them when I try removing them, so 🤷. May make it work for other boards in the future, but may not be a priority for a while. No promises. ↩

2. Well, "designed" is perhaps too strong a word. I've haphazardly and painfully iterated over dozens of permutations, gradually removing annoyances / disruptions to my flow. ↩