Also accepting
Getting Started With Your New ErgoDox EZ

Congratulations! You’re the proud owner of a new ErgoDox EZ. If you’ve only ever used traditional keyboards then this tool can seem a bit intimidating, but don’t worry: This guide will take you through everything you need to get up and running.

1 - Connecting the keyboard

In the box you should have two cables:

  • A 3.5mm TRRS cable: this connects the two halves of your keyboard. TRRS stands for  tip-ring-ring-sleeve, and can be replaced with any other TRRS cable if you want to customize or extend it.
  • A mini USB cable: this connects the keyboard to your computer.

When you connect everything up, the 3 LEDs on the board should light up in a ripple effect to show that everything is powered.

2 - Getting your computer to recognise the keyboard

If you’re on Windows or Linux, you should be able to just plug the keyboard in, and go. On OS X however, there might be a couple of steps to go through in order to get it to recognise the keyboard. See Configuring the keyboard type on OS X.

3 - Starting to type

The layout of the ErgoDox EZ is extremely configurable, but if you want to start typing straight away you can find the default layout here: http://configure.ergodox-ez.com/keyboard_layouts/new

The secondary functions of keys - what happens when you press a key while holding Shift or Alt/Option - aren’t shown on the layout, but these behave exactly as they do on a regular keyboard, so for example pressing ‘Shift’ and ‘1’ will result in a ‘!’.

The ErgoDox EZ is open-source, but the firmware it ships with is already very advanced. When you take your ErgoDox EZ out of the box and plug it in, this is what you get:


Click here for a printable PDF of the keymap

4 - Changing the layout

Changing the keyboard layout is easy - at a high level the process is as follows:

  1. Create a new layout using the online configurator
  2. Compile it and download it to your computer
  3. Flash it to the keyboard using a flashing application

Here’s a video which covers the whole process: 

Creating a new layout

The mapping of what command, character or symbol gets sent to the computer when you press a particular key is part of what is called the ‘firmware’ and is stored on a chip in the keyboard itself. In order to create a new layout we’ll need to create a new version of this firmware.

ErgoDox EZ provides an online tool called the ‘configurator’ (http://configure.ergodox-ez.com/)  which does the heavy lifting for you and lets you create the layout using your browser. .

Compile and download

Once you’re happy with your layout, hit the ‘Compile this layout’ button. This will lock your changes and generate a .hex file which can be understood by the chip on the keyboard.

Notice that the URL now includes a short 6-character slug - e.g. http://configure.ergodox-ez.com/keyboard_layouts/qzjavy/edit. That slug uniquely identifies your layout and you can always use this link to get back to your layout. Most people customize their layouts again and again, making subtle tweaks over time as they learn what works for them.

You can now download the .hex file, which will be named something like ergodox_ez_firmware_qzjavy_my_awesome_layout.hex

Flash the firmware

The process of removing the old firmware on a device and installing a new one is called ‘flashing’. To do this you’ll need to download a small flashing application. The ErgoDox EZ runs on a Teensy microcontroller, so the app is called the Teensy loader. You can download it at https://www.pjrc.com/teensy/loader.html for Windows, OS X, and Linux.

First you need to give the loader your .hex file. There are two steps to flashing the firmware (program and reboot) but you can select an ‘Auto’ mode in the app which will do everything in one go.

To actually start the flashing process you need to push a button on the microcontroller. You can do this by gently inserting a paperclip into the small hole in the top right of the right-hand half of the keyboard until you feel a click.

When this is successful, the loader app should say ‘reboot OK’ and an LED on the keyboard will flash briefly.

Here’s a video going through the flashing process: 

5 - Learning to type again

You might find that typing on the ErgoDox will be difficult at first, particularly if it’s your first split keyboard. Even if you’re a seasoned touch typist, the unfamiliar columnar layout can take a bit of getting used to. This can be immensely frustrating to start with, but it’s easily overcome with a bit of practice.

Typing tests can be a good way to get back up to speed, and there are many available for free online. If you’re a programmer, look for coding typing practice services, since regular ones will miss out the punctuation you use in code.

For regular typing, we recommend KeyHero.com. You can select the ErgoDox EZ as your keyboard when you make a profile on the site, and track your progress over time.

For coding typing practice, we recommend typing.io. It lets you work with real code in several languages, so you get to practice parentheses and curlies etc.