← Homepage

[Linux] · · 2 min read

How to make Linux properly dectect your ZSA keyboard

TL;DR

The Moonlander Mark I and other ZSA keyboards can be flashed with a modified version of their firmware through a software called Wally. ZSA also offers a browser-based live training system on Oryx. However, neither work out-of-the-box on Linux – Wally needs a few dependencies related to GTK3 and libusb that may not be installed by default, and both Oryx and Wally need a new udev rule to properly detect ZSA keyboards.

The Moonlander Mark I and other ZSA keyboards can receive a modified version of their firmware through a software called Wally. That software sends a binary file generated by the Oryx configurator to the keyboard. Each reflash requires the following steps:

  1. Compiling the desired layout on the Oryx configurator
  2. Opening Wally on the command line or using its GUI
  3. Following the steps on the screen (selecting the binary file, pressing the reset button, waiting for the firmware reflash to finish)

Oryx also offers a live training feature in Chrome-based browsers. However, both won’t work out-of-the-box on Linux – you have to install and change a few things before you can enjoy them.

Installing Wally’s dependencies on Linux

Wally needs dependencies related to libusb and, additionally, to GTK3 if you want to use its GUI. According to ZSA’s documentation, these are the packages needed on the most popular Linux distributions:

  • Arch family: gtk3 webkit2gtk libusb
  • Debian family: libusb-dev
  • RHEL family: gtk3 webkit2gtk3 libusb

Creating a udev rule for Wally and Oryx

Udev rules are created so events related to connected devices can be accessed without conceding unnecessary privileges to certain parts of the system.

To create a udev rule for Wally, create a file called 50-wally.rules on /etc/udev/rules.d/ using sudo.


sudo touch /etc/udev/rules.d/50-wally.rules

In that file, you should add the following lines:

# ErgoDox EZ
ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="04[789B]?", ENV{ID_MM_DEVICE_IGNORE}="1"
ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="04[789A]?", ENV{MTP_NO_PROBE}="1"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="04[789ABCD]?", MODE:="0666"
KERNEL=="ttyACM*", ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="04[789B]?", MODE:="0666"

# Moonlander e Planck EZ
SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", \
    MODE:="0666", \
    SYMLINK+="stm32_dfu"

Finally, make sure your user is part of the plugdev group:


sudo groupadd plugdev


sudo usermod -aG plugdev $USER

Don’t forget to log out after making those changes so your system can detect and apply them!

Voilà! Your system is ready to use both Wally and Oryx live training.

References

  1. Wally’s documentation on GitHub

Footnotes

If you use macOS, you also need to install libusb using brew:


brew install libusb