Map an Unrecognised Keyboard Scancode with setkeycodes

You will identify a key that Linux does not recognise, assign its scancode a kernel keycode, and verify that the mapping works. The change is live in the current kernel session. It is not a permanent keyboard configuration, so you will also record the original mapping before changing it.

Allow about 10 minutes if the key is easy to isolate. You need a Linux virtual console, the kbd package, and root access for the mapping. A graphical terminal is not a reliable place to run showkey: use a real text console, usually reached with Ctrl+Alt+F3, and switch back with your desktop's usual console key.

1. Check the installed command

Start by checking which program will run and which version it reports. This matters because the installed kbd 2.6.4 command accepts options that the older local manual page does not list.

$ command -v setkeycodes
/usr/bin/setkeycodes
$ setkeycodes --version
setkeycodes from kbd 2.6.4

Read the command's own usage text when in doubt:

$ setkeycodes --help
Usage: setkeycodes [option...] scancode keycode ...

On this version, -C or --console=DEV selects a console device, while -h and -V print help and the version. The installed manual's OPTIONS section says "None", so prefer the binary's output for these version-specific options.

2. Find the unknown scancode

Move to a virtual console before running the detector. The command waits for keyboard activity and exits after 10 seconds without a key event. Press only the unusual key you want to investigate, then allow it to time out.

$ showkey --scancodes
kb mode was UNICODE
 press any key (program terminates 10s after last keypress)...
e0 6f

The exact output depends on the keyboard. The example shows the two-byte extended scancode e0 6f. Write it without the space as e06f when passing it to setkeycodes. If you see no output, check that you are on a virtual console and that the key is not being intercepted by firmware or a desktop session.

3. Record the current mapping

Before changing state, save the kernel's existing scancode-to-keycode table. This gives you evidence for troubleshooting and the value needed to undo the change.

$ getkeycodes | tee "$HOME/setkeycodes-before.txt"
Plain scancodes xx (hex)     Keycode (dec)
00: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
...
Escaped scancodes e0 xx (hex)
e06f: 112

The table is host-specific and can be long. Find the line for the scancode you intend to alter. If there is no existing entry, record that fact too. Do not pick a keycode already assigned to an important key unless you have a deliberate reason: keycodes are kernel-wide identifiers, not labels that belong only to your new key.

4. Choose a keycode and apply the mapping

Choose a free keycode supported by your kernel. The manual describes the historical range as 1 to 127 and notes that 2.6 kernels use 1 to 255, with 1 to 239 suggested as the safer working range. Use the keycode your later keymap or application expects. The example assigns the unusual key to 112, as in the manual.

$ sudo setkeycodes e06f 112

A successful run normally prints nothing and returns status zero:

$ printf 'exit status: %s\n' "$?"
exit status: 0

Arguments are consumed in pairs, so multiple mappings can be supplied in one command:

$ sudo setkeycodes e06f 112 e071 113

Scancodes are hexadecimal. Keycodes are decimal. Do not write 0x or use hexadecimal for the keycode unless your particular command output and kernel documentation explicitly support that choice.

5. Verify the resulting keycode

Run the keycode viewer and press the remapped key. It should now produce the number you selected. Release the key as well, then wait for showkey to finish.

$ showkey --keycodes
kb mode was UNICODE
 press any key (program terminates 10s after last keypress)...
keycode 112 press
keycode 112 release

That confirms the kernel's keycode event. It does not define an application action. To give the key a console function, use a keymap with loadkeys. X keyboard mappings are separate: the setkeycodes manual explicitly warns that Linux keycodes and X keycodes are not the same system.

6. Recover from a wrong mapping

If the test is wrong, restore the original keycode from the file you saved in step 3. For example, if e06f was originally mapped to 112, use that original value again:

$ sudo setkeycodes e06f 112

If the scancode had no useful previous mapping, the safest recovery is to reboot, because this setting is held by the running kernel and is not automatically persistent. Do not guess a restore value. Check the saved table or obtain the mapping from a known-good machine with the same keyboard and kernel setup.

Common failures are usually straightforward:

• "Could not get a file descriptor referring to the console": run from a virtual console, or use the installed command's --console=DEV option with the correct console device.
• "Not enough arguments": provide complete scancode and keycode pairs. A trailing scancode has no keycode.
• "error reading scancode": use hexadecimal characters only, such as e06f.
• The key still does nothing: repeat discovery with showkey --scancodes. Firmware may emit a different sequence on each operating system or mode.
• The command fails to remap the key: older kernels can hardwire low scancodes. The kernel may also reject a keycode or scancode it cannot represent.

Done means

• You identified the scancode on a Linux virtual console.
• You saved the pre-change table and know the recovery value.
• setkeycodes returned status zero for the intended pair.
• showkey --keycodes reported the chosen keycode on press and release.
• You understand that the mapping is live-session state and that graphical key mappings need separate configuration.