ErgoDox EZ in German on a Mac

info

date: 2015-05-22 23:36:00

tags: mechanical keyboards Ergodox EZ

category: keyboards

Created by: Stephan Bösebeck

logged in

ADMIN


ErgoDox EZ in German on a Mac

The ErgoDox EZ in German on a Mac

This introduction and review is already available in German here. Yes, I admit, I was following the Indiegogo campagne of the ErgoDox-EZ quite a while. And since about 5 days now I'm a proud owner of an ErgoDox-EZ keyboard! Details about the campaign and the ErgoDox-EZ can be found here. …591a20f6722c740f15a3f010…

Unfortunately the keyboard was designed for the english speaking areas and does have it's issues with international layouts. Hence it also has problems with the German layout - that means, when setting the operating system to German, the keys are not at the place they should be. At least not with the default firmware. Most of the special characters were "somewhere" on the keyboard - ok, that could be learned. And you need to get used to this keyboard a bit. But some of the umlauts (öäüß) were spread around the keyboard as well. This made fluent typing (if you're touch-typing you know what I mean) nearly impossible. Well, the internet states this keyboard is fully programmable, everybody can make his own layout. Ok, this was not as easy as it sounds, but not as hard as it could be. Especially because I did not only want to fix the German layout, I also wanted to address other issues as well:

  • as already mentioned, the umlauts were spread across the keyboard, often in the lowest row of keys. They should return to the usual QWERTZ-location
  • I did have problems with the space key only being on the left side of the keyboard, as I'm typing space with both thumbs. (update: after using that, I learnt that having space on the right, having backspace on the left works way better!)
  • the location of CMD-keys was a bit bad * the ALT-keys were also a bit awkwardly located
  • I liked the idea of different layers, but the "Coder"-layer was not working with a German layout - about 70% of the keys were just sending the wrong keycodes (sometimes even umlauts) - that means, that about 70% of the keys were actually there, but at a wrong place. And the places were mixed up a lot. So, this thing is so greatly programmable, I read. let's go - how does that work? Well, this was kind of a setback, as this was not easy to find. There are a lot of github projects and forum discussion around the ErgoDox, but not really a simple howto. Thanks to Erez Zukerman (he initiated the indiegogo campagne) and that he replied after just a couple of hours after each of my questions (including the different time zones!), it did not take that long to get into the topic. Now, compiling a new custom firmware for the ErgoDox-EZ is no big deal anymore.

Disclaimer: what I describe here, are my findings, things that worked well for me. I'm not claiming this to be complete, or fitting for everybody (e.g. I cover only OSX German here). And, of course, this is probably not free of errors and faults. So, if you use these information, it's your responsibility. And please, read further documentation.

DE-Layout for the ErgoDox EZ on a Mac

I try to address all the issues mentioned above and created a first version of such a layout - it can be downloaded

here. Feel free to test it... This is what the layout looks like: …591a20f6722c740f15a3f00f… There are some features I'd like to point out:

  • There are 4 layers in total, default layer (all normal keys), symbol or coder layer (containing all kinds of brackets, symbols etc which come in handy when coding), the media layer (there you can control the mouse and it contains multimedia keys like play/pause, volume up/down...) and last but not least a number block.
  • All umlauts are at their usual location * Because the umlauts are at their usual location, some of the special characters had to be moved to the lowest row of keys (like #)
  • the cmd and alt keys are now in the middle of the keyboard (on both halfs), CTRL is where the upper cursor keys were located. So, CTRL, CMD and ALT are located in a vertical row on the "inner" edge of each half of the ErgoDox EZ.
  • There is a space key on each half located in the thumb block
  • the tab and ESC-Keys were moved to their default location
  • the Caps-Lock-key is a layer switch now (as I don't use Caps-Lock at all)
  • several keycodes (like CTRL) are defined on multiple locations due to several reasons: sometimes I like to type for example CTRL on the right, sometimes on the left half of the keyboard, depending on the context. and I did not always know what to put at a certain key - too many keys there :) As already mentioned, this is a layout that works for me quite ok now. I will probably improve it over time (fortunately that is possible). It is opensource and available in github. Maybe you have additional ideas, how to improve things. Or you create your own custom firmware. But this is just the beginning...

Beginners guide / howto for ErgoDox on a (german) Mac

As we speak about beginning. I did not find a good howto, how to start with the ErgoDox-EZ on the Mac, especially with a mapping the keys and such, creating a custom firmware. There is an english wiki being created right now

here. No real how to or similar. But there are actually not many steps necessary to alter an existing layout, compile a new firmware and finally upload it to the ErgoDox-EZ (sometimes called "flashing" the device). But before we get to that, let's just explain some terms you'll read all the time when looking for information about the ErgoDox.

ErgoDox vs ErgoDox-EZ

The ErgoDox keyboard is already available quite some time now and could be ordered at massdrop.com. Unfortunately, it was necessary to build the opensource keyboard yourself. That means, you'd get a lot of parts, you need to put together, soldering them , build a case, etc... And this is not working for everybody, as some of us do not have the time for such a DIY-project, or simply lack the knowledge and craftsmanship. And: if a little mistake happens, you end up with a really beatuiful, but not working keyboard. This is where Erez Zukerman comes in - his indiegogo project addresses exactly that by creating a real product out of an opensource DIY-keyboard. A product, you can buy, like any other product, including warranty and support. But still: everything still is opensource, including the things that are built right now especially for the ErgoDox EZ (like custom firmware)

massdrop

At massdrop.com the first version of the ErgoDox (not EZ!) could be bought. As mentioned above, this was just a bag full of parts, you needed to do all the soldering and building it up from scratch. But at massdrop you get a configurator which is capable of creating .hex files directly and visually. You can create your layout there and end up with a file you can directly flash on your ErgoDox. There are some issues when it comes to non-standard keycodes, though. So I did not find a way to do the

long type or other special functionalities there. That's why I took the manual approach. If you only need a simple layout, without fancy stuff, the configurator on massdrop might be the easiest way to create a working .hex-file.

Teensy

This actually is the hardware the ErgoDox (and the ErgoDox-EZ) is built upon. This is not very important, only if you wanted to build an own custom firmware from another code base. You also need to upload the firmware to the ErgoDox, if you want to change the layout. On a mac you can use the tool

teensy loader, which is named after the hardware. This tool takes some .hex-files and uploads it to your ErgoDox. You can download your copy here.

QMK Firmware

This is the standard firmware for the ErgoDox-EZ. You can guess by the way I'm saying that, that there are probably some other alternatives out there. And on github you can find some of those. I did not dive into that topic yet, I'll stick to the "original" for now.

.hex-Files

As already mentioned above, the firmware for the ErgoDox-EZ (or more precise for the Teensy Microcontroller) es stored in .hex-files after compiling. Only those files are needed. When you compile, you end up with a whole bunch of new files (like .sym, .obj and alike) which are not really necessary. You only need the .hex file.

How to install a new firmware

This is rather simple if you already have a proper firmware file in .hex-format. Some examples of those can be downloaded from the official repository here. This is the firmware project repository for the QMK-Firmware - there is a subdirectory ´keyboard/ergodox-ez/keymaps´ where you can find some of those .hex-files. My version of the layout can be downloaded here. To install this file, you only need to follow these easy steps: 1. Download the .hex file (if you compile it yourself, you end up with such a file also) 2. Open the App Teensy Loader (see above - Teensy). Then take a paperclip and klick the button on the keyboard on the upper right (there is a little hole in the case). This brings your ErgoDox EZ into programming mode. 3. Open the .hex file (first icon from the left - looks like a document icon) 4. To upload (aka flash) the firmware file to your keyboard, click on the 2nd button from the left ("rounded" Arrow). You'll see a progress bar during the upload process. 5. now klick on the reboot button (small arrow, 3rd icon from the left) After that, your new firmware is installed and used. You should see your changes now. I experienced some kind of "failures" after the reboot, like, the keyboard was stuck in a certain mode, the left half of the keyboard would not react... but I could fix it by just unplugging it and replugging it after a couple of seconds. I flashed the ErgoDox-EZ now about a dozen times, and in maybe a 3rd of those cases, an error like described happened. All could be fixed in no-time. So, don't panic!

howto create your own firmware

To do this, you need to do some preparations. As already mentioned I only consider MacOSX here - I did not try the ErgoDox on Linux or Windows. You should install brew.sh. If you have macports installed, you might end up with an error. We need to install a so called cross compiler. This is a compiler, that produces code not for the hardware it is currently running on, but something completely different. In our case this is the Teensy 2 microcontroller. If you use macports you'd have to find, how to install this crosscompiler. With ´brew´ the installation is just a few lines: brew tap osx-cross/avr brew install avr-libc after that you need to checkout the project from github. Details you can find there, but this is the command, you need (creates a folder in current directory):

git clone https://github.com/jackhumbert/qmk_firmware.git
 now go to the directory

qmk_firmware/keyboards/ergodox_ez. for testing, you should run make there, this will create the default layout .hex file in this directory. The file is called ergodox_ez.hex. If you end up with an error message, take a close look. Probably you only need to install some tools or something. If you want to create a different than the default layout, you need to store the name of your layout into some environment Variable: export KEYMAP=osx_de if you run make now, this layout will be created. If the corresponding C-File exists in the directory

keymaps (here the filename is keymap_osx_de.c. You can easily change an existing C-File, create a completely new one (not recommended), or copy an existing C-File and alter it to your liking. You only need to change the environment variable accordingly. If you need additional information about what possibilities you have with this C-Files and what is possible, have a close look at the project documentation. I really hope, this little howto is helpful for you and your new ErgoDox-EZ!

Features of the ErgoDox-EZ - layout programming details

As you now know, how to compile and upload a new firmware, let's have a look at the features, you might use in those firmwares. I call the process of defining the layout for your keyboard in C-Files "layout programming" - it is not real programming, although there a datascructures involved, some C-experience is surely beneficial. But it is not real programming... you usually do not need to do loops, if-then-else or something. But you need to know some things.

Keycodes

First, every key can be programmed so send any keycode a keyboard might have (and actually mouse also). So, it would be possible, to change the position of keys completely (e.g. DVORAK, NEO or ADNW layouts. All alternatives to the existing QWERTY/Z layout). You could also create a special layout for a special purpose. Like a special software, where you actually do not type a lot, but really use hotkeys and shortcuts. (like in a game or other special purpose software, CAD, PhotoEditing... whatever you use). In the QMK-Firmware, every of those layouts needs a corresponding C-File (see above). In this C-File there is the layout defined as an array of 64bit integer values, every

place in this array determines the key, the value of this determines the keycode that is going to be send from this key when pressed (or released...). Imagine the keys are numbered from the top left, to the bottom right, each half of the keyboard separately. So in my layout, the first keycode in this array defining it is the ESC-Key. The name for that in the C-File is KC_ESC. All "raw" keycodes have the prefix KC_, there are international definitions of keycodes also with their corresponding prefix for the country (like, DE_), but in my case, those keycodes were meant for Windows, not OSX. But that is no big deal, just think about what you would type.

Layers

You can have several of those layouts defined in the c-file. Actually, the data structure is an array of arrays, the latter ones defining a layout each. So, when you switch between layout, you can completely redefine the whole keys (with one exception - the key you use for switching between layers, see below) There is one keycode defined, called KC_TRNS, which actually is no real keycode but telling the firmware, "if this key is pressed, use the keycode from the layer below the current one". This does not work with the first (base) layout in your configuration, because we need to have something defined to fall back on. So, when you start up the keyboard, you start with that layer 0, the base layer. When you hit one of those layer switches, you switch to a different layer, lets say layer 3. That means, layer 3 is on top of layer 0. If you have any keys defined as KC_TRNS in layer 3, pressing one of them when switched to that layer, acutally issues the keycode from layer 0. And to make things a bit more complicated: you can actually stack those layers. You could define a layer switch with one key, pressing anotherone will add a layer to that stack. KC_TRNS will then fallback to the layer below in the current stack. This feature could be used, if you need a similar behaviour like with ALT and SHIFT. Think about it: when you Press shift, the keys switch all to upper case, when you press alt, some special characters occur. But when you hit both, the layout changes again, at least for some keys. Acutally, this stacking of layouts is pretty standard. We just were not aware of it... With that you could create your own more or less simple layout, without any layers or any fancy features like long type or something. This is - at least as I understood it - what you can get from the massdrop configurator.

Special keypresses

But there are features, you might enjoy...

  • you can not only send a simple keycode, but also one in combination with a modifier (like shift, alt, cmd, ctrl... and so on). This can be done easily by adding for example LSFT to your keycode, LSFT(KC_7) would send a shift 7 keycode - usually the /. In this case it is actually pressing the left shift for doing that, but that usually does not make much of a difference.
  • you can make a key not sending a real keycode but making a switch to a different layer. in the DE-Layout this is actually done with the "Tab"-key, just switches to and out of the cursor layer. Please keep in mind: your layer-switch key, should always be defined to have the keycode KC_TRNS in the target layer, otherwise you might not be able to switch back. Toggling a layer on and of is done with the function TG(), as parameter you give the number of the layer you want to toggle, like TG(3) which would switch to your layout on index 3 (always starting at 0 (baselayout), this is the 4th layer!).

  • you have the option to define keys to behave differently when pressed long or just typed quickly. This is useful for modifiers. You can have the hyper key issued when pressed long, but when typed it sends a normal keycode. There are actually several ways of achieving this behaviour. First you can use the method LT() where in the brackets you add two arguments. First the layer it shoul switch to, when pressed long, the 2nd one is the keycode to be issued when typed. The other way is to use functions with the suffix _T, like CTL_T(). This one means, issue the keycode for control when pressed and held, but send the keycode given as argument, when typed. In my layout definition this is used for the Y and Minus-key to be also used as CTRL. Which comes in quite handy some times. with that you can define quite some layout - take a look at the baselayout for the osx_de version:

    //Base layer KEYMAP(

        KC_ESC,                  DE_1,         DE_2,   DE_3,   DE_4,   DE_5,   DE_6,
    KC_TAB,                  DE_Q,         DE_W,   DE_E,   DE_R,   DE_T,   KC_LGUI,
    KC_LALT,                   DE_A,         DE_S,   DE_D,   DE_F,   DE_G,
    KC_LSFT,                 CTL_T(DE_Y),  DE_X,   DE_C,   DE_V,   DE_B,   KC_LALT,
    LT(SYMB,DE_LESS),        M(M_DE_CIRC_CTRLCMD),      M(M_DE_PLUS_CTRLALT), LALT(KC_LSFT),  LGUI(KC_LSFT),
                                                                    M(M_MEH_SH_ACUT),       TG(2),
                                                                                            KC_HOME,
                                                                    KC_BSPC,KC_DEL,         LT(SMLY,KC_END),
    // right hand
         M(M_CTRL_CMDC),  DE_7,   DE_8,   DE_9,   DE_0,   DE_SS,            DE_HASH,
         KC_RGUI,     DE_Z,   DE_U,   DE_I,   DE_O,   DE_P,                 DE_UE,
                      DE_H,   DE_J,   DE_K,   DE_L,   DE_OE,                ALT_T(DE_AE),
         KC_RALT,     DE_N,   DE_M,   DE_COMM,DE_DOT, CTL_T(DE_MINS),       KC_RSFT,
                              KC_LEFT,  KC_UP,KC_DOWN,KC_RIGHT,        LT(SYMB,DE_PLUS),
         TG(4),       ALL_T(DE_ACUT),
         KC_PGUP,
         KC_PGDN,KC_ENT, KC_SPC
),

One additional thing you should consider. When you have more than let's say two layers, it would be very useful to show the user, which layout is currently active. This is best done using the 3 different LEDs on the keyboard. To define that, you need to have a look at the method

matrix_scan_user. There you can do something depending on the currently active layer. In the case of the osx_de-layout, it looks like this:

void * matrix_scan_user(void) {

  uint8_t layer = biton32(layer_state);

  ergodox_board_led_off();
  ergodox_right_led_1_off();
  ergodox_right_led_2_off();
  ergodox_right_led_3_off();
  switch (layer) {
    // TODO: Make this relevant to the ErgoDox EZ.
    case 1:
        ergodox_right_led_1_on();
        break;
    case 2:
        ergodox_right_led_2_on();
        break;
    case 3:
        ergodox_right_led_3_on();
        break;
    case 4:
        ergodox_right_led_1_on();
        ergodox_right_led_3_on();
        break;
    default:
        // none
        break;
  }

};

I think this is more or less self explaining. The every case statement defines what to do for each layer. So for layer 0 (not listed here) all LED will be off. For layer 1, the led 1 will be on (the red one)... and so on. This function is called periodocally in a loop, so there you could add any other custom code, if you liked. These are the major features, I needed to implement my layout. There are more features, that might be useful (like stacked layers), but for now things work fine. I will work on improvements, if you have any suggestions, just leave me a note...

ErgoDox-EZ - Should you buy it?

Actually, that is a tough question. I think, it was worth it. But I use the keyboard only a couple of days now. I was quite fond of my "Razer Blackwidow" also and that changed over time. In this very moment when I'm typing this text I can only say, it feels very worthy, the switches feel like Cherry (but they aren't), the feedback is good as expected from a mechanical keyboard. Of course these switches do make som noise, you do not only get tactile feedback, but also audible one - I like that noise, but this is maybe not everybodys way of working. I installed dampener rings on the keys in order to reduce the sound wen typing through. But I actually like this "noise" a lot and it motivates me. But that is my personal opinion. And I ordered the ErgoDox-EZ with that Switches that are comparable with the Cherry blue ones, but there are different options. For me the ErgoDox-EZ is very close to the perfect keyboard. There are some things that might be missing (LED backlighting maybe). But I really like it. Right now, I like typing with the ErgoDox-EZ, it also helps me to go easy on my elbows and wrists, which are somewhat aching after a long day. This was one major reason in getting an ergonomic keyboard. I will maybe also create a ADNW-Layout (neo2 based layout, optimized for German and English typing), but that is a very different thing....

Update after one week: Still like typing a lot with the ErgoDox. Especially as i got my custom layout up and running. It makes things a lot more smooth. Typing is a breeze... Also, I have to say, the support from Erez and his team is great! Thanks again. I am really astonished, how quickly I could adjust to the new keyboard. After just a couple of days, it really felt awkward typing on a normal keyboard again. This actually is a good sign!

update after some weeks of use

I got used to the ErgoDox quite fast. Really still like typing on it. And I learned some things about my own layout: having space on both sides of the keyboard is actually not that great. I miss having the delete key easily accessible. So... I removed the space key on the left side of the keyboard and replaced it with backspace, putting the current backspace to be a DEL-key. This seems to work ok... And: I really was not using the CTRL-keys on the upper row. Used the keys on both pinky fingers for CTRL. That works better actually. I put CMD-C / CMD-V there... at least for now. Maybe I'll experiment with macros there... Did not come up with a better solution for that... Also still looking for something useful to put on the Caps-Lock-Key... right now its only a mode / layer switch. Did not come up with something fancy for that yet.  

Annother update - one month in to 2016

I really like typing on the ErgoDox EZ, it feels great, I'm quite fast and my layout seems to be working fine now for me. Although I needed to add some additional features:

Smiley Macro Layer

I thought I need to play a bit with macros and wanted to put some things I often type there. So I decided to create a smiley layer. This is available in the currently merged version of the firmware. When pressing the lowest, rightest key on the left halfs keyboard thumb block you temporarily enter this layer and can type smileys with the right hand side! Works like charm! 😉 :-D EgoShooter Layer The default layout I have created is optimal for typing (at least for me) - but it did not work at all for EgoShooters like Counterstrike global offensive or alike. I had to create an additional layer. But I did not want to waste a key just for switching to this layer, and - obviously - did not want to have a key pressed all the time in order to be "temporarily" in that layer. I wanted to switch from one layer to this new layer and only there... Right now, when enter the symbol / coder layer you can switch to the ego shooter layer by typing the top left key on the right keyboard half. Then all 3 LEDs will be on indicating that you are ready to go for some serious ego shooting ;-) The changes are more or less minimal: * left side backspace becomes space * left side delete becomes control * left side < / symbol layer switch becomes Ctrl * the outer thumb keys on the left side become F1-F4 maybe there will be some additional changes to this, but right now, it seems to work quite good. Happy fraggin'

** Another Month - another update **

Still love typing on the ergodox, but I start feeling uncomfortable writing on a "normal" keyboard. I had to install the "reinforcement kit" last week, as I got one of the ErgoDox-EZ' with a slight fault (look here)

For some reason, I did not like having the numbers on the right side starting with 6, I wanted them to start with 7. So I changed the layout to reflect that. That works fine for me and has some advantages:

  • I could put the # to the top right key
  • I could put the F12 there as well
  • the 6 is now on the left side, top rightmost key. This was CMD-V before. Missing that to some extend. I'll have to have a look for that.

as some time went by, here is a new update again

I played with the layout a bit again. I did not like the asymmetric shape of the numbers, and it did not really work well. I changed a lot of things today:

  • moving cursor key layout back to the "deafult" ergodox
  • adding ISO-Cursor keys to the symbol layer
  • adding a CTRL-SHIFT key on the rightmost, topmost key on the left half
  • needed to move the # somewhere useful. Put it on the topleft key on the right half
  • some fixes, especially adding a , to the number pad. This caused problems with typing some numbers already

maybe this is the best layout for my case. I was astonished how hard it is to get rid of the "used" positions of keys. And I actually do not like to move things to totally different locations - this would mean I cannot type on an usual keyboard anymore fluently. And this is not working with carrying the macbook from meeting to meeting.

really like playing with the programming of the ergodox! this is fun. And it will improve the layout over time. Still need to find some way to build these layout pictures somewhat more easily - right now is's pain!

** Update on documentation **

The layout went through some iterations till today and for now it seems to be ok. Go check it out at github. There is also a new Project I created that (for now) helps me createing a png of the layout so that you get a better overview. Later this might be used to create layouts as well.

Check the post here and the github page here

the current layout looks like this: