Learning through failure - a keyboard creation journey


  • Built a custom keyboard cuz I have weirdo nerve pain issues.  
  • Learned a lot cuz I failed a lot.  
  • Maybe 'do it right the first time' is a bad frame of mind.  
  • The keyboard ended up being kinda nifty.  
  • It has lights, and a trackball, and QMK, and it helps my issues.  
  • \o/

(tl;dr is internet lingo that means, too long; didn't read)

Pain as a key ingredient

An old proverb says, 'necessity is the mother of invention', and that is how this story begins.

Over the last few years, age or stress or something has caught up with me and I developed the need to change my human-to-computer interface.  Mousing changed to trackballing.  The traditional keyboard was swapped out for an ergonomic, and then split keyboard.  Complicated multi-finger-and-hand key combinations were replaced by single keypress macros.  And yet more was still needed.

It's often said that change only happens with pain - indeed, the organizations many of us work in seem to apply this as law - and so, unsurprisingly, I seem to work the same way.  There is something to be said for understanding the 'socio' in 'sociotechnical systems', as well as the psychology component of Deming's 'system of profound knowledge'.  And so, with pain girding me, I set out on the next step...the niche of custom ergonomic keyboards. (not covered here...the array of other things being tried in parallel)

Above is one of the last 'as close as it gets' iterations...where we were at before heading down the path of...

Build or buy?

In software development (ok, everywhere...?), there is always a question of discerning when to buy something pre-made, or when it is time to build something yourself.  Wardley maps paint this picture very clearly, illustrating a range of 'idea genesis' (thing entirely non-existent, you must make it) through to 'utility' (it's so ubiquitous that the sudden absence of it is a surprise).  In the case of ergonomics, there is a limited portion of the population that exactly matches your ergonomic dimensions.  In the case of specific ergonomic problems, there is only you.

Now, there are some prebuilt options that are close to what I needed, so the build/buy decision needed weighting.  The rationale for me to go 'build' ended up being 'because I can, because it's less risky, and because we'll end up with a 3D printer for our trouble'.  Cost-wise, it was a gamble, and probably ended up costing a bit more - but risk-wise, it meant that there were no dead ends if something doesn't quite work out.

The major need was to have a split keyboard with integrated trackball, where the trackball could be used from a 'home row' hand position.  There is only one commercial offering that provides this (at the time of this writing), and it uses bespoke closed-source software to customize it.  Given the obvious risks of that path, and that it was almost the cost of the 3D printer alone, we had our decision.

What does it take?

Setting cost aside, there are a number of components in a keyboard.  A picture is perhaps best.

Yes, I know this is butchering the point of Wardley maps.

Clearly there are also a number of special skillsets required...skillsets that can be learned.

  • 3D design work (using the tool, and executing your vision)
  • 3D printing (unfortunately not just as simple as 'send file to printer')
  • Relatively simple electronics and soldering? (I still don't get why some solder joints stopped working)
  • Basic programming and debugging? (in C++?)
  • Tying all together the ergonomic, the physical, the mechanical, the electrical, and the code
Blessed as I am, some things I can do, but the rest I would have to be willing to learn.

Furthermore, there are obviously some resources you need...
  • time (as mentioned, took me over four months)
  • money (the obvious question, how much, is directly tied to your need; similarly, your self-control - anyone suggesting this is a cheap exercise should be asked deeper questions)
  • tools (soldering iron, 3D printer, computer that can run Fusion, multimeter, various hand tools, a place to work on stuff that can occasionally be smelly - see more detail at the bottom of this post)

Design goals

The course of the project led me to add to this list, some things silly, some again by necessity.
  • Split keyboard, columnar key layout (I could never use a non-split keyboard again, disregarding my personal issues)
  • Integral trackball accessible from home row hand position
  • QMK software for customizability, layers, trackball functionality
  • Chassis design that aids troubleshooting, simplifies modelling, speeds prototyping, lowers print costs (time and plastic)
  • Key-well design (i.e. not-flat), 3x6 layout to encourage thumb usage and QMK automation
  • Lots of thumb keys to both maximize 'single key' functionality and reduce pinky usage
  • Per-key RGB LEDs to function as rapid-cue labels, speeding keymap memorization, looking baller
  • Hotswap key switches, re-use Moonlander keycaps (OEM row three size, "piano keys" on the thumbs)
The Moonlander I had grown accustomed to was wonderful, but had too few thumb keys...not to mention no trackball...so it was the baseline.  Replicate the Moonlander, but with more stuff.  This would turn out to be a lot to ask, unsurprisingly.  Anyone interested in split keyboards should strongly consider one as their entrypoint - the Oryx software that you get access to (Oryx is a QMK wrapper in GUI form) does a LOT of heavy lifting.  The whole package they offer is truly an amazing product.

Learning is failing

Learning is hard, a fire that consumes your patience and time - easily extinguished by pride.

That is a box full of prototypes and test shells, plus a pile of 29 broken/suspect PCBs.  (note, the kb has only 57 keys...).  Each shell takes about 24 hours to print.  Each PCB took, once I got the hang of it, about 10 minutes to prep-solder, and then another 5-10 minutes to solder into place.

Then I tried printing out existing examples like this and this and this.  They all were great in their own rights, but didn't quite work for me.  I did learn through what wouldn't work, what might work.
And so, the Fusion360 design work began in earnest.  Sketchup just wouldn't cut it for this project, so I had to learn Fusion, but it came bundled with a whole new paradigm of modeling - parametric, and timeline-based referencing and whatnot.  After much stumbling, while it has latent flaws, I'm mostly comfortable with it, in no small part to folks like this.

jThe design as of this writing looks like this...

It's alive!

Seeing all of the LEDs working and the layers doing their thing and the auto-mouse-layer and the drag-scroll...the QMK folks really have something special here.  There's something about seeing a thing come to life from what the community is doing, your imagination, some software, some plastic, and some code.

A quick run-down of the functionality I use...
  • Default layer - a normal qwerty keymap, like any normal keyboard would have; one button works to toggle drag-scroll on/off; two buttons on the left thumb cluster are tab back/fwd; two buttons on the right thumb cluster are Mac 'spaces' left/right; etc etc etc
  • Mouse layer - the JKL keys become left, middle, and right click; YU are Chrome back/forward buttons
  • Nav layer - triggered by left thumb, right hand suddenly has arrows, pgup/dn, home/end, normal arrows work like alt-arrow
  • Symbols layer - all the letter keys become the symbols on the left hand, and right hand is the numpad; more tab/terminal switching functionality; VS Code multi-line select is one button, etc
  • Drag-scroll toggle - click a button, and the trackball switches to two scroll wheels - vertical on vertical swipes, horizontal on sideways swipes.
  • Mouse layer auto-on - after the trackball moves three "units" the mouse layer is triggered automatically.  After 750ms of inactivity, it reverts to the previous layer.  I continue to play with these settings...but it works just how I want it to most of the time.
  • Per-key RGB, per-layer - so every layer has a corresponding key colour - effectively acts as labels, it's quite effective at helping me memorize the keymap, and adapt to keymap changes. 
It's worth noting that I'm not using tap dance, nor that many layers compared to some.  The great thing about software is that you can add that in later with a few lines of code...

Furthermore, and this made life very easy a number of times...the modular design really was a game changer.  A view from the bottom shows the different components - the key-wells and thumb clusters are independent parts, something like a dozen individual parts.  This shines when you have to print it out, and something goes wrong with one part, or when you want to re-do the key layout, and don't have to reprint the whole lower chassis.  Or, in today's case, you need to tilt the whole keyboard forward, so you just reprint the parts that hold the bottom to the top.

Learning by doing

The project took about four months of solid work - not sacrificing God, my wife, my kids, my family, my day job - to bring to 'revision 1' fruition.  This came about by doing the following in roughly this order...
  • Read the right blog posts at the right time in the right order, discover that this is a solvable problem
  • Figure out what components, printer, etc to order, and where to order them from
  • Order them, discover some stuff is out of stock or can't ship to me, find other suppliers
  • While waiting for things to arrive, start looking at the Dactyl generator code, Fusion360
  • Spend at least a month on F360 before discovering that you've been doing it wrong (parametric)
  • Spend another month re-learning F360, and printing test pieces
  • Start printing shells that are already done, hoping they will work out
    • Narrator: They did not.
  • Discover 3D printing is actually a rabbit hole all its own, spend a month printing almost non-stop to learn the ins and outs
As an example of the iterating, here's the first piece I printed for the keyboard...
  • Give up on your design methodology again, re-do the design entirely so you can spend less time printing.
  • Finally get a design that feels good printed and assembled
    • Protip: "feels good at rest" and "feels good at the end of 10 hours"...these are not the same thing.
  • Spend at least a week creating a wiring diagram, realizing that this is why flexible PCBs are the way you'd ideally go
  • Discover that soldering is very time consuming, spend a week soldering, testing, re-soldering
  • Discover that you have no comprehension of how the source code actually works, get help from the community, only to...
  • Discover that your soldering skills are apparently not electronics-grade, discard almost half of your assembled PCBs and re-do them (thankful you bought extras...right?...right?)
  • Spend hours and hours reading code and adding comments in an effort to understand why your LEDs won't work properly
  • Re-do another handful of PCBs
This became a normal activity...modular design saves the day!
  • Discover that you still don't understand the code/framework - many hours later find out that your non-master half is not lighting up because there is a very tiny 'if slave' block that is missing the RGB function
  • Spend many many many more hours getting the keymaps and layers figured out
  • Accidentally git reset --hard everything you have done because you're a hubris-fueled chump sometimes, and then humbly thank God because in your hubris you did the ol' "keyboard.old" trick into the trash bin, and so you're able to recover from catastrophe, not deserving that kind of grace but getting it anyways.
  • Discover that your entire chassis design is tilted too far up at the back, and you need to reprint basically the whole thing; use scrap wood to tilt it up and make it useable
  • Write a the start of a blog post to procrastinate this next step
  • Replace key switches to deal with finger pain, break another section of LEDs, have to troubleshoot and then reflow solder on one pin of one LED
  • Refactor your design to accommodate the new tilt, reprint the parts
  • Still see issues with the keyboard that need addressing...like the obviously-not-done wrist rests...

How the story ends

Well, this post was an incoherent ramble.

I think a good example of the point of this story is that today, I was able to go from 'zero palm rests' to 'palm rests, check'. (the big white tray thingy)

When all this started, that would have been a week of effort, for sure.

Anyways, even though more changes have to be made, all of the design goals are met.  The success story here is that the trackball integration works just as I'd hoped, and I no longer have to do wrist gymnastics with the Moonlander/Ploopy combination.  It's pretty comfortable, although my "innovative" thumb clusters and arrow cluster might not work out.  Trying to fit the trackball and maintain comfortable thumb clusters is hard.

Something I haven't mentioned is the perseverance required to continually change the thing you interface with to accomplish work.  If need had not been driving me, I'm not certain that I would have followed through.

The flip side is that although learning takes time, and is often frustrating...annnd practice makes perfect might be a bit enthusiastic...day by day, you do get somewhere, or in this case...something.

Further reading

So very much reading was done...all sorts of standing on the shoulders of giants around here.

My very extended build journal (175 pages and counting...): 

My code (very work in progress, very copy-pasta'd from Drashna's OG tractyl manuform): 

Full build logs
Other reference

Suggested tools/parts, further reading...

Not an exhaustive list at all, but just the things I felt needed highlighting to anyone heading down this path.


Popular posts from this blog

Learning Opportunities - Watching/listening list

DFSR - eventid 4312 - replication just won't work