Una aplicación para mapear tu mini-teclado MKESPN K806 en Linux

Hoy traigo una herramienta recientemente salida del horno que desarrollé para un problema muy concreto: usar el mini teclado económico MKESPN K806 en Linux cuando no existe soporte nativo fiable. Es un regalo que me hicieron hace tiempo y que por falta de un software para mapearlo no había podido utilizar hasta ahora que, he tenido algo de tiempo para investigar y desarrollar la solución. Si tienes un teclado de estos o uno parecido esto te será útil, además publico el código por lo que podría adaptarse para otros parecidos.

Esta utilidad combina dos piezas: un daemon que escucha el dispositivo físico y ejecuta acciones, y una pequeña aplicación gráfica (Tkinter). Está pensada para ser simple, fiable y fácil de adaptar a tu flujo de trabajo. El código completo y las instrucciones están publicadas en GitHub para quien quiera usarla o contribuir.

La herramienta se ha desarrollado y probado principalmente en GNOME con X11 sobre Ubuntu. Otras configuraciones (por ejemplo GNOME en Wayland, KDE, Sway u otros compositores) pueden requerir adaptaciones y algunas funcionalidades —como la inyección de teclas mediante xdotool— pueden no funcionar o comportarse de forma distinta.

Mini teclado MKESPN K806 mecánico de 8 teclas con disposición 4x2, teclas de color naranja numeradas del 1 al 8. En la esquina superior derecha se encuentra un botón rojo y una pequeña placa visible, todo montado sobre una base transparente y atornillada, sobre fondo gris.

Aunque nació para el MKESPN K806, puede funcionar con teclados similares que expongan eventos EV_KEY; sin embargo, el soporte para otros modelos es experimental y no garantizado.

El MKESPN K806 no dispone de soporte oficial en Linux y las herramientas genéricas probadas no guardaban mapeos de forma fiable entre sesiones, o fallaban. Esta herramienta ofrece:

• Persistencia de mapeos en JSON (~/.keymap.json).
• Resolución a rutas estables (/dev/input/by-id/...) para sobrevivir a cambios en el enumerado de dispositivos entre reinicios.
• Un daemon ligero que escucha eventos vía evdev y ejecuta acciones configuradas (combinaciones de teclas con xdotool o comandos shell).
• Una interfaz para detectar el dispositivo, capturar códigos de tecla, editar acciones y probarlas en vivo.

En realidad está formada por dos componentes:

• mini_keypad_daemon.py: proceso en segundo plano que abre el dispositivo, agarra los eventos y ejecuta acciones mapeadas.
• mini_keypad_mapper.py: aplicación Tkinter para crear, editar, probar y guardar los mapeos de teclas.

Dependencias mínimas

• Python 3
• python3-evdev
• xdotool (para inyectar combinaciones en X11; en Wayland habrá limitaciones)
• Tkinter (para la UI) o la biblioteca GUI estándar de tu sistema

Instalación rápida

1. Instala dependencias (ejemplo Ubuntu/Debian):

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

2. Clona el repo y coloca los scripts en un directorio de tu elección, por ejemplo ~/.local/bin.

3. Crea tu ~/.keymap.json o usa la UI para generar uno (la app incluye defaults sugeridos).

Formato de configuración (ejemplo)

    {
    "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.

Nota: las claves del objeto mapping deben ser códigos de evento (evdev), y los kind soportados son combo (traducido a xdotool key ...) y command que ejecuta un comando shell.

Ejecución como servicio

Para que el daemon se ejecute automáticamente en cada inicio de sesión se recomienda configurarlo como servicio de usuario en systemd. A continuación tienes un ejemplo más completo y algunas instrucciones útiles para instalarlo, iniciarlo y depurarlo.

Archivo de unidad de ejemplo (usuario): ~/.config/systemd/user/mkespn-k806.service

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

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

    [Install]
    WantedBy=default.target
    

Cambia USUARIO por el usuario que ejecutará el demonio de escucha del mini teclado. Así puedes instalarlo y comandos básicos:

1. Copia el archivo anterior a ~/.config/systemd/user/mkespn-k806.service.
2. Recarga las unidades del usuario y habilita el servicio ahora:

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

3. Verifica el estado y los logs:

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

Limitaciones actuales

• Hotplug: el daemon no detecta automáticamente la conexión del teclado después de arrancar. Si conectas el dispositivo tras iniciar el servicio, tendrás que reiniciar el servicio (systemctl --user restart mkespn-k806.service).
• LEDs/retroiluminación: la versión actual no gestiona LEDs ni retroiluminación; si tu teclado tiene iluminación, esta herramienta no la controla.
• Hot-keys multi-sesión: comportamientos en sesiones múltiples de usuario (por ejemplo, múltiples X11/VT) no han sido ampliamente probados.
• Wayland: la inyección de teclas mediante xdotool no funciona en Wayland puro; en estos entornos busca alternativas específicas del compositor.

Seguridad y permisos (detallado)

El daemon necesita leer eventos desde /dev/input/event*. Evita ejecutar el servicio como root en producción; en su lugar usa alguna de estas opciones:

1. Reglas udev (recomendado): crea /etc/udev/rules.d/99-mini-keypad.rules con contenido similar a:

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

Tras crear la regla, recarga udev: sudo udevadm control --reload-rules && sudo udevadm trigger.

1. Grupo input: añade el usuario al grupo que tenga acceso a dispositivos de entrada: sudo usermod -aG input $USER y reinicia sesión.

2. Root solo para pruebas: si usas root para depuración, hazlo temporalmente y evita esa práctica en máquinas de producción.

Ejemplos prácticos de uso

A continuación tienes una tabla con ejemplos de atajos típicos que puedes mapear. Copia el value al campo correspondiente en tu perfil (combo o command):

Posibles mejoras

• Soporte Wayland: estudiar alternativas a xdotool y adaptar la ejecución de combinaciones a cada compositor.
• Auto-detección y reconexión (hotplug) del dispositivo.
• Mejoras UI: iconos, perfiles múltiples, exportación/importación y tests de usabilidad.
• Control de LEDs/retroiluminación donde el hardware lo permita.
• Distintos perfiles de mapeos

Licencia y contribuciones

El proyecto se publica bajo la licencia MIT (cambia si prefieres otra). Las contribuciones son bienvenidas: abre issues con información reproducible, PRs con mejoras o discusiones sobre compatibilidad. Indica en el repo si prefieres otra licencia o restricciones de uso.

En Github está el código completo, issues y una guía rápida. Este proyecto nació de una necesidad práctica: usar un mini-teclado barato de forma fiable en mi día a día. Si te interesa la herramienta, prueba la UI primero, genera tu ~/.keymap.json y, si te encaja, ejecuta el daemon como servicio. Si tienes mejoras, ideas o dispositivos similares, contribuye en GitHub. Espero ayudar a que aquellos poseedores de este mini teclado puedan hacerlo funcionar correctamente en sus Linux, cualquier duda o sugerencia es bienvenida y Happy Coding!!