Home | History | Annotate | Download | only in input 
      1 <!--
      2    Copyright 2011 The Android Open Source Project
      3 
      4    Licensed under the Apache License, Version 2.0 (the "License");
      5    you may not use this file except in compliance with the License.
      6    You may obtain a copy of the License at
      7 
      8        http://www.apache.org/licenses/LICENSE-2.0
      9 
     10    Unless required by applicable law or agreed to in writing, software
     11    distributed under the License is distributed on an "AS IS" BASIS,
     12    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13    See the License for the specific language governing permissions and
     14    limitations under the License.
     15 -->
     16 
     17 # Input Device Configuration Files #
     18 
     19 Input device configuration files (`.idc` files) contain device-specific
     20 configuration properties that affect the behavior of input devices.
     21 
     22 Input device configuration files are typically not necessary for standard
     23 peripherals such as HID keyboards and mice since the default system behavior
     24 usually ensures that they will work out of the box.  On the other hand,
     25 built-in embedded devices, particularly touch screens, almost always
     26 require input device configuration files to specify their behavior.
     27 
     28 ## Rationale ##
     29 
     30 Android automatically detects and configures most input device capabilities
     31 based on the event types and properties that are reported by the associated
     32 Linux kernel input device driver.
     33 
     34 For example, if an input device supports the `EV_REL` event type and codes
     35 `REL_X` and `REL_Y` as well as the `EV_KEY` event type and `BTN_MOUSE`,
     36 then Android will classify the input device as a mouse.  The default behavior
     37 for a mouse is to present an on-screen cursor which tracks the mouse's movements
     38 and simulates touches when the mouse is clicked.  Although the mouse can
     39 be configured differently, the default behavior is usually sufficient for
     40 standard mouse peripherals.
     41 
     42 Certain classes of input devices are more ambiguous.  For example, multi-touch
     43 touch screens and touch pads both support the `EV_ABS` event type and codes
     44 `ABS_MT_POSITION_X` and `ABS_MT_POSITION_Y` at a minimum.  However, the intended
     45 uses of these devices are quite different and cannot always be determined
     46 automatically.  Also, additional information is required to make sense of the
     47 pressure and size information reported by touch devices.  Hence touch devices,
     48 especially built-in touch screens, usually need IDC files.
     49 
     50 ## Location ##
     51 
     52 Input device configuration files are located by USB vendor, product (and
     53 optionally version) id or by input device name.
     54 
     55 The following paths are consulted in order.
     56 
     57 *   `/system/usr/idc/Vendor_XXXX_Product_XXXX_Version_XXXX.idc`
     58 *   `/system/usr/idc/Vendor_XXXX_Product_XXXX.idc`
     59 *   `/system/usr/idc/DEVICE_NAME.idc`
     60 *   `/data/system/devices/idc/Vendor_XXXX_Product_XXXX_Version_XXXX.idc`
     61 *   `/data/system/devices/idc/Vendor_XXXX_Product_XXXX.idc`
     62 *   `/data/system/devices/idc/DEVICE_NAME.idc`
     63 
     64 When constructing a file path that contains the device name, all characters
     65 in the device name other than '0'-'9', 'a'-'z', 'A'-'Z', '-' or '\_' are replaced by '\_'.
     66 
     67 ## Syntax ##
     68 
     69 An input device configuration file is a plain text file consisting of property
     70 assignments and comments.
     71 
     72 ### Properties ###
     73 
     74 Property assignments each consist of a property name, an `=`, a property value,
     75 and a new line.  Like this:
     76 
     77     property = value
     78 
     79 Property names are non-empty literal text identifiers.  They must not contain
     80 whitespace.  Each components of the input system defines a set of properties
     81 that are used to configure its function.
     82 
     83 Property values are non-empty string literals, integers or floating point numbers.
     84 They must not contain whitespace or the reserved characters `\` or `"`.
     85 
     86 Property names and values are case-sensitive.
     87 
     88 ### Comments ###
     89 
     90 Comment lines begin with '#' and continue to the end of the line.  Like this:
     91 
     92     # A comment!
     93 
     94 Blank lines are ignored.
     95 
     96 ### Example ###
     97 
     98     # This is an example of an input device configuration file.
     99     # It might be used to describe the characteristics of a built-in touch screen.
    100 
    101     # This is an internal device, not an external peripheral attached to the USB
    102     # or Bluetooth bus.
    103     device.internal = 1
    104 
    105     # The device should behave as a touch screen, which uses the same orientation
    106     # as the built-in display.
    107     touch.deviceType = touchScreen
    108     touch.orientationAware = 1
    109 
    110     # Additional calibration properties...
    111     # etc...
    112 
    113 ## Common Properties ##
    114 
    115 The following properties are common to all input device classes.
    116 
    117 Refer to the documentation of each input device class for information about the
    118 special properties used by each class.
    119 
    120 #### `device.internal` ####
    121 
    122 *Definition:* `device.internal` = `0` | `1`
    123 
    124 Specifies whether the input device is an internal built-in component as opposed to an
    125 externally attached (most likely removable) peripheral.
    126 
    127 *   If the value is `0`, the device is external.
    128 
    129 *   If the value is `1`, the device is internal.
    130 
    131 *   If the value is not specified, the default value is `0` for all devices on the
    132     USB (BUS_USB) or Bluetooth (BUS_BLUETOOTH) bus, `1` otherwise.
    133 
    134 This property determines default policy decisions regarding wake events.
    135 
    136 Internal input devices generally do not wake the display from sleep unless explicitly
    137 configured to do so in the key layout file or in a hardcoded policy rule.  This
    138 distinction prevents key presses and touches from spuriously waking up your phone
    139 when it is in your pocket.  Usually there are only a small handful of wake keys defined.
    140 
    141 Conversely, external input devices usually wake the device more aggressively because
    142 they are assumed to be turned off or not plugged in during transport.  For example,
    143 pressing any key on an external keyboard is a good indicator that the user wants the
    144 device to wake up and respond.
    145 
    146 It is important to ensure that the value of the `device.internal` property is set
    147 correctly for all internal input devices.
    148 
    149 ## Validation ##
    150 
    151 Make sure to validate your input device configuration files using the
    152 [Validate Keymaps](/tech/input/validate-keymaps.html) tool.
    153