Keyboardio is a family company made possible by the maturation of open hardware. Since 2017, it has been selling mechanical keyboards that quickly found a high-end niche market among keyboard enthusiasts, including me. However, for even longer, it has been working to develop Chrysalis, a graphical interface for customizing keyboard layouts. When I recently bought a Model 100, Keyboardio's latest flagship product, I assumed that by this time Chrysalis would be fully operational after nine years. Instead, here is what I found.

My expectations were high, given the careful attention Keyboardio pays to other aspects of its business. As a customer from Keyboardio's first fundraiser, I have long been impressed by the company's quick support and its interaction on its community forum. Physically, too, Keyboardio's products have had considerable thought put into them, and are so ergonomically advanced that I can type up to 10 hours a day without any strain on its Model 01 and Model 100 products (Figure 1). Both are minimalist boards of 66 keys divided into halves, each of which is designed to minimize finger movement. In addition, the halves can be placed as close or as far apart as desired, and, by adjusting their stands, slanted to almost any angle. Moreover, with the keys mounted on slabs of maple or walnut, these two boards have an unparalleled elegance in a field dominated by functional concerns. The Keyboardio Atreus is less aesthetic, but is equally well-designed for its role as a portable keyboard for laptops with full-sized keys.

Figure 1: Keyboardio's flagship product, the Model 100. It replaces the Model 01. Both keyboards look similar.

Meanwhile, the customization of keyboards remains less polished. The Model 100 comes with firmware pre-installed, but, as with many mechanical keyboards, the customization of individual keystrokes or entire layouts (or layers) is a major selling point. However, the Model 100 ships with only a single link to how go about the process – and the link is not to the necessary how-tos, but to basic pointers about using the keyboard. Basically, setup involves installing Kaleidoscope, Keyboardio's firmware, and creating a sketch (source code) in Arduino IDE, using keycodes to create a map of a layout and to write macros, and then, finally, to compile and flash the sketch’s binary on to the board itself (Figure 2). To say the least, this is a laborious process, and a moment's inattention will cause it to fail. Admittedly, users are likely to modify existing samples, and unlikely to write a sketch entirely by themselves. Yet, as Gergely Nagy (aka Algernon), a contractor who has been a lead developer for Chrysalis from the start, told me in 2019:

"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 2: The Arduino IDE showing a sketch for the Model100 scrolled to a keymap.

Chrysalis gets around this obstacle by installing with only the parts of Kaleidoscope that are absolutely necessary, and flashing changes at a single click. Yet even it has obstacles of its own. While urging users to try Chrysalis, its GitHub page describes Chrysalis as "alpha quality software." Moreover, the first time it runs, Chrysalis warns of a bug in early versions that needs to be fixed immediately, but without explaining where to find the current version number (it's in the top left-hand menu). It then goes on to give online instructions that were added to the online documentation because of a bug. Before users even try Chrysalis, they may be deterred almost as much as by using Arduino IDE.

Chrysalis in Action

All the same, despite these shortcomings, Chrysalis is still easier to use than creating a sketch in Arduino. Upon opening, Chrysalis locates a keyboard attached to the system (Figure 3), then opens on a map of the default layer. Below the map is a standard full-size keyboard to select key assignments from. Changing a key is as simple as selecting a key on a given layer and clicking a replacement on the full-size keyboard, then clicking on the Save Changes button in the lower left corner (Figure 4). Further customization is available from the right-hand pane (Figure 5). By choosing a layer on the top of the right-hand pane, another layer can be mapped separately, or customized with a standard key layout like Dvorak or Qwerty by pressing the Backup and Restore button. Once you have more than one layer, you will also need to choose a key for switching layers from Layers and Keymaps. In addition, from the Preferences menu (Figure 6), you can set the default layer and print a map of each layer for easy reference. Keys may also be set as Blocked or Transparent to affect if they can be read by higher layers.

Figure 3: Chrysalis-s pane to select a keyboard to edit.

Figure 4: Chrysalis' keyboard selection editor. Above: The Model 100's key layout. Below: A standard keyboard from which to select a keymapping.

Figure 5: The pane on the right lists possible customizations.

Figure 6: Chrysalis' menu contains tools for preferences and non-editing tasks.

For simple macros, the kind usually activated by keyboard short cuts, you can choose a modifier then a key. For example, I have a layer designed for editing text with keys for Cut (Ctrl+X), Copy (Ctrl+C). Paste (Ctrl+V), Undo (Ctrl+Z), and Save (Ctrl+S). Each of these only saves a single keystroke each time it is used, but during a day's work those keystrokes add up, saving time and stress to my hands. For now, more complicated macros must somehow be placed in a sketch, which is a problem in itself (see below). Perhaps the process is still unimplemented? Some are referenced in Chrysalis under Dynamic Macros and Macros. Others that must go into a sketch include Secondary Action, or events triggered when a key is held down, rather than merely pressed, and Tap Dance, or keys that activate different actions depending on how many times you tap them, as well as One-Shot, Space Cadet, and Leader. All these latter choices will be familiar mainly to many keyboard aficionados who may have used them on other customizable keyboards. Some will need to be enabled and defined in the menu (Figure 7). Still other options include controls for LED backlights and their Brightness, as well as for computer Volume, Media Control, and Mouse Controls. With such choices, a minimal keyboard such as the Model 100 can have just as much power as a full-size keyboard, and often far more.

Figure 7: The menu includes settings for advanced macros.

Alpha Performance Problems

Perhaps two-thirds of the time, Chrysalis is serviceable; although, for advanced choices, Arduino sketches remain necessary. For that other third, the fact that it is alpha software becomes obvious. When changes are saved, Chrysalis may randomly time out, leaving keystrokes erratic or unresponsive on the Model 100. Fortunately, this alarming behavior can be fixed by unplugging the USB cable and replugging it, but the failed customization must still be tried again. Another major problem is that once a key is selected for customization, the only way to unselect it is to close Chrysalis without saving. However, the greatest problem is that nowhere are users informed that Chrysalis overrides any subsequent changes made with an Arduino sketch. Because sketches have more options than Chrysalis and are required for macros, this is no small problem. To use a sketch after using Chrysalis, you must first do a factory reset, then run two utilities buried in the Kaleidoscope directories. Because this knowledge is not given up front, the result can be hours of frustration for both users and the company’s support as properly written sketches fail to have any effect despite being successfully flashed.

To be fair, Keyboardio is a small company with limited resources, and new product development likely has a higher priority than Chrysalis. Perhaps unsurprisingly, much of the company's efforts have gone into its Kaleidoscope firmware, an extremely stable piece of software whose GitHub page lists 107 contributors, with half a dozen having over 50,000 commits, and several dozen others having made 50-500. By contrast, Chrysalis' GitHub page shows that most of the work has been by two developers, each of whom has vastly more commits than the other 40 contributors combined. Assuming my experience is typical, in the end I question whether the company should be encouraging customers to use such unfinished software or take so long to develop it. Both choices seem against its own interests. For myself, I feel safer falling back on the Arduino ID, my only consolation being that I will probably need to make few additional changes for a year or two. Yet just because I can usually fumble through complex instructions does not mean I am eager to do so. As reluctant as I am to criticize a product I admire and depend on daily, a reliable version of Chrysalis is years overdue, to say nothing of more documentation.