1 <html devsite> 2 <head> 3 <title>Key Layout Files</title> 4 <meta name="project_path" value="/_project.yaml" /> 5 <meta name="book_path" value="/_book.yaml" /> 6 </head> 7 <body> 8 <!-- 9 Copyright 2017 The Android Open Source Project 10 11 Licensed under the Apache License, Version 2.0 (the "License"); 12 you may not use this file except in compliance with the License. 13 You may obtain a copy of the License at 14 15 http://www.apache.org/licenses/LICENSE-2.0 16 17 Unless required by applicable law or agreed to in writing, software 18 distributed under the License is distributed on an "AS IS" BASIS, 19 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 20 See the License for the specific language governing permissions and 21 limitations under the License. 22 --> 23 24 25 26 <p>Key layout files (<code>.kl</code> files) map Linux key codes and axis codes 27 to Android key codes and axis codes and specify associated policy flags. 28 Device-specific key layout files are:</p> 29 <ul> 30 <li><em>Required</em> for internal (built-in) input devices with keys, including 31 special keys such as volume, power, and headset media keys.</li> 32 <li><em>Optional</em> for other input devices but <em>recommended</em> for 33 special-purpose keyboards and joysticks.</li> 34 </ul> 35 <p>If no device-specific key layout file is available, the system chooses a 36 default instead.</p> 37 38 <h2 id="location">Location</h2> 39 <p>Key layout files are located by USB vendor, product (and optionally version) 40 id or by input device name. The following paths are consulted in order:</p> 41 <ul> 42 <li><code>/system/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl</code></li> 43 <li><code>/system/usr/keylayout/Vendor_XXXX_Product_XXXX.kl</code></li> 44 <li><code>/system/usr/keylayout/DEVICE_NAME.kl</code></li> 45 <li><code>/data/system/devices/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl</code></li> 46 <li><code>/data/system/devices/keylayout/Vendor_XXXX_Product_XXXX.kl</code></li> 47 <li><code>/data/system/devices/keylayout/DEVICE_NAME.kl</code></li> 48 <li><code>/system/usr/keylayout/Generic.kl</code></li> 49 <li><code>/data/system/devices/keylayout/Generic.kl</code></li> 50 </ul> 51 <p>When constructing a file path that contains the device name, all characters 52 in the device name other than '0'-'9', 'a'-'z', 53 'A'-'Z', '-' or '_' are replaced by 54 '_'.</p> 55 56 <h2 id="generic-key-layout-file">Generic Key Layout File</h2> 57 <p>The system provides a special built-in generic key layout file called 58 <code>Generic.kl</code>. This key layout is intended to support a variety of 59 standard external keyboards and joysticks. <strong>Do not modify the generic key 60 layout!</strong></p> 61 62 <h2 id="syntax">Syntax</h2> 63 <p>A key layout file is a plain text file consisting of key or axis declarations 64 and flags.</p> 65 66 <h3 id="key-declarations">Key Declarations</h3> 67 <p>Key declarations consist of the keyword <code>key</code> followed by a Linux 68 key code number and Android key code name, or the keyword usage followed by a 69 HID usage and Android key code name. The HID usage is represented as a 32-bit 70 integer, where the high 16-bits represent the HID usage page and the low 16-bits 71 represent the HID usage ID. Either declaration can be followed by an optional 72 set of whitespace-delimited policy flags.</p> 73 <pre class="devsite-click-to-copy"> 74 key 1 ESCAPE 75 key 114 VOLUME_DOWN 76 key 16 Q VIRTUAL 77 key usage 0x0c006F BRIGHTNESS_UP 78 </pre> 79 <p>The following policy flags are recognized:</p> 80 <ul> 81 <li><code>FUNCTION</code>: The key should be interpreted as if the FUNCTION key 82 were also pressed.</li> 83 <li><code>GESTURE</code>: The key generated by a user gesture, such as palming 84 the touchscreen.</li> 85 <li><code>VIRTUAL</code>: The key is a virtual soft key (capacitive button) 86 adjacent to the main touch screen. This causes special debouncing logic to be 87 enabled (see below).</li> 88 </ul> 89 90 <h3 id="axis-declarations">Axis Declarations</h3> 91 <p>Axis declarations each consist of the keyword <code>axis</code> followed by a 92 Linux axis code number and qualifiers that control the behavior of the axis 93 including at least one Android axis code name.</p> 94 95 <h4 id="basic-axes">Basic Axes</h4> 96 <p>A basic axis simply maps a Linux axis code to an Android axis code name. The 97 following declaration maps <code>ABS_X</code> (indicated by <code>0x00</code>) 98 to <code>AXIS_X</code> (indicated by <code>X</code>).</p> 99 <pre class="devsite-click-to-copy"> 100 axis 0x00 X 101 </pre> 102 <p>In the above example, if the value of <code>ABS_X</code> is <code>5</code> 103 then <code>AXIS_X</code> is set to <code>5</code>.</p> 104 105 <h4 id="split-axes">Split Axes</h4> 106 <p>A split axis maps a Linux axis code to two Android axis code names, such that 107 values less than or greater than a threshold are split across two different axes 108 when mapped. This mapping is useful when a single physical axis reported by the 109 device encodes two different mutually exclusive logical axes.</p> 110 <p>The following declaration maps values of the <code>ABS_Y</code> axis 111 (indicated by <code>0x01</code>) to <code>AXIS_GAS</code> when less than 112 <code>0x7f</code> or to <code>AXIS_BRAKE</code> when greater than 113 <code>0x7f</code>.</p> 114 <pre class="devsite-click-to-copy"> 115 axis 0x01 split 0x7f GAS BRAKE</pre> 116 <p>In the above example, if the value of <code>ABS_Y</code> is <code>0x7d</code> 117 then <code>AXIS_GAS</code> is set to <code>2</code> (<code>0x7f - 0x7d</code>) 118 and <code>AXIS_BRAKE</code> is set to <code>0</code>. Conversely, if the value 119 of <code>ABS_Y</code> is <code>0x83</code> then <code>AXIS_GAS</code> is set to 120 <code>0</code> and <code>AXIS_BRAKE</code> is set to <code>4</code> 121 (<code>0x83 - 0x7f</code>). Finally, if the value of <code>ABS_Y</code> equals 122 the split value of <code>0x7f</code> then both <code>AXIS_GAS</code> and 123 <code>AXIS_BRAKE</code> are set to <code>0</code>.</p> 124 125 <h4 id="inverted-axes">Inverted Axes</h4> 126 <p>An inverted axis inverts the sign of the axis value. The following 127 declaration maps <code>ABS_RZ</code> (indicated by <code>0x05</code>) to 128 <code>AXIS_BRAKE</code> (indicated by <code>BRAKE</code>), and inverts the 129 output by negating it.</p> 130 <pre class="devsite-click-to-copy"> 131 axis 0x05 invert BRAKE 132 </pre> 133 <p>In the above example, if the value of <code>ABS_RZ</code> is <code>2</code> 134 then <code>AXIS_BRAKE</code> is set to <code>-2</code>.</p> 135 136 <h4 id="center-flat-position-option">Center Flat Position Option</h4> 137 <p>The center flat position is the neutral position of the axis, such as when 138 a directional pad is in the very middle of its range and the user is not 139 touching it.</p> 140 <p>The Linux input protocol provides a way for input device drivers to specify 141 the center flat position of joystick axes but not all of them do and some of 142 them provide incorrect values. To resolve this issue, an axis declaration may be 143 followed by a <code>flat</code> option that specifies the value of the center 144 flat position for the axis.</p> 145 <pre class="devsite-click-to-copy"> 146 axis 0x03 Z flat 4096 147 </pre> 148 <p>In the above example, the center flat position is set to <code>4096</code>. 149 </p> 150 151 <h3 id="comments">Comments</h3> 152 <p>Comment lines begin with # and continue to the end of the line:</p> 153 <pre class="devsite-click-to-copy"> 154 # A comment! 155 </pre> 156 <p>Blank lines are ignored.</p> 157 158 <h3 id="examples">Examples</h3> 159 160 <h4 id="keyboard">Keyboard</h4> 161 <pre class="devsite-click-to-copy"> 162 # This is an example of a key layout file for a keyboard. 163 164 key 1 ESCAPE 165 key 2 1 166 key 3 2 167 key 4 3 168 key 5 4 169 key 6 5 170 key 7 6 171 key 8 7 172 key 9 8 173 key 10 9 174 key 11 0 175 key 12 MINUS 176 key 13 EQUALS 177 key 14 DEL 178 179 # etc... 180 </pre> 181 182 <h4 id="system-controls">System Controls</h4> 183 <pre class="devsite-click-to-copy"> 184 # This is an example of a key layout file for basic system controls, 185 # such as volume and power keys which are typically implemented as GPIO pins 186 # the device decodes into key presses. 187 188 key 114 VOLUME_DOWN 189 key 115 VOLUME_UP 190 key 116 POWER 191 </pre> 192 193 <h4 id="capacitive-buttons">Capacitive Buttons</h4> 194 <pre class="devsite-click-to-copy"> 195 # This is an example of a key layout file for a touch device with capacitive buttons. 196 197 key 139 MENU VIRTUAL 198 key 102 HOME VIRTUAL 199 key 158 BACK VIRTUAL 200 key 217 SEARCH VIRTUAL 201 </pre> 202 203 <h4 id="headset-jack-media-controls">Headset Jack Media Controls</h4> 204 <pre class="devsite-click-to-copy"> 205 # This is an example of a key layout file for headset mounted media controls. 206 # A typical headset jack interface might have special control wires or detect known 207 # resistive loads as corresponding to media functions or volume controls. 208 # This file assumes that the driver decodes these signals and reports media 209 # controls as key presses. 210 211 key 163 MEDIA_NEXT 212 key 165 MEDIA_PREVIOUS 213 key 226 HEADSETHOOK 214 </pre> 215 216 <h4 id="joystick">Joystick</h4> 217 <pre class="devsite-click-to-copy"> 218 # This is an example of a key layout file for a joystick. 219 220 # These are the buttons that the joystick supports, represented as keys. 221 key 304 BUTTON_A 222 key 305 BUTTON_B 223 key 307 BUTTON_X 224 key 308 BUTTON_Y 225 key 310 BUTTON_L1 226 key 311 BUTTON_R1 227 key 314 BUTTON_SELECT 228 key 315 BUTTON_START 229 key 316 BUTTON_MODE 230 key 317 BUTTON_THUMBL 231 key 318 BUTTON_THUMBR 232 233 # Left and right stick. 234 # The reported value for flat is 128 in a range of -32767 to 32768, which is absurd. 235 # This confuses applications that rely on the flat value because the joystick 236 # actually settles in a flat range of +/- 4096 or so. We override it here. 237 axis 0x00 X flat 4096 238 axis 0x01 Y flat 4096 239 axis 0x03 Z flat 4096 240 axis 0x04 RZ flat 4096 241 242 # Triggers. 243 axis 0x02 LTRIGGER 244 axis 0x05 RTRIGGER 245 246 # Hat. 247 axis 0x10 HAT_X 248 axis 0x11 HAT_Y 249 </pre> 250 251 <h2 id="virtual-soft-keys">Virtual Soft Keys</h2> 252 <p>The input system provides special features for implementing virtual soft keys 253 in the following use cases:</p> 254 <ol> 255 <li>If the virtual soft keys are displayed graphically on the screen (such as on 256 the Galaxy Nexus), they are implemented by the Navigation Bar component in the 257 System UI package. Because graphical virtual soft keys are implemented at a high 258 layer in the system, key layout files are not involved and the following 259 information does not apply.</li> 260 <li>If the virtual soft keys are implemented as an extended touchable region 261 that is part of the main touch screen (such as on the Nexus One), the input 262 system uses a virtual key map file to translate X/Y touch coordinates into 263 Linux key codes, then uses the key layout file to translate Linux key codes into 264 Android key codes (for details on virtual key map files, see 265 <a href="touch-devices.html">Touch Devices</a>). The key layout file for the 266 touch screen input device must specify the appropriate key mapping and include 267 the <code>VIRTUAL</code> flag for each key.</li> 268 <li>If the virtual soft keys are implemented as capacitive buttons separate from 269 the main touch screen (such as on the Nexus S), the kernel device driver or 270 firmware is responsible for translating touches into Linux key codes which the 271 input system then translates into Android key codes using the key layout file. 272 The key layout file for the capacitive button input device must specify the 273 appropriate key mapping and include the <code>VIRTUAL</code> flag for each key.</li> 274 </ol> 275 <p>When virtual soft keys are located within or in close physical proximity of 276 the touch screen, it is easy for users to accidentally press a button when 277 touching near the bottom of the screen or when sliding a finger top-to-bottom or 278 bottom-to-top on the screen. To prevent this, the input system applies a little 279 debouncing such that virtual soft key presses are ignored for a brief period of 280 time after the most recent touch on the touch screen (this delay is called the 281 <em>virtual key quiet time</em>).</p> 282 <p>To enable virtual soft key debouncing:</p> 283 <ol> 284 <li>Provide a key layout file for the touch screen or capacitive button 285 input device with the <code>VIRTUAL</code> flag set for each key. 286 <pre class="devsite-click-to-copy"> 287 key 139 MENU VIRTUAL 288 key 102 HOME VIRTUAL 289 key 158 BACK VIRTUAL 290 key 217 SEARCH VIRTUAL 291 </pre> 292 </li> 293 <li>Set the value of the virtual key quiet time in a resource overlay for the 294 framework <code>config.xml</code> resource. 295 <pre class="devsite-click-to-copy"> 296 <!-- Specifies the amount of time to disable virtual keys after the screen 297 is touched to filter out accidental virtual key presses due to swiping gestures 298 or taps near the edge of the display. May be 0 to disable the feature. 299 It is recommended that this value be no more than 250 ms. 300 This feature should be disabled for most devices. --> 301 302 <integer name="config_virtualKeyQuietTimeMillis">250</integer> 303 </pre> 304 </li> 305 </ol> 306 307 <h2 id="validation">Validation</h2> 308 <p>You should validate your key layout files using the 309 <a href="validate-keymaps.html">Validate Keymaps</a> tool.</p> 310 </body> 311 </html> 312