ch57x-keyboard-tool: programming cheap macro keypads from the command line

The tool exists because the bundled software is bad

The README explains the motivation concretely. These macro keyboards are popular on AliExpress and sellers often include software for programming them, but that software requires Windows, is described as very ugly and inconvenient, can only program one key at a time, and does not expose all keyboard features. ch57x-keyboard-tool is the replacement: a command line utility that takes a configuration file and writes it to the device. It supports both wired and wireless keyboards, with and without knobs, in sizes from 3x1 with one knob up to 3x4 with two knobs. The one hardware constraint is stated with a warning sign: even a wireless keyboard must be connected to the computer with a USB cable when programming.

Support is pinned to three USB ID pairs, and the config is the interface

The supported hardware is defined by USB vendor and product IDs, and the README lists them in hexadecimal as 1189:8890, 1189:8840 and 1189:8842. That narrow list is the tool's real boundary, and it is the first thing to check before anything else. The configuration side is a YAML file, and the workflow is five steps: connect the keyboard with a USB cable, study the available actions in doc/actions.md, create a configuration based on the provided example-mapping.yaml, validate it, and upload it. The example file is described as containing extensive documentation inside, and the recommended practice is to edit it or, better, to save a modified copy under a different name so the original stays a reference.

Four commands do the work, and validation is a separate pass

The command set is small enough to hold in your head, and separating validation from upload is the part that pays off. To list the key names the device understands, there is a show-keys command.

./ch57x-keyboard-tool show-keys

Then the configuration is checked before it is written.

./ch57x-keyboard-tool validate your-config.yaml

And only then is it uploaded.

./ch57x-keyboard-tool upload your-config.yaml

On Linux the upload may fail with an access denied message for insufficient permissions, in which case the README suggests running it under sudo, or configuring udev so that all users may program the keyboard. The udev rule it proposes matches on the USB subsystem and the same vendor and product ID.

SUBSYSTEM=="usb", ATTR{idVendor}=="1189", ATTR{idProduct}=="8890", TAG+="uaccess"

The rule is then picked up by reloading udev and triggering it.

The LED command differs by model, which is the sharpest edge

If the keyboard supports it, the LED configuration can be changed, and the README flags that the arguments are model-specific because different models have different LED capabilities. For the 0x8840 and 0x8842 models the syntax takes a layer followed by one or more modes, and the modes are off for no lights, backlight with a colour for a constant glow, shock and shock2 for a flashing effect on key press, and press for a single key lighting up when pressed. Supported colours are red, orange, yellow, green, cyan, blue and purple, with white additionally available for backlight. The 0x8890 model is simpler, since it only sets the LED to the first mode, likely steady on.

./ch57x-keyboard-tool led 1

It writes bindings and exits, which is a deliberate scope limit

The FAQ answers the question most people ask first, which is how to run a script or emulate several keys on a key press, and the answer is a refusal with a reason. The tool does just one job, it writes your key bindings into the keyboard and then exits, and it does not listen for key presses. Automation based on key presses is not within the scope of the utility. The README then gives the workaround, which is a chord plus a third-party automation tool such as BetterTouchTool: pick a chord you do not usually use such as alt-ctrl-shift-1, assign it to a key, and let the external tool listen for it. That design keeps the tool small and the firmware unmodified, at the cost of the one feature macro keypad owners most want.

Feature requests are answered honestly because there is no datasheet

The second FAQ entry explains the author's own limits. There is no detailed datasheet for these keyboards, so the author says whether something can be implemented only after seeing other software that does it, at which point replicating the behaviour is theoretically possible. Doing it requires either the exact keyboard model in hand or a reverse engineering effort by the person asking. The README also notes the tool's own scope limits, with a note about 3x1 keys plus 1 knob keyboard limitations as its own section, and the supported keyboards section points to photos of the supported boards. The other notes cover the number of layers, where all the boards the author has seen have three switchable layers, and the difference between macOS and Windows keyboard keys.

Diagnostics for USB devices, and a Rust dependency set that fits

The Diagnostics section covers finding and listing connected USB devices on macOS, Linux and Windows, and monitoring generated keyboard and mouse events, which is how you check whether a binding you just uploaded does what you expected. The Cargo.toml shows how small the program is. The dependencies are rusb for talking to USB devices, clap with derive for the command line, serde with derive and serde_yaml for the configuration format, nom for parsing, strum and strum_macros for the enum plumbing, enumset, itertools, log with env_logger for diagnostics, anyhow for error handling, and indoc for the documentation strings. The package is version 1.7.0 on edition 2024, licensed MIT OR Apache-2.0, and published to docs.rs.

Two installation routes, and a Windows driver requirement

You can take a prebuilt release from GitHub, or build it yourself with cargo. For the latter, the README lists the rustup installation routes per platform: brew install rustup-init with rustup-init on the Mac, the rustup.rs shell script on Linux, and rustup-init.exe on Windows. The install command itself is a single line.

cargo install ch57x-keyboard-tool

There is also a platform-specific prerequisite, and it is easy to miss. On Windows the README asks you to install USBDK.

Editorial conclusion

ch57x-keyboard-tool fits the owner of a cheap ch57x macro keypad who is stuck with the bundled Windows software, because the whole workflow becomes one YAML file that can be validated before it is uploaded and then kept in version control, which is what the vendor utility cannot offer. It is a poor fit for anything beyond those keypads, since the tool is scoped to three USB vendor and product ID pairs, and it is a poor fit if you want the keypad to trigger actions by itself, because the tool writes bindings and exits. Verify first that your keyboard's IDs match 1189:8890, 1189:8840 or 1189:8842, since the README states the keyboard must be connected over USB even when it is a wireless model.

Frequently asked questions

Official sources

1. Issues
2. kriomant/ch57x-keyboard-tool on GitHub
3. License: MIT
4. README
5. Releases