About a week in, a few tips and findings

After roughly a week with the Keyboardio, I am in love with my new keyboard; I’ve gone well beyond a layout that approximated my old ErgoDox EZ to really digging into the internals and making it my own. It’s a lovely piece of hardware, and the Matias Quiet Click are now my favorite switches. Here are a few things I thought worth sharing.

Shifted keys on the default layer

I program Ruby, which means underscores all over the place. Normally this key is a little out of reach, and while the default Keyboardio layout puts it in an easier location, I try to optimize against stretching my right pinky as much as I can as this has been a source of past RSI, so I stuck the underscore in a thumb key.

For the most part doing this with a simple LSHIFT(Key_Minus) was fine, but when I really got typing fast I’d notice the letter following the underscore would sometimes come in capitalized. I don’t know if this should count as a bug, but regardless I was able to fix the issue myself by using a macro instead:

Macros.play(MACRODOWN(D(LeftShift), T(Minus), U(LeftShift)));

This seems to prevent accidental shifting no matter how fast I type.

Mouse keys

For mousing, I use a Magic Trackpad, rotated 180 degrees for a negative incline (the Mac tool Karabiner lets you do this) combined with a gel wrist rest. It works great, but clicking is a bit straining, and dragging things way across the screen is sometimes a problem (and I’m not a fan of the 3-finger gesture for doing this, it doesn’t really solve this problem).

My solution was to change the Prog key into left-click. Now I can drag to my heart’s content. In fact, I’ve found myself using this for pretty much all clicking, it’s just much less straining. I liked it so much I went ahead and changed the LED key to right-click.

Using Prog to Prog

I build and flash the firmware from the command line, which requires you to hit Enter once you’ve got the Prog key down and you’re ready to flash. Having that set to click got annoying, because I had to remember to make sure the mouse cursor was positioned over the terminal window so I wouldn’t click out of the app before hitting Enter.

My first solution was to use XXX to block that key on the Fn layer, so instead of holding Prog and hitting Enter, I’d do Fn-Prog and hit Enter, preventing the click. Then I got clever and set Fn-Prog to Enter, saving a step and eliminating the mouse click problem at the same time. Using a macro to hit enter with MACRODOWN prevents it from sending a ton of Enter keys to the terminal while the firmware is flashed.


The Butterfly key uses the OneShot plugin to switch to an emoji layer, where the keys are mnemonics for my most frequently used emojis:

Butterfly-T = :thinking:
Butterfly-S = ¯_(ツ)_/¯ (stolen from Algernon’s firmware)
Butterfly-K = :kissing_heart:
Butterfly-B = :beer:
Butterfly-C = :beers:

I’ll probably add many more over time.

Surprisingly, this customization took a good amount of time to figure out. The main thing? You need to pass in the UTF-16BE (Big-Endian) hex code for your emoji. Unicode Table quickly became a favorite resource. So, for example, the beer emoji:


Can’t find the serial port??

I was getting an error very similar to the one described here (if not exactly the same; I don’t have that scroll buffer anymore): "Can't find Model 01 serial port name" on macOS

I went and made sure I had the latest master as described in that thread, but no avail. The only way I could reflash the firmware was to unplug the keyboard and hold Prog while plugging it in (as someone described in the linked thread). After too much time debugging, I figured out that it seemed to be caused by KALEIDOSCOPE_HOSTOS_GUESSER. Disabling this and setting my OS manually got me back to consistently flashing the firmware without issue. The proper way to set the OS wasn’t documented. This line in the setup function does it for me:


Hopefully this will be helpful in tracking down that bug! In the meantime, I’m fine with setting the OS manually as I’m only using this keyboard with my main machine.


The included pods are pretty great! Definitely a huge improvement over the little tenting arms that come with the ErgoDox EZ. But…

For a few days I had my keyboard mounted to the arms of my desk chair…this is the dream. I used these:

It worked…ok. The adjustability was alright, and the stability was pretty decent…for a while. The problem is those little clamps couldn’t really get a grip on the arms of my chair due to the shape of them, so they would slowly get looser, which is not good. The clamps are really meant to attach to a bar, such as on a mic stand.

What I may end up doing, unless I find an easier solution, is spend a little time in the woodshop and build some custom clamps that attach to chair arms and have a protruding dowel rod for the camera mount clamps to attach to. That is unless there’s a part like a t-nut with the right threads I can just stick directly into my custom clamps (fewer moving parts would be ideal). I’ll take suggestions here, and I’ll be sure to update when I have a satisfactory mounting setup.

Word-editing layer

Something similar I had on my ErgoDox EZ. I have a thumb button that switches to a layer with Alt-Arrow keys and Alt-Backspace for word editing. I do this a lot, and while I could do it by chording, a single modifier key is nice to have.

Unicode on Mac

Another issue I had with the emoji layer was getting them to actually type correctly. It was a minute before I noticed the note at the bottom of the Unicode plugin that I found that I needed to change my Keyboard Preferences to use the “Unicode Hex Input” input source. I did that and things were working great.

That is, until I noticed that my word-editing layer was not working in certain apps. Apparently the included Unicode Hex Input configuration on macOS doesn’t configure this for you. While I can’t remember everything I did to correct this, a combination of a tool called Ukulele, restarting it a few times (seems to be kind of a buggy tool), and logging out and back in eventually got me where I was able to consistently use my word-editing layer across all apps. Hopefully if anyone runs into a similar issue they’ll find this post and it’ll point them in the right direction at least.


Alfred is a great tool for so many reasons. I’ve assigned the Any key to LALT(Key_Space) for the easiest possible access.

Alfred can also be used to set up universal shortcuts. The Function keys are great for switching to the same app every time (unlike GUI-Tab which is forever changing the order out from under you if you’re moving about rapidly). In the past I used this in conjunction with my ErgoDox to make an app-switching layer, where the assigned function keys were on mnemonic letters for those apps. This time around I’m just using the function keys where they are by default with the Fn key which is working fine. The palm Fn-key truly is a game-changer in general.

That’s it for now

I am absolutely loving this keyboard. I like it better than my old Kinesis Advantage, and better than my ErgoDox EZ. The wait was long and arduous, almost 2 years from preorder to delivery, but it was well worth it. Perhaps soon I’ll be almost done tweaking the ever-loving crap out of it, and maybe even get some actual work done!


Here’s what’s killing me, I can’t for the life of me modify the macros in any way. The documentation doesn’t seem to match the code base at all. I get errors even if I’m mimicking the predefined macros just for testing. It seems like the firmware version loaded in Arduino is maybe different than what’s in the documentation and I’m really unfamiliar with C++ file structures, so I’m super frustrated trying to just make a basic change.

You may have firmware out of date. Last time I had to make major changes I wanted to update to the latest firmware and the path wasn’t exactly straightforward. I assume this issue might be mitigated by using the Chrysalis software rather than modifying the firmware by hand, assuming your goals are achievable within Chrysalis. I’m fairly certain mine are, but Chysalis wasn’t in a usable state for me back when I first got my Model 01. Now that it is, I’m planning on switching over to it at some point, but as this will take some effort, and my layout has been pretty stable for a while, it’s not a top priority.

If you’re still having issues, start a thread in the appropriate subforum and I’m sure someone will be happy to help!

1 Like

@cvincent - I can’t get Chrysalis to work on either my PC or my Mac either, so maybe you’re correct about the firmware not being the correct version, but I did download, build and install (I think) the latest version from GitHub. The big selling point for me with this keyboard was the ability to program my own behavior so it’s frustrating not to be able to do that.

Can you share what kinds of errors you get, and perhaps the code you’re trying to use, too? That’d be a huge help for us to be able to assist you in fixing those errors.

1 Like