Cheap Chinese macro keyboard configuration

Macro keyboards are great, they can be used to reduce the number of shortcuts to remember, and come handy, when you work in a scenario, where your right hand holds a mouse, and you issue commands with the other. Sound or video editing, graphics work, and of course games work best with your favorite hotkeys in a bunch. That’s where macro keypads enter.

While Elgato created the definitive macro pad, with tiny OLED displays to display what a key is assigned to, they are expensive. If you are a hobbyist, you may be glad to hear, there are other ways to get your macro needs covered: the internet is full of cheaper alternatives from China, 2/3/4/9/12/16 buttons and 0-3 knobs.

While they all look different, they have one thing in common: their software is terrible. The manufacturers use similar components and layouts but mostly drive them with a CH57x family chipset. The software they provide come in three variants:

They are notoriously difficult to get software for. At the time of writing some are available on, but the resellers usually just provide a dubious Google Drive link, which may or may not contain malware. The tools are not universal, some are not working with some versions of the keyboards for some reason.

I personally use these terrible tools to set my keyboard’s layout up to keys I don’t otherwise use and use AutoHotkey to map the keypresses to what I want to do. But that implies you find a set of keys you would not otherwise use, which sounds like a challenge.

What keys to map to?

It is lesser known that the standard keycodes contain a set of function keys that are not present on any keyboard, these are F13-F24, so these are great candidates to extend your keyboard. Setting these up is not possible using Gen1 software, so if you end up with one like that, you may find that you need to map your macro keys to combinations that already exist and mapped in your favorite applications. I found that mapping to “Ctrl-Alt-Shift” keys from A-Z are safe to use.

How to map F13-F24 if the keypad SW does not support it?

If, like me, you WANT to use the F13+ keys and are unlucky to own one that has no support from the available software or even if you happen to run an operating system other than Windows, you need to find some other solution.

After several weeks of searching, I found the ch57x-keyboard-tool, which provides a way to configure all these ch57xx based keyboards freely. It requires some finesse as the configuration of a HID device is not an everyday task, but if you follow this guide, and the manual of the tool, it should not be a problem.

  • On Windows you will need to install USBDK and restart Windows when prompted. Without this the program WILL NOT WORK!
  • Download, extract the latest release from this link
  • Modify the example-mapping.yaml to your favorite layout (it’s just the F keys for me, and a few more randoms for the knobs)
  • Find the USB ID of your device: Open Device manager, find Human Interface Devices and select your macro keyboard’s USB Input Device. If your machine is anything like mine, there will be tons of devices there. The easiest I found, to identify which one is the macropad, was by unplugging and replugging the pad, so it will be the last to show in the list.
  • Open calculator, turn it to programmer mode, select HEX input, and type your VID (1189) and PID (8890) to calculate the decimal values (4489 and 34960 for mine)
  • Use the command line to run the ch57x-keyboard-tool.exe with all your parameters

Once the keymap is loaded, you can remap anything using AutoHotkey, add layers or whatever you feel like.

Using AutoHotkey to remap to your keystrokes

I like to consider the macropad an input device and map its keys on my PC. This allows me to use soft layouts, OSD which is important for my workflow.

Autohotkey has a useful programming language, so you do all sorts of interesting reactions to your keypresses.

See the following example, taken from my config, which shows some examples of what can be done with near zero programming:

F13 and F15 are mapped to send Escape and Ctrl-V respectively. The original presses are effectively hidden from the OS, and it thinks the corresponding keys were pressed.

F14 translates the keypress into multiple presses, allowing you to do any kind of macros.

F16 is commented, as it is not remapped, but directly configured within the application that I use.

If you, like me, run out of F keys in, and remap the knobs to Modifier + Key (e.g., Shift-F13) make sure to define your hotkeys, with the UP modifier.

Why? About the knobs, you should be aware that the keys are sent as individual keypresses, but sometimes out of order. It can happen when you scroll too fast, or even too slow. This will confuse AutoHotkey, and that may believe the modifier and the key are pressed and released individually.

This is mostly a note for myself, so I won’t forget how it eventually worked. I hope it helps others. Your milage may vary.

8 thoughts on “Cheap Chinese macro keyboard configuration

  1. I get this output after running the command with the parameters:

    D:\Desktop\MacroPad\ch57x-keyboard-tool-x86_64-pc-windows-msvc>ch57x-keyboard-tool.exe –vendor-id 4489 –product-id 34960 upload

    1. Hi Bernardo,
      Unfortunately I can’t help you on that information only.

      To be successful using this tool, you’ll
      – need to install the drivers, that I mentioned
      – verify that’s the correct device id
      – create the yaml file to your liking
      – upload the file from a CMD window

      To do so, you’ll need to use the documentation, that comes with the tool.

      If you provide more context, I may be able to help.

    1. I am happy if I helped.
      My experience is with ch57xx based macro pads, that go up to 16 keys and three dials. I believe, what you described may be based on a different hardware.
      Check the description of the vendor, to see what their product is based on. As this is a more serious device, it may be compatible with via that opens up a ton of possibilities. If it is not in the product page, just ask the vendor. They will provide software for their product anyway, that will be good for most users.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.