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

GitHub repository: ergoblue/src-adafruit
Code for the controller is in the "control" directory and can be compiled with a Go compiler.
Code for the keyboard halves is in the "keyboard" directory. You need Arduino along with my fork of Adafruit's nRF52 Arduino package.

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.

Non-modifiers are released immediately when they are pressed.
Modifiers are released along with the next non-modifier key.
Typing in the standard manner will continue to work since you press the modifier before the non-modifier key; the firmware just doesn't care whether you release the modifier before or after pressing the non-modifier key.
Pressing a modifier for the second time without having pressed an intermediate non-modifier will also release the modifier modifier.
There is a modifier lock that keeps the subsequent modifier pressed until the corresponding modifier key is pressed again. This is necessary for Alt-Tab on Linux and Windows and Cmd-Tab on MacOS.

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.

Add function resumeLoop() so the main loop can be resumed after an interrupt event. This allows the keyboard to suspend the main loop and sleep when nothing is pressed.
Remove code relating to DFU over Bluetooth.
Add function for setting the BLE slave latency. This reduces the frequency with which the microprocessor needs to receive data from the controller, thus reducing energy consumption.

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.

Determine the MAC address of the Raspberry Pi functioning as the keyboard controller.
Add the aforementioned MAC address to keyboard/keyboard.ino.
Load the program onto both 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.

Update control/main.go with the MAC address of the two keyboard halves.
Define Bluetooth devices and configure each with the appropriate MAC address, keyboard layout, and operating system.
Define configuration for USB keyboard (usb163) if desired.
Define the default output device that the controller defaults to on boot.
Use bluetoothctl to pair with the two keyboard halves.
Run go generate in the control directory.
Build everything in the control directory to /root/bin/control.
Start server with control/boot.sh.

Return to parent post