October 24, 2021

Ergodox EZ customization - let's do it!

The above purports to be documentation about how to do this. I want to start by making a simple change. I want "space" to be in the same place for both right and left thumbs. This means moving return somewhere (for now anyway) or temporarily doing away with it. To start we will just try to nuke return (on the right thumb) for now and make it a space.

The game starts with Oryx, which is their graphical configurator. See the link above. You go to the link, select the Ergodox EZ, select configure, and you are well on your way. I click "modify", then assign a name "Vim for Trebisky". Then I click on the offending key that is currently "return" and find "Spacing: space" and bam, the key is redefined.

A big button at bottom center says "compile this layout", so I click that. I am told that Oryx generates C code. Whatever the case, when compiling is done it offers to let me download the result. I click the download link, and "bam" it downloads a hex file: 

/home/tom/Downloads/ergodox_ez_shine_vim-for-trebisky_ENybG_6GzWE.hex
I copy this to /home/tom/Ergodox

It also warns me that I will need version 2.10 of wally. I run the wally I have and there is simply no telling what version it is, and it won't tell me in any of the usual ways. They provide links to download a suitable version, including one for linux, so I just download what they are offering. The file I get is different, and smaller than what I downloaded back in August of 2020. I rename my old "wally" and replace it with what I just downloaded (putting it into /home/tom/bin).

I cd to my Ergodox directory and type "wally". It fires up a GUI (the old version just gives an empty blank window) with a button saying "Select File". I have to navigate to the Ergodox directory, which seems a bit lame since I just made sure to selet that as my current directory. It then cues me to use a paperclip to press the reset button on the keyboard, which I do, and "bam" I am running the new firmware. You don't have to hold down the hidden button, just click it and wait a second or two. A quick test shows that the right thumb now gets a space where it used to get a return.

Now what I do is to create an account and then repeat the process while logged in. This after finding my prior layout just evaporated. Such is cloud computing and why we would rather have all the files on our own machine. But I had virtually no time invested yet.

Downloading the source

There is a link right at the bottom of Oryx to download the source. Click this, and "bam" you get a zip file in your Download directory. It contains the hex file along with other stuff, including 3 actual source files: 
config.h
keymap.c
rules.mk
The file "keymap.c" is the heart of the issue, the rest is just boilerplate. Given this, you could jump into the next section and learn enough to abandon using Oryx.

The file "keymap.c" is not all that big, only 218 lines of C source.

QMK and real hacking

Oryx is just a cloud based graphical front end to the QMK firmware build process. You can clone QMK from github and hack the C source if you wish instead, thus becoming a true "macho dude".

What about training and such?

Now it simply tells me "no compatible devices found". I suppose I can do without live training, but this is unfortunate.

Some searching suggests the following. First add this line to /etc/udev/rules.d/50-oryx.rules 

SUBSYSTEM=="usb", ATTR{idVendor}=="3297", GROUP="plugdev"
Then unplug and replug the keyboard. Then restart chrome.

This works! All thanks to a reddit post.

It even says "Vim for Trebisky", the very label I gave my layout in Oryx.

In fact, a bit of close examination shows me that live training and oryx configurating are both aspects of the same Oryx cloud based setup.

Visualization

I ran across this and liked it. It is a nice bit of python code for one thing. It is for the moonlander, but the idea has merit and I hope it wouldn't be too hard to adapt it for the ergodox EZ.

Have any comments? Questions? Drop me a line!