Return to parent post

ErgoBlue Firmware

The firmware on my original ErgoDox was implemented with custom code on top of QMK. However given the features that I wanted on my ErgoBlue keyboard, it made more sense to design the entire firmware from scratch. It's fairly straightforward to customize if you have some programming experience since Go is a relatively simple language.

Source Code

Keyboard Layout

As Colemak user, the firmware has first class support for alternative keyboard layouts. These are sometimes handled by the operating system and other times by the keyboard itself. On your laptop, the layout is handled by the operating system since laptops typically come with a QWERTY layout. On your desktop, your keyboard may have a Colemak mode that does not require any changes to your operating system. Given that I use my ErgoBlue with both, occasionally swapping quickly between the two, the firmware must support both.

The mechanism for inputting non-ASCII characters (such as accented Spanish characters) differs between operating systems. The firmware allows keys to be defined such that the output sequence depends on the operating system. For example for the é character, the firmware will do Alt-E-E on MacOS and iOS and AltGr-E on Linux and Windows (assuming they have been configured with an international English layout). Other things such as emojis currently only work on Linux as it relies on inputting arbitrary Unicode code points using Ctrl-Shift-U. This can be trivially extended to work on MacOS and Windows, which also have some form of Unicode input.

For users that do not use QWERTY or Colemak, the firmware can certainly be customized to your own layout but you will to need to write a bit of code to customize it.

Support for Multiple Devices

One of the most important features of the firmware is seamless switching between different devices. This is particularly helpful when doing cross platform development where I am constantly switching between multiple devices. Keys such as Home can be configured to send the key itself on Linux and Windows and Ctrl-Arrow on MacOS and iOS.

The keyboard layout and the operating system is defined for each MAC address and the firmware adjusts the output accordingly. When using the Raspberry Pi Zero W as the controller, one device can use it as a USB keyboard. The keyboard can also be used with the Raspberry Pi itself.

It is possible to extend the firmware to switch a mouse to the same device as the keyboard. However there is some non-trivial amount of work to get the mouse latency to an acceptable level.

Keyboard Layers

Very much like in QMK, I have grouped keys into a number of different layers. If you are not familiar with the concept of layers, take a look at QMK's documentations. If you would like to see the exact layout, you should look the code in control/keymap.go. There may be a future blog post on the rationale behind my specific layout.

While my firmware only implements a small subset of all the possibilities, the hope is that it has been written in a way such that it is easy to extend.

Sticky Key

The firmware currently has no concept of holding down a key. Sticky key is on by default.

If software that you are using requires correctly knowing when a key is released (such as for many games), you will need to make some changes to the controller firmware. It should be reasonably straightforward if you have prior programming experience.

N Key Rollover (NKRO)

The firmware for the keyboard halves fully support n-key rollover (NKRO), though it is not handled by the controller due to my preference for having sticky keys. 6-key rollover should be reasonably straightforward to implement. N-key rollover should definitely be doable when using the controller as a USB keyboard. You will likely need to change the HID report format to one mentioned in TMK's documentation. This may or may not extend to HID over Bluetooth and I have no experience with that.

Security Considerations

I have not spent enough time assessing the security of the code and the way the code handles Bluetooth and can therefore make no security claims. Standard disclaimers apply.

Adafruit nRF52 Fork

My fork of adafruit/Adafruit_nRF52_Arduino contains a number of changes that is necessary for the ErgoBlue keyboard microprocessors.

To use this fork, the easiest way is to replace the appropriate Arduino directory. On MacOS, the directory is Library/Arduino15/packages/adafruit/hardware/nrf52/0.9.3. The version number may differ. The location on Windows and Linux is likely similar.

Keyboard Setup

Here is a high level overview of how to setup the two keyboard halves.

Raspberry Pi Setup

Here is a high level overview of how to setup the Raspberry Pi to be used as the keyboard controller. This omits a lot of details that are more evident in the source code.

Return to parent post