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 19Input device configuration files (`.idc` files) contain device-specific 20configuration properties that affect the behavior of input devices. 21 22Input device configuration files are typically not necessary for standard 23peripherals such as HID keyboards and mice since the default system behavior 24usually ensures that they will work out of the box. On the other hand, 25built-in embedded devices, particularly touch screens, almost always 26require input device configuration files to specify their behavior. 27 28## Rationale ## 29 30Android automatically detects and configures most input device capabilities 31based on the event types and properties that are reported by the associated 32Linux kernel input device driver. 33 34For 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`, 36then Android will classify the input device as a mouse. The default behavior 37for a mouse is to present an on-screen cursor which tracks the mouse's movements 38and simulates touches when the mouse is clicked. Although the mouse can 39be configured differently, the default behavior is usually sufficient for 40standard mouse peripherals. 41 42Certain classes of input devices are more ambiguous. For example, multi-touch 43touch 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 45uses of these devices are quite different and cannot always be determined 46automatically. Also, additional information is required to make sense of the 47pressure and size information reported by touch devices. Hence touch devices, 48especially built-in touch screens, usually need IDC files. 49 50## Location ## 51 52Input device configuration files are located by USB vendor, product (and 53optionally version) id or by input device name. 54 55The 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 64When constructing a file path that contains the device name, all characters 65in the device name other than '0'-'9', 'a'-'z', 'A'-'Z', '-' or '\_' are replaced by '\_'. 66 67## Syntax ## 68 69An input device configuration file is a plain text file consisting of property 70assignments and comments. 71 72### Properties ### 73 74Property assignments each consist of a property name, an `=`, a property value, 75and a new line. Like this: 76 77 property = value 78 79Property names are non-empty literal text identifiers. They must not contain 80whitespace. Each components of the input system defines a set of properties 81that are used to configure its function. 82 83Property values are non-empty string literals, integers or floating point numbers. 84They must not contain whitespace or the reserved characters `\` or `"`. 85 86Property names and values are case-sensitive. 87 88### Comments ### 89 90Comment lines begin with '#' and continue to the end of the line. Like this: 91 92 # A comment! 93 94Blank 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 115The following properties are common to all input device classes. 116 117Refer to the documentation of each input device class for information about the 118special properties used by each class. 119 120#### `device.internal` #### 121 122*Definition:* `device.internal` = `0` | `1` 123 124Specifies whether the input device is an internal built-in component as opposed to an 125externally 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 134This property determines default policy decisions regarding wake events. 135 136Internal input devices generally do not wake the display from sleep unless explicitly 137configured to do so in the key layout file or in a hardcoded policy rule. This 138distinction prevents key presses and touches from spuriously waking up your phone 139when it is in your pocket. Usually there are only a small handful of wake keys defined. 140 141Conversely, external input devices usually wake the device more aggressively because 142they are assumed to be turned off or not plugged in during transport. For example, 143pressing any key on an external keyboard is a good indicator that the user wants the 144device to wake up and respond. 145 146It is important to ensure that the value of the `device.internal` property is set 147correctly for all internal input devices. 148 149## Validation ## 150 151Make sure to validate your input device configuration files using the 152[Validate Keymaps](/tech/input/validate-keymaps.html) tool. 153