I recently built an Atreus keyboard. This keyboard is an extremely small keyboard with only 42 keys. Below is the photo of my result.

As you can see, it has a split layout and the keys are aligned vertically and staggered. Thanks to using Ergodox keyboards since 2014, I'm very used to this key layout and find it superior to traditional keyboards.

The keyboard is very small. To give you an idea of how small it is, here is a photo of it next to one of my Ergodox keyboards and with a bit of my fingers in the shot.

Building the keyboard was pretty straight forward. The included instructions are thorough and include plenty of photos. All of the components are through-hole so the soldering is not difficult. This would be a good first keyboard project.

I already had USB cable, key switches, key caps, and a micro-controller so I purchased the partial kit from Phil. It came with everything else, except for something to coat the wood, that you need to build the keyboard. I wanted to connect the keyboard to USB C ports, so I used a micro to USB C cable.

I enjoyed the color of the laser cut wood and appreciated the burn marks. I didn't want to lose the color or burns so I coated the wood with a water based clear polyurethane with a satin finish. This was probably the most difficult part of the build, and it was pretty easy, simply because I lack experience finishing wood.

When reading other build logs I noticed that someone else put a zip tie on their USB cable to help prevent it from tugging on the micro-controller. I have no idea how helpful this is but it seemed like a good thing to do so I also did it. To do this you basically just wrap the cable with a zip tie and cram it against the case so that the zip tie prevents tugging on the micro-controller. You can see it in the picture below.

I've only been typing on the keyboard for basically this blog post but I've already found myself adapting to it pretty quickly. I don't intend for it to replace my Ergodox for normal usage but I think it will be a great portable keyboard.

Overall it was a fun project and I'm glad I did it. I look forward to customizing the firmware to make the key layout fit my usage.

Last fall I started to work in an office again. I've used a hand-built Ergodox for years now and really prefer working on it. This meant I needed another ergodox for the office. Luckily, now you don't have to build your own. I bought an Ergodox EZ¹.

The Ergodox EZ uses the QMK firmware. This has a lot of fancier options than the firmware I had been using on my hand-built ergodox.

This mostly didn't matter and I just configured the Ergodox EZ to match my original Ergodox's layout. Then I started a new job and found myself programming in Scala using IntelliJ IDEA.

Shockingly, after not using IntelliJ for years, I still remembered many of the keyboard shortcuts. This was great! Unfortunately, in my years since last using IntelliJ, I created some conflicting keyboard shortcuts for managing my window layout. These were mostly shortcuts that involved holding Command + Alt and pushing an arrow key. Luckily, the QMK firmware supports a Meh key.

What is the Meh key? It is a key that presses Control + Alt + Shift all at the same time.

This is great for setting up shortcuts that don't conflict with ones found in most normal programs. This let me change my window manger shortcuts to use the Meh key and I was then conflict free.

I can't handle having different shortcuts across different machines with the same OS, so I needed to needed to update my original Ergodox to use the QMK firmware so I could also have a Meh key at home. Luckily, the QMK firmware also works on it and, maybe even more luckily, the Ergodox EZ firmware just works with my original Ergodox.

This actually means I can simply take the compiled Ergodox EZ firmware and flash it straight to my Ergodox. Any time I've done this the keyboard keeps working.

Unfortunately, the LEDs in my original Ergodox are mostly hidden by non-translucent keys. These LEDs indicate when I'm not main layer and I find them really useful. I only have a single translucent keycap and would prefer only that LED to be used.

Here are the steps I took to make that change.

1. Use the graphical QMK Configurator to visually configure my keyboard layout. In the Keymap Name field, put jakemcc.
2. Click the Compile button in the above configurator.
3. Download the full source.
4. Unzip the source and edit qmk_firmware/keyboards/ergodox_ez/keymaps/jakemcc/keymap.c to include snippet of code below this list.
5. In qmk_firmware run make ergodox_ez:jakemcc.
6. Find ergodox_ez_jakemcc.hex and flash my original Ergodox.

uint32_t layer_state_set_user(uint32_t state) {
  if (biton32(state) == 0) {
    ergodox_right_led_1_off();
  } else {
    ergodox_right_led_1_on();
  }
  return state;
}

This snippet gets added to the bottom of the keymap.c. It only turns on led 1, which is the one under my translucent key, whenever my keyboard isn't on layer 0.

Now, I can use the fancy Meh key to be conflict free and easily tell when I'm not on my main layer. This is wonderful.

1. I bought one with Cherry MX Clear switches. I've since switched them to Cherry MX Browns. The clears were too firm for me. I did not get Cherry MX Blues because I didn't want my fellow coworkers to be annoyed by the glorious clickty-clack of those switches.↩

The ErgoDox is a great keyboard. One its appeals is that you can build your own firmware. This makes it possible to rearrange the keys however you want and tweak other functionality. The firmware is fairly advanced and allows you to have multiple layers to your keyboard.

Multiple layers allow the ErgoDox to have fewer physical keys than traditional keyboards. How often do you use an F key? If you are like me the answer is almost never. Why bother having a dedicated key?

Another benefit of multiple layers is that your keyboard is multiple keyboards in one. Do you use the Dvorak layout and your roommate use Qwerty? Program both a Dvorak layer and a Qwerty layer into your keyboard and switch between them with the push of a button.

The only downside I've noticed of multiple layers is that I'll switch between them by accident. This is frustrating as all of a sudden your keyboard works differently and there is no indication that you are on a different layer.

The ErgoDox has a few LEDs in it that I have never used. I don't even have the needed keys as part of my keyboard layout (Caps lock? Who uses caps lock? I don't need to shout that often). I decided to repurpose the num lock LED as an indicator that I'm off the main layer.

This was a straight forward change. In the firmware there is a variable that holds what keyboard layer is active. All I had to do to get the num lock LED on when I changed layers was to move the layers_head variable higher in main.c and then change the conditional to turn on the num lock LED when layers_head != 0. This is the commit that does this change. It could have been done as a three line change.

I highly recommend making this change. Now I just need to find a transparent DSA keycaps so I can see the LED easier.

Earlier this year I built an ErgoDox. The ErgoDox is a split hand mechanical keyboard whose design has been released under the GNU GPLv3. There are a few standard ¹ ways of getting the parts. It basically comes down to sourcing all the parts yourself or buying a bundle from Massdrop. I opted to wait until Massdrop was selling them and bought a kit from them.

Why?

1. I've used an ergonomic keyboard for years and was intrigued by the split hand design.
2. I wanted to try out Cherry MX key switches.
3. Using your thumb for more than just space bar made a lot of sense to me.
4. The firmware lets you have multiple layers. I thought this could be really useful.
5. The project sounded fun. I used to make physical devices and this seemed like a good way to do that again.

Buying

As mentioned earlier I bought my parts from Massdrop. In the buy I participated in I had the option of a full hand case or the traditional case and I opted for the full hand. As part of the buy I also bought additional aluminum top layers, a blank set of DSA ² keycaps, and Cherry MX blue key switches.

If I were doing it again I would not buy the extra aluminum top layer. I built one of my hands using the aluminum and the other with the basic acrylic top. I enjoy both the look and feel of the acrylic hand better.

I would also not buy the set of DSA keycaps from Massdrop. It was convenient and a bit cheaper to buy from them but had I known I could get different colors from Signature Plastics I would have done that.

I also bought eight "deep-dish" DSA keys direct from Signature Plastics. These keys feel different which lets me know when my fingers are above the home row. I'd recommend doing this. You can order from this page.

For key switches I bought Cherry MX Blues through Massdrop. Blues are extremely clicky. You can easily hear me typing in every room of my apartment. It is very satisfying.

After using the keyboard for about a week I also ended up buying some pads for my wrists. I occasionally rest my wrists on the keyboard and the keyboard's edge would dig into me.

Building

I followed Massdrop's step-by-step guide and this YouTube video. Another great resource is the community at GeekHack. I'd recommend reading and watching as much as possible before starting your build.

I built this using a cheap soldering iron I've had for years, very thin solder, solder wick, and a multimeter. I don't know if this would have been easier with better tools or not but those got the job done.

While soldering the surface mount diodes I was in the zone and soldered a few locations that didn't actually need to be soldered. When you are soldering the diodes you should only be soldering them to the locations that have the key silk screen.

My system for minimizing errors while soldering the diodes is the following five steps.

1. Lay down some solder on one of the pads.
2. Put the correct end of the diode on top of that solder, reheat and push down.
3. Test the connection with a multimeter.
4. Solder the other half of the diode.
5. Test the connection.

I batched up the steps. I'd do a whole row of the first step, then move to the second for the entire row, then do the third, etc. Being rigorous about testing every connection is important. Catching mistakes early makes it easier to fix the mistakes.

If you solder a diode on the wrong way there is a huge difference (at least for me using solder wick) between the difficulty of fixing the error when only one pad has been soldered versus two pads. I soldered more than one diode backwards and a mistake noticed after soldering only one pad was easy to fix. After soldering both pads it took serious effort.

Eventually you'll need to cut open a USB cable. I ended up removing the plastic housing using a Dremel. When soldering the wires to the USB holes I was too concerned with it looking pretty and did not leave plenty of wire. This made it harder to solder and as a result I ended up doing a poor job that resulted in a short. After desoldering and destroying another cable, but leaving more wire, I managed to do a better job. I originally noticed the short because I kept getting warnings from my computer about my USB Keyboard drawing too much power.

I've annotated a copy of Massdrop's instructions using Evernote. It contains the above tips inline.

Firmware

After you physically build your keyboard you need to build the firmware. There are a few different firmwares that can work and you can discover those on GeekHack. I'm using a fork of what Massdrop's graphical configuration tool uses. It is based off benblazak/ergodox-firmware.

One of the exciting things about the ErgoDox is tweaking the firmware. I took the base firmware and modified it to have media key support and light up the LEDs when I'm on any layer besides the base. Some people have added the ability to record keyboard macros and other neat features. I encourage you to take a look at the source even if you use the graphical configuration tool. I haven't explored beyond benblazak/ergodox-firmware so I can't compare it to other firmwares.

Conclusion

I really enjoy it. Building it was both fun and frustrating ³.

After using the keyboard for a few months I've found that I really only use three (on each hand) of the thumb cluster keys. I also don't use the keyboard layers too often. I have three layers programmed and I always stay on the main one unless I want to hit a media key.

Would I recommend building your own ErgoDox? If you already can or are willing to learn to solder and this sounds at all interesting to you I would recommend it. The project can be frustrating but the result is great.

The Future

There is still a lot left to explore in the custom keyboard space. Even so I have no plans on leaving the ErgoDox anytime soon. In terms of improving my ErgoDox, I plan on poking around the different firmwares at some point. I'd also like to explore tenting options.

Resources

• GeekHack ErgoDox thread
• GeekHack FAQ Useful for general information about keyboard topics.
• GeekHack Cherry actuation forces
• Massdrop Buy
• Massdrop Configuration Tool
• benblazak/ergodox-firmware
• TMK firmware for ErgoDox One of the alternative firmwares.

1. I feel a bit odd using the word standard to describe acquiring parts to build a keyboard.↩

2. This page has diagrams that shows the different keycap families.↩

3. Those surface mount diodes are so tiny.↩