Instantly share code, notes, and snippets.

What would you like to do?
Reflections on my ErgoDox keyboard

My ErgoDox Keyboard

I spent a lot of money ($236) on a computer keyboard. A computer keyboard that you can only buy a couple times per year, that you can't purchase in any store, which took three months to arrive after I placed the order, that I had to painstakingly solder together myself.

The design is called the ErgoDox. has periodic group-buying events where they solicit buyers for all the parts, as a cost savings measure. If you were to order in small quantities through electrionics retailers like or to build for yourself a single keyboard, the cost could be above $500.

I had been noodling around for a while on my own design for "the perfect keyboard" with very slow success, as I have very little experience with electronics. But, thanks to the recent "maker" movement the field of printed circuit board manufacturing is becoming more accessible to hobbyists, so I was giving it a go. Despite not getting very far into a design, I still managed to take down lots of notes about what I thought the "perfect" keyboard should, and should not, contain.

Then I stumbled over the ErgoDox, which was very close to being perfect, and was immediately available. So I snapped one up, along with tools to assemble it. I'm still training myself to type on it faster but so far I'm very happy with my purchase.

What's perfect about the Ergodox?

These are the killer features of the ErgoDox, which no commercially-manufactured keyboard available today replicates. If you want to make something as great as the ErgoDox, you won't succeed without copying these features first. On the other hand, these features get you half-way there: a less-perfect but cheaper keyboard that incorporates these features might have swayed my purchasing decision.

Fully programmable

The ErgoDox is fully programmable. Not just key macros, not just changing the letter layout around. The microprocessor that the ErgoDox uses to translate keypresses into signals that your computer understands is an ATMEGA32U4, very similar to the general-purpose one used in the Arduino hobbyist electronics platform. You can literally write some C code using the Arduino software or a text editor on Linux, compile, and load it into the chip to precisely specify everything it does. The daughter-board containing the microchip is an off-the-shelf $16 Teensy 2.0. Since that miniature board is used in many applications besides this keyboard, it is very easy to find information about communicating with it.

I can configure the keyboard to dim and illuminate the LEDs however I like. I can put modifier keys wherever I like. I can have as many Fn keys as I like, or different flavors of Fn key.

Open Hardware, Open Source

The source code for the default Ergodox firmware is available on GitHub. If I want to tweak how it works, I don't have to start from scratch. I can make a little change and experiment. I can learn everything about how it works; nothing is secret.

The original hardware designs are available as well, for both the case and the circuit board.

  • If I want in the future to replace the layered-acrylic case with a 3D-printed one that I design myself, I don't have to spend ages tediously measuring the dimensions of the circuit board.
  • If I want to in the future create something similar to the ErgoDox but with fewer keys or keys in different physical position, I can base my work on the original designs without fear of being sued.
  • If I spill coffee in it and fry its microcontroller 10 years from now after the ATMEGA32U4 has long been replaced, I (or anyone) can modify the design to use a new chip and repair it.

Problems with other keyboards

There are a lot of other fancy (and less expensive) computer keyboards on the market. Why not use one of those? Why is the ErgoDox superior?

Dead Fn-combination keys

As a Linux user, I have almost complete control over my keyboard layout. I can ask Linux to map any key symbol or function to any scancode sent to the computer by the keyboard. This lets me rearrange keys however I want, change where the modifier keys are, and what they do. However, there's lots of keyboard hardware out there that confounds my efforts to design a "perfect" layout. For example:

To save space, the Happy Hacking Keyboard Lite II places Page Up, Page Down, Home, and End on the Fn-triggered level of the inverted-T arrow keys, in the most intuitive way. I have become very used to this. It's not labeled, but the same combination works on modern Apple keyboards as well. The Lenovo x230 and Fujitsu u904 laptops, however, place those functions elsewhere, sometimes in very far-away and unintuitive places.

I would like to ask Linux to simply assign PgUp/PgDn/Home/End to Fn+arrow combinations on those laptops to get the same layout as on my HHKBl2, but I can't. No Fn+(arrow key) combination on those machines produces a scancode at all! There are only a select few arbitrary keys for which the Fn key does anything. To make matters worse, on the Lenovo, one or two of those Fn key combinations produces not one but several scancodes for a single keypress! The result is that there exists no way, even with the most configurable operating system in existence, to build a keyboard arrangement on those machines that is not annoying.

In my perfect keyboard, every key combination would generate a scancode, so I would not be restricted in how I configure my operating system to interpret keypresses. Since I have full control over the software running inside the ErgoDox, I can make that happen.

Thus, I can set up the ErgoDox to be a strange-looking but familiar QWERTY layout, that when used with my Linux keyboard configuration, have every character and symbol exactly where I want it.

I have never found a commercially-manufactured keyboard which gives users write-access to its main microcontroller the way the ErgoDox does, even among expensive "hacker" and "gamer" keyboards with mechanical switches. Without that feature, I'm stuck with whatever decisions the manufacturer makes about where the Fn key should go, which keys it should affect, and what those effects should be.

Too many keys

I don't want a lot of keys. Many of the keys on most of my keyboards go completely unused. How often do I use Pause/Break? F12? I don't want to strain my fingers reaching for keys, or slow myself down by moving my hands away from center. I don't mind learning chord-combinations to accomplish those goals.

The ErgoDox has 72 keys in total, which is fewer than most keyboards have. In comparison, my HHKBL2 is a "60% Keyboard" with only 65 keys.

To reach some of the keys on the ErgoDox I still have to abandon the home-row. I'd prefer a less expensive, more compact keyboard that has even fewer keys, but that's a minor critique compared to everything the ErgoDox gets right. Since it is so configurable, I could simply let those hard-to-reach keys go unused and configure the other keys to work the way I want with chording. With that in mind this complaint is only about the potential price and size difference a "60%" flavor of the ErgoDox might make.

Bizarre key arrangements

Some keyboard manufacturers create keyboards with fewer keys, but in order to keep functions like PgUp/PgDn on a dedicated unshifted key or a set of inverted-T arrow keys they will squish keys together into nonstandard shapes or a strange arrangement. Things that particularly bother me:

  • A tiny (1x1) shift key to make room for the up-arrow of an inverted-t arrow keys set
  • Nonstandard-height keys like the half-height arrows on the HHKB Lite 2
  • An extra column of navigation keys to the right of the enter/shift keys

All the keys on the Ergodox are uniformly 1x1, 1x1.5 or 1x2 standard key-widths. If the original manufacturer stops producing keycaps, or if I simply feel like replacing some, I don't have to get an expensive one-off custom order the way I would if I wanted to replace the Happy Hacking's arrow-key caps.

All the modifier-keys (like shift) along the far edge of the ErgoDox are wide, so they can be more easily struck by the pinkie finger while chording, as they should be. Any other arrangement decisions are moot, since the board is so configurable I can set keys where I like them.

Squishy keys

I want mechanical keyswitches with crisp tactile feedback, like the original IBM model M had.

Fortunately, in recent years more people are demanding quality mechanical keyswitches and several keyboard manufacturers have actually taken notice. One keyboard manufacturer who holds the original IBM Model M keyboard patent still produces them, but many others design keyboards using individual mechanical keyswitches. Cherry MX keyswitches are one such model that has gained notoriety for quality.

Unfortunately, most commercial keyboard manufacturers target either small or mechanical. Only since around 2012 have I noticed some rare keyboards that have both a comparatively small number of keys, and offer mechanical keyswitches. (And they still suffer from the dead Fn-keys problem.)

The ErgoDox may be ordered with your choice of flavor of Cherry MX mechanical keyswitches. I ordered mine with silent tactile feedback Cherry MX Clear switches, but I have a stockpile of "clicky" tactile feedback Cherry MX Blues that I could swap in, if I should decide that I prefer them.

As a bonus, Cherry MX keyswitches have become popular enough that many keycap manufacturers design their product to fit them; if I decide I don't like the material, color, or markings on my keycaps, I can swap them out for any of the many others made for the Cherry MX switch.

(I had a set of P.I. Engineering X-Keys caps which I used for a while on my ErgoDox before deciding that I didn't like them as much as the set that the ErgoDox kit came with.)

The ErgoDox kit comes with a keycap-removal tool, which was a very nice and welcome addition.

Chained at the wrist

I don't touch-type, at least not in the "correct" way. I can type at a decent clip without looking at the keys but I don't use the home-row; I've just gradually over 15 years of typing become familiar enough to do it. Unfortunately my typing speed is hampered by a large number of mis-strokes, and I sometimes wonder if maybe I should teach myself how to touch-type properly.

However, there's no way I'm going to start training myself to touch-type without an ergonomic keyboard, otherwise I'll end up destroying my wrists with carpal tunnel syndrome in no time. I'm indignant that almost all keyboards are necessarily one unit, prohibiting me from separating my hands and placing them wherever I feel most comfortable. So, if I'm going to the trouble to design a perfect keyboard, it has to be a "split" board that are two independently-positionable half-keyboards. Fortunately the ErgoDox is just that.

I'm still unsure about this home-row thing. I've given it a try and even with the ErgoDox, forcing my hands to return to home row after every keypress, and forcing myself to restrict certain fingers to certain columns of keys feels dangerously uncomfortable. I suspect the vertical key offsets per-finger are not quite enough for my hands. I might just train myself up on the new layout using a modified "home" that allows my hand to be more flat when at rest.

What I would change

The ErgoDox is nearly perfect, and none of my critiques are severe enough for me to even moderately dislike it. But, here they are:

No published parts list

I had some trouble figuring out which parts to buy if I need to replace one of the bolts that hold the acrylic case together. It would be nice if this information was published somewhere on the web.

No included key-leveling hardware

Wide keys can feel "wobbily." Your space bar probably has an additional key-leveling mechanism underneath it to make it so that when you strike the very edge, it does not tilt, but instead moves straight down without sticking.

The ErgoDox is fully functional without key leveling hardware on its wide keys. It's only barely noticeable. But I notice it, and I'm concerned about the stress a torquing key puts on my amateurly-soldered connection between the keyswitch and the circuit board.

There exist two different types of key leveling mechanisms for Cherry MX keycaps that I know of, but the ErgoDox kit includes neither, and is only compatible with the "Costar"-manufactured variant. (I already had a set of the Cherry-manufactured variant, so I previously thought the ErgoDox supported no key leveling mechanisms at all.) Fortunately, a set of Costar key leveling mechanisms for Cherry MX keys can be obtained for a few bucks at

Unfortunately, the Costar key leveling hardware is not a perfect fit; they do not snap securely into place. Fortunately, this problem is solved with a drop of glue.

No backlight, opaque caps, fixed LED placement

I enjoy a backlight on my keyboard, so if I have to abandon home-row while working in the dark I can find my way back quickly. Also it's not always easy to find a symbol like ^ & or * on the number-row, on the first try, in the dark, for this non-touch-typist.

When I was designing my own keyboard, I figured, well if I'm spending all this time, I might as well go all-out. I tried to figure out how to put not just an LED behind every key, but an individually-addressable RGB LED under every key, so the keyboard could become a fancy light-show or a highly flexible notification system. With a sunk cost this large, it would be delightful to include some "bling" for my time and effort.

The ErgoDox has only the standard three LEDs, in standard red, for Num Lock, Caps Lock, and Scroll Lock. The uselessness of those indicators doesn't bother me since I can configure the LEDs to do whatever I like. But they are positioned under three specific keys and unless I manufacture my own printed circuit board, can't be attached anywhere else. In addition, the default keycaps that come with the ErgoDox kits are opaque black, so you can't really even see the LEDs without drilling a hole in the caps or something.

So, even without going crazy with eye-candy, I would have liked it if the design allowed the builder to choose to put the LEDs near the top of the board, and not under keycaps which might be opaque.

I suspect there are unused I/O pins on the Teensy++; if there are enough, a modified circuit board design could support a 7-segment LED digit, without increasing the manufacturing cost of the board. (TODO: investigate this.) You could probably do something even more advanced by connecting a 7-segment display with backpack to the I2C bus, if there's enough bandwidth to do both that and the matrix scanning.

On the other hand: a big motivation of mine is to learn to touch-type on a weird and different layout like Dvorak, Colemak, or Workman, so I shouldn't be looking at the keyboard anyway.

The case could be more clever

The case for the Ergodox is five layers of clear laser-cut acrylic, bound together by seven small somewhat loose-fitting nuts and bolts per hand. It makes for a nice showing-off-the-guts of the keyboard and is probably one of the most inexpensive and straightforward ways to manufacture a case in these quantities, but there are some improvements that could be made, without even abandoning the medium of laser-cut acrylic.

As I mentioned, the fasteners provided in my kit are slightly too long and the nuts are capped so you can't screw them down until they are tight. This is an easy fix: include uncapped nuts instead, so they may be tightened securely. For those who have already made a purchase: these are metric M3 machine screws. #6 screws will not fit the case holes. I used a pair of #6 lock washers on each screw to tighten the fit, which works well. (In fact, lock washers are probably a good idea even with uncapped nuts, to prevent them from loosening after thousands of keystrokes.)

If we consider different case designs there may be even better ways to improve the case:

This acrylic stand is one example of a mechanism to hold a nut in place while a bolt secures pieces of acrylic. Employing perpendicular pieces of acrylic could eliminate some of the play still aparrent in the layers. But my favorite example is the genius Adafruit Pi Box, an enclosure for a Raspberry Pi which takes advantage of the flexible tolerances of acrylic to produce a box which needs no metal hardware at all! Wow! A set of six plates of acrylic just snap together with no tools.

I imagine that it should be possible to make an ErgoDox enclosure that needs no screws to hold together, includes standoffs for an adjustable incline, will not wiggle, all while using less material (reducing manufacturing costs.)

On the other hand, the design is open hardware. If I'm so damn clever, I should just design that case and submit a pull request for the benefit of the community. As it should be!

The acrylic case included with the ErgoDox includes two somewhat large pieces of scrap acrylic. I assume this was included to provide strength during shipping to the case layer from which it was cut. Recently I've found that these two scraps, propped haphazardly like ramps against the edge of the keyboard, make for rather comfortable makeshift wrist-rests. It would only take a few more hits with the acrylic-cutting laser to transform these pieces of scrap into a sturdy, attractive, snap-together, removable wrist rest, that matches the case, at no additional materials cost. Another design on my to-do list to create and submit.

Why an OS-level layout customization?

I can configure the keys on the ErgoDox to produce whichever scancodes I like, so why stick to QWERTY and make the layout modifications in the OS?

I hate CamelCaseVariableNames and I hate underscore_separated_variable_names. For URLs, I much prefer urls-with-dashes to urls_with_underscores even though the latter is easier to read. I suspect that the reason behind these preferences is the slow tedium involved in typing them. Using the shift key so many times within a single word dramatically slows down typing speed. If I made underscore an unshifted character on my keyboard, would my preferences change?

Starting from that question, I began to think that maybe the top row of number keys was not as useful, as, say, unshifted punctuation characters frequently used when programming. In order to achieve that, I need to dictate that, for example, the shifted version of the dash key should be something other than the underscore character. Keyboards have little control over this mapping; it's all in the OS.

(Technically, if I were forced to use a toy OS that did not let you make these configuration changes, I could set up the ErgoDox to silently insert fake "shift" keypresses when needed, in order to create the layout I prefer. That's great but the possibility of a shift key occuring where I don't want it or don't expect it seems complex. Maybe I should work on that design, so that I might plug my keyboard into any computer configured for a standard QWERTY-US keyboard and immediately have my preferred layout.)

By the way, I'm not the only one in my house very emotionally invested in their keyboard. My wife won't use any keyboard other than the microscopic 9"x3" Sanwa SKB-SL10SV. Its keys are 33% physically smaller than standard keyboard keys, which she finds more comfortable to use than a standard-sized keyboard.


This comment has been minimized.

mattmanning commented Feb 11, 2014

Nice write up. I just built mine and I'm really enjoying it so far. Here's a parts list, fwiw:


This comment has been minimized.

ezmac commented Jul 11, 2014

If you're still using the massdrop configurator, try the TMK firmware. There's no configurator for it, but it will let you have symbols like )$}(+!@ on a single keystroke. I've done something similar with mine.
On layer 1 FN14 keys reference the same key in layer 2 and send that key shifted. You could modify it to shift layer 0's numbers unless shift was already held to reverse the shift on your number keys.


This comment has been minimized.

nclundsten commented Feb 15, 2016

Thanks for this, i program from home and am trying to fix some of my not-so-ergonomic ways.. especially hoping to replace my "standard" mechanical keyboard which puts my arms in that terrible "/" configuration

do you have each half placed at the end of your chairs arm wrests so that your arms are more comfortable? if so, how is this working for you?


This comment has been minimized.

alexjj commented Mar 20, 2016

Nice write up. I just got my ergodox, the EZ prebuilt version. It highlighted my terrible hand and fingering/typing technique pretty quickly. I'm keen to fix it though.

The hardest part is figuring out what keys I want where! I like the idea of hyper/multi-press keys for shortcuts. eg. sending ctrl+shift+alt+super with one key, helps prevent conflicts but saves my fingers.


This comment has been minimized.

cStuartHardwick commented Jul 20, 2016

If you care enough to buy and assemble an ErgoDox, you really should learn to touchtype. You don't "Always go back to the home row" except while learning. You just maintain awareness of where the home row is. I BIG part of touchtyping is learning to type common words and word parts and autocenter on the home row in preparation for what comes next. But when typing, you look ahead and move one hand while the other is setting it up with, say, the previous word or prefix. The better you are, the less you think consciously about the home row, but you always return to it when pausing and resuming.

You sound like me, in that you basically know how to touch type, but can benefit tremendously from a little methodical review. I highly recommend this tool, which is free. I'll warn you though, resist going too fast. This tool uses statistics to assess which keys you need to work on an when you are ready to move on. It works really well if you try to type accurately at an even, consistent rate, but you'll never make it though trying to type at max speed and blow past the errors.

I learned to type many years ago and decided to use this tool to brush up and break old habits before using my ErgoDox with blank keys. Works like a charm.


This comment has been minimized.

cStuartHardwick commented Jul 25, 2016

I can verify what others have said. The ErgoDoc thumb cluster is to far away. I'm six foot one and can only reach the two larger (and innermost) thumb keys without stretching if I place the keypads just so. The Kinesis is much better in this regard.

Incidentally, I mapped my ErgoDox to emulate the Kinesis so I can touchtype on blank keycaps. You can read about it and link to my ErgoDoc config here if interested.


This comment has been minimized.

kevinduffey commented Mar 24, 2017

A bit late to the party.. but if you read this..and havent seen the Model 01 yet.. you owe it to yourself to check it out. 2 piece split keyboard, more powerful processor (or similar..cant remember), fully programmable including multiple layers with shift/lock key capabilities as well as key combos, backllit LED, mechanical, and built in a wood keyboard frame, with tilt/tent options and more. A bit more in cost than the Ergo Dox, but by far the most beautiful keyboard youll find.


This comment has been minimized.

falbatech commented Jan 10, 2018

Custom mechanical keyboard: ErgoDox, Atreus and GH60 is available here: (Europe)


This comment has been minimized.

niico100 commented Nov 6, 2018

Backlit keys now available for preorder on Ergodox EZ.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment