Key layout files

Key layout files (.kl files) map Linux key codes and axis codes to Android key codes and axis codes and specify associated policy flags. Device-specific key layout files are:

  • Required for internal (built-in) input devices with keys, including special keys such as volume, power, and headset media keys.
  • Optional for other input devices but recommended for special-purpose keyboards and joysticks.

If no device-specific key layout file is available, the system chooses a default instead.

Location

Key layout files are located by USB vendor, product (and optionally version) id or by input device name. The following paths are consulted in order:

  • /odm/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl
  • /vendor/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl
  • /system/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl
  • /data/system/devices/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl
  • /odm/usr/keylayout/Vendor_XXXX_Product_XXXX.kl
  • /vendor/usr/keylayout/Vendor_XXXX_Product_XXXX.kl
  • /system/usr/keylayout/Vendor_XXXX_Product_XXXX.kl
  • /data/system/devices/keylayout/Vendor_XXXX_Product_XXXX.kl
  • /odm/usr/keylayout/DEVICE_NAME.kl
  • /vendor/usr/keylayout/DEVICE_NAME.kl
  • /system/usr/keylayout/DEVICE_NAME.kl
  • /data/system/devices/keylayout/DEVICE_NAME.kl
  • /odm/usr/keylayout/Generic.kl
  • /vendor/usr/keylayout/Generic.kl
  • /system/usr/keylayout/Generic.kl
  • /data/system/devices/keylayout/Generic.kl

When constructing a file path that contains the device name, all characters in the device name other than '0'-'9', 'a'-'z', 'A'-'Z', '-' or '_' are replaced by '_'.

Generic key layout file

The system provides a special built-in generic key layout file called Generic.kl. This key layout is intended to support a variety of standard external keyboards and joysticks. Do not modify the generic key layout!

Syntax

A key layout file is a plain text file consisting of key or axis declarations and flags.

Key declarations

Key declarations consist of the keyword key followed by a Linux key code number and Android key code name, or the keyword usage followed by a HID usage and Android key code name. The HID usage is represented as a 32-bit integer, where the high 16-bits represent the HID usage page and the low 16-bits represent the HID usage ID. Either declaration can be followed by an optional set of whitespace-delimited policy flags.

key 1     ESCAPE
key 114   VOLUME_DOWN
key 16    Q                 VIRTUAL
key usage 0x0c006F          BRIGHTNESS_UP

The following policy flags are recognized:

  • FUNCTION: The key should be interpreted as if the FUNCTION key were also pressed.
  • GESTURE: The key generated by a user gesture, such as palming the touchscreen.
  • VIRTUAL: The key is a virtual soft key (capacitive button) adjacent to the main touch screen. This causes special debouncing logic to be enabled (see below).

Axis declarations

Axis declarations each consist of the keyword axis followed by a Linux axis code number and qualifiers that control the behavior of the axis including at least one Android axis code name.

Basic axes

A basic axis simply maps a Linux axis code to an Android axis code name. The following declaration maps ABS_X (indicated by 0x00) to AXIS_X (indicated by X).

axis 0x00 X

In the above example, if the value of ABS_X is 5 then AXIS_X is set to 5.

Split axes

A split axis maps a Linux axis code to two Android axis code names, such that values less than or greater than a threshold are split across two different axes when mapped. This mapping is useful when a single physical axis reported by the device encodes two different mutually exclusive logical axes.

The following declaration maps values of the ABS_Y axis (indicated by 0x01) to AXIS_GAS when less than 0x7f or to AXIS_BRAKE when greater than 0x7f.

axis 0x01 split 0x7f GAS BRAKE

In the above example, if the value of ABS_Y is 0x7d then AXIS_GAS is set to 2 (0x7f - 0x7d) and AXIS_BRAKE is set to 0. Conversely, if the value of ABS_Y is 0x83 then AXIS_GAS is set to 0 and AXIS_BRAKE is set to 4 (0x83 - 0x7f). Finally, if the value of ABS_Y equals the split value of 0x7f then both AXIS_GAS and AXIS_BRAKE are set to 0.

Inverted axes

An inverted axis inverts the sign of the axis value. The following declaration maps ABS_RZ (indicated by 0x05) to AXIS_BRAKE (indicated by BRAKE), and inverts the output by negating it.

axis 0x05 invert BRAKE

In the above example, if the value of ABS_RZ is 2 then AXIS_BRAKE is set to -2.

Center flat option

A joystick device may report input events even when the joystick is not being used, due to noise. This noise typically comes from the left and/or right sticks, and causes the driver to report a position value near 0. The "center flat" value specifies the amount of noise to expect from the controller at rest.

The Linux input protocol provides a way for input device drivers to specify the center flat value of joystick axes, but not all drivers report it and some of them provide incorrect values. To resolve this issue, an axis declaration may be followed by a flat option that specifies the width of the region around the center position of the axis that should be considered as centered.

For example, if a device driver reports values for AXIS_X between 0 and 100, then 0 will be mapped to -1 and 100 will be mapped to 1 by the Android input system. The center of the range will be 50 in the unscaled coordinates and 0 in the scaled coordinates. If a flat value is equal to 10, then the developers should assume that any AXIS_X value reported between -0.1 and 0.1 (between 40 and 60 in unscaled coordinates) is noise, and treat those values coming from the joystick as zero.

Note: While the key layout file specifies the value for the driver coordinate space, the value reported by android.view.InputDevice.MotionRange#getFlat() is in the Android coordinate space.

axis 0x03 Z flat 4096

In the above example, the center flat value is set to 4096.

Comments

Comment lines begin with # and continue to the end of the line:

# A comment!

Blank lines are ignored.

Examples

Keyboard

# This is an example of a key layout file for a keyboard.

key 1     ESCAPE
key 2     1
key 3     2
key 4     3
key 5     4
key 6     5
key 7     6
key 8     7
key 9     8
key 10    9
key 11    0
key 12    MINUS
key 13    EQUALS
key 14    DEL

# etc...

System controls

# This is an example of a key layout file for basic system controls,
# such as volume and power keys which are typically implemented as GPIO pins
# the device decodes into key presses.

key 114   VOLUME_DOWN
key 115   VOLUME_UP
key 116   POWER

Capacitive buttons

# This is an example of a key layout file for a touch device with capacitive buttons.

key 139    MENU           VIRTUAL
key 172    HOME           VIRTUAL
key 158    BACK           VIRTUAL
key 217    SEARCH         VIRTUAL

Headset jack media controls

# This is an example of a key layout file for headset mounted media controls.
# A typical headset jack interface might have special control wires or detect known
# resistive loads as corresponding to media functions or volume controls.
# This file assumes that the driver decodes these signals and reports media
# controls as key presses.

key 163   MEDIA_NEXT
key 165   MEDIA_PREVIOUS
key 226   HEADSETHOOK

Joystick

# This is an example of a key layout file for a joystick.

# These are the buttons that the joystick supports, represented as keys.
key 304   BUTTON_A
key 305   BUTTON_B
key 307   BUTTON_X
key 308   BUTTON_Y
key 310   BUTTON_L1
key 311   BUTTON_R1
key 314   BUTTON_SELECT
key 315   BUTTON_START
key 316   BUTTON_MODE
key 317   BUTTON_THUMBL
key 318   BUTTON_THUMBR

# Left and right stick.
# The reported value for flat is 128 in a range of -32767 to 32768, which is absurd.
# This confuses applications that rely on the flat value because the joystick
# actually settles in a flat range of +/- 4096 or so. We override it here.
axis 0x00 X flat 4096
axis 0x01 Y flat 4096
axis 0x03 Z flat 4096
axis 0x04 RZ flat 4096

# Triggers.
axis 0x02 LTRIGGER
axis 0x05 RTRIGGER

# Hat.
axis 0x10 HAT_X
axis 0x11 HAT_Y

Virtual soft keys

The input system provides special features for implementing virtual soft keys in the following use cases:

  1. If the virtual soft keys are displayed graphically on the screen (such as on the Galaxy Nexus), they are implemented by the Navigation Bar component in the System UI package. Because graphical virtual soft keys are implemented at a high layer in the system, key layout files are not involved and the following information does not apply.
  2. If the virtual soft keys are implemented as an extended touchable region that is part of the main touch screen (such as on the Nexus One), the input system uses a virtual key map file to translate X/Y touch coordinates into Linux key codes, then uses the key layout file to translate Linux key codes into Android key codes (for details on virtual key map files, see Touch devices). The key layout file for the touch screen input device must specify the appropriate key mapping and include the VIRTUAL flag for each key.
  3. If the virtual soft keys are implemented as capacitive buttons separate from the main touch screen (such as on the Nexus S), the kernel device driver or firmware is responsible for translating touches into Linux key codes which the input system then translates into Android key codes using the key layout file. The key layout file for the capacitive button input device must specify the appropriate key mapping and include the VIRTUAL flag for each key.

When virtual soft keys are located within or in close physical proximity of the touch screen, it is easy for users to accidentally press a button when touching near the bottom of the screen or when sliding a finger top-to-bottom or bottom-to-top on the screen. To prevent this, the input system applies a little debouncing such that virtual soft key presses are ignored for a brief period of time after the most recent touch on the touch screen (this delay is called the virtual key quiet time).

To enable virtual soft key debouncing:

  1. Provide a key layout file for the touch screen or capacitive button input device with the VIRTUAL flag set for each key. 
    key 139    MENU           VIRTUAL
key 172    HOME           VIRTUAL
key 158    BACK           VIRTUAL
key 217    SEARCH         VIRTUAL
  2. Set the value of the virtual key quiet time in a resource overlay for the framework config.xml resource. 
    <!-- Specifies the amount of time to disable virtual keys after the screen
is touched to filter out accidental virtual key presses due to swiping gestures
or taps near the edge of the display. May be 0 to disable the feature.
It is recommended that this value be no more than 250 ms.
This feature should be disabled for most devices. -->

<integer name="config_virtualKeyQuietTimeMillis">250</integer>

Validation

You should validate your key layout files using the Validate Keymaps tool.