WonKey

Macropad configuration tool for Linux

One key,
to rule them all.

Configure supported USB macropads and mini-keyboards from one Linux CLI. Bind keys, rotary knobs, macros, mouse actions, media controls, and RGB or LED lighting.

Get WonKey Quick start

Open source. Linux only. Supports XFKEY One Key Max, CH57x Macropads, and SayoDevice Macropads. See supported devices.

wonkey · Linux
# Inspect connected devices
$ wonkey

# Set a key combination
$ wonkey key ctrl+shift+f13

# Bind a rotary knob to volume up
$ wonkey media knob-right volumeup

# Choose static blue RGB lighting
$ wonkey rgb static 0000ff

Features

Make it yours

Control your macropad keys, knobs, and lighting from the command line. WonKey shows each change and verifies device state as it saves.

Explore the Wiki
Keys, knobs, and layers
Bind single keys or modifier chords (Ctrl, Shift, Alt, Super) with wonkey key. Target buttons, knobs, and layers on multi-control pads. Set key triggers with wonkey trigger on supported devices.
RGB and LED lighting
Set 24-bit RGB colours and effects with wonkey rgb on XFKEY and SayoDevice pads. Set LED backlight modes (off, reactive, cycle) with wonkey led on CH57x pads.
Macros, media, mouse, and firmware
Bind key sequences (wonkey macro), media controls (wonkey media), or relative mouse actions (wonkey mouse) to any button or knob. Check or update official SayoDevice firmware with wonkey firmware.

Everyday shortcuts

Mute a meeting. Dictate a thought.

Bind dedicated shortcuts to a single-key pad or to any button on a multi-key macropad.

Google Meet

Toggle your microphone in Google Meet.

wonkey key ctrl+d

Keep the meeting page focused. Check Ctrl+D in your Linux browser first.

Google Meet shortcuts

Zoom

Toggle your microphone in the Linux desktop app.

wonkey key alt+a

Keep the Zoom app focused.

Zoom shortcuts

Handy

Press to record. Press again to transcribe.

wonkey key ctrl+shift+h

In Handy, set the transcription shortcut to Ctrl+Shift+H. Turn off Push To Talk for toggle mode.

On Wayland, follow Handy's desktop shortcut setup.

Handy settings

How it works

Guarded writes from inspection to readback

Inspect connected macropads at any time. Write commands validate device capabilities, show the proposed change, and verify settings on supported hardware.

  1. wonkey

    Inspect connected pads

    Run wonkey with no arguments to list connected macropads, their USB paths, and their supported commands.

  2. wonkey key / media

    Bind keys and knobs

    Assign keys, macros, media actions, or mouse controls. Target specific keys, knobs, or layers when supported.

  3. wonkey rgb / led

    Configure lighting

    Set RGB lighting modes and hex colours with wonkey rgb or LED backlight modes with wonkey led.

  4. Guarded writes

    Validate and save

    WonKey checks device capabilities and descriptors before every write, and verifies 128-byte readback where supported.

Unchanged settings on XFKEY One Key Max send no settings writes. See the supported devices table for per-device capabilities and readback support.

Compatibility

Supported devices

WonKey discovers compatible USB macropads automatically and validates commands against each device's hardware capabilities.

Device USB ID Controls Supported Commands Settings Readback
XFKEY One Key Max (0112) af88:6688 1 key key, trigger, macro, mouse, media, rgb Full 128-byte readback
CH57x Macropad (Gen 1) 1189:8890, 514c:8890 Up to 12 keys, 3 knobs, 15 layers key, macro, mouse, media, led Write-only firmware
CH57x Macropad (Gen 2) 1189 / 514c : 8830, 8831, 8832, 8833, 8840, 8842, 8850, 8851 Up to 12 keys, 4 knobs, 15 layers key, macro, mouse, media, led Layout (0xFB) and Layer 1 (0xFA) readback
SayoDevice Macropad (HID v1 / v2) 8089:0002, 0003, 0004, 0005, 0009, 000a, 000b, 000c, 000e Up to 12 keys, 4 knobs, 5 layers key, macro, mouse, media, rgb, firmware Key (0x10 / 0x16), Light (0x11 / 0x10), and Info (0x00) readback
SayoDevice Bootloader (Recovery) 8089:0006, 0007, 0008 Bootloader mode only firmware Model and version via CHECK_FW (0x01)

Install

Get WonKey on Linux

Install WonKey 0.1.1 with your Linux package manager. Choose a download for x86_64 or ARM64.

Compare downloads with the SHA-256 checksums before installation.

After installation, run wonkey --help. Help does not access the device.

WonKey needs permission to access the macropad's USB or hidraw device node. WonKey does not install udev permission rules. See the Wiki for hardware setup and all options.

Getting started Releases
Debian / Ubuntu

Download the .deb, then run its command from the download directory.

x86_64 package

sudo apt install ./wonkey_0.1.1_linux_amd64.deb

ARM64 package

sudo apt install ./wonkey_0.1.1_linux_arm64.deb
Fedora

Download the .rpm, then run its command from the download directory.

x86_64 package

sudo dnf install ./wonkey_0.1.1_linux_amd64.rpm

ARM64 package

sudo dnf install ./wonkey_0.1.1_linux_arm64.rpm
openSUSE

Download the .rpm, then run its command from the download directory.

x86_64 package

sudo zypper install ./wonkey_0.1.1_linux_amd64.rpm

ARM64 package

sudo zypper install ./wonkey_0.1.1_linux_arm64.rpm
Alpine

Download the .apk, then run its command from the download directory. The package is unsigned, so apk requires --allow-untrusted.

x86_64 package

sudo apk add --allow-untrusted ./wonkey_0.1.1_linux_amd64.apk

ARM64 package

sudo apk add --allow-untrusted ./wonkey_0.1.1_linux_arm64.apk
Arch Linux (AUR)

Install xfkey-wonkey-bin from the AUR. Requires yay.

yay -S xfkey-wonkey-bin
Binary archive

Download an archive, then extract and install it from the download directory.

x86_64 archive

tar -xzf WonKey_0.1.1_linux_amd64.tar.gz
sudo install -m 0755 wonkey /usr/local/bin/wonkey

ARM64 archive

tar -xzf WonKey_0.1.1_linux_arm64.tar.gz
sudo install -m 0755 wonkey /usr/local/bin/wonkey
Build from source

Requires Git, Go 1.25 or later, and just.

git clone --branch v0.1.1 --depth 1 https://github.com/wimpysworld/WonKey.git
cd WonKey
just build
sudo install -m 0755 ./wonkey /usr/local/bin/wonkey

The build replaces ./wonkey in the source directory.