Skip to content
wimpysworldPublic

About

Macropad configuration tool for Linux. One key, to rule them all 1️⃣

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

WonKey
WonKey

Macropad configuration tool for Linux. One key, to rule them all 1️⃣

Made with 💝 for 🐧

Configure USB macropads and mini-keyboards from one Linux CLI. Inspect connected pads with wonkey, bind keys, rotary knobs, multi-stroke macros, consumer media controls, and relative mouse actions, and set RGB or LED lighting.

Supported devices

Device USB ID Controls Supported Commands Settings Readback
XFKEY One Key Max (0112) af88:6688 1 key key, trigger, macro, mouse, media, rgb Full settings 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 and Layer 1 bindings
SayoDevice Macropad 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 bindings, lighting, and firmware version
SayoDevice Bootloader (Recovery) Application PID with product Bootloader (8089:000c for the 2x3P, confirmed by capture), or manifest pid2 8089:0006, 0007, 0008, 0009 for HID v1 directories 2 to 5 (unconfirmed) Bootloader mode only firmware Model, firmware version, and CHECK_FW reply bytes

Install

Platform Repository
Debian and Ubuntu apt.wimpys.world
Fedora and openSUSE rpm.wimpys.world
Arch Linux pkg.wimpys.world
Alpine Linux apk.wimpys.world
Nix and NixOS nix.wimpys.world

Each repository is signed, and its page gives the setup steps and keeps WonKey up to date.

Any Linux

bin installs and updates the release binary:

bin install github.com/wimpysworld/WonKey

Your user needs permission to access the macropad's USB or vendor hidraw device node.

Build from source

Requires Git, Go 1.25 or later, and just.

just build
sudo install -m 0755 ./bin/wonkey /usr/local/bin/wonkey

Make it yours

Inspect connected macropads and read current settings without changing them:

wonkey

wonkey lists each connected macropad with its [N] device number, USB path, layout where readable, supported commands, and readable settings. When multiple macropads are connected, pass --device <N> to target device [N] (for example wonkey key f13 --device 2).

Bind keys, rotary knobs, and key triggers:

wonkey key f13
wonkey key ctrl+shift+a
wonkey key key2 f13
wonkey key knob-press mute --layer 2
wonkey trigger release

Combine a base key with optional ctrl+, shift+, alt+, or super+ modifiers. On multi-control pads, pass an optional control name (key1..key12, knob-left, knob-press, knob-right, knob1-left..knob4-right) and --layer <N>, or use wonkey trigger <press|release|both> on single-key pads that support triggers.

Bind relative mouse actions, consumer media controls, or multi-stroke macros:

wonkey mouse left+right --x -20 --y 10
wonkey mouse wheelup
wonkey media playpause
wonkey media knob-right volumeup
wonkey macro a,f13,enter --interval 50 --repeat 2
wonkey macro key3 ctrl+c,ctrl+v --layer 2

Assign mouse buttons, relative cursor movement, wheel ticks, media keys, or comma-separated key sequences to any supported button or rotary knob.

Set RGB lighting or LED backlight modes:

wonkey rgb static 0000ff
wonkey rgb off
wonkey led reactive
wonkey led cycle
wonkey led off

Use wonkey rgb for 24-bit RGB modes and hex colours on XFKEY and SayoDevice macropads, or wonkey led for LED backlight modes (off, reactive, cycle) on CH57x macropads.

Check or update official vendor firmware on SayoDevice macropads:

wonkey firmware
wonkey firmware check
wonkey firmware update

wonkey firmware checks the device's firmware version against the official SayoDevice vendor manifest without modifying the pad. wonkey firmware update downloads and installs the latest official vendor firmware or recovers a device in bootloader mode. After the flash, it waits up to 60 seconds for the device to restart, then confirms the model and firmware version with one Info query. When the restart or the version is not confirmed, the command prints the next step and exits with status 1.

Documentation

About

Macropad configuration tool for Linux. One key, to rule them all 1️⃣

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages