How to compile the tmk_keyboard firmware for ErgoDox on Mac OS X

I received my ErgoDox keyboard from Massdrop a month or so ago. After a false start because of some missing parts, and with the help of a friend handy with a soldering iron, it is now up and running.

I've wanted to try the Norman layout for a while. This seemed like the perfect opportunity. The ErgoDox is so different anyway, changing the layout would should not pose too much of a problem? That's the theory. Unfortunately, the "official" ErgoDox firmware doesn't come with Norman. I didn't want to start hacking at keyboard firmware before even getting it up and running, so I decided to try tmk_keyboard.

This is how I got it working.

Install dependencies

We need to install AVR Libc. This package contains C libraries for AVR microcontrollers (used by the Teensy microcontroller in the ErgoDox) and most importantly for us, a version of GCC that will allow us to build the firmware.

AVR Libc is a Free Software project whose goal is to provide a high quality C library for use with GCC on Atmel AVR microcontrollers.

You can install the dependencies using Homebrew.

$ brew tap larsimmisch/avr
$ brew install avr-libc

Build the firmware

There are many versions of the tmk_keyboard firmware available on GitHub. I'm using Tenderlove's fork.

Get the source code.

git clone

Change to the ErgoDox keyboard firmware directory.

cd tmk_keyboard/keyboard/ergodox

Build the firmware.

make clean
make -f Makefile

You should now have a file called ergodox_pjrc.hex in the directory. This is what you need to load onto the keyboard.

Install the firmware

I used the Teensy Loader app. Follow the instructions on their website choosing the ergodox_pjrc.hex file that we just built.

Hopefully, that should be it. Good luck fellow ErgoDox owners!