Home | History | Annotate | Download | only in input
      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 &#39;0&#39;-&#39;9&#39;, &#39;a&#39;-&#39;z&#39;,
     53 &#39;A&#39;-&#39;Z&#39;, &#39;-&#39; or &#39;&#95;&#39; are replaced by
     54 &#39;&#95;&#39;.</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 &lt;!-- 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. --&gt;
    301 
    302 &lt;integer name="config_virtualKeyQuietTimeMillis"&gt;250&lt;/integer&gt;
    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