1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
|
<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>
|
