published : 2017-05-20 changed: 2020-04-16
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 (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!
keymap.cfiles for you, but you cannot flash them to your keyboard.
keymap.cfile 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
DE_OSX_ACTall "meaning" the same key.
keymap.cfile, 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.
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:
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.
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...
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.
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
When the keymap was parsed successfully you should get a display of the base layer of this layout.
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.
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.
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.
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
KC_TRNSis 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!
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!
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
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.
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:
Open a keymap. You need to choose the directory, not the file!
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!
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!
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.
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.
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.
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:
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.
All actions a macro can do, are the following:
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:
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...
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.
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!
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:
java -jar ergodoxgenerator-VERSION.jar
created Stephan Bösebeck (stephan)