Map scancodes to keycodes - ArchWiki

# Map scancodes to keycodes

Note: This page assumes that you have read Extra keyboard keys, which provides wider context to the problem.

Mapping scancodes to keycodes is universal and not specific to Linux console or Xorg, which means that changes to this mapping will be effective in both.

There are two ways of mapping scancodes to keycodes:

- Using udev
- Using setkeycodes

The preferred method is to use udev because it uses hardware information (which is a quite reliable source) to choose the keyboard model in a database. It means that if your keyboard model has been found in the database, your keys are recognized out of the box.

## Identifying scancodes

You need to know the scancodes of keys you wish to remap. See Extra keyboard keys#Scancodes for details.

## Using udev

udev provides a builtin function called hwdb to maintain the hardware database index in `/etc/udev/hwdb.bin`. The database is compiled from files with .hwdb extension located in directories `/usr/lib/udev/hwdb.d/`, `/run/udev/hwdb.d/` and `/etc/udev/hwdb.d/`. The default scancodes-to-keycodes mapping file is `/usr/lib/udev/hwdb.d/60-keyboard.hwdb`. See `man udev` for details.

The .hwdb file can contain multiple blocks of mappings for different keyboards, or one block can be applied to multiple keyboards. The `keyboard:` prefix is used to match a block against a hardware, the following hardware matches are supported:

- USB keyboards identified by the usb kernel modalias:

      keyboard:usb:v<vendor_id>p<product_id>*

  where `<vendor_id>` and `<product_id>` are the 4-digit hex uppercase vendor and product IDs (you can find those by running the `lsusb` command).
- AT keyboard DMI data matches:

      keyboard:dmi:bvn*:bvr*:bd*:svn<vendor>:pn<product>:pvr*

  where `<vendor>` and `<product>` are the firmware-provided strings exported by the kernel DMI modalias.
- Platform driver device name and DMI data match:

      keyboard:name:<input_device_name>:dmi:bvn*:bvr*:bd*:svn<vendor>:pn*

  where `<input_device_name>` is the name device specified by the driver and `<vendor>` is the firmware-provided string exported by the kernel DMI modalias.

The format of each line in the block body is `KEYBOARD_KEY_<scancode>=<keycode>`. The value of `<scancode>` is hexadecimal, but without the leading `0x` (i.e. specify `a0` instead of `0xa0`), whereas the value of `<keycode>` is the lower-case keycode name string as listed in `/usr/include/linux/input.h` (see the `KEY_<KEYCODE>` variables), a sorted list is available at [1]. It is not possible to specify decimal value in `<keycode>`.

### Example for custom hwdb

The example hwdb file will match all USB and AT keyboards:

    /etc/udev/hwdb.d/90-custom-keyboard.hwdb

    keyboard:usb:v*p*
    keyboard:dmi:bvn*:bvr*:bd*:svn*:pn*:pvr*
     KEYBOARD_KEY_10=suspend
     KEYBOARD_KEY_a0=search

### Updating the Hardware Database Index

After changing the configuration files, the hardware database index, `hwdb.bin`, needs to be rebuilt.

- Update `hwdb.bin` manually by running

    # udevadm hwdb --update

- Update automatically on each reboot by commenting out `ConditionNeedsUpdate` in `systemd-udev-hwdb-update.service`.

    /usr/lib/systemd/system/systemd-udev-hwdb-update.service

    #  This file is part of systemd.
    .
    .
    #ConditionNeedsUpdate=/etc
    .
    .

After `systemd-udev-hwdb-update.service` finished loading `systemd-udev-trigger.service` will reload the changes from `hwdb.bin`.

- Automatically after Systemd upgrade.

On each upgrade of Systemd, the installation script rebuilds `hwdb.bin` by running `# udevadm hwdb --update` so we don't need to care about it.

### Reloading the Hardware Database Index

The kernel loads `hwdb.bin` as part of the boot process, rebooting the system will promise the loading of the updated `hwdb.bin`.

With `udevadm` it's possible to load new key mapping from the updated `hwdb.bin` by running

    # udevadm trigger

Be aware that with `udevadm` only added or changed key mapping are loaded so if we delete a mapping from the config file, rebuild `hwdb.bin` and run `# udevadm trigger` then the deleted mapping still kept by the kernel, at least until a reboot.

## Using setkeycodes

setkeycodes is a tool to load scancodes-to-keycodes mapping table into Linux kernel. Its usage is:

    # setkeycodes scancode keycode ...

It is possible to specify multiple pairs at once. Scancodes are given in hexadecimal, keycodes in decimal.

Category:

- Keyboards