Building my first keyboard (and you can too)
starting with knowing absolutely nothing about building keyboards
This keyboard building guide and saga started off with me simply wanting an adorable keyboard…
…and subsequently deciding that building my own ergonomic keyboard was my best course of action.
When I started this project, I knew absolutely nothing about keyboards or how to build them. I found it a bit difficult to find good material on building a keyboard, so I figured I’d write down everything I learned in a way that’s easy to understand.
The body
First, you’ll need to decide what kind of body you want your keyboard to have. There are lots of options ranging anywhere from a typical flat keyboard to a split ergonomic one and everything in between.
I chose the Dactyl, which is a split ergonomic body similar to the Kinesis Advantage II.
In my case, I wasn’t able to buy the body, so I needed to 3D print it. You can find online printers that will print and ship your body for you, or you can print your own (I actually found a guy on Reddit who prints 3D keyboards).
Unless the print comes out absolutely perfectly and is the color you want, you’ll probably also want to paint the body. You’ll want to get a gap filler primer spray paint and spray a few layers of that to smooth things out and then finish it with whatever color you want.
The switches
Switches are possibly the most important part of your keyboard. They are the mechanism underneath your actual keys that moves down when you press a key.
People have many different switch preferences. The main facets of a switch are how much force it takes to push it down (operating force), how quickly it activates a keypress (actuation distance), and how the key feels when you press it: if there is a little bump (tactile), if it clicks, or nothing at all (linear).
I went with the Kailh Red switches since their operating force was just a little bit more than the Cherry Mx Reds.
The keycaps
Most keycaps won’t have much of an effect on how you type, but they can give your keyboard a different look and feel. You can customize colors, fonts, or even have blank keys.
As it turns out, keys come in different shapes and sizes. Most keyboards have keys that are tilted based on where your fingers are when you type and are named based on the row they are in. These range from R1 (i.e. the bottom row) which is tilted inwards for when you hit a key with your finger pointed towards you, through R4 (i.e. the top row) which is tilted outwards for when you hit a key with your finger pointed away from you. R2 keys still have a bit of an incline to them and R3 keys are the most level of the different types.
Most keyboards still work with keys shaped like this, but you may want to check if those key shapes will work if your keyboard is an unusual shape.
Other keyboards have keys that are all one level, but these are harder to customize.
The microcontroller(s)
You will need one or possibly two microcontrollers so your keyboard knows what to do. Which microcontrollers you choose can impact which firmware you use and how things get wired.
I ended up using two Pro Micros, one for each hand of my keyboard and a TRRS (tip ring ring sleeve, your typical audio cable with two male ends) cable for the sides to talk to each other.
The wiring
I decided to handwire my keyboard. The other option is to have a PCB (printable circuit board) printed.
Tools
If you are handwiring your keyboard, you’ll likely need the following things:
- very thin conductive wire — copper wire is a typical choice. It needs to be very thin because it needs to be able to fit in the narrow space inside of your keyboard.
- solder — if you’re handwiring, you’ll need to solder different parts of your keyboard together. Soldering uses a soldering iron to heat metal and create a little metal “joints” that helps hold things in place and is also conductive. Lead based solder works best as its melting point is much lower than non-lead based alternatives. For beginners (like me!), it’s easier to use lead based solder, but be sure to work in a well ventilated area when soldering.
- soldering iron —the tool that will actually heat the solder. I’m not a soldering expert, but the general idea is to heat the metal you want the solder to melt onto, not the solder itself.
- electrical tape — it’s important that certain parts of your keyboard don’t touch each other, and the easiest way to insulate those parts is probably with electrical tape.
- diodes —diodes are like a one way street for electricity by only letting the current flow in but not out. They help your microcontroller know which key you’ve pressed. You’ll need as many diodes as you have keys.
- TRRS cable — TRRS (or tip ring ring sleeve) is commonly known as an audio cable and will be used to transfer information between the two hands of your keyboard.
- TRRS mount — This is what your TRRS cable will be plugged into. You’ll need two of these (one to connect to each microcontroller on each hand).
- Micro USB-to-USB cable — This is what will connect your keyboard to your computer. For fun, you can actually build your own cable. I did this and it was a bit nerve wracking, but in the end I had an adorable pink cable I built myself so 🤷.
- multimeter — this will help test connections for your keys.
Switches
First, you’ll need to shove all of your switches into all of the holes in the top part of your keyboard. The part that you can push down will go on the top of your keyboard (that’s where the keycap will go). There should be a little slit in each switch. This slit should be oriented to be at the top.
You’ll need to secure the switches in place as well. I used a tiny bit of super glue on the keyboard body and then again after inserting the switch around the edges.
Wiring
Now comes the wiring. There aren’t a lot of guides or information out there for wiring, so I made a few diagrams to make things easier.
For your microcontroller to know which key is being pressed, we need to wire the keyboard into rows and columns. Your microcontroller will know which key is being pressed by getting a signal from both the row and the column.
The actual wiring can be a bit tricky as you can’t let any wires touch that aren’t supposed to be wired together. That means that the columns and rows need to be insulated from each other. One way of doing this is to buy thin insulated wire and strip some of the coating off of the wire with a wire stripper or a razor blade.
This method ensures that your wires won’t cross each other, but it’s also a bit tedious. Because the wire is so thin, it’s really hard to not cut the wire itself. Additionally, when I tried to screw the case on at the end, I found that the wires were too thick for certain areas of the body, which made the case not fit quite right.
Another method is to use uncoated copper wire. After each row/column is completed, you can lay down electrical tape to insulate that wire. Though this method makes the actual wiring more efficient, it is prone to wires crossing after the fact as the electrical tape tends to move a bit as the case squeezes together. This resulted in an arduous debugging session trying to figure out why everything worked when the case was off, but not after screwing it together.
Switches
On the underside of your switch, you will see two pins. In doesn’t matter which one you use for rows and which one you use for columns, but you should be consistent for all of your keys.
I decided columns for the upper gold pin and rows for the lower silver pin. I wired rows with diodes and wire, and the columns with just wire.
Rows
I started off wiring the rows since the wiring is a little less complicated (and jumbled) than the columns. Each color and letter+number name corresponds to a pin (named the same) on the Pro Micro. For example, the red B6 row should include switches A1, B1, C1, D1, E1, F1, and should be wired to pin B6 on the Pro Micro.
Note that it doesn’t matter which part of the row is wired to the Pro Micro, just that it’s connected somehow (this is useful since there’s not a lot of room and it can be hard to see which wires are going where).
Diodes
For each switch, you’ll need to attach a diode. It doesn’t matter which pin, as long as you’re consistent. I chose the silver pin for all of my diodes.
Each diode has one end that’s a different color. In my case, one end was black. The black end will be what connects to the wire and the non-black end will connect to the pin itself.
The wire coming from the black side of each diode will need to be soldered to the silver pin on each switch. I made a little loop on the non-black side of each diode to help with placement on the pin and soldering.
The wire for each row will need to be soldered to the wire coming from the non-black side of each diode.
Test the connections
After each stage of wiring, it’s a good idea to test the connections you’ve made. With a multimeter set to the continuity setting, take one lead and touch it to the beginning of your row/column and take the other lead and touch it the the end of your row/column (the wire usually works best instead of the solder point). You should hear a tone if it’s connected.
You can also use this method to test that wires aren’t touching. If you touch one lead to a part of a row/column and the other lead to a part of a different row/column, you shouldn’t hear a tone (which is good)!
Columns
Wiring the columns is similar to wiring the rows. The columns, however, need to be wired to the thumb cluster as well. This can be a bit complex as you’ll need to run wires on the lower part of the board where there isn’t a lot of room and there are a lot of other wires running as well.
For the columns, I opted to use the uncoated copper wire method since a lot of wire needed to be run and it needed to be thin enough to fit my case.
For each column, the wire needs to connect to the other pin on each switch (in this case the gold pin). I ran the wire by looping it around each pin post. Like the rows, each connection to the pin will need to be soldered.
Once you have both the rows and the columns wired, it’s time to wire up the Pro Micro. As shown in the diagrams above, each row and column maps to a pin on the microcontroller.
You can wire it in any way that’s easiest for the wires to reach. For wiring rows, I soldered wires around column D for each row and ran them to the microcontroller. For wiring columns, I ran wires from the top (A1 — D1) of each column to the micro controller. Remember, these all need to be insulated from each other, especially near the microcontroller.
Each pin with a wire running to it on the Pro Micro will need to be soldered.
TRRS
Once all of the rows and columns have wired and soldered to the microcontroller, it’s time to wire how the two hands will talk to each other.
There are 4 pins on the TRRS mount, but we only need to use 3 of them (we don’t all the channels) and each pin corresponds to a pin on the microcontroller. It doesn’t matter which pins on the TRRS are connected to the pins on the Pro Micro, just that each hand is wired the same.
The TRRS mount isn’t too difficult to solder, but it’s a bit fragile. The TRRS mount needs to sit perfectly in the slot that exits the keyboard case (since you’ll be plugging a TRRS cable into it).
This completes one hand! Now you just have to do it all over again for the other hand….
Firmware
Now that everything is wired, it’s time to make the keys do something.
I used the QMK firmware, which is pretty standard, flexible, and easy to get going. There are pretty good QMK guides, and even some specifically for the Dactyl, but I’ll explain the annoying bits here.
First off, download the QMK firmware.
You’ll need to install a bunch of things. Most of this is straightforward if you’re using anything but a Mac, but I used a Mac.
Make sure you have homebrew installed and then run the following in a terminal:
brew tap osx-cross/avr
brew tap PX4/homebrew-px4
brew install libusb
brew link --force avr-gcc@7
brew install dfu-programmer
brew install gcc-arm-none-eabi
brew install avrdudeNote that you need a specific version of avr-gcc. This is because of a bug in avr-gcc 8.2.0 (the most recent version when this post was written).
Layout
I followed the QMK literature (the reference section is great) for creating my key layout. Here’s what I came up with:
The main layer has a typical QWERTY layout (similar to what’s on the Kinesis Advantage II). However, there are a few key differences.
First, I map one of my left thumb keys to ⌘ (CMD/COMMAND). I find this super useful as it’s a key I use often.
Second, I map what would be CAPSLOCK to HYPER. My HYPER key is essentially an extra modifier key that I use for focusing windows and switching between applications. When tapped, the HYPER key acts as ESC. HYPER isn’t a real modifier key, but you can fake one with CMD+CTRL+OPTION+SHIFT, which no one would ever press otherwise. I used to use software to create they HYPER key, but now the HYPER key is baked into the firmware.
The sub layer has all of the keys that I don’t need but are pretty convenient to have at my ~ fingertips ~. This includes brightness adjustment, volume adjustment, and media controls on the left hand, and a full numpad on the right hand. I also have a convenience button for flashing my firmware and of course the same TOGGLE LAYER key to get back to the main layer.
Once you have your layout configured, you can compile it by running:sudo make path/to/makefile:default
Flashing
Now the fun part. Flashing the firmware.
First you’ll need to either run avrdude (a command line tool) or the QMK toolbox (a GUI tool that uses avrdude under the hood. I used version 0.0.9).
Running with avrdude
• Run sudo make path/to/makefile:default:avrdude
• There should be output that says it’s waiting for you to flash.
• When you reset the microcontroller (see below), the firmware should automatically be flashed.
Running with QMK Toobox
• Navigate to where the hex file of your firmware is in the top box.
• Make sure the microcontroller is set to atmega32U4 in the dropdown.
• Check the “Auto Flash” box.
• When you reset the microcontroller (see below), the firmware should automatically be flashed.
When you’re ready to flash the firmware, plug one hand of your keyboard into you computer. You’ll need to flash both sides, so make sure in your config.h that#define MASTER_RIGHT or #define MASTER_LEFT is uncommented for whatever hand you’re flashing.
Every microcontroller is a little different, and the Pro Micro is one of the most annoying to flash.
You need to have the Pro Micro exposed and physically take a piece of wire and briefly touch it to the GND and RST pins. You should see the little red light blink off. Note: it’s nice to configure a way to flash the firmware in your keymapping so that you don’t need to access the Pro Micro every time.
Keycaps
All that’s left now put on all of your keycaps. Gently but firmly push the keycaps onto the top part of each switch. And don’t forget to screw on the back of your keyboard!
And boom! Now you have a functioning keyboard that you BUILT YOURSELF.
P.S.
Building anything takes a lot of time, trial, and error. Things don’t go perfectly the first time. I broke many a wire when trying to strip the coating off, glued switches the wrong way, and I even snapped off the micro-USB end of a Pro Micro when plugging in a cable AFTER MY KEYBOARD WAS TOTALLY FINISHED. I had to order a new Pro Micro, which I found out was defective after I re-soldered it, so I had to order YET ANOTHER ONE and re-solder that.
Needless to say, things take time and don’t always go the way you planned. But don’t give up because in the end you have a killer keyboard and you’ll have learned so much. 😅
