By definition, open hardware requires open source software. However, the software is often overlooked, because the hardware is more tangible. Yet the software being written for open hardware often leads to new results and industry standards – everything from utilities for securing mobile devices to applications for prosthetics. A case in point is Chrysalis [1], the graphical interface for the Model 01 keyboard from Keyboardio [2]. Recently, I talked to Gergely Nagy (aka Algernon), the contractor who is the lead developer for Chrysalis, about the history of the project and where its development is heading.

Keyboardio is a small company that began shipping its stylish, ergonomic, and programmable keyboards in November 2017. It has shipped thousands of Model 01 keyboards, each powered by an Arduino ATmega3244 microcontroller. The advantage of using an Arduino is that the Arduino IDE includes a feature for flashing the firmware, which allows for both programmable keys and layers or multiple keyboard layouts that can by swapped in and out in one or two keystrokes. In fact, the Model 01 supports up to 32 layers. Flashing the firmware makes all this customization possible.

The Arduino IDE is easy to use if you have programming experience. However, for ordinary users, as Nagy points out, "Flashing can be very scary, for a multitude of reasons, and you need special tools for it, often with arcane incantations to make them do what you need them to do. And programming keyboards? Eeeh, not friendly at all. For the average person, who just wants to rearrange their layout, having to install Arduino and edit source code is well past their comfort zone. Some are willing to go there and end up enjoying it, [but] many are not" (Figure 1).

Figure 1: Without Chrysalis, flashing firmware requires editing a text file while referring to a list of key codes.

Chrysalis is named for Keyboardio's butterfly logo, which is derived from the shape of the Model 01's divided keyboard. You do not have to be an English major to infer from the name the suggestion that Chrysalis will transform open hardware keyboards in general and allow them to take flight and realize their full potential. What Chrysalis does is allow the editing of the firmware already on the keyboard, rather than uploading a new file from the Arduino IDE.

"With Chrysalis," Nagy says, "you don't need to know what keycodes are, or what you can or cannot put on a keymap. You don't have to deal with syntax errors. You don't have to deal with source code, nor compilers, nor flashing tools. You just launch the application and click your way through. It's much more limited than programming, indeed. But for the things it offers, it's so much friendlier, too." In effect, Chrysalis opens up keyboard customization to users who might not otherwise attempt it.

The Road to Chrysalis

Nagy can pinpoint the date he started using Linux: December 26, 1996. He started using Debian two years later and became a Debian Developer in late 2000. What he calls his "drive-by contributions" include syslog-ng, Riemann, GStreamer, and the Hy programing language. His introduction to keyboard firmwares came from contributing to QMK Firmware, which develops firmware for open source keyboards and is used by at least half a dozen projects and companies, including Planck, ErgoDox EZ, and Atreus [3]. For QMK, Nagy developed Tap Dance [4], a feature that allows keys to type different characters depending on the number of times they are struck.

Nagy's involvement with Keyboardio began around the time that the company was running its crowdfunding campaign in 2015. As he details in his blog [5], his current keyboard needed replacing; he pre-ordered a Keyboardio Model 01 and bought an ErgoDox EZ to use while waiting for his Model 01 to ship. "That led me down a deep, deep rabbit hole," Nagy says. "I like to tweak things, and having open source firmware at my finger tips was too much temptation to resist."

Nagy found that the ErgoDox EZ was not to his liking, but none of the other open hardware keyboards could match the ErgoDox EZ's features. "A lot was missing, and the firmware wasn't set up the way I like," he says. After a short-lived effort to write his own firmware, Nagy was hired as a contractor for Keyboardio in late 2017, where he continues to work on Keyboardio's Kaleidoscope firmware. He began working on Chrysalis "because I felt there's a need for it, and no one else was working on anything similar. Most GUIs for open source keyboards were inadequate, as they allowed one to save a HEX file one could later flash. I wanted something that can directly talk to the keyboard, to allow people to change layouts, colormaps, you name it, without having to compile anything, [and] without the need to reflash the keyboard."

Nagy did look at Agent, the configuration tool for the Ultimate Hacking Keyboard [6]. However, he concluded that "the protocol it uses is way too complicated and rigid for what I had in mind. I wanted the protocol to be easily extensible." In consultation with Jesse Vincent, Keyboardio's cofounder and CTO, Nagy developed "a very simple protocol between keyboard and host over USB. A human readable one, too. One that is easy to implement on the firmware side, and easy to work with on the host side, too. One that is also incredibly easy to extend, because it doesn't have many rules and is more about convention than about policy. Chrysalis is built on top of this protocol, but the protocol itself is not tied to it in any way. I can talk to the keyboard from the shell, from Emacs, from Python, or anywhere else, too."

A development team quickly formed. Besides Jesse Vincent, in the early stages, James Cash developed code and was responsible for the original keymap editor. Simon-Claudius Wystrach contributed to the interface, while Matt Venn of Dygma Labs contributed ideas and mock-ups.

In addition, Nagy credits his wife, Csilla Nagy. "Plenty of the polish that's going into Chrysalis recently [is] going in because we discussed the UI, and she gave me ideas, or pinpointed pain points. You see, I'm not a UI developer. I'm not even a JavaScript hacker. I'm much more comfortable in lower-level things. My preferred form of working on my layout is C++ code (I'd say Lisp, but I've yet to build a keyboard with an MCU that can run Lisp). I don't even particularly like UI development, either."

By the time the Model 01 shipped in late 2017, Chrysalis was starting to become usable. However, at the same time, Nagy realized that, as currently structured, the project was not sustainable.

One problem was that Nagy had become almost the sole contributor – and at the time, he was working a full-time job and had recently become the father of twins. The situation improved when he became a Keyboardio contractor, but he adds that "most of my time was still spent on firmware, as that was deemed more important at the time."

Neither was the situation helped by Nagy's early decision to develop in ClojureScript [7]. Nagy made the decision because he was familiar with the language and enjoyed writing in it. "This," he says, "had the advantage that I was able to come up with a proof of concept pretty fast. But it also had a huge downside: Very few people know ClojureScript, and even fewer have Model 01s. So the pool of potential contributors was small." In addition, Nagy admits that the first version of Chrysalis "also showed signs of me not being a UI person. It wasn't designed well and had very rough edges. It wasn't easy to work with, even for someone familiar with ClojureScript."

Because of these problems, around the time that the Model 01 shipped, Keyboardio made the decision to rewrite Chrysalis in JavaScript. Nagy remains the main contributor, but, as I write, he has recently released version 0.0.6 of Chrysalis [8] for Linux, macOS, and Windows. It features a revamped interface, but its support for other features remains limited.

A Quick Tour of Chrysalis Today

According to Nagy, Chrysalis "talks a very simple, text-based protocol over USB serial. The most interesting parts are the firmware, really. With the factory firmware that the Model 01 ships with, the keymap is stored in read-only memory, [and] we're obviously unable to overwrite that without flashing. We can't use RAM to store the keymap either, because that doesn't persist through keyboard reboots – and RAM is also the most limited resource on the board. So we store a few layers in EEPROM 9 (Electrically Erasable Programmable Read-Only Memory) [9]. Chrysalis asks the keyboard for the keymap, how many read-only layers it has, and which one is the default one. So it can present all the layers, and a few extra with which one's free to do as desired. [Y]ou do have to pre-allocate space in EEPROM for the extra layers."

Currently, Chrysalis allows users to select a keyboard (Figure 2) and then make minor adjustments to a keymap or create a new layer (Figure 3). Macros are not supported. If you have the Colormap plugin installed [10] – which must be enabled by flashing – you can also set the LED backlights behind each key (Figure 4). It also can flash new firmware, allowing users to customize without using the Arduino IDE, although the firmware still has to be edited elsewhere.

Figure 2: Using Chrysalis begins with selecting the input device.

Figure 3: Individual keybindings and entire layouts are supported.

Figure 4: The backlights of keys can be customized if the keyboard's firmware includes the Colormap plugin.

The results of editing in Chrysalis are not imported to a new firmware file, but rather saved directly to the keyboard.

At this stage, Chrysalis is at a late alpha or early beta state. However, it has already started to make its influence known. Dygma [11], which participated in early development, plans to use Kaleidoscope for the firmware in its keyboards and continues to follow the development of Chrysalis as well. In addition, two years ago, I was told that Kaleidescope and Chrysalis are the basis of the interface for Input Club's customizable keyboards [12]. Despite the rewrite, Chrysalis appears well on its way to answering the need for an easy way to customize open hardware keyboards. With contributions from one or two programmers, its influence would be felt faster, but for now, at least progress continues, even it if is slower than customers would probably prefer.