Jump to content

# Map scancodes to keycodes

2 languages

- 日本語
- 中文（简体）

From ArchWiki

Related articles

- Xorg/Keyboard configuration
- Linux console/Keyboard configuration

This page assumes that you have read Keyboard input, which provides wider context.

Mapping scancodes to keycodes is achieved in a layer lower than Xorg and Linux console, which means that changes to this mapping will be effective in both. [1][2][3] Note that this method can only be used for simple 1:1 key remaps; see Input remap utilities for programs which allow more complex remaps at the same low level.

There are two ways of mapping scancodes to keycodes:

- Using udev
- Using setkeycodes(8)

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 Keyboard input#Identifying 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 hwdb(7) for details.

The .hwdb file can apply key mappings to one or more keyboards based on hardware ID glob patterns. You may obtain device identification info by running evemu-describe(1) as the root user. This command is provided by the evemu package.

The `evdev:` prefix is used to match hardware against a block of mappings. The following hardware matches are supported:

- Generic input devices (also USB keyboards) identified by the usb kernel modalias:

      evdev:input:b<bus_id>v<vendor_id>p<product_id>e<version_id>-<input_modalias>

  with the following 4-digit hex uppercase fields:
  - `<vendor_id>`, `<product_id>` and `<version_id>`: vendor, product and version IDs matching the output of the `lsusb` command.
  - `<bus_id>` is the 4-digit hex bus id and should be 0003 for usb devices. The possible `<bus_id>` values are defined in `/usr/include/linux/input.h` (you can run `awk '/BUS_/ {print $2, $3}' /usr/include/linux/input.h` to get a list).
  - `<input_modalias>` is an arbitrary length input-modalias describing the device capabilities. The other fields are sufficient to uniquely identify the device, so you can use a glob here.
  If you have the device currently plugged into your computer then you can get the whole modalias at once using sysfs, as demonstrated in #Remap specific device.

- Input driver device name and DMI data match:

      evdev: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-event-codes.h` (see the `KEY_<KEYCODE>` variables), a sorted list is available at [4]. It is not possible to specify decimal value in `<keycode>`.

### Examples

#### Remap all devices

Suppose we want to remap a couple of common keys for all AT keyboards:

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

    evdev:atkbd:*
     KEYBOARD_KEY_10=suspend
     KEYBOARD_KEY_a0=search

#### Remap specific device

Suppose we want to remap a device that you happen to currently have plugged in. You should already have the evdev path (e.g. `/dev/input/event17`) as well as the scancode (e.g. `70039` for caps lock). Now, using the event number, you can query sysfs for the modalias:

    cat /sys/class/input/event17/device/modalias

    input:b0003v32ACp0012e0111-e0,1,4,1...

This device could be matched with the following hwdb rule:

    /etc/udev/hwdb.d/90-remap.hwdb

    evdev:input:b0003v32ACp0012e0111*
     KEYBOARD_KEY_70039=rightctrl # This example maps the 70039 scancode to the "rightctrl" keycode.

#### Disable key

To block the `Sleep` key, bind it to the "reserved" keyword. Alternatively, you can use "unknown" to map it to the `NoSymbol` key. For example:

    /etc/udev/hwdb.d/90-block-sleep.hwdb

    evdev:input:b0003v03F0p020C* # hp 5308 keyboard controller
     KEYBOARD_KEY_10082=reserved

### 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

    # systemd-hwdb update

- Update automatically on each reboot by commenting out `ConditionNeedsUpdate` in `systemd-hwdb-update.service` using a replacement unit file

    /etc/systemd/system/systemd-hwdb-update.service

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

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

- Automatically after systemd upgrade.

On each upgrade of systemd, the `30-systemd-hwdb.hook` rebuilds `hwdb.bin` by running `systemd-hwdb --usr update` as the root user, so we do not 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 is 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 configuration file, rebuild `hwdb.bin` and run `udevadm trigger` as the root user, then the deleted mapping still kept by the kernel, at least until a reboot.

### Querying the database

You can check that your configuration was loaded either by pressing keys, or by running `udevadm info`. For the USB keyboard in the above example, this outputs the mapping we configured as follows:

    # udevadm info /dev/input/by-path/*-usb-*-kbd | grep KEYBOARD_KEY
    E: KEYBOARD_KEY_70039=leftalt
    E: KEYBOARD_KEY_700e2=leftctrl

## 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.

Note:

The factual accuracy of this article or section is disputed.

Reason: On Linux 6.7.8-zen1-1-zen, this appears to fail quietly rather than emitting an error. (Discuss in Talk:Map scancodes to keycodes)

Apparently setkeycodes does not work with USB keyboards (Linux 3.14.44-1-lts):

    # setkeycodes 45 30     # bind NumLock (0x45) to KEY_A (30) on AT keyboard
    (successful)
    # setkeycodes 70053 30  # bind NumLock (0x70053) to KEY_A (30) on USB keyboard
    KDSETKEYCODE: Invalid argument
    failed to set scancode 620d3 to keycode 31

If using this simple command, changes will be lost after reboot. The changes can be made permanent by creating a new service:

    /etc/systemd/system/setkeycodes.service

    [Unit]
    Description=Change keycodes at boot

    [Service]
    Type=oneshot
    ExecStart=/usr/bin/setkeycodes [scancode] [keycode] [scancode] [keycode] [...]

    [Install]
    WantedBy=multi-user.target

and enabling `setkeycodes.service`.

Category:

- Keyboard configuration

Hidden category:

- Pages or sections flagged with Template:Accuracy