EVREMAP(1)

💖 EVREMAP(1) 💖

okay bestie, sit down, hydrate, because today we're learning about evremap — the section 1 (user commands) manual page for the keyboard input remapper for Linux/Wayland systems. yes. THE keyboard remapper. let's go 🦋

✨ NAME ✨

evremap — keyboard input remapper for Linux/Wayland systems 💅

🌸 DESCRIPTION 🌸

so the way evremap works is lowkey genius: it grabs exclusive access to an input device and keeps its own little mental model of which keys are currently pressed. then it applies your remapping configuration on top of that to figure out the effective set of pressed keys, and emits the appropriate changes to a virtual output device. it's giving puppet master. it's giving middle management for your keyboard. 🎀

and because evremap targets the evdev layer of libinput, its remapping is effective system-wide — like, in Wayland, in X11, AND in the linux console. no cap, all three. 👑

oh and pspsps: evtest(1) can be used to identify keycodes of an input device. handy bestie behavior fr fr.

🫶 USAGE:

evremap remap config-file --delay <delay>

evremap list-devices

evremap list-keys

evremap debug-events

🎀 FLAGS:

• -d, --delay <delay> — Startup delay in second 🕐
• -h, --help — Prints help information 🙈
• -V, --version — Prints version information ⭐

🦋 SUBCOMMANDS:

• help — Prints this message or the help of the given subcommand(s) 🧚
• list-devices — Rather than running the remapper, list currently available devices. This is helpful to check their names when setting up the initial configuration 💻
• list-keys — Show a list of possible KEY_XXX values 🔑
• debug-events — Listen to events and print them out to facilitate learning which keys/buttons have which labels for your device(s) 👀
• remap — Load a remapper config and run the remapper. This usually requires running as root to obtain exclusive access to the input devices 🔥

🌈 FILE 🌈

• /etc/evremap.conf — Mapping configuration file 💜

🍓 Sample Configuration 🍓

okay here's the whole config, verbatim, because every line of it matters:

# The name of the device to remap.
# Run `sudo evremap list-devices` to see the devices available
# on your system.
device_name = "AT Translated Set 2 keyboard"

# If you have multiple devices with the same name, you can optionally
# specify the `phys` value that is printed by the `list-devices` subcommand
# phys = "usb-0000:07:00.3-2.1.1/input0"

# Configure CAPSLOCK as a Dual Role key.
# Holding it produces LEFTCTRL, but tapping it
# will produce ESC.
# Both `tap` and `hold` can expand to multiple output keys.
[[dual_role]]
input = "KEY_CAPSLOCK"
hold = ["KEY_LEFTCTRL"]
tap = ["KEY_ESC"]
# This config snippet is useful if your keyboard has an arrow
# cluster, but doesn't have page up, page down, home or end
# keys.  Here we're configuring ALT+arrow to map to those functions.
[[remap]]
input = ["KEY_LEFTALT", "KEY_UP"]
output = ["KEY_PAGEUP"]

[[remap]]
input = ["KEY_LEFTALT", "KEY_DOWN"]
output = ["KEY_PAGEDOWN"]

[[remap]]
input = ["KEY_LEFTALT", "KEY_LEFT"]
output = ["KEY_HOME"]

[[remap]]
input = ["KEY_LEFTALT", "KEY_RIGHT"]
output = ["KEY_END"]

# When applying remapping configuration, ordering is important:
# Dual Role entries are always processed first Remap entries are applied in
# the order that they appear in your configuration file

# Here's an example where ordering is important: on the PixelBook Go keyboard, the
# function key row has alternate functions on the keycaps. It is natural to want
# the mute button to mute by default, but to emit the F8 key when holding alt. We
# can express that with the following configuration:

[[remap]]
input = ["KEY_LEFTALT", "KEY_F8"]
# When our `input` is matched, our list of `output` is prevented from
# matching as the `input` of subsequent rules.
output = ["KEY_F8"]

[[remap]]
input = ["KEY_F8"]
output = ["KEY_MUTE"]

warning bestie!! ordering is IMPORTANT when applying remapping configuration: Dual Role entries are always processed first, and Remap entries are applied in the order that they appear in your configuration file. the PixelBook Go example above is literally there to show you why that matters. do not shuffle your rules around and then act surprised. 💀

👑 SEE ALSO 👑

• evtest(1)

💜 AUTHOR 💜

This man page was written by Yifei Zhan <yifei@zhan.science> using README.md from https://github.com/wez/evremap

This program was written by Wez Furlong

okay that's the whole thing, you ate it, you understood it, main character energy achieved ✨ this was evremap version 0.1.0, dated May 2024, and honestly? iconic. go remap something. ily, bye 🎀💅🦋