Layout change for ErgoDox Ez

On April 30, 2016, in Linux, by jafo

I’ve been using the ErgoDox Ez and I really like it but there are some layout changes I wanted to do.  I held off doing it for a while because to change the layout you have to build an entire new firmware for it, which I wanted to dedicate enough time to completing successfully.  In the end, once I had all the parts together and the new layout figured out, it took me 15-30 minutes to do.  Using this guide I could probably do it in 5m, except for the changing the keymap file portion.  That is a bit fiddly and also just requires thought about what you want to do.  This should work on the ErgoDox, but I label this the Ez instructions because it uses the Ez default keymap.


  • Decide on what changes you want to make and write them down.  For example, I wanted to put grave accent where tab usually is, make the key left of “a” be Esc when tapped and Win when held, etc…
  • Download the Teensy flash program from
  • Set up the udev rules as mentioned in the above page.
  • sudo apt-get install gcc-avr avr-libc dfu-programmer
  • Clone the repository: git clone
  • Go to the ErgoDox EZ directory: cd qmk_firmware/keyboard/ergodox_ez/keymaps
  • Make a directory for your keymap: mkdir mykeymap
  • Copy over default layout: cp default/keymap.c mykeymap/

Changing ErgoDoc Ez Layout

  • Modify mykeymap/keymap.c to adjust your layout.  I was able to figure it out by looking at it, but if you need instructions look starting here:
  • Build the new keymap: make KEYMAP=mykeymap
  • Copy the hex file to your directory: cp ergodox_ez.hex keymaps/mykeymap
  • Run the Teensy program: /path/to/teensy.64
  • Press the recessed button through the hole in the upper right corner of the keyboard with a paperclip.
  • Press the right arrow button and select the hex file you created.
  • Press the down arrow to reboot the Teensy.
  • Test the keyboard.
  • Repeat this section until you are happy.

Keymap Cheat-sheet

  • “a” key: KC_A
  • Win when held, Esc when tapped: GUI_T(KC_ESC)
  • Layer 1 when held, Grave accent when tapped: LT(SYMB,KC_GRV)
  • Switch to/from Layer 1: TG(SYMB)
  • Switch to/from Layer 2: TG(MDIA)
  • Control when held, “z” when tapped: CTL_T(KC_Z)


There is a GUI configurator at that I didn’t use because I really want the keys that you can tap for one thing and hold for another, and I couldn’t see that it was supported there.

If you don’t want the keys that you, for example, tap to get “z” and hold to get Ctrl, then the Massdrop GUI configurator linked above may be the way to go.  It gives you a hex file directly.  I really wanted those dual use keys though.  I really wanted to start with the default ErgoDox Ez layout and make a few changes, and this is the easiest way to do that.

I use the Windows key a lot for my window manager (i3wm), and the default layout had left Win on the thumb pad and the right Win on my pinky.  That asymmetry for a modifier key was very hard to get used to.  So I think I’d try to keep modifiers symmetric in the future.

Tagged with: