An app to map your MKESPN K806 mini-keypad on Linux

Sep 1, 2025

I recently finished a small tool I developed for a very specific problem: using the inexpensive MKESPN K806 mini-keypad on Linux when there isn’t reliable native support. I was given this keypad some time ago but, without a stable mapping tool, I couldn’t put it to use—until I had some time to research and build a solution. If you own this keypad or a similar one, this will be useful; the code is published so it can be adapted to other models.

The utility combines two parts: a daemon that listens to the physical device and executes actions, and a small graphical application (Tkinter). It aims to be simple, reliable and easy to adapt to your workflow. The full code and instructions are available on GitHub for anyone who wants to use it or contribute.

The tool was developed and tested mainly on GNOME with X11 on Ubuntu. Other setups (for example GNOME on Wayland, KDE, Sway or other compositors) may require adjustments and some features—like key injection via xdotool—might not work or may behave differently.

MKESPN K806 mini mechanical keyboard with 8 keys arranged in a 4x2 layout, featuring orange keycaps numbered 1 to 8. A red button and a small visible circuit board are located in the top right corner, all mounted on a transparent, screw-fixed base over a gray background.

Although it was born for the MKESPN K806, it can work with similar keypads that expose EV_KEY events; support for other models is experimental and not guaranteed.

The MKESPN K806 has no official Linux support and the generic tools I tested either didn’t persist mappings reliably between sessions or were flaky. This tool provides:

• Persistent mappings in JSON (~/.keymap.json).
• Resolution to stable paths (/dev/input/by-id/...) so mappings survive device renaming between reboots.
• A lightweight daemon that listens to events via evdev and executes configured actions (key combos using xdotool or shell commands).
• A UI to detect the device, capture key codes, edit actions and test them live.

The project actually contains two components:

• mini_keypad_daemon.py: a background process that opens the device, grabs events and runs mapped actions.
• mini_keypad_mapper.py: a Tkinter app to create, edit, test and save key mappings.

Minimum dependencies

• Python 3
• python3-evdev
• xdotool (to inject combinations on X11; limited or unsupported on Wayland)
• Tkinter (the UI library available on most systems)

Quick install

1. Install dependencies (Ubuntu/Debian example):

  sudo apt update
  sudo apt install -y python3 python3-evdev xdotool python3-tk
   

2. Clone the repo and put the scripts in a directory of your choice, for example ~/.local/bin.

3. Create your ~/.keymap.json or use the UI to generate one (the app includes suggested defaults).

Configuration format (example)

  {
    "device_path": "/dev/input/by-id/usb-MKESPN_K806-event-kbd",
    "enabled": true,
    "mapping": {
      "116": { "kind": "combo", "value": "Ctrl+Alt+T" },
      "117": { "kind": "command", "value": "firefox" }
    }
  }
    

Screenshot of the 'Mini Keypad Mapper' app showing the main interface for configuring a numeric keypad with custom actions. It includes device selection, start/stop buttons, a visual layout with numbered keys 1 to 8 highlighted in blue (indicating mapped keys), an action editor on the right, and a keymap table with actions like opening browsers, running scripts and triggering key combos like Ctrl+Alt+T.

Note: the keys in the mapping object must be event codes (from evdev), and supported kind values are combo (translated to xdotool key ...) and command which runs a shell command.

Running as a service

To run the daemon automatically at login it’s recommended to configure it as a user systemd service. Below is an example unit file and some useful instructions to install, start and debug it.

Example user unit file: ~/.config/systemd/user/mkespn-k806.service

  [Unit]
  Description=MKESPN K806 Keymap Daemon
  After=graphical-session.target

  [Service]
  ExecStart=/usr/bin/python3 /home/USER/mini_keypad_daemon.py
  Restart=always
  Environment=DISPLAY=:1
  Environment=XAUTHORITY=/home/USER/.Xauthority
  Environment=PATH=/usr/local/bin:/usr/bin:/bin:/home/USER/bin:/home/USER/.local/bin

  [Install]
  WantedBy=default.target
    

Replace USER with the account that will run the daemon. Then you can install and manage it like this:

1. Copy the file to ~/.config/systemd/user/mkespn-k806.service.
2. Reload user units and enable the service now:

  systemctl --user daemon-reload
  systemctl --user enable --now mkespn-k806.service
    

3. Check status and logs:

  systemctl --user status mkespn-k806.service
  journalctl --user -u mkespn-k806.service -f
    

Current limitations

• Hotplug: the daemon does not automatically detect the keyboard if it is plugged in after startup. If you connect the device after the service has started, restart the service (systemctl --user restart mkespn-k806.service).
• LEDs/backlight: the current version does not control LEDs or backlighting; if your keypad has lighting, this tool does not manage it.
• Multi-session hot-keys: behavior across multiple user sessions (for example, several X11/VT sessions) hasn’t been widely tested.
• Wayland: key injection via xdotool does not work on pure Wayland; look for compositor-specific alternatives in those environments.

Security and permissions (detailed)

The daemon needs to read events from /dev/input/event*. Avoid running the service as root in production; instead use one of these options:

1. udev rules (recommended): create /etc/udev/rules.d/99-mini-keypad.rules with something like:

  KERNEL=="event*", ATTRS{name}=="MKESPN K806", GROUP="input", MODE="0660"
   

After creating the rule reload udev: sudo udevadm control --reload-rules && sudo udevadm trigger.

2. Input group: add the user to the group that has access to input devices: sudo usermod -aG input $USER and log out/in.

3. Root for debugging: if you use root for testing do it temporarily and avoid that practice on production machines.

Practical examples

Here are some typical shortcuts you can map. Copy the value into the corresponding field in your profile (combo or command):

Possible improvements

• Wayland support: study alternatives to xdotool and adapt combo execution to each compositor.
• Auto-detection and reconnection (hotplug) for the device.
• UI improvements: icons, multiple profiles, import/export and usability tests.
• LED/backlight control where the hardware allows it.
• Multiple mapping profiles

License and contributions

The project is published under the MIT license (change if you prefer another). Contributions are welcome: open issues with reproducible information, PRs with improvements or discussions about compatibility. Note in the repo if you prefer a different license or restrictions.

The GitHub repo contains the full code, issues and a short guide. This project was born from a practical need: to make a cheap mini-keypad reliably usable in my daily workflow. If the tool interests you, try the UI first to generate ~/.keymap.json and, if it fits, run the daemon as a service. If you have improvements, ideas or similar devices, contribute on GitHub. Happy Coding!