{"title":"","byline":null,"dir":null,"lang":null,"content":"

ch57x-keyboard-tool Macro Keyboard Configuration Utility

\n

\"Last \"Release

\n

Table of Contents

\n\n

What is this?

\n

This keyboard configuration utility is for programming small keyboards, such as the one shown below:

\n

\"Picture

\n

Such macro keyboards are popular on AliExpress, and sellers often include software for programming, but:

\n
    \n
  • It requires Windows
    • \n
  • It is very ugly and inconvenient
    • \n
  • It can only program one key at a time
    • \n
  • It does not expose all keyboard features
    • \n
\n

There are several modifications of such keyboards with different numbers of buttons and knobs (see the photos of supported keyboards) and with/without Bluetooth.

\n

Both wired and wireless keyboards are supported.\n⚠️ However, the keyboard must be connected to the computer with a USB cable when programming.

\n

Supported keyboards

\n

This utility has been reported to work with:

\n
    \n
  • 3×4 with 2 knobs (Bluetooth version)
    • \n
  • 3×3 with 2 knobs
    • \n
  • 3x2 with 1 knob
    • \n
  • 3x1 with 1 knob with limitations
    • \n
  • 4x1 without knobs
    • \n
\n

Keyboard with following vendor/product IDs are supported: 1189:8890, 1189:8840, 1189:8842 (hexadecimal).

\n

For more details, refer to the Supported Macro Keyboards section.

\n

Installation

\n

There are two ways to download the keyboard utility: getting a prebuilt release or building it yourself.

\n

Prebuilt release

\n

Simply download the latest release from GitHub.

\n

Or build it yourself

\n
    \n
  1. Install the cargo utility using rustup:\n
      \n
    • Brew: brew install rustup-init && rustup-init
      • \n
    • Linux: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
      • \n
    • Windows: Download and run rustup-init.exe
      • \n
    \n
    2. \n
  2. Execute cargo install ch57x-keyboard-tool.
    3. \n
\n

If you are on Windows

\n

Install USBDK.

\n

Usage

\n
    \n
  1. Connect the keyboard to the computer with a USB cable.
    2. \n
  2. Study available actions.
    3. \n
  3. Create a configuration file based on the provided example-mapping.yaml.
    4. \n
  4. Validate the configuration file.
    5. \n
  5. Upload the configuration to the keyboard.
    6. \n
  6. Done! 🎉
    7. \n
\n

Create configuration file

\n

Edit existing example-mapping.yaml or (better) save modified copy under different name.

\n

Example config file has extensive documentation inside.

\n

You may also get list of supported key names using:

\n
./ch57x-keyboard-tool show-keys
\n

Validate the config file

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

Upload the config to the keyboard

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

Permissions on Linux

\n

Use 'sudo' if you get 'Access denied (insufficient permissions)':

\n
sudo ./ch57x-keyboard-tool upload your-config.yaml
\n

Alternatively, you may configure udev to give all users permission to program keyboard:

\n

Create file /etc/udev/rules.d/50-usb-macrokeyboard.rules with content:

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

Reload udev configuration

\n
sudo udevadm control --reload\nsudo udevadm trigger
\n

Change LED configuration

\n

If your keyboard supports it, you can change the LED configuration.

\n

Note: LED command arguments are model-specific. Different keyboard models have different LED capabilities.

\n

0x8840 and 0x8842

\n

Syntax: ./ch57x-keyboard-tool led <layer> <mode>...

\n

Modes:

\n
    \n
  • off - LEDs off
    • \n
  • backlight - backlight always on with color
    • \n
  • shock - no backlight, shock effect with color when key pressed
    • \n
  • shock2 - no backlight, shock2 effect with color when key pressed
    • \n
  • press - no backlight, light up key with color when pressed
    • \n
\n

Supported key colors: red, orange, yellow, green, cyan, blue, purple.\nBacklight additionally supports white.

\n

0x8890

\n

Set the LED to the first mode (likely \"Steady on\")

\n
./ch57x-keyboard-tool led 1
\n

FAQ

\n

How to do ... on key press?

\n

A common question/request is about automation, such as \"How to run a script?\", \"emulate several keys\", or \"how to trigger an action with a key press?\"

\n

This tool does just one job: writes your key bindings into the keyboard and then exits.\nIt does not listen for key presses.\nAutomation based on key presses is not within the scope of this utility tool.

\n

If you seek any automation, use third-party automation tools like BetterTouchTool.

\n
    \n
  1. Choose a chord you do not usually use (like alt-ctrl-shift-1).
    2. \n
  2. Assign the chord to a key.
    3. \n
  3. Use a third-party automation tool to listen for this chord and have it perform the desired action.
    4. \n
  4. Done! 🎉
    5. \n
\n

Can you implement ... feature?

\n

I don't have detailed datasheet for these keyboards. So I can say whether something can implemented until you show me any software that can do it. Then it is teoretically possible to replicate behavior.

\n

However, doing it requires either exact keyboard model in my hands or you to performa reverse engeneering.

\n

Notes

\n

Number of layers

\n

All keyboards I have seen have three layers (three key configurations which may be switched).\nHowever, if your keyboard does not support layer switching, just keep a single layer in the configuration file.

\n

Custom keyboard layouts

\n

Note that you specify key to emulate press for, not character which is produced by pressing it.\nSo if you use a custom keyboard layout, like Dvorak, you have to see how required key is labelled in QWERTY layout.

\n

3x1 keys + 1 knob keyboard limitations

\n

This modification does support key modifiers (like ctrl-, alt-, and cmd-) for the first key in sequence only.

\n

So, you can use: ctrl-alt-del,1,2, but not ctrl-alt-del,alt-1,2.

\n

macOS vs Windows keyboard keys

\n

A friendly reminder that some keys have different names on macOS and Windows.\nThese keys have aliases for both platforms, you may use them interchangeably.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Key NamemacOS KeyWindows Key
Command / Windowscmdwin
Option / Altoptalt
\n

Commands and options

\n
ch57x-keyboard-tool [OPTIONS] <COMMAND>
\n

Commands and their descriptions:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
CommandDescription
show-keysDisplay a list of all supported keys and modifiers
validateValidate key mappings config from stdin
uploadUpload key mappings from stdin to the device
ledConfigure LED backlight (model-specific arguments)
help, -h, --helpPrint this message or the help of the given subcommand(s)
\n

Advanced options, you don't have to use this normally:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OptionDescriptionNotes
--vendor-id <VENDOR_ID>Vendor ID of the keyboardDefault: 4489
--product-id <PRODUCT_ID>Product ID of the keyboardDefault: 34960
--address <ADDRESS>Address of the keyboard
\n

⚠️ The ability to override the vendor/product ID does not mean that you can use this utility to program arbitrary keyboards!

\n

Diagnostics

\n

When reporting an issue, please include diagnostics such as the list of attached USB devices and the output of the keyboard and mouse monitoring tools.

\n

How to find and list connected USB devices

\n

macOS

\n
system_profiler SPUSBDataType
\n

or

\n\n

Linux

\n\n

Windows

\n
Get-PnpDevice | Where-Object { $_.Class -eq 'USB' } | Format-Table Name, DeviceID, Manufacturer, Status, Description -AutoSize
\n

Monitoring generated keyboard and mouse events

\n

The simplest and cross-platform way to monitor keyboard and mouse events is using the keyboard and mouse Python modules.

\n

Monitoring keyboard:

\n
pip3 install keyboard\nsudo python3 -m keyboard
\n

Monitoring mouse:

\n
    \n
  • The latest published 'mouse' module doesn't support macOS, so use the latest version from GitHub
    • \n
\n
git clone https://github.com/boppreh/mouse\ncd mouse\npython3 -m mouse
\n

Supported macro keyboards

\n\n

Photos of supported keyboards

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
KindPhoto
3x2 with 1 knob\"keyboard-6-1\"
3x2 with 1 knob\"keyboard-6-1\"
3x1 with 1 knob\"keyboard-3-1\"
3×3 with 2 knobs\"keyboard-12-2\"
4x3 with 3 knobs\"keyboard-4-3\"
4×1 without knobs\"keyboard-4-1\"
5×3 with 3 knobs\"keyboard-15-3\"
\n
","textContent":"ch57x-keyboard-tool Macro Keyboard Configuration Utility\n \nTable of Contents \n\nWhat is this?\n\nSupported keyboards\n\n\nInstallation\n\nPrebuilt release\nBuild it yourself\n\n\nUsage\n\nCommands and options\nValidate the config file\nUpload the config to the keyboard\nChange LED configuration\nWindows / PowerShell\n\n\nFAQ\n\nHow to do … on key press?\nCan you implement … feature?\n\n\nNotes\n\nNumber of layers\nCustom keyboard layouts\n3x1 keys + 1 knob keyboard limitations\nmacOS vs Windows keyboard keys\n\n\nDiagnostics\n\nHow to find and list connected USB devices\n\nmacOS\nLinux\nWindows\n\n\nMonitoring generated keyboard and mouse events\n\n\nSupported macro keyboards\n\nPhotos of supported keyboards\n\n\n\nWhat is this?\nThis keyboard configuration utility is for programming small keyboards, such as the one shown below:\n\nSuch macro keyboards are popular on AliExpress, and sellers often include software for programming, but:\n\nIt requires Windows\nIt is very ugly and inconvenient\nIt can only program one key at a time\nIt does not expose all keyboard features\n\nThere are several modifications of such keyboards with different numbers of buttons and knobs (see the photos of supported keyboards) and with/without Bluetooth.\nBoth wired and wireless keyboards are supported.\n⚠️ However, the keyboard must be connected to the computer with a USB cable when programming.\nSupported keyboards\nThis utility has been reported to work with:\n\n3×4 with 2 knobs (Bluetooth version)\n3×3 with 2 knobs\n3x2 with 1 knob\n3x1 with 1 knob with limitations\n4x1 without knobs\n\nKeyboard with following vendor/product IDs are supported: 1189:8890, 1189:8840, 1189:8842 (hexadecimal).\nFor more details, refer to the Supported Macro Keyboards section.\nInstallation\nThere are two ways to download the keyboard utility: getting a prebuilt release or building it yourself.\nPrebuilt release\nSimply download the latest release from GitHub.\nOr build it yourself\n\nInstall the cargo utility using rustup:\n\nBrew: brew install rustup-init && rustup-init\nLinux: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\nWindows: Download and run rustup-init.exe\n\n\nExecute cargo install ch57x-keyboard-tool.\n\nIf you are on Windows\nInstall USBDK.\nUsage\n\nConnect the keyboard to the computer with a USB cable.\nStudy available actions.\nCreate a configuration file based on the provided example-mapping.yaml.\nValidate the configuration file.\nUpload the configuration to the keyboard.\nDone! 🎉\n\nCreate configuration file\nEdit existing example-mapping.yaml or (better) save modified copy under different name.\nExample config file has extensive documentation inside.\nYou may also get list of supported key names using:\n./ch57x-keyboard-tool show-keys\nValidate the config file\n./ch57x-keyboard-tool validate your-config.yaml\nUpload the config to the keyboard\n./ch57x-keyboard-tool upload your-config.yaml\nPermissions on Linux\nUse 'sudo' if you get 'Access denied (insufficient permissions)':\nsudo ./ch57x-keyboard-tool upload your-config.yaml\nAlternatively, you may configure udev to give all users permission to program keyboard:\nCreate file /etc/udev/rules.d/50-usb-macrokeyboard.rules with content:\nSUBSYSTEM==\"usb\", ATTR{idVendor}==\"1189\", ATTR{idProduct}==\"8890\", TAG+=\"uaccess\"\n\nReload udev configuration\nsudo udevadm control --reload\nsudo udevadm trigger\nChange LED configuration\nIf your keyboard supports it, you can change the LED configuration.\nNote: LED command arguments are model-specific. Different keyboard models have different LED capabilities.\n0x8840 and 0x8842\nSyntax: ./ch57x-keyboard-tool led ...\nModes:\n\noff - LEDs off\nbacklight - backlight always on with color\nshock - no backlight, shock effect with color when key pressed\nshock2 - no backlight, shock2 effect with color when key pressed\npress - no backlight, light up key with color when pressed\n\nSupported key colors: red, orange, yellow, green, cyan, blue, purple.\nBacklight additionally supports white.\n0x8890\nSet the LED to the first mode (likely \"Steady on\")\n./ch57x-keyboard-tool led 1\nFAQ\nHow to do ... on key press?\nA common question/request is about automation, such as \"How to run a script?\", \"emulate several keys\", or \"how to trigger an action with a key press?\"\nThis tool does just one job: writes your key bindings into the keyboard and then exits.\nIt does not listen for key presses.\nAutomation based on key presses is not within the scope of this utility tool.\nIf you seek any automation, use third-party automation tools like BetterTouchTool.\n\nChoose a chord you do not usually use (like alt-ctrl-shift-1).\nAssign the chord to a key.\nUse a third-party automation tool to listen for this chord and have it perform the desired action.\nDone! 🎉\n\nCan you implement ... feature?\nI don't have detailed datasheet for these keyboards. So I can say whether something can implemented until you show me any software that can do it. Then it is teoretically possible to replicate behavior.\nHowever, doing it requires either exact keyboard model in my hands or you to performa reverse engeneering.\nNotes\nNumber of layers\nAll keyboards I have seen have three layers (three key configurations which may be switched).\nHowever, if your keyboard does not support layer switching, just keep a single layer in the configuration file.\nCustom keyboard layouts\nNote that you specify key to emulate press for, not character which is produced by pressing it.\nSo if you use a custom keyboard layout, like Dvorak, you have to see how required key is labelled in QWERTY layout.\n3x1 keys + 1 knob keyboard limitations\nThis modification does support key modifiers (like ctrl-, alt-, and cmd-) for the first key in sequence only.\nSo, you can use: ctrl-alt-del,1,2, but not ctrl-alt-del,alt-1,2.\nmacOS vs Windows keyboard keys\nA friendly reminder that some keys have different names on macOS and Windows.\nThese keys have aliases for both platforms, you may use them interchangeably.\n\n\n\nKey Name\nmacOS Key\nWindows Key\n\n\n\n\nCommand / Windows\ncmd\nwin\n\n\nOption / Alt\nopt\nalt\n\n\n\nCommands and options\nch57x-keyboard-tool [OPTIONS] \nCommands and their descriptions:\n\n\n\nCommand\nDescription\n\n\n\n\nshow-keys\nDisplay a list of all supported keys and modifiers\n\n\nvalidate\nValidate key mappings config from stdin\n\n\nupload\nUpload key mappings from stdin to the device\n\n\nled\nConfigure LED backlight (model-specific arguments)\n\n\nhelp, -h, --help\nPrint this message or the help of the given subcommand(s)\n\n\n\nAdvanced options, you don't have to use this normally:\n\n\n\nOption\nDescription\nNotes\n\n\n\n\n--vendor-id \nVendor ID of the keyboard\nDefault: 4489\n\n\n--product-id \nProduct ID of the keyboard\nDefault: 34960\n\n\n--address
\nAddress of the keyboard\n\n\n\n\n⚠️ The ability to override the vendor/product ID does not mean that you can use this utility to program arbitrary keyboards!\nDiagnostics\nWhen reporting an issue, please include diagnostics such as the list of attached USB devices and the output of the keyboard and mouse monitoring tools.\nHow to find and list connected USB devices\nmacOS\nsystem_profiler SPUSBDataType\nor\n\nLinux\n\nWindows\nGet-PnpDevice | Where-Object { $_.Class -eq 'USB' } | Format-Table Name, DeviceID, Manufacturer, Status, Description -AutoSize\nMonitoring generated keyboard and mouse events\nThe simplest and cross-platform way to monitor keyboard and mouse events is using the keyboard and mouse Python modules.\nMonitoring keyboard:\npip3 install keyboard\nsudo python3 -m keyboard\nMonitoring mouse:\n\nThe latest published 'mouse' module doesn't support macOS, so use the latest version from GitHub\n\ngit clone https://github.com/boppreh/mouse\ncd mouse\npython3 -m mouse\nSupported macro keyboards\n\nProduct ID: 0x8890, 0x8840\n\nVendor ID: 0x1189 (Trisat Industrial Co., Ltd.)\namazon.co.jp/dp/B0CF5L8HP3\n\n\n\nPhotos of supported keyboards\n\n\n\nKind\nPhoto\n\n\n\n\n3x2 with 1 knob\n\n\n\n3x2 with 1 knob\n\n\n\n3x1 with 1 knob\n\n\n\n3×3 with 2 knobs\n\n\n\n4x3 with 3 knobs\n\n\n\n4×1 without knobs\n\n\n\n5×3 with 3 knobs\n\n\n\n\n","length":7926,"excerpt":"ch57x-keyboard-tool Macro Keyboard Configuration Utility","siteName":null}