Graphite Keyboard Layout

I’ve been using the Gallium keyboard layout for a couple of months now, and I’m pretty happy with it for typing letters. However, I’ve been curious whether I could do any better in terms of punctuation. This has led me to investigate the Graphite layout to see what I might be missing out on.

Why I Care

The Graphite layout is very similar to Gallium, but has some optimisations concerning punctuation. I’ve been keen to try it out, but something has been holding me back. To understand, let’s take a look at Graphite mapped to a \(6 \times 4\) split keyboard like the ZSA Voyager:

1
2
3
4
5
6
7
8
9

  ! @ # $ %  ^ & * ( ) +
~ B L D W Z  _ F O U J :
| N R T S G  Y H A E I ?
  Q X M C V  K P > " <

  1 2 3 4 5  6 7 8 9 0 =
` b l d w z  ' f o u j ;
\ n r t s g  y h a e i ,
  q x m c v  k p . - /

The top four rows show the shifted versions of the keys, whereas the bottom four rows shows the regular unshifed layout. Some things to note are that some of the shifted punctuation keys are different to what you normally get on a standard keyboard layout. For example,

• a shifted hyphen (-) gives a double quote ("), not an underscore (_).
• a shifted apostrophe (') gives an underscore (_), not a double quote (")
• a shifted slash (/) gives a less-than sign (<), not a question mark (?)

There are also a couple of other tweaks that interested me, such as moving the C and V to the more easily reachable bottom row, and putting D, W and : (from my Symbol layer) closer together for some more convenient Vim shortcuts.

The creator of the Gallium layout explains in the Graphite GitHub Repository the rationale behind splitting the normal association between shifted and unshifted punctuation characters, but in short it comes down to avoiding some common Single Finger Bigrams (SFBs) involving punctuation characters. It sounds great in theory, but can create some difficulties in the implementation. While I had no problems to implement this layout on my Corne keyboard running Vial/QMK, it was a different story for my ZSA Voyager which has become my daily driver.

The issue was that keyboards don’t send characters; they send scancodes. If for example you press shift and /, the keyboard will send the scancodes for those two keys. It is then up to the keyboard logic in your computer’s operating system to put those two scancodes together and make the decision to send a ? character to the running application – the keyboard gets no say in this.

So, if you want this logic to be handled by your keyboard so that when you press shift and / your application sees a < character, your keyboard needs to detect when you press shift and /, and then ’lie’ to your computer by sending the scancodes for the shift and , (comma) keys so that the OS sends your application a < character. The feature in QMK which allows your keyboard to lie in such a manner is called Key Overrides . This feature is easily configured on a keyboard running QMK Vial (like my Corne), but it is unfortunately not supported by ZSA’s Oryx web configutation tool. I wanted to keep all my keyboard layouts as consistent as possible, and I wanted to continue using the Oryx configuration tool, so I was hesitant to move to Graphite. However, a small ray of hope soon arrived in my email inbox…

A Glimmer of Hope from ZSA

As a ZSA customer, I receive from them a regular newsletter from them, which led me to an article with the title “Using a DIY tool to add custom features to your Oryx layout ”. This sounded just like what I was waiting for!

The concept is that you maintain the majority of your layout using the Oryx web configutator. However, if you want to enable an additional “unsupported” feature – like, say, key overrides – you take the QMK code generated by Oryx and merge in your desired changes into the keymap code. The author of the article provides instructions and scripts that help to automate this process. I had previously built custom QMK firmware for my Corne keyboards with no issues, so I was keen to give this a try.

I followed the instructions in the article and soon had a customised build of my Oryx layout with the required key overrides enabled and configured. I flashed the new firmware to my Voyager, and it sprung back to life… until I pressed a key, that is. The keyboard froze! The firmware would initiase, but it would crash as soon as I tried to type something. I experimented, thinking I may have messed up the key override code, but it would crash even when I didn’t make any changes to the base Oryx code. There could be an issue with the build scripts/tools supplied by the author of the article, but I didn’t have time to try to debug it and instead decided to stick with the Gallium layout that was already serving me quite well.

A New Way Forward (aka “Tap Dancing” around the problem)

I continued to use my Gallium layout, writing lesson notes for my students in \(\LaTeX\), and I wondered how the Graphite layout would perhaps make it easier to type all that \(\LaTeX\) code. A new idea started to form: what if, instead of messing around with shifted punctuation, I used the “tap dance” feature to implement the required key mappings for my punctuation? This would be similar to the “Auto Caps” feature where you hold down a key to get its shifted version. Tap-dance has the flexibility to output whatever scancode(s) you like when you hold down a key. An added benefit is that I can still use the

This was very easy to implement using the Oryx tool, and doesn’t require the use of and unsupported/untested features that could mess with the stability of my keyboard. I applied the needed changes to my Oryx layout, and you can inspect it using the following Oryx link .

I’m going to perservere with this new layout for a while, and I’ll report back here how it goes!