If you read my blog, you might have noticed, that I'm fond of cool keyboards. We IT-guys use them the whole day, but most keyboards are just awful to work with. So I'm glad I found a "proper" ergonomic one, my ErgodoxEZ (look at http://ergodox-ez.com for more information or read my review here).

One of the greatest things about the ErgodoxEZ is its programmability. But you actually need to know how to code, in order to get it to run easily. And even if you do, it is not very intuitive to create a c-program that runs on your keyboard and is showing your layout.

There is a WYSIWYG-Editor at massdrop.com, but unfortunately I never got it to work properly - and it is somewhat limited in functionality (like Macro support etc).

Hence, I started creating my own little tool for creating my layouts and optimizing them...

The ErgodoxLayoutGenerator

The ErgodoxLayoutGenerator (very clumsy name, but I could not think of something more better for now - lets just call it ELG for short) is programmed in Java, so it should work on all machines and OSs java is available for. You need to have the latest version of the Java8 installed... As I got some feedback already: It needs to be the latest official Oracle JDK or JRE, it does not work with OpenJDK out of the box. If you need any help using OpenJDK, just contact me...

The idea is pretty much similar to the one in massdrop, but the ErgodoxLayoutGenerator is built around the qmk firmware, and it generates a keymap.c file for your local installation!

Prerequisites and remarks

1. you need a current version of Oracle Java installed on your system
2. you should have a current version of the QMK-Firmware repository cloned to your machine for the LayoutGenerator to make any sense. It will still generate keymap.c files for you, but you cannot flash them to your keyboard.
3. Although the qmk-firmware is available for a bunch of keyboards, the ErgodoxLayoutGenerator is only covering the Ergodox and ErgodoxEZ (hence the name).
4. keep in mind, that the ErgodoxLayoutGenerator is still in development and was not heavily tested on different environments or OS's.
5. If you have any feature requests or ideas you want to share, please visit the github project page here
6. The ELG cannot reach the flexibility of a c-program of course. It is limited to the most basic functionalities. For example it lacks support for UTF-Characters and the GUI definitely needs to be refurbished. But I never wanted to win a desgin price with that - it should just work.
7. The ELG does read the keymap.c file and parses it to some extend. But that means, it is very relying on the structure of the file to be more or less similar to the "official" ergodox layouts that come with the qmk-firmware. If you want to use the ELG to work with your layout, you should make sure, that your keymap file does follow this lead
8. There is support for custom macros, where you can just add c-code to your layout. There is no checking if that is correct or highlighting or whatever.
9. The support for non-us keyboard layouts is a bit... clumsy. You can use the proper keycodes in most cases, but especially when creating macros, the automatic generation of macro strings, is not working. It will create macros for the US layout. This is limited due to the fact that there is no regulation on how to name the keycode definitions. For example, there could be a KC_ACUT, DE_ACCENT, DE_OSX_ACT all "meaning" the same key.
10. As the ELG is reading in your keymap.c file, things might get messy. If you use one of the standard keymaps, all should go fine. But if you use some of the advanced stuff, things will go wrong. It will probably parse the keymap and most of the functions will show up fine, but some things might go missing. At the moment there is no support for the FN[1-9]-keys! So, if your keyboard uses those, please make sure, that you replace the functionality with a macro.

The parsing of the C-Files does have its drawbacks, but the great advantage is the possibility to have ELG read in existing keymaps! That does work most of the time.

Getting Started

Usually it should be ok to get the latest release from the gitub page. Download the JAR-File attached to the release and double click it. If java is installed properly, it should start up fine and you should see a screen with an empty layout: …591a20f6722c740f15a3f02e…

starting it from commandline

If the above does not work, you can try to run the jar file from commandline with java -jar ergodoxgenerator-1.0BETA2.jar - or whatever file you downloaded. If it still does not work, you'd get a proper errormessage then. On the github page you can create an issue for that.

Sometimes it might be helping, to not use the JAR-Start funktionality of java, but run it manually: java -cp ergodoxgenerator-1.0BETA2.jar de.caluga.ergodox.Main. If you get the same error as above, please create an issue at github.

compiling it yourself

If you're a java-guy, you can compile it yourself (and hopefully contribute to the project). The project is a standard maven project. So if you cloned the repository to your local machine, running mvn install should compile everything. Your executeable will then be in the directory target and called ergodoxgenerator-1.0-SNAPSHOT-shaded.jar. This one should be executeable...

Defining the QMK-Sourcedir

At the bottom of the main window, there is a button called set qmk sourcedir. Here you should set the root directory of the qmk sources. This is necessary for putting the layout at the proper position at the end. If you did not specify this directory, you always need to navigate there manually.

Opening a keymap

If you defined the QMK-Sourcedir, the open dialog will start in the correct directory for the ergodox layouts. You choose the directory of the keymap, as all keymap files actually are called keymap.c.

When the keymap was parsed successfully you should get a display of the base layer of this layout.

UI explanation

Layer chooser

Usually an ergodox layout consists of several different layers. Like when hitting ALT on a keyboard, all keys do something else. But here you are more or less free to define as many layers as you want (not really, your keyboard has limited memory). To switch to the different layers, you need to press or hold a key (see below). when changing the layer in this combobox, the layout will be shown accordingly. …591a20f6722c740f15a3f030…

Adding, renaming, deleting layers

When creating a layer, you only have one layer called base defined. The buttons on the top let you create new layers, rename them or delete them. Attention: Deleting layers and still having layer toggles or macros referencing them, will cause unexpected behavior. Also you should not rename the base layer, as this might also cause problems later.

LED indicators

on the top right of the window, you can see the 3 LEDs the ergodox does have. You can switch them on and off by clicking for the selected layer. This reflects the behaviour of the LEDs when flashed on your keyboard.

…591a20f6722c740f15a3f033…

…591a20f6722c740f15a3f034…

…591a20f6722c740f15a3f035…

the keys

the main portion of the screen is filled with keys. These represent the corresponding key on the ergodox keyobard. If you select a key, it will be marked (green border) and a more detailed description of the key is shown in the lower part of the window. Assigning functionality to a specific key can be done via the context menu. Just right click on a key, it will be marked and then you can

• clear: well, this usually means, that the keycode KC_TRNS is assigned to that key. This code states, that this key should behave as defined in the "previous" layer (usually base). This can of course not work in the base layer!
• assign a key: well, you assign a keycode to that specific key. The keycode is represented in Text. All keycodes starting with KC_ are the "default" ones. There are also different keycodes for different locales or OS, like DE_OSX_. You can also assign here a combination of keys. Like "Shift-A" or "CMD-S". If you specify more than one modifier, a macro will be created for you!
• assign layertoggle: This will create a key that can toggle a certain layer on and off.
• assign layertoggle/type: this is temporarily toggling to a specific layer as long as the corresponding key is held. When the key is released, you return to the layer before. If you just type that key, it will issue a different keycode. For Example, y does issue CTRL when held in my layout
• Assign macro: This is the most feature rich thing, see below. Attention: The macro functionality is not 100% implemented yet!

the legend

At the lower part of the window there are representations of some colors and keys. Those state, that a green marked key would be of type Layertoggle / type, and hence shows two informations: first line is the key being typed, 2nd line is the layer to switch to as long as the key is held

Save Button

There you will be asked for the file to store the keymap to. This file should always be named keymap.c and should be stored in the QMK-Sourcedir at keyboards/ergodox-ez/keymaps/YOUR_KEYMAP, where YOUR_KEYMAP needs to be replaced with the name of your keymap.

When you want to store a completely new keymap, you need to create this directory yourself. You can do that from within the save dialog.

Save Img

This will create a PNG showing all layers. This is useful to add to your layouts, if you want to publish them and have them merged to the official qmk repository as it makes it easier for others to use your layout. like this one: …591a20f6722c740f15a3f041…

open

Open a keymap. You need to choose the directory, not the file!

reopen last

If you are a bit like me, you usually work on your own layout again and again. The button "reopen last" will open the file you last opened or saved!

create

Creates a completely new layout - Attention There is no "are you sure"-Question yet! IF you hit that button now, you'll end up with a new empty layout!

Assigning keys

When assigning keys, you first need to choose the "prefix" of the keycode names. Usually the prefix is related to the locale. Like "DE_OSX" is the German OSX version of some keycodes. all keycodes starting with "KC_" are the default (US-layout) keycodes.

You can add a modifier to the key if you want. And there are 2 different ways these modifiers might work: all at once (like SHIFT-A for a capital A) or the modifier when held, the key when typed! Like when holding the key Y, you hold CTRL, when typing it, it is just a plain old y. …591a20f6722c740f15a3f02d…

assigning a layer toggle

For this functionality you only need to define the layer you want to switch to. Quite simple. When flashed to your keyboard, the corresponding key will switch on a specific layer when hit, and switch it off again when hit again. If you switch to such a layer in that way, it is probably a good idea, to set the leds properly. …591a20f6722c740f15a3f029…

assigning layer toggle / type

as already mentioned above, this will create a key, that will temporarily switch to a layer as long as the key is pressed. If you only type the key (= pressing it shortly), you will just type a normal key. …591a20f6722c740f15a3f032…

assigning a macro

The assignment of macros is quite easy, you can just choose one from the dropdown and then hit "assign macro". This works only like that, if the file you opened has some macros defined.

If you hit the "new Macro" or "edit macro" button, the Macro editor is shown. You can create, delete, or edit the macros in this layout.

The ErgodoxLayoutGenerator supports these kind of macros:

• TypeMacro: This is a typing macro. Which means, it will send a series of keystrokes when the key is pressed
• HoldKeyMacro: this is very similar to the above, but there is a different set of actions that can be defined, when the key is released. Example: When the key is pressed, CMD+SHIFT is pressed, A is typed. When released, CMD+Shift are also released.
• LongPressTypeMacro: Different behavior is the key is pressed and held or only typed shortly
• layer toggle macro: well, use a macro to toggle a layer
• Custom macro: custom c-code

ATTENTION The Macros only support keycodes that do not represent a combination of keys. For example the keycode DE_OSX_QUOT is actually a replacement for LSFT(DE_OSX_HASH). This will not work in a macro, it will only send the keycode DE_OSX_HASH without the modifier. If you want your macro to work in your locale you need to be aware if this key is typed with a modifier or not.

…591a20f6722c740f15a3f02f…

…591a20f6722c740f15a3f036…

…591a20f6722c740f15a3f038…

…591a20f6722c740f15a3f037…

…591a20f6722c740f15a3f039…

…591a20f6722c740f15a3f03a…

All actions a macro can do, are the following:

• DOWN(KEYCODE). press down a key
• UP(KEYCODE). release the key
• TYPE(KEYCODE). Type this key
• W(199) . Wait some milliseconds, 199 in this case
• I(1). Change the Interval and set it to 1 in this case

you just add these together, separated by comma, and you have your macro actions for the specified case. …591a20f6722c740f15a3f03b…

Additional notes

This little project was first of all only built to run on my machine and make it more easy for myself to tweak with the layout. So it is only tested on a Mac OSX machine, not sure how it will work on windows or linux.

There are still a lot of things missing:

• gui layout could be improved a lot. Especially in the Macro-Workflow
• Errorhandling is completely missing
• some "are you sure"-Dialogs need to be added.
• store if you changed something on the layout, if so, ask before quitting, erasing...
• code quality is... prototype grade!

Compiling it

the latest versions of the ELG do have a "compile" button. When you have your keymap saved and the qmk-sourcedir is set, you can compile it. This is done by running the commands make clean and make in the qmk directory of the ergodox-ez.

This can only work, if your system is capable of compiling it. Please ensure that you have everything installed and is in your path. Take a look at the qmk-github page for more information on how to prepare your system.

When the compilation finished successfully, you can read the log output. USually that is not very interesting, if everything worked fine. On errors you can check closely what went wrong.

When this dialog is dismissed, you will be asked if you want to copy the .hex file - which is the result of the compilation - to the keymap directory. This is useful, if you want to submit your code to the official github project. When your keymap does also have a .hex file, everybody can just download an use it without having to deal with compilation and stuff.

If you just compile for yourself, hit "no" there...

little Update:

The release Candidate is here... completely with support for a new Type of Macro called ToggleLayerAndHold which will toggle a layer as long as the key is pressed, or, if the key is only typed, toggle the layer as with the TG() function call.

…591a20f6722c740f15a3f03e…

Also, the latest version will add a list of all Macros to the PNG file and a short description... helpful for documenting things. …591a20f6722c740f15a3f042…

And now there is a compile button, which will compile your layout if everything is set correctly! The resulting .hex file can then be uploaded to your Ergodox or Ergodox-EZ!

…591a20f6722c740f15a3f040…

Bugs and issues

If you find anything not properly working and you think it is a bug in the ELG, do not hesitate and create an issue at the github page. Please provide the following:

• the log output (for compiling and such). If it is related to the ELG, the log is not shown by default. If you want to see the output, you need to start the ELG in the shell / commandline using java -jar ergodoxgenerator-VERSION.jar
• what happened
• what did you want to happen
• what did you try to accomplish
• maybe the resulting keymap