New advertisers: 50% off your first month with code FIRSTMONTHSee slots

Interactive mapping of Linux input devices' buttons to evdev codes, with a shared device-mapping library lookup.

version
0.2.0
GitHub stars
32
View on GitHub

What it does

  • Adds map-input-device and lookup-device-mapping skills plus the idmap.py script with list, info, capture, press, library, and watch commands
  • Runs a guided press session that asks for one button at a time and confirms each evdev code as it arrives
  • Writes a device profile mapping physical labels to evdev codes and predicted browser gamepad indexes
  • Designed for building per-device bindings in apps, input-remapper presets, or shortcuts on Linux

Identify a Linux input device (gamepad, macro pad, pedal, remote), map each button to its evdev code one press at a time, and look devices up in a shared mapping library.

Add marketplace

/plugin marketplace add danielrosehill/Claude-Code-Plugins

Run it inside Claude Code once, then install the plugin below.

Install

/plugin install input-device-mapper@danielrosehill

Run it inside Claude Code after adding the marketplace.

Files

Discovered from source

Look up a device in a mapping library

Before mapping a device from scratch, check whether a library already has it. A library is a devices.json index (schema device-mappings-index/1) listing devices by USB vendor:product, each pointing to a repo and a profile file.

Default library: https://github.com/danielrosehill/Device-Mappings (devices.json on main), the plugin author's own collection. Use another one with --library <url or local path> or the DEVICE_MAPPINGS_LIBRARY environment variable; a library can be any repo or folder that follows the same schema.

Steps

  1. Match everything connected:
    python3 -I <plugin>/scripts/idmap.py library
    
    matched lists connected devices that have entries (repo, profile file, formats, press_verified); not_in_library lists the rest by vendor:product and name.
  2. For a match, fetch the profile (profile_url, raw file) and read it. Report the device, what it presents (driver, nodes) and the button table; say whether the library marks it press-verified.
  3. Use it for what the user wants: hand the button table to an app, apply the SDL line or hwdb snippet it carries, or set up a remapper. Check one or two buttons live with idmap.py press <device> --label <button> before relying on an entry that is not press-verified, or when the mode or firmware may differ (product ID matches but layout can change with a mode switch).
  4. No match: offer the map-input-device skill, then add the result to the library: a repo per device with device.json, a row in the library README and an entry in its devices.json:
    {"name": "...", "type": "gamepad|foot-pedal|macro-keypad|...", "usb": "vvvv:pppp", "driver": "...",
     "formats": ["device.json", "sdl", "hwdb", "..."], "press_verified": true,
     "repo": "<owner>/<repo>", "profile": "device.json"}
    
    Leave per-unit serial numbers out of anything published (ID_SERIAL, iSerial, evdev Uniq, /dev/input/by-id names): replace them with <serial>.

Notes

  • One USB ID can cover several entries (modes, firmware revisions); show all and let the user pick.
  • Virtual devices (0000:0000, ydotoold, uinput) never match and can be ignored.

Readme

Input Device Mapper

Identify an input device on Linux and map its physical buttons to what the system actually receives. Plug in a gamepad, macro pad, foot pedal or presentation remote; the agent finds it (vendor:product, driver, stable /dev/input/by-id path), asks you to press one button at a time and confirms each as you go, and writes a device profile: physical label → evdev code → predicted browser gamepad index.

What a session looks like

The agent names one button, waits for the press, confirms what it sent, then names the next:

Agent asks for A; the press is read as BTN_A, code 304, browser button 0 Confirmed, the agent asks for B and waits

Use it before building per-device bindings in an app, an input-remapper preset or a shortcut.

Skills

  • map-input-device: find the device, read its declared keys/axes, run the guided press session, check the browser's Gamepad API view, record the profile.
  • lookup-device-mapping: match connected devices against a mapping library by vendor:product and load the existing profile. Default library: Device-Mappings; point --library or DEVICE_MAPPINGS_LIBRARY at your own devices.json.

Script

scripts/idmap.py (python3 + python3-evdev), JSON output:

CommandDoes
listevery evdev node with vendor:product, bus, driver, class, stable paths
info <dev>udev properties, declared keys, axes and ranges, force feedback
capture <dev> --count Nthe first N distinct inputs, in press order (keys, hat directions, axes past half travel)
press <dev> --label Lwait for one input and print it (the guided session)
library [--library URL]which connected devices a mapping library already has
watch <dev> --seconds Severy press as JSON lines

<dev> is /dev/input/eventN, a /dev/input/by-id/... path, or vvvv:pppp.

Needs read access to /dev/input/event*: be in the input group (sudo usermod -aG input $USER, then log in again).

Relation to hotkey-builder

hotkey-builder finds free keyboard keys and binds shortcuts. This plugin is device-first: what is this thing, and what does each of its buttons send, including gamepads and analog triggers.

Installation

claude plugins install input-device-mapper@danielrosehill

License

MIT

Details

Marketplace
danielrosehill/Claude-Code-Plugins
Source
danielrosehill/Input-Device-Mapper-Plugin
Author
Daniel Rosehill
Category
Linux Sysadmin
License
MIT

More from danielrosehill/Claude-Code-Plugins

All 264

Similar to input-device-mapper

More Development Tools