Weekend Project: Configure Your Keyboard Into Submission


Most of us take our keyboards for granted when they’re working smoothly; perhaps we struggle for a bit finding the correct keyboard layout when doing a fresh Linux install, but once the OS is up and running they tend to stay out of our way. Except for those one or two keys that never quite do what they are supposed to.  From the application “hot keys” on full-sized or multimedia keyboards to the peculiar add-ons sported by some laptop and netbook models, there are bound to be one or two specialty keys that need tweaking. You’ll need some time and a couple of spare terminal windows to configure them into submission.

Keyboard Madness

Modern Linux desktop environments make the basic keyboard configuration process far simpler than it used to be, but it is still confusing. GNOME, for example, splits configuration between two graphical tools: gnome-keyboard-properties (launched from the System -> Preferences -> Keyboard menu entry), and gnome-keybinding-properties (found at System -> Preferences -> Keyboard Shortcuts). KDE places more of its keyboard configuration options in one place, KControl, but it also splits them into categories that make sense only for the developer, separating System Settings -> Computer Administration -> Keyboard & Mouse -> Global Keyboard Shortcuts from System Settings -> Computer Administration -> Input Actions from System Settings -> Computer Administration -> Keyboard & Mouse -> Standard Keyboard Shortcuts.

In addition, neither tool really gives you full control, but only a pre-selected subset of what X can really do. To really take charge, you need to dig into the X keyboard extension and understand what these GUI tools actually do.

Starting Simple: Multimedia and “Internet” Keys

Because the multimedia, email, and WWW keys found on newer keyboards are not used for general text input, it is easiest to get started on key mapping with them — there are fewer repercussions if you make a mistake. The overall outline is that you will determine which keycode each key actually sends when pressed, then list these keycodes and assign a meaning to each of them in a configuration file.

To capture the codes, run the command xev from a shell prompt. This will launch a square window named “Event Tester” or something roughly equivalent. All X input actions you perform inside that window (both keystrokes and mouse actions) will be reported as output in the shell window. Move the mouse over the window and press one of the multimedia buttons. You will hopefully see two paragraphs of output, one for the KeyPress event and one for the KeyRelease event that follows it.

Most of the output is irrelevant for this exercise, but note the keycode number on the third line. You should jot this down in a text editor, and you will also need to notice if any keysym is currently assigned in the parentheses following the keycode. The Caps Lock key, for example, produces this in line three:

state 0x0, keycode 66 (keysym 0xffe5, Caps_Lock), same_screen YES,

The keycode is 66, and the presence of the Caps_Lock string after the comma tells us that this key is already assigned. An unassigned key such as a multimedia key will say (keysym 0x0, NoSymbol) instead.

When you have collected the keycodes for all of the keys you need to assign, create a plain text file named .Xmodmap in your home directory. At a command line, run xmodmap -pke. This is your current keymap, which you should copy and paste into your new ~/.Xmodmap file. On each line, you will see an entry for one key, with the syntax:

keycode NNN = SomeKeysym

For example, keycode 162 = XF86AudioPlay. The keysyms for normal characters are the character themselves, from a to Z, plus punctuation, numerals, and so on. There is probably no reason to ever touch them. Just scroll down to the keycodes for the keys you need to assign, and if the keysym value is blank, add one. If the entire line is absent, you can add it.

To load the keymap, run xmodmap ~/.Xmodmap. To make sure it runs at every login, add that line to your .xinitrc file.

XF86AudioPlay in the example above is one of the predefined “extra” keysyms available for multimedia keyboards, and part of Xorg. A list of the most recent existing definitions is available on most distros at /usr/share/X11/XKeysymDB, but can also be found in the Xorg source code. Many are defined to fit common commercial keyboards, such as the XF86Audio* controls or XF86Mail, but some are generic, such as XF86Launch0 through XF86LaunchF. You can use these to get the most out of a peculiar keyboard design.

What action each of these extended keysyms performs is determined by the session; this is where the GNOME and KDE tools can come into play. The gnome-keybinding-properties and KDE Standard Keyboard Shortcut editors have lists of common commands, many of which (like “Launch email client”) can be directly associated with one of the keysyms your keyboard now sends. You bind the selected action to the key simply by highlighting it and pressing the desired multimedia key.

Problem Keys

As you have no doubt already guessed, you use the same procedure to map meaningful functions to the remaining unused keys on your keyboard. As long as there is a keysym defined for the action, character, or behavior you want to assign, .Xmodmap can do it. The caveat here is that if you mess up and disable all of your “Return” or “Shift” keys, you may have to restart the machine at the power switch, drop into a virtual terminal, and remove the offending .Xmodmap file to recover.

This is what you need to do to take care of common keyboard quirks like the otherwise useless “Windows” key or Mac-centric “Open Apple” key. Simply grab the keycode reported by xev, and assign it to a useful keysym. Consult the full Xorg list in the source code if you are unsure of the proper keysym name; it is “Shift_L” not “L_Shift,” and “Prior” instead of “Page_Up.”

Here are some specifics you may want to start with….  The Compose key used to enter many accented and extended characters is called “Multi_key” keysym. Many users on Apple hardware map the “Open Apple” keys to “Control_L” and “Control_R” because of the convenient proximity and lack of normal “Control” keys.  Apple laptops are usually missing the “Alt_R” key but have an extra Enter key in its place, allowing for an easy fix.

One key that is not as easy is the “Function” or “Fn” key. Fn’s keysym is “F35” but it usually operates as a modifier key a la Shift or Control, and its behavior is not consistent across platforms because it is tied to the system BIOS and not to the physical keyboard itself. Thus, for a laptop, you may need to search for help specific to your manufacturer, and for a desktop machine you will want to look for help based on the motherboard manufacturer.

Fortunately, these days the most common problem is not that the Fn key is unrecognized but that its behavior is “inverted” — that is to say, you have to hold down the Fn key to get the normal F1 through F12 keystrokes, and without holding down Fn, what should be the modified functions (such as Print Screen) are relayed. If you just want to assign functions to the modified F-keys, xev will report the correct keycodes both for unmodified and Fn-modified key presses.

You can even map an otherwise unused key to a mouse middle- or right-click on laptops that feature only one or two trackpad buttons.  The keysyms are Pointer_Button2 and Pointer_Button3, respectively.

Advanced Keyboarding

There remain a few hardware-oriented keys commonly found on netbooks and laptops that require special handling because they bypass the normal keyboard system, instead generating Advanced Configuration and Power Interface (ACPI) or other low-level calls. Examples include Sleep/Suspend buttons, optical device eject buttons, WiFi and Bluetooth power toggle, and screen brightness.

Enabling these keys is usually a collection of ad-hoc solutions that vary from manufacturer to manufacturer, but it can almost always be done. For ASUS EEE PCs, install the eeepc-acpi-scripts package. For Lenovo Thinkpads, the thinkpad-acpi drivers fill the same role, as well as an older solution called tpb. Apple hardware owners should look for nvidia-bl-dkms to enable keyboard backlight support, and pommed for other hotkeys.  It is annoying, but at least having gone through the X keymap remapping process, you understand why these platform-specific keys do not always simply work out of the box.

Finally, with the exception of the ACPI-specific tools mentioned in the preceding paragraphs, note that most of the examples deal with remapping keys through the X Window system. That is probably of use to the widest range of users, particularly for “multimedia” functions that have no analogue in non-X environments, but it does not include everyone. If you need to adjust your keyboard mapping at the terminal, you can do many of the same tasks performed by xmodmap using the loadkeys tool instead. The syntax of the loadkeys configuration is only slightly different, and the dumpkeys utility performs most of the same functions served by xev, with results that will be valid on a terminal-only server or over an SSH connection. Try not to use loadkeys and xmodmap to monkey with your configuration on the same system, though — the results won’t be pretty to troubleshoot.

Extra Credit

Despite all of the power X, xmodmap, and the various Linux ACPI systems give you over your keyboard’s behavior, one thing still won’t change — and that’s the fact that no one has a use for the Scroll Lock key. You can remap it easy enough with the information above, but if you really want a challenge, try looking into making better use of the keyboard LED that accompanies it, Num Lock, and Caps Lock. A project named ledcontrol exists that attempts to give you full command over the blinking lights at your fingertips — with your imagination the only limit.

Alternatively, you might find it more rewarding to bind some of the extended Xorg keysyms to work with a full multimedia application like MythTV; often these applications provide functionality beyond the basic one-keystroke-per-command model, so special steps are required to enable full use of multimedia keys. You have anywhere from 100 to 120 keys on your keyboard, so you’d might as well put them to maximum use.