311 lines
13 KiB
HTML
311 lines
13 KiB
HTML
<html devsite>
|
|
<head>
|
|
<title>Key Layout Files</title>
|
|
<meta name="project_path" value="/_project.yaml" />
|
|
<meta name="book_path" value="/_book.yaml" />
|
|
</head>
|
|
<body>
|
|
<!--
|
|
Copyright 2017 The Android Open Source Project
|
|
|
|
Licensed under the Apache License, Version 2.0 (the "License");
|
|
you may not use this file except in compliance with the License.
|
|
You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
-->
|
|
|
|
|
|
|
|
<p>Key layout files (<code>.kl</code> 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:</p>
|
|
<ul>
|
|
<li><em>Required</em> for internal (built-in) input devices with keys, including
|
|
special keys such as volume, power, and headset media keys.</li>
|
|
<li><em>Optional</em> for other input devices but <em>recommended</em> for
|
|
special-purpose keyboards and joysticks.</li>
|
|
</ul>
|
|
<p>If no device-specific key layout file is available, the system chooses a
|
|
default instead.</p>
|
|
|
|
<h2 id="location">Location</h2>
|
|
<p>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:</p>
|
|
<ul>
|
|
<li><code>/system/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl</code></li>
|
|
<li><code>/system/usr/keylayout/Vendor_XXXX_Product_XXXX.kl</code></li>
|
|
<li><code>/system/usr/keylayout/DEVICE_NAME.kl</code></li>
|
|
<li><code>/data/system/devices/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl</code></li>
|
|
<li><code>/data/system/devices/keylayout/Vendor_XXXX_Product_XXXX.kl</code></li>
|
|
<li><code>/data/system/devices/keylayout/DEVICE_NAME.kl</code></li>
|
|
<li><code>/system/usr/keylayout/Generic.kl</code></li>
|
|
<li><code>/data/system/devices/keylayout/Generic.kl</code></li>
|
|
</ul>
|
|
<p>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
|
|
'_'.</p>
|
|
|
|
<h2 id="generic-key-layout-file">Generic Key Layout File</h2>
|
|
<p>The system provides a special built-in generic key layout file called
|
|
<code>Generic.kl</code>. This key layout is intended to support a variety of
|
|
standard external keyboards and joysticks. <strong>Do not modify the generic key
|
|
layout!</strong></p>
|
|
|
|
<h2 id="syntax">Syntax</h2>
|
|
<p>A key layout file is a plain text file consisting of key or axis declarations
|
|
and flags.</p>
|
|
|
|
<h3 id="key-declarations">Key Declarations</h3>
|
|
<p>Key declarations consist of the keyword <code>key</code> 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.</p>
|
|
<pre class="devsite-click-to-copy">
|
|
key 1 ESCAPE
|
|
key 114 VOLUME_DOWN
|
|
key 16 Q VIRTUAL
|
|
key usage 0x0c006F BRIGHTNESS_UP
|
|
</pre>
|
|
<p>The following policy flags are recognized:</p>
|
|
<ul>
|
|
<li><code>FUNCTION</code>: The key should be interpreted as if the FUNCTION key
|
|
were also pressed.</li>
|
|
<li><code>GESTURE</code>: The key generated by a user gesture, such as palming
|
|
the touchscreen.</li>
|
|
<li><code>VIRTUAL</code>: 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).</li>
|
|
</ul>
|
|
|
|
<h3 id="axis-declarations">Axis Declarations</h3>
|
|
<p>Axis declarations each consist of the keyword <code>axis</code> followed by a
|
|
Linux axis code number and qualifiers that control the behavior of the axis
|
|
including at least one Android axis code name.</p>
|
|
|
|
<h4 id="basic-axes">Basic Axes</h4>
|
|
<p>A basic axis simply maps a Linux axis code to an Android axis code name. The
|
|
following declaration maps <code>ABS_X</code> (indicated by <code>0x00</code>)
|
|
to <code>AXIS_X</code> (indicated by <code>X</code>).</p>
|
|
<pre class="devsite-click-to-copy">
|
|
axis 0x00 X
|
|
</pre>
|
|
<p>In the above example, if the value of <code>ABS_X</code> is <code>5</code>
|
|
then <code>AXIS_X</code> is set to <code>5</code>.</p>
|
|
|
|
<h4 id="split-axes">Split Axes</h4>
|
|
<p>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.</p>
|
|
<p>The following declaration maps values of the <code>ABS_Y</code> axis
|
|
(indicated by <code>0x01</code>) to <code>AXIS_GAS</code> when less than
|
|
<code>0x7f</code> or to <code>AXIS_BRAKE</code> when greater than
|
|
<code>0x7f</code>.</p>
|
|
<pre class="devsite-click-to-copy">
|
|
axis 0x01 split 0x7f GAS BRAKE</pre>
|
|
<p>In the above example, if the value of <code>ABS_Y</code> is <code>0x7d</code>
|
|
then <code>AXIS_GAS</code> is set to <code>2</code> (<code>0x7f - 0x7d</code>)
|
|
and <code>AXIS_BRAKE</code> is set to <code>0</code>. Conversely, if the value
|
|
of <code>ABS_Y</code> is <code>0x83</code> then <code>AXIS_GAS</code> is set to
|
|
<code>0</code> and <code>AXIS_BRAKE</code> is set to <code>4</code>
|
|
(<code>0x83 - 0x7f</code>). Finally, if the value of <code>ABS_Y</code> equals
|
|
the split value of <code>0x7f</code> then both <code>AXIS_GAS</code> and
|
|
<code>AXIS_BRAKE</code> are set to <code>0</code>.</p>
|
|
|
|
<h4 id="inverted-axes">Inverted Axes</h4>
|
|
<p>An inverted axis inverts the sign of the axis value. The following
|
|
declaration maps <code>ABS_RZ</code> (indicated by <code>0x05</code>) to
|
|
<code>AXIS_BRAKE</code> (indicated by <code>BRAKE</code>), and inverts the
|
|
output by negating it.</p>
|
|
<pre class="devsite-click-to-copy">
|
|
axis 0x05 invert BRAKE
|
|
</pre>
|
|
<p>In the above example, if the value of <code>ABS_RZ</code> is <code>2</code>
|
|
then <code>AXIS_BRAKE</code> is set to <code>-2</code>.</p>
|
|
|
|
<h4 id="center-flat-position-option">Center Flat Position Option</h4>
|
|
<p>The center flat position is the neutral position of the axis, such as when
|
|
a directional pad is in the very middle of its range and the user is not
|
|
touching it.</p>
|
|
<p>The Linux input protocol provides a way for input device drivers to specify
|
|
the center flat position of joystick axes but not all of them do and some of
|
|
them provide incorrect values. To resolve this issue, an axis declaration may be
|
|
followed by a <code>flat</code> option that specifies the value of the center
|
|
flat position for the axis.</p>
|
|
<pre class="devsite-click-to-copy">
|
|
axis 0x03 Z flat 4096
|
|
</pre>
|
|
<p>In the above example, the center flat position is set to <code>4096</code>.
|
|
</p>
|
|
|
|
<h3 id="comments">Comments</h3>
|
|
<p>Comment lines begin with # and continue to the end of the line:</p>
|
|
<pre class="devsite-click-to-copy">
|
|
# A comment!
|
|
</pre>
|
|
<p>Blank lines are ignored.</p>
|
|
|
|
<h3 id="examples">Examples</h3>
|
|
|
|
<h4 id="keyboard">Keyboard</h4>
|
|
<pre class="devsite-click-to-copy">
|
|
# 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...
|
|
</pre>
|
|
|
|
<h4 id="system-controls">System Controls</h4>
|
|
<pre class="devsite-click-to-copy">
|
|
# 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
|
|
</pre>
|
|
|
|
<h4 id="capacitive-buttons">Capacitive Buttons</h4>
|
|
<pre class="devsite-click-to-copy">
|
|
# This is an example of a key layout file for a touch device with capacitive buttons.
|
|
|
|
key 139 MENU VIRTUAL
|
|
key 102 HOME VIRTUAL
|
|
key 158 BACK VIRTUAL
|
|
key 217 SEARCH VIRTUAL
|
|
</pre>
|
|
|
|
<h4 id="headset-jack-media-controls">Headset Jack Media Controls</h4>
|
|
<pre class="devsite-click-to-copy">
|
|
# 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
|
|
</pre>
|
|
|
|
<h4 id="joystick">Joystick</h4>
|
|
<pre class="devsite-click-to-copy">
|
|
# 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
|
|
</pre>
|
|
|
|
<h2 id="virtual-soft-keys">Virtual Soft Keys</h2>
|
|
<p>The input system provides special features for implementing virtual soft keys
|
|
in the following use cases:</p>
|
|
<ol>
|
|
<li>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.</li>
|
|
<li>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
|
|
<a href="touch-devices.html">Touch Devices</a>). The key layout file for the
|
|
touch screen input device must specify the appropriate key mapping and include
|
|
the <code>VIRTUAL</code> flag for each key.</li>
|
|
<li>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 <code>VIRTUAL</code> flag for each key.</li>
|
|
</ol>
|
|
<p>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
|
|
<em>virtual key quiet time</em>).</p>
|
|
<p>To enable virtual soft key debouncing:</p>
|
|
<ol>
|
|
<li>Provide a key layout file for the touch screen or capacitive button
|
|
input device with the <code>VIRTUAL</code> flag set for each key.
|
|
<pre class="devsite-click-to-copy">
|
|
key 139 MENU VIRTUAL
|
|
key 102 HOME VIRTUAL
|
|
key 158 BACK VIRTUAL
|
|
key 217 SEARCH VIRTUAL
|
|
</pre>
|
|
</li>
|
|
<li>Set the value of the virtual key quiet time in a resource overlay for the
|
|
framework <code>config.xml</code> resource.
|
|
<pre class="devsite-click-to-copy">
|
|
<!-- 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>
|
|
</pre>
|
|
</li>
|
|
</ol>
|
|
|
|
<h2 id="validation">Validation</h2>
|
|
<p>You should validate your key layout files using the
|
|
<a href="validate-keymaps.html">Validate Keymaps</a> tool.</p>
|
|
</body>
|
|
</html>
|