KBMAP

Linux keyboard mapping utility

About

Mapping physical keyboard keys under Linux system is tricky. Since there is multiple places where you can interrupt and handle keystroke, there is a ton of solutions for different levels. KBMAP focuses on handling keystroke straight from the physical device, before converting keycode to the keysym (it's a place, where windowing system applies keyboard layouts and locales).

KBMAP allows you to apply flexible configurations directly to the keyboard input device without writing a mess of C code or breaking system config files.

KBMAP is heavily inspired by QMK - highly customizable mechanical keyboard firmware. Basically, ideally KBMAP will be the QMK of any non-programmable keyboard (and maybe not only keyboard).

Installing

pip install kbmap

Usage

Usage: kbmap [OPTIONS] DEVICE_NAME

  Create virtual device that will remap keyboard events from device with
  name DEVICE_NAME.

Options:
  --version          Show the version and exit.
  -c, --config TEXT  Mapping configuration path.
  -n, --name TEXT    Name of the virtual device that will write events.
  -v, --verbose      Print detailed logs.
  --help             Show this message and exit.

FAQ

Q: How it works?
A: KBMAP uses evdev - a Linux input event interface. There is python binding for evdev library: python-evdev. Mapping algorithm:

1. Find a target device by name (specified with DEVICE_NAME argument)
2. Create new uinput device (kind of a virtual input device) with specified name (--name option)
3. Grab target device (so only KBMAP process receive input events)
4. Listen for key events from target device
5. Perform remapping based on config file (specified with CONFIG_PATH argument)
6. Dispatch events through created uinput device

Q: Linux only?
A: Yes, since evdev is a specific Linux interface, KBMAP cannot be used on non-unix operating systems.

Q: Alternatives for Windows?
A: AutoHotkey.

Q: How is KBMAP related to QMK?
A: QMK has a lot of mapping features. But QMK is a firmware and you cannot use it unless your keyboard is programmable. The mind behind KBMAP is to allow non-programmable keyboard users to achieve QMK-like customizability with their input device. Current goal is to reach TMK (a program, QMK being forked from) functionality.

Q: I am getting UInputError: "/dev/uinput" cannot be opened for writing.
A: Solution.

Q: How to run KBMAP at system boot?
A: It can be done in several ways, check out stackoverflow question and Arch Linux wiki page.

Q: What features are already implemented?
Q: How to configure KBMAP?
Q: KBMAP keycodes?
A: See wiki.

Documentation

Documentation and useful resources can be found in wiki.