+title: Readme

• Contents :toc:

• [[#project-description][Project Description]]

  • [[#note][Note]]
  • [[#donations-welcome][DONATIONS WELCOME]]

• [[#installation][Installation]]

• [[#configuration-mappings][Configuration Mappings]]

  • [[#orientation][Orientation]]
  • [[#macropad-setup][Macropad Setup]]
  • [[#layers][Layers]]

• [[#usage][Usage]]

  • [[#udev-rules-for-linux][udev rules for linux]]
  • [[#supported-keys][Supported keys]]
  • [[#validate-configuration][Validate configuration]]
  • [[#program-the-keyboard][Program the keyboard]]
  • [[#led-support][LED Support]]

• [[#windows][Windows]]

  • [[#compiling][Compiling]]
  • [[#running-the-application][Running the Application]]

• Project Description

** Note 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.

** DONATIONS WELCOME [[https://www.buymeacoffee.com/kamaaina][https://cdn.buymeacoffee.com/buttons/default-orange.png]]

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:

[[images/keyboard-6-1.png]] [[images/keyboard-12-2.png]] [[images/keyboard-3-1.jpg]] [[images/keyboard-4-0.png]] [[images/keyboard-6-1_2.png]] [[images/keyboard-15-3.jpg]]

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

• Installation Clone the repository and build the tool

+begin_example

cargo build --release

+end_example

• Configuration Mappings 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

** Orientation

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

+begin_src ron

( device: ( orientation: "normal",

+end_src

** Macropad Setup

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.

+begin_src ron

    rows: 3,
    cols: 4,
    knobs: 2,
),

+end_src

** Layers

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

+begin_src ron

layers: [
    (

+end_src

*** Buttons 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

+begin_src ron

        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")],

+end_src

*** Rotary Encoders

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

+begin_src ron

        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")),
        ],
    ),

+end_src

*** Mouse Events

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'

+begin_src ron

    (
        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")),
        ],
    ),

+end_src

*** Multimedia Support

Multimedia commands are also supported. Howerver, they cannot be mixed with normal keys and modifiers

+begin_src ron

    (
        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")),
        ],
    ),
],

)

+end_src

• Usage

** udev rules for linux To access the device without being root, copy the 80-macropad.rules to /etc/udev/rules.d and reload udev

+begin_example

sudo cp 80-macropad.rules /etc/udev/rules.d sudo udevadm trigger

+end_example

** Supported keys A list of supported keys can be found by running

+begin_example

macropad-tool show-keys

+end_example

** Validate configuration

+begin_example

macropad-tool validate -h macropad-tool validate # by default looks for a mapping.ron file macropad-tool validate -c # to specify a different configuration file

+end_example

** Program the keyboard Needs root access or ensure udev rules was added. For Windows, need Administrator command prompt

+begin_example

macropad-tool program -h macropad-tool program # by defult looks for a mapping.ron file macropad-tool program -c # to specify a different configuration file

+end_example

** LED Support Some keyboards support LEDs and you can program the different modes via the led command

+begin_example

macropad-tool led # Only for 8840 model macropad-tool led 1 1 red macropad-tool led -h # the help menu about different modes/colors

+end_example

• Windows

** Compiling Installing rust with the installer prompts to install visual studio community edition (which is free) and is sufficient to build the executable

** Running the Application

• You will need to install the USB Development Kit to be able to talk to the macropad. https://github.com/daynix/UsbDk/releases