Also accepting
Getting Started With Your New ErgoDox EZ

Congratulations!

You’re the proud owner of a new ErgoDox EZ. Thank you for picking our keyboard! If you’ve only ever used traditional keyboards, this tool can seem a bit intimidating, but don’t worry: This guide will take you through everything you need to start your journey towards a more ergonomic writing experience.

Remember, this is a journey — a typing adventure if you will. You’ve been typing with staggered, old-style keyboards for years; you’ll quickly notice your bad habits when starting with an ErgoDox EZ. Don’t fret: With this guide and practice, you’ll be able to regain your typing speed and enjoy a keyboard that’s perfectly customized for your individual needs. Soon you’ll be left wondering why ErgoDox EZ is not the standard layout!

What’s in the box

  • The keyboard (2 halves).
  • TA 3.5mm TRRS cable: this connects the two halves of your keyboard. TRRS stands for tip-ring-ring-sleeve (the connector type) 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.
  • Six small red washers. These can be inserted between the tilt/tent leg and the keyboard, to disable the positive stops (the clicks at specific angles and allow infinite adjustability.
  • If you ordered the printed keycaps, you will also receive two loose F and J keys with tactile nubs on them, which you can replace your existing F and J keys with.
  • The Wing wrist rest comes in its own box.

Connecting the keyboard.

Connecting the keyboard is simple. First, connect both halves using the 3.5mm TRRS cable. Then plug the USB cable into the keyboard’s right half, and connect it to your computer.

When you connect everything up, the three status LEDs on the board should light up in a ripple effect to show that the keyboard is connected.

Operating System Setup

This setup will depend on your operating system. If you’re on Windows or Linux, just plug the keyboard in, and go. On OS X however, there might be a couple of steps to go through.

See Configuring the keyboard type on OS X.

Positioning your Keyboard

It might sound redundant, but we recommend that at this point, you take a good look at the keyboard. Your ErgoDox EZ is a two-piece board. This is something that you need to take advantage of as much as possible.

You want to avoid having the two pieces too close to each other: Don’t replicate what you do with your normal keyboard. Instead, we recommend that you begin by placing the two pieces at shoulder length, ensuring that the home row aligns with your fingers. Your posture should be completely relaxed — just extend your arms naturally at shoulder width, note where your hands fall, and put the keyboard there. Let the board come to you, not the other way around.

Once the keyboard is positioned at the proper distance, place the Wing wrist rests. We recommend that you don’t tilt the keyboard just yet. Instead, put your hands on the keyboard so that your fingers are on the home row and the thumb keys. The Wing does not have to touch the keyboard — we made these elements separate so you can control the distance, depending on the size of your hands. The Wing should be under the root of your wrist, or your palm, and your fingers should be resting naturally on the home row of the keyboard. If that requires an inch or distance between the Wing and the board, that’s absolutely fine.

Note the angle of rotation of both halves relative to your body. They don’t have to be straight — you can angle them outwards slightly, so that your wrist does not have to flex in any direction at all.

At this point, without typing, your position should feel completely relaxed and natural. You’re just laying your hands on the desk in a very comfortable way… and there happens to be a keyboard right under your fingers.

Now that the keyboard’s general position feels comfortable, it’s a good time to play around with the tilt tent kit. Loosen the thumb screw (no tools required), and rotate the legs. You may want to start with the inner two legs, to create a “tent” position. This can be a very moderate angle and it would still make a difference. Once the leg clicks into position, gently tighten the thumb screw again.

This setup is not a one-time thing: Shift your position throughout your day. Feel free to move all four elements (two keyboard halves and two Wing halves) around as you work. Listen to your body, find what feels comfortable for you.

Starting to Type

Now that you have your ErgoDox EZ in the right position for you, it’s time to start typing!

We recommend that you take a look at the default ErgoDox EZ layout that comes preloaded on your keyboard. If you don’t like it, jump straight into the customizer to make your very own!

See Configuring the keyboard type on OS X.
Click here for a printable PDF of the keymap

Note: 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 ‘!’.

Typing Recommendations

Remember: You’re relearning how to type, so it’s going to take some time before you get back to your normal typing speeds. It might be frustrating at first, but with practice, you’ll improve.

If this is your first ortholinear keyboard, you’re going to find yourself discovering some of those bad habits you acquired with your old keyboard. That’s okay, you’ll get there! Just keep on practicing until you’re back to your normal speeds.

For regular typing practice, 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.

If you’ve been typing for years, suddenly practicing it may feel awkward at first. It’s all good — deliberate practice is an important thing and it will help you improve rapidly.

Make it pretty, turn on the lights!

If you ordered the Ergodox EZ Shine version, you could turn on the LED Lighting of your keyboard by pressing the “Lights on” switch located on the Layer #1 ( if using the default Ergodox EZ Layout ). Here’s a quick GIF:

Turn on the lights

More Control! (customizing the firmware)

Your Ergodox EZ requires no software to work. All the customization is done on your board, at firmware level. This means that nothing you do here will burden your machine, and it’s all cross platform and is portable. Just plug your keyboard into any random computer, and your familiar custom layout is right there, zero installation needed.

The layout that comes pre-loaded on your Ergodox EZ is not perfect for you — it can’t be, because in ergonomics, one size does not fit all. It’s time to unleash the power of the ErgoDox EZ and truly make it your own.

Before we get started on the firmware side of things, let’s get some terms out of the way.

Firmware
Permanent software programmed into a read-only memory.
Software
The programs and other operating information used by a computer.
QMK
Quantum Mechanical Keyboard Firmware. This is the open-source firmware running on the ErgoDox EZ, as well as a number of other keyboards. You can check it out at https://github.com/qmk/qmk_firmware
Configurator
Our custom Graphical Configurator at http://configure.ergodox-ez.com, which acts as an easy-to-use frontend to common QMK operations. The configurator generates a C file, and QMK then compiles it into code that can run on your keyboard.
Dual-function Key
Tap your A key, and it sends the letter A as expected. Press and hold it down… and it becomes Ctrl. That is the power of dual-function keys: When tapped, they send a character. When held, they act as a modifier. Alt, Ctrl and friends have never been easier to reach.
Layer
With QMK, your keyboard has up to 32 layers. Layer 0 is the base layout, at the bottom of the stack. You can then add any number of layers on top, and redefine one or more keys per layer. So your second layer (layer 1) can have number keys right on your home row, for example. So instead of reaching for far-away keys, you just toggle a layer, and the key you need is right at your fingertips.
Layer toggle types
  • Momentary (MO):
    This is like a Shift key. Hold down a momentary toggle, and you’re taken to another layer. Let go, and you drop back to layer 0.
  • Toggle (TG):
    This is similar to a Caps Lock. Tap once, and you’re moved to that layer. You’ll stay on that layer until you tap the layer toggle key again. Depending on the type, you’ll momentarily/permanently have access to the key bindings of that specific layer.
  • One-shot (OSL):
    Tap this key, and you’re moved to the layer. Tap a single key on the layer, and you will then be sent back to layer 0. Like Shift, but without having to hold down two keys at once.
  • Tap-Toggle (TT):
    A combination of Momentary and Toggle. Hold this key, and the layer is active only as long as you hold it. Tap it briefly, and you’re moved to the destination layer until you tap it again.
  • Direct switch (TO):
    All other layer switches go up (allow you to switch from layer 0 to layer 1, for example). TO is the only one which also allows you to switch down (from layer 3 to layer 2, for example).

Using the graphical configurator

Just put the video here that we have now.

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

You can create a new layout by clicking “Clone and modify layout”.

Clone layout

This will take you to a new view where you will be able to add new layers, modify individual keys, and more.

Customizing the layout

After cloning a layout you’ll get a very similar view to the one that you saw before, only now you can actually change things.

Let’s begin by explaining the multiple sections:

Customizer Sections

1. Layout Name.

You can specify a name that describes your Layout, our users usually append a version to this field, for their own reference.

2. Layers

Here you can add or remove layers.

3. Key Binds

This is where you’ll spend most of your time. You can click any key to modify its function.

For example, let’s say that you want to modify the “A” key. You can go ahead and click the key, a box will appear which will show as follows:

Modify Key

From here you can press another key to override the keycode that is assigned to that key; however, you can always click the dropdown and search for the available options. In this example, let’s say that we want to have the “A” key send the “A” keycode if tapped, but momentarily switch layers if you hold the key.

So we begin by searching for “Layer”, this will show us all the Layer related functionality. You can read what the available functions do by reading the description in the dropdown.

Modifier Layer

Based on what we want and the description on the search results, we can see that “LT” is a perfect fit, so we go ahead and select it. This action will add a couple of options to the box, Layer and Command. We select Layer 1 as we want to momentarily switch to said layer, and we select “A” as the command.

After doing this we can click outside of the box, and your keybind will be displayed:

Modifier Layer

You can repeat this process as many times as you want to build your own layout, we recommend that you take your time to explore the multiple options that are offered to you. Remember: This is a journey keyboard, this won’t be the last time you edit your layout!

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.

Coming 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 achieve this by bookmarking the URL of your layout.

http://configure.ergodox-ez.com/keyboard_layouts/qjnvox/clone

This link uniquely identifies your layout and you can always use it to go back to your layout. You can bookmark this address or you can just get the id from the compiled .hex file that you download after compiling, which by default will be named something like ergodox_ez_firmware_qpeypd_title.hex

Flash the firmware

The process of installing a new firmware is called ‘flashing’. To do this you’ll need to download a small flashing application. 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. Open your file in the loader, and click the Auto button.

Reset Board

To actually start the flashing process you need to push the reset button on the keyboard. 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. After you press the button, let go (don’t keep it pressed).

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:

Customizing in code: Working with the underlying firmware

The firmware running on the ErgoDox EZ is the [Quantum Mechanical Keyboard Firmware] (or QMK, for short), which we actively support. It’s a third-party open-source project running on multiple keyboards, with over 300 contributors and thousands of forks.

If you enjoy working directly with the code driving the keyboard, you can dig right into QMK on GitHub, compile it locally, and customize your keyboard at the deepest levels possible. This is a good startingpoint — QMK is extensively documented.

More Control! (hardware)

We are super friendly to modding. It’s in the DNA of the keyboard. We’re all for you modding your board. That said, obviously if you mod it you own it. Take that into account — some of these things will void your warranty, but that’s part of the fun :)

The Ergodox design has no glue or annoying tabs, and we made it easy to open up and mod. But before we get into those advanced customization subjects, let us get started with something that won’t void your warranty.

Changing the keycaps.

You can change the keycaps by using a keycap puller – we recommend that you’re careful with the strength that you apply, as the Ergodox EZ design allows you to open the switch if you want to do advanced modding ( continue reading below ).

This process should be very straight forward if you have a keycap puller; however, if you don’t, you can always attempt to use alternate methods. Such as using two credit cards, wedging them underneath opposite sides of the key and using the leverage to pop the key off.

Warranty

We understand that Ergodox EZ is a serious investment in your future well being, and our warranty reflects this.. From the moment your keyboard arrives at your doorstep your keyboard is covered.

Please note that your warranty is non transferrable. Our keyboards are not marked with serial numbers — we use your original proof of purchase. If you didn’t buy a keyboard directly from us, it is unfortunately not covered by our warranty.

What is covered by our warranty?

Basically, any reasonable use. If a keyswitch starts chattering, we’ve got your back. If the board stops working one day without you having done anything to it (never happened so far, but it is covered). It’s a two-year warranty, and we really care, so just email us. The warranty is non-transferrable though, and applies to the original buyer of the keyboard.

What is not covered?

Any damage that is caused by accident, abuse, misuse, liquid contact, fire or environmental causes.  Don’t spill coffee on your keyboard, it doesn’t need it.

Still have a question?

Simple fill out this form, or email contact@ergodox-ez.com — we're always happy to help. :)