Introduction: ErgoDox Mechanical Keyboard

About: Programming and building things since I was 13. Love to learn new things.

The ErgoDox keyboard is a split, mechanical and programmable keyboard. It is fully open-source so, all you need to build it is buy the parts and dedicate the time.

I work as a software engineer and am always looking for ways to improve my productivity and make my typing easier. I actually first heard about this when the "ErgoDox EZ" kickstarter project came out. I was interested, but didn't want to spend ~$300 for a keyboard, and I thought it could be a really good project to build on my own.

It was the first time for me using a laser cutter, so that was fun. :)

After a few weeks of using it, I almost gave up - actually gave up for a while, but then decided to give it another go, and now I love it! The learning curve is definitely steep and that can be really frustrating, but once you get used to it, you'll love it!

I strongly recommend you first read the whole instructable, and view all the images. Make sure you have all the pieces and understand what you need to do. It will help you along the way.


(If you're looking for a video of someone building this same keyboard, so you can actually see how the steps are done, then take a look at this. I used it, and it helped me a lot)

Step 1: Gathering Parts

The keyboard is built from the PCB (printed circuit boards), some small electronic components, switches, keycaps and the case. All the parts except for the case can be ordered online and I will list them here.
The case can be made from multiple acrylic sheets cut with a laser cutter, or could be printed with a 3d printer. I did the laser cutting, since I figured it will take less time and more importantly, I think it looks cooler!

  • PCB's (two - one for each hand) - link
  • 76x 5-pin mechanical key switches - You can get which ever one's you like. Cherry MX are the most popular I think among mechanical keyboard enthusiasts, but I found that Gateron are much cheaper and almost similar in quality. I got them on aliexpress. - link
  • 76x keycaps - I think it's important you don't just get any keycaps, but a set that's built for the ergodox layout, since each keycap has a slight angle, and when you assemble them correctly it curves in a specific way.
    I found mine on ebay, but I can't find the link now. I found the same thing on amazon (I hope it's exactly what I have). link
  • Teensy USB board 2.0 - link
    (The one in the link has the pins attached already. If you get it without the pins, then you'll just need to solder them yourself)
  • Various Electronic Components (I bought them all on DigiKey, but you can find them on other sites, like ebay or aliexpress as well)
    • MCP23018-E/SP I/O expander (This specific part I could only find on DigiKey or Arrow)
    • 2 x 2.2k Ω resistors ("red red red" band colors)
    • 3 x 220 Ω resistors (for the LED's)
    • 3 x LED's
    • 76 x 1N4148 diodes - I got the surface mount ones (SOD-123) but in hindsight I should've gotten the 'through hole' ones. I read online that they also fit in the case, and they're much easier to solder.
    • 1 x 0.1 µF ceramic capacitor (The capacitor should be marked with "104")
    • 1 x USB mini B connector WM17115
    • 1 x USB mini B plug with short cable (You can take an old USB mini B cable you have from any old gadget or device you have laying around - you'll destroy the cable for this, so make sure you don't need it)
    • 2 x 3.5mm TRRS sockets - These are basically headphone sockets, but you need to make sure they're the ones with 4 connections and not 3 like many headphones have.
    • some jumper cables (or you can use what you clipped off from the resistors after soldering)
  • The case - For the case, you'll need a few acrylic sheets. Each side is made from 5 layers. The top and bottom layers are 3mm thick, and the 3 layers in the middle are 4mm thick.
  • m3 x 20mm bolts - You'll need quite a few. This is for closing the case. link

Disclaimer: Some of the links have affiliate tags, which means I might earn a little if you buy them from this link. I don't work for any of those companies, and don't make a living from these links. It just took me a few hours to write this article, so it would be cool to get just a bit in return for it. Also, it has no effect on the price for you.

Step 2: Soldering the Diodes

You need to solder a single diode for each button on the keyboard. This part took me the longest (mostly because I got the surface mount diodes which I never soldered before), which is about 3-4 hours soldering.

Each button on the PCB is marked by four corners of a square, and on one of the sides of the square you'll notice two holes, one surrounded by a circle, and the other surrounded by a square. This is where you solder the diode.

Before soldering the diodes there are two very important things you should notice:

  1. The diodes are soldered on the bottom side of the PCB (So you can place the switches on the top side). This means that for the right side pcb, you solder on the side that says "Left Hand" and for the left side pcb, you solder on the side that says "Right Hand".
  2. You need to make sure you solder them in the right direction! Diodes are meant to only allow current to flow in one direction, so soldering them in the wrong way means the buttons won't work.

    How do you know which way to solder them?
    One side of the diode is called a "Cathode" and the other is called "Anode" -
    If you got the "through hole" diodes then the cathode is marked with a black ring around it. (The anode side is an orange-reddish color).
    If you got the surface mount (like I did), then the cathode is marked with a very light white line closer to one of the sides. This is really hard to see sometimes, and might require good lighting and a magnifying glass.
    (You can read more about diodes here)

Another tip: If you got the surface mount diodes, make sure to use thin solder. I used 0.3mm and I think it was a good choice.

Step 3: Soldering the Other Electronic Components - Right Hand Side

Take the "Right Hand" PCB and place it on the table so you see the text "Right Hand" (Your diodes should now be on the bottom of the PCB).

Now, solder these components:

  1. Solder the Teensy 2.0 in the top right corner of the PCB. You should see holes that match the teensy chip exactly, and you'll just need to make sure the mini-usb port of the chip is pointing towards the center of the PCB (or pointing left), and the reset button on the teensy is pointing towards the outer part, or to the right side.
    (If you ordered the teensy without the legs attached, then you'll need to solder them on first.)
  2. Soldering the resistors - You have 5 resistors to solder on this side. Three 220 ohm resistors in each spot that has the word "LED" printed under it (LEDa, LEDb, LEDc). Two more 2.2k ohm resistors in the spots marked 2.2k
  3. Solder the headphone jack - This is on the left upper corner of the PCB. The pins on the headphone jack should fit exactly in the pcb holes, and then you turn over the PCB and solder all the pins.
  4. Jumper wires - On each side of the headphone jack, you should see 3 holes. Two of those whole our surrounded with a black outline. These need to be soldered together (see photo above). You can use any jumper wire. I used the legs leftover i cut off from the resistors that I soldered.
  5. Solder the USB port - This also fits in the place it's marked on the PCB, and then you turn over the pcb and solder all the pins in place.

Step 4: Soldering the Other Electronic Components - Left Hand Side

Now you're going to take the side that says "Left Hand" on it. Again, the diodes should not be visible to you, because they're on the bottom.

On this side, you'll need to solder these components:

  1. Solder the MCP23018-E/SP I/O expander to the top left corner of the PCB. This should fit perfectly in the holes. Make sure you put the notch on the chip facing the right way. (Look at the images I added to make sure you got it right. On mine, when the notch is pointing the right direction, the text is upside down - not sure if it's like that on all chips, so you need to see the notch)
  2. Solder the capacitor above it. Again, look at the image I posted here, and make sure you put the capacitor in the right holes.
  3. Solder the headphone jack in place. (This should be positioned on the top right corner of the left keyboard)
  4. Solder jumper wires on the sides of the headphone jack - connecting the two holes marked in black, just like we did on the right side of the keyboard.

Step 5: Connecting the USB Ports - Right Hand Side

Now you need to connect the usb port on the teensy to the usb port you soldered on the chip, so you can hook up the keyboard to your computer.

I took an old usb cable I had lying around, and cut open the usb side to expose it completely. Then I cut the wire, and exposed the wires that are connected to the usb cable.
The side of the USB male connected you hook up to the teensy, and the other end, that you expose the wires, you'll need to solder to the PCB

Make sure you connect the colored wires to the right positions on the PCB port!

  • The white wire is connected to the hole that's printed as 'D - ' (Data minus)
  • Green should be connected to 'D +' (Data plus)
  • Black will be connected to GND (Ground)
  • Red is connected to Vcc

(Some usb cables might have a fifth wire - If it does, you won't need it.)

Step 6: The Case

You have two options for the case: Laser cutting acrylic or 3d printing.
I went with acrylic, since it just seemed easier. 3d printers need calibration, the extruder can get clogged, you need to make sure you have enough plastic and other possible problems you can run into. That's beside the fact that it will take at least a few hours to print and the final result won't be as smooth as using acrylic.

At work I have access to an Epilog mini laser cutter. Using it was really easy. I don't think I should explain here how to use the laser cutter, you can find several guides on that, or ask someone that knows if you have access to one.

I'll attach the DXF files here. The laser cutter I used can cut sheets up to 30x60 cm, and on each sheet I managed to cut 3 pieces. Each side of the keyboard requires 5 pieces - the top and bottom should be 3mm thick and the three middle pieces should be 4mm thick. Make sure you cut each layer from the right thickness. Before you cut, look at the file names to know which sketch is each layer.

That means, if you arrange the three middle pieces on a single sheet, then you need two sheets of 3mm thickness, and another 2 sheets of 4mm thickness.

(by the way, if you don't have access to a laser cutter nor a 3d printer, I remember finding on google a site that will print or cut the case for you and ship it to you. I don't know how much it will cost though).

Step 7: Soldering the Switches

Now that you have the pcb's with the electronic components soldered, and the case ready, you're ready to solder the switches on.

First, you need to place the middle layer of the case (layer 3) above the pcb, and insert the switches on top. You should have a "sandwich" - the third acrylic layer in the middle, and the pcb below, and the switches above. The base of the switches fit right inside the square-like cuts of the acrylic. You might need to apply a little pressure to get them in, but make sure not too much pressure, and make sure you don't break or damage of the of the electronic components when doing so.

Also, look at the pins on the switch, and make sure you're inserting them in the right orientation.

Once you placed all of them in place, you can turn over the pcb, and solder the pins of all the switches. There's a lot of soldering to do here too, but this is much faster than the diodes since the pins are thick, held firmly in place, and you can use thicker solder for them.

Step 8: Putting the Rest of the Case Together

After all the switches are soldered, you can put the rest of the case together. This should be pretty straight-forward. Again, here you'll need to make sure you placing the right layers in the right order.

(Note: make sure to take off the acrylic protective stickers before putting it all together. After taking off the stickers, I wiped the acrylics with a cotton pad and a little alcohol to make sure they're clean.)

There was a tiny problem I had here - When assembling the layers, I realized the headphone jack is a little thicker than 3mm..
I took a small round file, and sanded a little curve in the layers that sit above and below the middle layer, exactly where the headphone jack is. You can see it in the images.

Step 9: Placing the Keycaps On

I personally ordered the cheapest keycaps I can find. I found a set that is made for the ergodox (and I suggest you do too) on ebay for about $20.

(I figured if I start using the keyboard a lot, i'll pimp it out with a cool set of colored keycaps! ;) )

If you get a set designed for the ergodox keyboard, then the keys will have a specific curvature to them, and you'll need to make sure you put the right ones in the right position - Even the blank ones that all look the same. It creates a comfortable angle for your hands when typing.

Step 10: Hooking It Up & Installing the Firmware

Now you're ready to hook it up, and go!!! (It should work out of the box, immediately. At least for me it did on my mac)

BUT... You'll probably want to customize the layout (because that's the whole point!). So...

  1. Download the Teensy firmware bootloader
  2. Then customize your layout - There are several ways to do it. I tried most of them, and personally I think the best is the one created by the people behing the ErgoDox EZ. You can try it here
    It's not that complicated to use, but if you need help then search youtube for guides - There are plenty of videos with tips and tricks for great layout configurations.
  3. Once you're done configuring, you need to download the compiled firmware with your configuration. At the bottom of the configurator there should be a 'download' button or link. You should get a '.hex' file.
  4. Drag the '.hex' file to the Teensy loader you downloaded earlier.
  5. Hit the 'Program' button which will copy the firmware to the 'teensy' chip, and then hit the 'reboot' button, and your Teensy should reboot with the new layout.
    (You can read more about it here)

Step 11: Conclusion

All in all I had a really fun time building this!

It was a cool idea, relatively simple (for someone with no professional electronic experience, and almost no experience as a hobbyist either), and actually manageable.
I think in total it took me ~10 hours, which I split over several days, about 30min a time, each time soldering just a few more components, or printing another layer.

The learning curve to get used to this keyboard is pretty steep - Getting used to the ortholinear layout took me about 2-3 days, but getting used to all the other changes took me another 2 weeks.
Customising the layout is a never-ending process, I'm always looking for optimising the keys I use more often in the most comfortable spots.

If you want more info on this, you should also look at the original ErgoDox EZ site that has a few videos and guides about using it.

First Time Author

Participated in the
First Time Author