Key Mapper

A tool to change and program the mapping of your input device buttons.

Usage

To open the UI to modify the mappings, look into your applications menu and search for 'Key Mapper' in settings. You can also start it via key-mapper-gtk. It works with both Wayland and X11.

If stuff doesn't work, check the output of key-mapper-gtk -d and feel free to open up an issue here.

Macros

It is possible to write timed macros into the center column:

• k(1).k(2) 1, 2
• r(3, k(a).w(500)) a, a, a with 500ms pause
• m(Control_L, k(a).k(x)) CTRL + a, CTRL + x
• k(1).h(k(2)).k(3) writes 1 2 2 ... 2 2 3 while the key is pressed

Documentation:

• r repeats the execution of the second parameter
• w waits in milliseconds
• k writes a single keystroke
• m holds a modifier while executing the second parameter
• h executes the parameter as long as the key is pressed down
• . executes two actions behind each other

Syntax errors are shown in the UI on save. each k function adds a short delay of 10ms that can be configured in ~/.config/key-mapper/config.

Key Names

Run key-mapper-service --key-names for a list of supported keys for the middle column. Examples:

• Alphanumeric a to z and 0 to 9
• Modifiers Alt_L Control_L Control_R Shift_L Shift_R
• Mouse buttons BTN_LEFT BTN_RIGHT BTN_MIDDLE BTN_SIDE ...
• Multimedia keys KEY_NEXTSONG KEY_PLAYPAUSE ...

Gamepads

Tested with the XBOX 360 Gamepad.

• Joystick movements will be translated to mouse movements
• The second joystick acts as a mouse wheel
• Buttons can be mapped to keycodes or macros
• The D-Pad only works as two buttons - horizontal and vertical

Installation

The tool shows and logs if there are issues, but usually, independent of the method, you should add yourself to the input and plugdev groups so that you can read information from your devices. You have to start the application via sudo otherwise. You may also need to grant yourself write access to /dev/uinput to be able to inject your programmed mapping.

There is a shortcut for configuring this stuff:

sudo key-mapper-service --setup-permissions
# now log out and back in

You also need the rights to write keycodes into your system. This seems to be already the case on some systems, but not all of them.

sudo setfacl -m u:$USER:rw- /dev/uinput

Manjaro/Arch

pacaur -S key-mapper-git

Ubuntu/Debian

wget "https://github.com/sezanzeb/key-mapper/releases/"\
"download/0.3.0/python3-key-mapper_0.3.0-1_all.deb"
sudo dpkg -i python3-key-mapper_0.3.0-1_all.deb

Git/pip

Depending on your distro, maybe you need to use --force to get all your files properly in place and overwrite a previous installation of key-mapper.

# method 1
sudo pip install git+https://github.com/sezanzeb/key-mapper.git
# method 2
git clone https://github.com/sezanzeb/key-mapper.git
cd key-mapper && sudo python3 setup.py install

Roadmap

• show a dropdown to select valid devices
• creating presets per device
• renaming presets
• show a mapping table
• make that list extend itself automatically
• read keycodes with evdev
• inject the mapping
• keep the system defaults for unmapped buttons
• button to stop mapping and using system defaults
• highlight changes and alert before discarding unsaved changes
• automatically load presets on login for plugged in devices
• make sure it works on wayland
• support timed macros, maybe using some sort of syntax
• add to the AUR, provide .deb file
• basic support for gamepads as keyboard and mouse combi
• executing a macro forever while holding down the key
• map D-Pad and Joystick directions as buttons, joystick purpose via config
• automatically load presets when devices get plugged in after login
• mapping a combined button press to a key

Tests

pylint keymapper --extension-pkg-whitelist=evdev
sudo pip install . && coverage run tests/test.py
coverage combine && coverage report -m

To read events, evtest is very helpful. Add -d to key-mapper-gtk to get debug output.