This started as a fun project to learn about rust and USB. It is a hobby project and changes/features are implemented as my free time permits. Please use caution before using this software as I assume no responsibility if it does not work or causes problems with your device.
Obviously I do not have all types of macropad nor do I intend to purchase them. However, if people want to donate macropads so support can be added for more devices, that is a big way to help grow this project.
This is an utility for programming small keyboards like this one:
Many of these keyboards are popular on AliExpress and Amazon, but the seller usually makes you download a windows exe file from a google drive account to program it. It also assumes
- you use Windows (which I do not)
- is clunky/shady (imho)
- most importantly does not expose all keyboard features
Clone the repository and build the tool
cargo build --release
The README.md file is written in emacs org mode. To get a sample configuration file, just tangle this file (C-c C-v t) from within emacs
Normal macropad orienation is when buttons are on the left side and rotary encoders are on the right. However, you may want to use the macropad in another orienation. To avoid remapping button positions in your head, just set it here.
Possible values are: (horizontal)
- ‘normal’: buttons on the left, rotary encoders on the right
- ‘upsidedown’: buttons on the right, rotary encoders on the left
(vertical)
- ‘clockwise’: buttons on the top, rotary encoders on the bottom
- ‘counterclockwise’: buttons on the bottom, rotary encoders on the top
(
device: (
orientation: "normal",There are different models of macropad with different numbers of buttons and rotary encoders. Set it here for proper handling. Count rows and columns with the macropad in normal orienation, with rotary encoders on the right side.
rows: 3,
cols: 4,
knobs: 2,
),The current layer is changed using a button on the side of the macropad and displayed with LEDs on top (only for the moment of changing). All macropads I saw had three layers
layers: [
(Array of buttons. In horizontal orienations it’s `rows` rows `columns` buttons each. In vertical: `columns` rows `rows` buttons
Each entry is either a sequence of keychords or a mouse event. A keychord is a combination of one key with optional modifiers, like ‘b’, ‘ctrl-alt-a’ or ‘win-rctrl-backspace’. It can also be just modifiers without a key: ‘ctrl-alt’
You can combine up to 17 chords into a sequence using commas: ‘ctrl-c,ctrl-v’
If you have a 0x884x product id, you can use the delay feature. This puts a delay between each key sequence. In the example below, when typeing out ‘foo@bar.com’ it will insert a 1000 msec delay between each keystroke. the maximum delay is 6000 msec. For all other product id’s, the software will ignore the delay value when programming the macropad
buttons: [
[(delay: 0, mapping: "ctrl-b"), (delay: 0, mapping: "ctrl-leftbracket"), (delay: 0, mapping: "ctrl-m") (delay: 0, mapping: "d")],
[(delay: 0, mapping: "ctrl-e"), (delay: 0, mapping: "ctrl-rightbracket"), (delay: 0, mapping: "ctrl-slash"), (delay: 0, mapping: "d")],
[(delay: 0, mapping: "space"), (delay: 1000, mapping: "f,o,o,shift-2,b,a,r,dot,c,o,m"), (delay: 0, mapping: "shift-p"), (delay: 0, mapping: "d")],Rotary encoders (aka knobs) are listed from left to right if horizontal and from top to bottom if vertical. They can be rotated counter-clockwise (ccw) or clockwise (cw) and pressed down like a button
knobs: [
(ccw: (delay: 0, mapping: "3"), press: (delay: 0, mapping: "3"), cw: (delay: 0, mapping: "3")),
(ccw: (delay: 0, mapping: "volumedown"), press: (delay: 0, mapping: "mute"), cw: (delay: 0, mapping: "volumeup")),
],
),Mouse events are clicks (‘click’, ‘rclick’, ‘mclick’) or wheel events (‘wheelup’, ‘wheeldown’) with one optional modifier, only ‘ctrl’, ‘shift’ and ‘alt’ are supported (‘ctrl-wheeldown’) Clicks may combine several buttons, like this: ‘click+rclick’
(
buttons: [
[(delay: 0, mapping: "click"), (delay: 0, mapping: "mclick"), (delay: 0, mapping: "rclick"), (delay: 0, mapping: "d")],
[(delay: 0, mapping: "wheelup"), (delay: 0, mapping: "wheeldown"), (delay: 0, mapping: "space"), (delay: 0, mapping: "d")],
[(delay: 0, mapping: "ctrl-wheelup"), (delay: 0, mapping: "ctrl-wheeldown"), (delay: 0, mapping: "right"), (delay: 0, mapping: "d")],
],
knobs: [
(ccw: (delay: 0, mapping: "3"), press: (delay: 0, mapping: "3"), cw: (delay: 0, mapping: "3")),
(ccw: (delay: 0, mapping: "volumedown"), press: (delay: 0, mapping: "mute"), cw: (delay: 0, mapping: "volumeup")),
],
),Multimedia commands are also supported. Howerver, they cannot be mixed with normal keys and modifiers
(
buttons: [
[(delay: 0, mapping: "ctrl-m"), (delay: 0, mapping: "ctrl-slash"), (delay: 0, mapping: "space"), (delay: 0, mapping: "p")],
[(delay: 0, mapping: "volumeup"), (delay: 0, mapping: "volumedown"), (delay: 0, mapping: "play"), (delay: 0, mapping: "next")],
[(delay: 0, mapping: "ctrl-rightbracket"), (delay: 0, mapping: "ctrl-leftbracket"), (delay: 0, mapping: "right"), (delay: 0, mapping: "left")],
],
knobs: [
(ccw: (delay: 0, mapping: "3"), press: (delay: 0, mapping: "3"), cw: (delay: 0, mapping: "3")),
(ccw: (delay: 0, mapping: "volumedown"), press: (delay: 0, mapping: "mute"), cw: (delay: 0, mapping: "volumeup")),
],
),
],
)To access the device without being root, copy the 80-macropad.rules to /etc/udev/rules.d and reload udev
sudo cp 80-macropad.rules /etc/udev/rules.d sudo udevadm trigger
A list of supported keys can be found by running
macropad-tool show-keys
macropad-tool validate -h macropad-tool validate # by default looks for a mapping.ron file macropad-tool validate -c <ron_file> # to specify a different configuration file
Needs root access or ensure udev rules was added. For Windows, need Administrator command prompt
macropad-tool program -h macropad-tool program # by defult looks for a mapping.ron file macropad-tool program -c <ron_file> # to specify a different configuration file
Some keyboards support LEDs and you can program the different modes via the led command
macropad-tool led <mode> <layer> <color> # Only for 8840 model macropad-tool led 1 1 red macropad-tool led -h # the help menu about different modes/colors
Installing rust with the installer prompts to install visual studio community edition (which is free) and is sufficient to build the executable
- You will need to install the USB Development Kit to be able to talk to the macropad. https://github.com/daynix/UsbDk/releases