Troubleshooting

Flashing the bundled firmware fails

There are a number of reasons flashing the bundled firmware can fail. The two most common ones are insufficient permissions, and forgetting to put the keyboard into programmable mode.

To flash a new firmware, most keyboards require you to put them into a programmable mode. For example, on the Keyboardio Model01, this means holding the Prog key when flashing — but the firmware update page will tell you what to do in most cases.

The other common cause is insufficient permissions. The user running Chrysalis needs to have access to the keyboard device. When connecting to the keyboard with Chrysalis, it will list the device filename under the keyboard name on the keyboard selection screen. The user running Chrysalis needs to have write access to this file. On Linux and OSX, you can look at the permissions by running ls -l <FILENAME>, and looking at the permissions and the owner. In most cases, adding your user to the group that owns the device, and logging in again is sufficient. You can do this with adduser $(whoami) <group> on Linux, and with usermod on OSX.

On Linux, you may suffer interference from ModemManager. You can check if it is running with a command like systemctl status ModemManager (output from Ubuntu 18.04):

$ systemctl status ModemManager
● ModemManager.service - Modem Manager
   Loaded: loaded (/lib/systemd/system/ModemManager.service; enabled; vendor preset: enabled)
   Active: active (running) since Mon 2019-10-21 23:07:23 PDT; 12min ago
 Main PID: 1023 (ModemManager)
    Tasks: 3 (limit: 4915)
   CGroup: /system.slice/ModemManager.service
           └─1023 /usr/sbin/ModemManager --filter-policy=strict

...
Oct 21 23:19:08 host ModemManager[1023]: <warn>  Could not grab port (tty/ttyACM0): 'Cannot add port 'tty/ttyACM0', unhandled serial type'
Oct 21 23:19:08 host ModemManager[1023]: <warn>  Couldn't create modem for device '/sys/devices/pci0000:00/0000:00:14.0/usb3/3-12': Failed to find primary AT port
Oct 21 23:19:20 host ModemManager[1023]: <info>  Couldn't check support for device '/sys/devices/pci0000:00/0000:00:14.0/usb3/3-12': not supported by any plugin

This output indicates that ModemManager is trying to grab the keyboard's device node. To temporarily disable it run sudo systemctl stop ModemManager — ModemManager will return upon reboot. To disable it permanently, sudo systemctl disable ModemManager.

Keyboard not detected

"No keyboards found!"

If you're not able to see your keyboard when first opening Chrysalis consider the following.

• Chrysalis doesn't work with Windows 8.1 out of the box.
  • Regarding this, Algernon said, "it needs a separately installed USB serial driver. There are a few of those around, but I had no luck with either, sadly."