Add section on input devices. Change-Id: Ib9c4909881df505b11537c28bd08182933a5565a
diff --git a/scripts/build.py b/scripts/build.py index 8188f51..1325a38 100755 --- a/scripts/build.py +++ b/scripts/build.py
@@ -9,7 +9,7 @@ # call markdown as a subprocess, and capture the output def markdown(raw_file): - extensions = '-x tables' + ' ' + '-x "toc(title=In This Document)"' + extensions = '-x tables -x "toc(title=In This Document)" -x def_list' command = 'markdown' + ' ' + extensions + ' ' + raw_file p = subprocess.Popen(command, stdout = subprocess.PIPE, shell = True) return p.communicate()[0]
diff --git a/src/assets/main.css b/src/assets/main.css index 59f2dd1..18662a1 100644 --- a/src/assets/main.css +++ b/src/assets/main.css
@@ -241,6 +241,15 @@ padding: 1em; } +dt { + color: #1f2a33; + font-size: 110%; +} + +dd { + margin: 1em 1em 1em 1em; +} + /* TABLE OF CONTENTS */ .toc {
diff --git a/src/tech/index.md b/src/tech/index.md index f7aa958..5653bda 100644 --- a/src/tech/index.md +++ b/src/tech/index.md
@@ -52,3 +52,9 @@ core Android platform. [» Android Security Overview](/tech/security/index.html) + +## Input Technical Information ## +Android's input subsystem is responsible for supporting touch screens, +keyboard, joysticks, mice and other devices. + +[» Input Information](/tech/input/index.html)
diff --git a/src/tech/input/dumpsys.md b/src/tech/input/dumpsys.md new file mode 100644 index 0000000..883e8c4 --- /dev/null +++ b/src/tech/input/dumpsys.md
@@ -0,0 +1,347 @@ +<!-- + Copyright 2011 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. +--> + +# Dumpsys # + +The `dumpsys` tool runs on the device and dumps interesting information +about the status of system services. + +## Usage ## + +The input system is part of the window manager. To dump its state, +run the following command. + + $ adb shell su -- dumpsys window + + WINDOW MANAGER INPUT (dumpsys window input) + Event Hub State: + BuiltInKeyboardId: -1 + Devices: + ... + +The set of information that is reported varies depending on the version of Android. + +### Event Hub State ### + +The `EventHub` component is responsible for communicating with the kernel device +drivers and identifying device capabilities. Accordingly, its state shows +information about how devices are configured. + + Event Hub State: + BuiltInKeyboardId: -1 + Devices: + 3: tuna-gpio-keypad + Classes: 0x00000001 + Path: /dev/input/event2 + Location: + UniqueId: + Identifier: bus=0x0000, vendor=0x0000, product=0x0000, version=0x0000 + KeyLayoutFile: /system/usr/keylayout/tuna-gpio-keypad.kl + KeyCharacterMapFile: /system/usr/keychars/tuna-gpio-keypad.kcm + ConfigurationFile: + 5: Tuna Headset Jack + Classes: 0x00000080 + Path: /dev/input/event5 + Location: ALSA + UniqueId: + Identifier: bus=0x0000, vendor=0x0000, product=0x0000, version=0x0000 + KeyLayoutFile: + KeyCharacterMapFile: + ConfigurationFile: + 6: Melfas MMSxxx Touchscreen + Classes: 0x00000014 + Path: /dev/input/event1 + Location: 3-0048/input0 + UniqueId: + Identifier: bus=0x0018, vendor=0x0000, product=0x0000, version=0x0000 + KeyLayoutFile: + KeyCharacterMapFile: + ConfigurationFile: /system/usr/idc/Melfas_MMSxxx_Touchscreen.idc + 7: Motorola Bluetooth Wireless Keyboard + Classes: 0x8000000b + Path: /dev/input/event6 + Location: 0C:DF:A4:B3:2D:BA + UniqueId: 00:0F:F6:80:02:CD + Identifier: bus=0x0005, vendor=0x22b8, product=0x093d, version=0x0288 + KeyLayoutFile: /system/usr/keylayout/Vendor_22b8_Product_093d.kl + KeyCharacterMapFile: /system/usr/keychars/Generic.kcm + ConfigurationFile: + +#### Things To Look For #### + +1. All of the expected input devices are present. + +2. Each input device has an appropriate key layout file, key character map file + and input device configuration file. If the files are missing or contain + syntax errors, then they will not be loaded. + +3. Each input device is being classified correctly. The bits in the `Classes` + field correspond to flags in `EventHub.h` such as `INPUT_DEVICE_CLASS_TOUCH_MT`. + +4. The `BuiltInKeyboardId` is correct. If the device does not have a built-in keyboard, + then the id must be `-1`, otherwise it should be the id of the built-in keyboard. + + If you observe that the `BuiltInKeyboardId` is not `-1` but it should be, then + you are missing a key character map file for a special function keypad somewhere. + Special function keypad devices should have key character map files that contain + just the line `type SPECIAL_FUNCTION` (that's what in the `tuna-gpio-keykad.kcm` + file we see mentioned above). + +### Input Reader State ### + +The `InputReader` is responsible for decoding input events from the kernel. +Its state dump shows information about how each input device is configured +and recent state changes that occurred, such as key presses or touches on +the touch screen. + +This is what a special function keypad looks like: + + Input Reader State: + Device 3: tuna-gpio-keypad + IsExternal: false + Sources: 0x00000101 + KeyboardType: 1 + Keyboard Input Mapper: + Parameters: + AssociatedDisplayId: -1 + OrientationAware: false + KeyboardType: 1 + Orientation: 0 + KeyDowns: 0 keys currently down + MetaState: 0x0 + DownTime: 75816923828000 + +Here is a touch screen. Notice all of the information about the resolution of +the device and the calibration parameters that were used. + + Device 6: Melfas MMSxxx Touchscreen + IsExternal: false + Sources: 0x00001002 + KeyboardType: 0 + Motion Ranges: + X: source=0x00001002, min=0.000, max=719.001, flat=0.000, fuzz=0.999 + Y: source=0x00001002, min=0.000, max=1279.001, flat=0.000, fuzz=0.999 + PRESSURE: source=0x00001002, min=0.000, max=1.000, flat=0.000, fuzz=0.000 + SIZE: source=0x00001002, min=0.000, max=1.000, flat=0.000, fuzz=0.000 + TOUCH_MAJOR: source=0x00001002, min=0.000, max=1468.605, flat=0.000, fuzz=0.000 + TOUCH_MINOR: source=0x00001002, min=0.000, max=1468.605, flat=0.000, fuzz=0.000 + TOOL_MAJOR: source=0x00001002, min=0.000, max=1468.605, flat=0.000, fuzz=0.000 + TOOL_MINOR: source=0x00001002, min=0.000, max=1468.605, flat=0.000, fuzz=0.000 + Touch Input Mapper: + Parameters: + GestureMode: spots + DeviceType: touchScreen + AssociatedDisplay: id=0, isExternal=false + OrientationAware: true + Raw Touch Axes: + X: min=0, max=720, flat=0, fuzz=0, resolution=0 + Y: min=0, max=1280, flat=0, fuzz=0, resolution=0 + Pressure: min=0, max=255, flat=0, fuzz=0, resolution=0 + TouchMajor: min=0, max=30, flat=0, fuzz=0, resolution=0 + TouchMinor: unknown range + ToolMajor: unknown range + ToolMinor: unknown range + Orientation: unknown range + Distance: unknown range + TiltX: unknown range + TiltY: unknown range + TrackingId: min=0, max=65535, flat=0, fuzz=0, resolution=0 + Slot: min=0, max=9, flat=0, fuzz=0, resolution=0 + Calibration: + touch.size.calibration: diameter + touch.size.scale: 10.000 + touch.size.bias: 0.000 + touch.size.isSummed: false + touch.pressure.calibration: amplitude + touch.pressure.scale: 0.005 + touch.orientation.calibration: none + touch.distance.calibration: none + SurfaceWidth: 720px + SurfaceHeight: 1280px + SurfaceOrientation: 0 + Translation and Scaling Factors: + XScale: 0.999 + YScale: 0.999 + XPrecision: 1.001 + YPrecision: 1.001 + GeometricScale: 0.999 + PressureScale: 0.005 + SizeScale: 0.033 + OrientationCenter: 0.000 + OrientationScale: 0.000 + DistanceScale: 0.000 + HaveTilt: false + TiltXCenter: 0.000 + TiltXScale: 0.000 + TiltYCenter: 0.000 + TiltYScale: 0.000 + Last Button State: 0x00000000 + Last Raw Touch: pointerCount=0 + Last Cooked Touch: pointerCount=0 + +Here is an external keyboard / mouse combo HID device. (This device doesn't actually +have a mouse but its HID descriptor says it does.) + + Device 7: Motorola Bluetooth Wireless Keyboard + IsExternal: true + Sources: 0x00002103 + KeyboardType: 2 + Motion Ranges: + X: source=0x00002002, min=0.000, max=719.000, flat=0.000, fuzz=0.000 + Y: source=0x00002002, min=0.000, max=1279.000, flat=0.000, fuzz=0.000 + PRESSURE: source=0x00002002, min=0.000, max=1.000, flat=0.000, fuzz=0.000 + VSCROLL: source=0x00002002, min=-1.000, max=1.000, flat=0.000, fuzz=0.000 + Keyboard Input Mapper: + Parameters: + AssociatedDisplayId: -1 + OrientationAware: false + KeyboardType: 2 + Orientation: 0 + KeyDowns: 0 keys currently down + MetaState: 0x0 + DownTime: 75868832946000 + Cursor Input Mapper: + Parameters: + AssociatedDisplayId: 0 + Mode: pointer + OrientationAware: false + XScale: 1.000 + YScale: 1.000 + XPrecision: 1.000 + YPrecision: 1.000 + HaveVWheel: true + HaveHWheel: false + VWheelScale: 1.000 + HWheelScale: 1.000 + Orientation: 0 + ButtonState: 0x00000000 + Down: false + DownTime: 0 + +Here is a joystick. Notice how all of the axes have been scaled to a normalized +range. The axis mapping can be configured using key layout files. + + Device 18: Logitech Logitech Cordless RumblePad 2 + IsExternal: true + Sources: 0x01000511 + KeyboardType: 1 + Motion Ranges: + X: source=0x01000010, min=-1.000, max=1.000, flat=0.118, fuzz=0.000 + Y: source=0x01000010, min=-1.000, max=1.000, flat=0.118, fuzz=0.000 + Z: source=0x01000010, min=-1.000, max=1.000, flat=0.118, fuzz=0.000 + RZ: source=0x01000010, min=-1.000, max=1.000, flat=0.118, fuzz=0.000 + HAT_X: source=0x01000010, min=-1.000, max=1.000, flat=0.000, fuzz=0.000 + HAT_Y: source=0x01000010, min=-1.000, max=1.000, flat=0.000, fuzz=0.000 + Keyboard Input Mapper: + Parameters: + AssociatedDisplayId: -1 + OrientationAware: false + KeyboardType: 1 + Orientation: 0 + KeyDowns: 0 keys currently down + MetaState: 0x0 + DownTime: 675270841000 + Joystick Input Mapper: + Axes: + X: min=-1.00000, max=1.00000, flat=0.11765, fuzz=0.00000 + scale=0.00784, offset=-1.00000, highScale=0.00784, highOffset=-1.00000 + rawAxis=0, rawMin=0, rawMax=255, rawFlat=15, rawFuzz=0, rawResolution=0 + Y: min=-1.00000, max=1.00000, flat=0.11765, fuzz=0.00000 + scale=0.00784, offset=-1.00000, highScale=0.00784, highOffset=-1.00000 + rawAxis=1, rawMin=0, rawMax=255, rawFlat=15, rawFuzz=0, rawResolution=0 + Z: min=-1.00000, max=1.00000, flat=0.11765, fuzz=0.00000 + scale=0.00784, offset=-1.00000, highScale=0.00784, highOffset=-1.00000 + rawAxis=2, rawMin=0, rawMax=255, rawFlat=15, rawFuzz=0, rawResolution=0 + RZ: min=-1.00000, max=1.00000, flat=0.11765, fuzz=0.00000 + scale=0.00784, offset=-1.00000, highScale=0.00784, highOffset=-1.00000 + rawAxis=5, rawMin=0, rawMax=255, rawFlat=15, rawFuzz=0, rawResolution=0 + HAT_X: min=-1.00000, max=1.00000, flat=0.00000, fuzz=0.00000 + scale=1.00000, offset=0.00000, highScale=1.00000, highOffset=0.00000 + rawAxis=16, rawMin=-1, rawMax=1, rawFlat=0, rawFuzz=0, rawResolution=0 + HAT_Y: min=-1.00000, max=1.00000, flat=0.00000, fuzz=0.00000 + scale=1.00000, offset=0.00000, highScale=1.00000, highOffset=0.00000 + rawAxis=17, rawMin=-1, rawMax=1, rawFlat=0, rawFuzz=0, rawResolution=0 + +At the end of the input reader dump there is some information about global configuration +parameters such as the mouse pointer speed. + + Configuration: + ExcludedDeviceNames: [] + VirtualKeyQuietTime: 0.0ms + PointerVelocityControlParameters: scale=1.000, lowThreshold=500.000, highThreshold=3000.000, acceleration=3.000 + WheelVelocityControlParameters: scale=1.000, lowThreshold=15.000, highThreshold=50.000, acceleration=4.000 + PointerGesture: + Enabled: true + QuietInterval: 100.0ms + DragMinSwitchSpeed: 50.0px/s + TapInterval: 150.0ms + TapDragInterval: 300.0ms + TapSlop: 20.0px + MultitouchSettleInterval: 100.0ms + MultitouchMinDistance: 15.0px + SwipeTransitionAngleCosine: 0.3 + SwipeMaxWidthRatio: 0.2 + MovementSpeedRatio: 0.8 + ZoomSpeedRatio: 0.3 + +#### Things To Look For #### + +1. All of the expected input devices are present. + +2. Each input device has been configured appropriately. Especially check the + touch screen and joystick axes. + +### Input Dispatcher State ### + +The `InputDispatcher` is responsible for sending input events to applications. +Its state dump shows information about which window is being touched, the +state of the input queue, whether an ANR is in progress, and so on. + + Input Dispatcher State: + DispatchEnabled: 1 + DispatchFrozen: 0 + FocusedApplication: name='AppWindowToken{41b03a10 token=Token{41bdcf78 ActivityRecord{418ab728 com.android.settings/.Settings}}}', dispatchingTimeout=5000.000ms + FocusedWindow: name='Window{41908458 Keyguard paused=false}' + TouchDown: false + TouchSplit: false + TouchDeviceId: -1 + TouchSource: 0x00000000 + TouchedWindows: <none> + Windows: + 0: name='Window{41bd5b18 NavigationBar paused=false}', paused=false, hasFocus=false, hasWallpaper=false, visible=true, canReceiveKeys=false, flags=0x05800068, type=0x000007e3, layer=181000, frame=[0,1184][720,1280], scale=1.000000, touchableRegion=[0,1184][720,1280], inputFeatures=0x00000000, ownerPid=306, ownerUid=1000, dispatchingTimeout=5000.000ms + 1: name='Window{41a19770 RecentsPanel paused=false}', paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01820100, type=0x000007de, layer=151000, frame=[0,0][720,1184], scale=1.000000, touchableRegion=[0,0][720,1184], inputFeatures=0x00000000, ownerPid=306, ownerUid=1000, dispatchingTimeout=5000.000ms + 2: name='Window{41a78768 StatusBar paused=false}', paused=false, hasFocus=false, hasWallpaper=false, visible=true, canReceiveKeys=false, flags=0x00800048, type=0x000007d0, layer=141000, frame=[0,0][720,50], scale=1.000000, touchableRegion=[0,0][720,50], inputFeatures=0x00000000, ownerPid=306, ownerUid=1000, dispatchingTimeout=5000.000ms + 3: name='Window{41877570 StatusBarExpanded paused=false}', paused=false, hasFocus=false, hasWallpaper=false, visible=true, canReceiveKeys=false, flags=0x01811328, type=0x000007e1, layer=131005, frame=[0,-1184][720,-114], scale=1.000000, touchableRegion=[0,-1184][720,-114], inputFeatures=0x00000000, ownerPid=306, ownerUid=1000, dispatchingTimeout=5000.000ms + 4: name='Window{41bedf20 TrackingView paused=false}', paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01020300, type=0x000007e1, layer=131000, frame=[0,-1032][720,102], scale=1.000000, touchableRegion=[0,-1032][720,102], inputFeatures=0x00000000, ownerPid=306, ownerUid=1000, dispatchingTimeout=5000.000ms + 5: name='Window{41908458 Keyguard paused=false}', paused=false, hasFocus=true, hasWallpaper=false, visible=true, canReceiveKeys=true, flags=0x15120800, type=0x000007d4, layer=111000, frame=[0,50][720,1184], scale=1.000000, touchableRegion=[0,50][720,1184], inputFeatures=0x00000000, ownerPid=205, ownerUid=1000, dispatchingTimeout=5000.000ms + 6: name='Window{4192cc30 com.android.phasebeam.PhaseBeamWallpaper paused=false}', paused=false, hasFocus=false, hasWallpaper=false, visible=true, canReceiveKeys=false, flags=0x00000308, type=0x000007dd, layer=21010, frame=[0,0][720,1184], scale=1.000000, touchableRegion=[0,0][720,1184], inputFeatures=0x00000000, ownerPid=429, ownerUid=10046, dispatchingTimeout=5000.000ms + 7: name='Window{41866c00 com.android.settings/com.android.settings.Settings paused=false}', paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01810100, type=0x00000001, layer=21005, frame=[0,0][720,1184], scale=1.000000, touchableRegion=[0,0][720,1184], inputFeatures=0x00000000, ownerPid=19000, ownerUid=1000, dispatchingTimeout=5000.000ms + 8: name='Window{4197c858 com.android.launcher/com.android.launcher2.Launcher paused=false}', paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01910100, type=0x00000001, layer=21000, frame=[0,0][720,1184], scale=1.000000, touchableRegion=[0,0][720,1184], inputFeatures=0x00000000, ownerPid=515, ownerUid=10032, dispatchingTimeout=5000.000ms + MonitoringChannels: <none> + InboundQueue: length=0 + ActiveConnections: <none> + AppSwitch: not pending + Configuration: + MaxEventsPerSecond: 90 + KeyRepeatDelay: 50.0ms + KeyRepeatTimeout: 500.0ms + +#### Things To Look For #### + +1. In general, all input events are being processed as expected. + +2. If you touch the touch screen and run dumpsys at the same time, then the `TouchedWindows` + line should show the window that you are touching.
diff --git a/src/tech/input/getevent.md b/src/tech/input/getevent.md new file mode 100644 index 0000000..5807753 --- /dev/null +++ b/src/tech/input/getevent.md
@@ -0,0 +1,112 @@ +<!-- + Copyright 2011 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. +--> + +# Getevent # + +The `getevent` tool runs on the device and provides information about input +devices and a live dump of kernel input events. + +It is very useful tool for ensuring that device drivers are reporing the +expected set of capabilities for each input device and are generating the +desired stream of input events. + +## Usage ## + +### Showing Device Capabilities ### + +It is often quite useful to see all of the keys and axes that a device reports. +Use the `-p` option to do that. + +Here is a list of all of the Linux key codes and other events that a +particular keyboard says it supports. + + $ adb shell su -- getevent -p + + name: "Motorola Bluetooth Wireless Keyboard" + events: + KEY (0001): 0001 0002 0003 0004 0005 0006 0007 0008 + 0009 000a 000b 000c 000d 000e 000f 0010 + 0011 0012 0013 0014 0015 0016 0017 0018 + 0019 001a 001b 001c 001d 001e 001f 0020 + 0021 0022 0023 0024 0025 0026 0027 0028 + 0029 002a 002b 002c 002d 002e 002f 0030 + 0031 0032 0033 0034 0035 0036 0037 0038 + 0039 003a 003b 003c 003d 003e 003f 0040 + 0041 0042 0043 0044 0045 0046 0047 0048 + 0049 004a 004b 004c 004d 004e 004f 0050 + 0051 0052 0053 0055 0056 0057 0058 0059 + 005a 005b 005c 005d 005e 005f 0060 0061 + 0062 0063 0064 0066 0067 0068 0069 006a + 006b 006c 006d 006e 006f 0071 0072 0073 + 0074 0075 0077 0079 007a 007b 007c 007d + 007e 007f 0080 0081 0082 0083 0084 0085 + 0086 0087 0088 0089 008a 008c 008e 0090 + 0096 0098 009b 009c 009e 009f 00a1 00a3 + 00a4 00a5 00a6 00ab 00ac 00ad 00b0 00b1 + 00b2 00b3 00b4 00b7 00b8 00b9 00ba 00bb + 00bc 00bd 00be 00bf 00c0 00c1 00c2 00d9 + 00f0 0110 0111 0112 01ba + REL (0002): 0000 0001 0008 + ABS (0003): 0028 : value 223, min 0, max 255, fuzz 0, flat 0, resolution 0 + 0029 : value 0, min 0, max 255, fuzz 0, flat 0, resolution 0 + 002a : value 0, min 0, max 255, fuzz 0, flat 0, resolution 0 + 002b : value 0, min 0, max 255, fuzz 0, flat 0, resolution 0 + MSC (0004): 0004 + LED (0011): 0000 0001 0002 0003 0004 + input props: + <none> + +The `-i` option shows even more information than `-p`, including HID mapping tables +and debugging information. + +The `-l` option uses textual labels for all event codes, which is handy. + + $ adb shell su -- getevent -lp /dev/input/event1 + + name: "Melfas MMSxxx Touchscreen" + events: + ABS (0003): ABS_MT_SLOT : value 0, min 0, max 9, fuzz 0, flat 0, resolution 0 + ABS_MT_TOUCH_MAJOR : value 0, min 0, max 30, fuzz 0, flat 0, resolution 0 + ABS_MT_POSITION_X : value 0, min 0, max 720, fuzz 0, flat 0, resolution 0 + ABS_MT_POSITION_Y : value 0, min 0, max 1280, fuzz 0, flat 0, resolution 0 + ABS_MT_TRACKING_ID : value 0, min 0, max 65535, fuzz 0, flat 0, resolution 0 + ABS_MT_PRESSURE : value 0, min 0, max 255, fuzz 0, flat 0, resolution 0 + input props: + INPUT_PROP_DIRECT + +### Showing Live Events ### + +This is what a two finger multitouch gesture looks like for a touch screen +that is using the Linux multitouch input protocol "B". We use the `-l` option +to show textual labels and `-t` to show timestamps. + + $ adb shell su -- getevent -lt /dev/input/event1 + + [ 78826.389007] EV_ABS ABS_MT_TRACKING_ID 0000001f + [ 78826.389038] EV_ABS ABS_MT_PRESSURE 000000ab + [ 78826.389038] EV_ABS ABS_MT_POSITION_X 000000ab + [ 78826.389068] EV_ABS ABS_MT_POSITION_Y 0000025b + [ 78826.389068] EV_ABS ABS_MT_SLOT 00000001 + [ 78826.389068] EV_ABS ABS_MT_TRACKING_ID 00000020 + [ 78826.389068] EV_ABS ABS_MT_PRESSURE 000000b9 + [ 78826.389099] EV_ABS ABS_MT_POSITION_X 0000019e + [ 78826.389099] EV_ABS ABS_MT_POSITION_Y 00000361 + [ 78826.389099] EV_SYN SYN_REPORT 00000000 + [ 78826.468688] EV_ABS ABS_MT_SLOT 00000000 + [ 78826.468688] EV_ABS ABS_MT_TRACKING_ID ffffffff + [ 78826.468719] EV_ABS ABS_MT_SLOT 00000001 + [ 78826.468719] EV_ABS ABS_MT_TRACKING_ID ffffffff + [ 78826.468719] EV_SYN SYN_REPORT 00000000
diff --git a/src/tech/input/index.md b/src/tech/input/index.md new file mode 100644 index 0000000..e01f200 --- /dev/null +++ b/src/tech/input/index.md
@@ -0,0 +1,24 @@ +<!-- + Copyright 2011 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. +--> + +# Input Technical Information # + +The Android input subsystem supports many different device classes, +including keyboard, joystick, trackball, mouse and touch screen. + +The documentation in this section describes how to configure, +calibrate, test, and write drivers for input devices. +
diff --git a/src/tech/input/input-device-configuration-files.md b/src/tech/input/input-device-configuration-files.md new file mode 100644 index 0000000..0a477d0 --- /dev/null +++ b/src/tech/input/input-device-configuration-files.md
@@ -0,0 +1,152 @@ +<!-- + Copyright 2011 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. +--> + +# Input Device Configuration Files # + +Input device configuration files (`.idc` files) contain device-specific +configuration properties that affect the behavior of input devices. + +Input device configuration files are typically not necessary for standard +peripherals such as HID keyboards and mice since the default system behavior +usually ensures that they will work out of the box. On the other hand, +built-in embedded devices, particularly touch screens, almost always +require input device configuration files to specify their behavior. + +## Rationale ## + +Android automatically detects and configures most input device capabilities +based on the event types and properties that are reported by the associated +Linux kernel input device driver. + +For example, if an input device supports the `EV_REL` event type and codes +`REL_X` and `REL_Y` as well as the `EV_KEY` event type and `BTN_MOUSE`, +then Android will classify the input device as a mouse. The default behavior +for a mouse is to present an on-screen cursor which tracks the mouse's movements +and simulates touches when the mouse is clicked. Although the mouse can +be configured differently, the default behavior is usually sufficient for +standard mouse peripherals. + +Certain classes of input devices are more ambiguous. For example, multi-touch +touch screens and touch pads both support the `EV_ABS` event type and codes +`ABS_MT_POSITION_X` and `ABS_MT_POSITION_Y` at a minimum. However, the intended +uses of these devices are quite different and cannot always be determined +automatically. Also, additional information is required to make sense of the +pressure and size information reported by touch devices. Hence touch devices, +especially built-in touch screens, usually need IDC files. + +## Location ## + +Input device configuration files are located by USB vendor, product (and +optionally version) id or by input device name. + +The following paths are consulted in order. + +* `/system/usr/idc/Vendor_XXXX_Product_XXXX_Version_XXXX.idc` +* `/system/usr/idc/Vendor_XXXX_Product_XXXX.idc` +* `/system/usr/idc/DEVICE_NAME.idc` +* `/data/system/devices/idc/Vendor_XXXX_Product_XXXX_Version_XXXX.idc` +* `/data/system/devices/idc/Vendor_XXXX_Product_XXXX.idc` +* `/data/system/devices/idc/DEVICE_NAME.idc` + +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 '_'. + +## Syntax ## + +An input device configuration file is a plain text file consisting of property +assignments and comments. + +### Properties ### + +Property assignments each consist of a property name, an `=`, a property value, +and a new line. Like this: + + property = value + +Property names are non-empty literal text identifiers. They must not contain +whitespace. Each components of the input system defines a set of properties +that are used to configure its function. + +Property values are non-empty string literals, integers or floating point numbers. +They must not contain whitespace or the reserved characters `\` or `"`. + +Property names and values are case-sensitive. + +### Comments ### + +Comment lines begin with '#' and continue to the end of the line. Like this: + + # A comment! + +Blank lines are ignored. + +### Example ### + + # This is an example of an input device configuration file. + # It might be used to describe the characteristics of a built-in touch screen. + + # This is an internal device, not an external peripheral attached to the USB + # or Bluetooth bus. + device.internal = 1 + + # The device should behave as a touch screen, which uses the same orientation + # as the built-in display. + touch.deviceType = touchScreen + touch.orientationAware = 1 + + # Additional calibration properties... + # etc... + +## Common Properties ## + +The following properties are common to all input device classes. + +Refer to the documentation of each input device class for information about the +special properties used by each class. + +#### `device.internal` #### + +*Definition:* `device.internal` = `0` | `1` + +Specifies whether the input device is an internal built-in component as opposed to an +externally attached (most likely removable) peripheral. + +* If the value is `0`, the device is external. + +* If the value is `1`, the device is internal. + +* If the value is not specified, the default value is `0` for all devices on the + USB (BUS_USB) or Bluetooth (BUS_BLUETOOTH) bus, `1` otherwise. + +This property determines default policy decisions regarding wake events. + +Internal input devices generally do not wake the display from sleep unless explicitly +configured to do so in the key layout file or in a hardcoded policy rule. This +distinction prevents key presses and touches from spuriously waking up your phone +when it is in your pocket. Usually there are only a small handful of wake keys defined. + +Conversely, external input devices usually wake the device more aggressively because +they are assumed to be turned off or not plugged in during transport. For example, +pressing any key on an external keyboard is a good indicator that the user wants the +device to wake up and respond. + +It is important to ensure that the value of the `device.internal` property is set +correctly for all internal input devices. + +## Validation ## + +Make sure to validate your input device configuration files using the +[Validate Keymaps](/tech/input/validate-keymaps.html) tool.
diff --git a/src/tech/input/key-character-map-files.md b/src/tech/input/key-character-map-files.md new file mode 100644 index 0000000..4a9ec34 --- /dev/null +++ b/src/tech/input/key-character-map-files.md
@@ -0,0 +1,493 @@ +<!-- + Copyright 2011 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. +--> + +# Key Character Map Files # + +Key character map files (`.kcm` files) are responsible for mapping combinations +of Android key codes with modifiers to Unicode characters. + +Device-specific key layout files are *required* for all internal (built-in) +input devices that have keys, if only to tell the system that the device +is special purpose only (not a full keyboard). + +Device-specific key layout files are *optional* for external keyboards, and +often aren't needed at all. The system provides a generic key character map +that is suitable for many external keyboards. + +If no device-specific key layout file is available, then the system will +choose a default instead. + +## Location ## + +Key character map files are located by USB vendor, product (and optionally version) +id or by input device name. + +The following paths are consulted in order. + +* `/system/usr/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm` +* `/system/usr/keychars/Vendor_XXXX_Product_XXXX.kcm` +* `/system/usr/keychars/DEVICE_NAME.kcm` +* `/data/system/devices/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm` +* `/data/system/devices/keychars/Vendor_XXXX_Product_XXXX.kcm` +* `/data/system/devices/keychars/DEVICE_NAME.kcm` +* `/system/usr/keychars/Generic.kcm` +* `/data/system/devices/keychars/Generic.kcm` +* `/system/usr/keychars/Virtual.kcm` +* `/data/system/devices/keychars/Virtual.kcm` + +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 '_'. + +## Generic Key Character Map File ## + +The system provides a special built-in key character map file called `Generic.kcm`. +This key character map is intended to support a variety of standard external +keyboards. + +*Do not modify the generic key character map!* + +## Virtual Key Character Map File ## + +The system provides a special built-in key character map file called `Virtual.kcm` +that is used by the virtual keyboard devices. + +The virtual keyboard device is a synthetic input device whose id is -1 +(see `KeyCharacterMap.VIRTUAL_KEYBOARD`). It is present on all Android devices +beginning with Android Honeycomb 3.0. The purpose of the virtual keyboard device +is to provide a known built-in input device that can be used for injecting +keystokes into applications by the IME or by test instrumentation, even +for devices that do not have built-in keyboards. + +The virtual keyboard is assumed to have a full QWERTY layout that is the +same on all devices. This makes it possible for applications to inject +keystrokes using the virtual keyboard device and always get the same results. + +*Do not modify the virtual key character map!* + +## Syntax ## + +A key character map file is a plain text file consisting of a keyboard type +declaration and a set of key declarations. + +### Keyboard Type Declaration ### + +A keyboard type declaration describes the overall behavior of the keyboard. +A character map file must contain a keyboard type declaration. For clarity, +it is often placed at the top of the file. + + type FULL + +The following keyboard types are recognized: + +* `NUMERIC`: A numeric (12-key) keyboard. + + A numeric keyboard supports text entry using a multi-tap approach. + It may be necessary to tap a key multiple times to generate the desired letter or symbol. + + This type of keyboard is generally designed for thumb typing. + + Corresponds to `KeyCharacterMap.NUMERIC`. + +* `PREDICTIVE`: A keyboard with all the letters, but with more than one letter per key. + + This type of keyboard is generally designed for thumb typing. + + Corresponds to `KeyCharacterMap.PREDICTIVE`. + +* `ALPHA`: A keyboard with all the letters, and maybe some numbers. + + An alphabetic keyboard supports text entry directly but may have a condensed + layout with a small form factor. In contrast to a `FULL` keyboard, some + symbols may only be accessible using special on-screen character pickers. + In addition, to improve typing speed and accuracy, the framework provides + special affordances for alphabetic keyboards such as auto-capitalization + and toggled / locked SHIFT and ALT keys. + + This type of keyboard is generally designed for thumb typing. + +* `FULL`: A full PC-style keyboard. + + A full keyboard behaves like a PC keyboard. All symbols are accessed directly + by pressing keys on the keyboard without on-screen support or affordances such + as auto-capitalization. + + This type of keyboard is generally designed for full two hand typing. + +* `SPECIAL_FUNCTION`: A keyboard that is only used to perform system control functions + rather than for typing. + + A special function keyboard consists only of non-printing keys such as + HOME and POWER that are not actually used for typing. + +The `Generic.kcm` and `Virtual.kcm` key character maps are both `FULL` keyboards. + +### Key Declarations ### + +Key declarations each consist of the keyword `key` followed by an Android key code +name, an open curly brace, a set of properties and behaviors and a close curly brace. + + key A { + label: 'A' + base: 'a' + shift, capslock: 'A' + ctrl, alt, meta: none + } + +#### Properties #### + +Each key property establishes a mapping from a key to a behavior. To make the +key character map files more compact, several properties can be mapped to the +same behavior by separating them with a comma. + +In the above example, the `label` property is assigned the `'A'` behavior. +Likewise, the `ctrl`, `alt` and `meta` properties are all simultaneously assigned +the `none` behavior. + +The following properties are recognized: + +* `label`: Specifies the label that is physically printed on the key, when it + consists of a single character. This is the value that is returned by + the `KeyCharacterMap.getDisplayLabel` method. + +* `number`: Specifies the behavior (character that should be typed) when a numeric + text view has focus, such as when the user is typing a phone number. + + Compact keyboards often combine multiple symbols into a single key, such that + the same key might be used to type `'1'` and `'a'` or `'#'` and `'q'`, perhaps. + For these keys, the `number` property should be set to indicate which symbol + should be typed in a numeric context, if any. + + Some typical "numeric" symbols are digits `'0'` through `'9'`, `'#'`, `'+'`, + `'('`, `')'`, `','`, and `'.'`. + +* `base`: Specifies the behavior (character that should be typed) when no modifiers + are pressed. + +* <modifier> or <modifier1>`+`<modifier2>`+`...: Specifies the + behavior (character that should be typed) when the key is pressed and all of the + specified modifiers are active. + + For example, the modifier property `shift` specifies a behavior that applies when + the either the LEFT SHIFT or RIGHT SHIFT modifier is pressed. + + Similarly, the modifier property `rshift+ralt` specifies a behavior that applies + when the both RIGHT SHIFT and RIGHT ALT modifiers are pressed together. + +The following modifiers are recognized in modifier properties: + +* `shift`: Applies when either the LEFT SHIFT or RIGHT SHIFT modifier is pressed. +* `lshift`: Applies when the LEFT SHIFT modifier is pressed. +* `rshift`: Applies when the RIGHT SHIFT modifier is pressed. +* `alt`: Applies when either the LEFT ALT or RIGHT ALT modifier is pressed. +* `lalt`: Applies when the LEFT ALT modifier is pressed. +* `ralt`: Applies when the RIGHT ALT modifier is pressed. +* `ctrl`: Applies when either the LEFT CONTROL or RIGHT CONTROL modifier is pressed. +* `lctrl`: Applies when the LEFT CONTROL modifier is pressed. +* `rctrl`: Applies when the RIGHT CONTROL modifier is pressed. +* `meta`: Applies when either the LEFT META or RIGHT META modifier is pressed. +* `lmeta`: Applies when the LEFT META modifier is pressed. +* `rmeta`: Applies when the RIGHT META modifier is pressed. +* `sym`: Applies when the SYMBOL modifier is pressed. +* `fn`: Applies when the FUNCTION modifier is pressed. +* `capslock`: Applies when the CAPS LOCK modifier is locked. +* `numlock`: Applies when the NUM LOCK modifier is locked. +* `scrolllock`: Applies when the SCROLL LOCK modifier is locked. + +The order in which the properties are listed is significant. When mapping a key to +a behavior, the system scans all relevant properties in order and returns the last +applicable behavior that it found. + +Consequently, properties that are specified later override properties that are +specified earlier for a given key. + +#### Behaviors #### + +Each property maps to a behavior. The most common behavior is typing a character +but there are others. + +The following behaviors are recognized: + +* `none`: Don't type a character. + + This behavior is the default when no character is specified. Specifying `none` + is optional but it improves clarity. + +* `'X'`: Type the specified character literal. + + This behavior causes the specified character to be entered into the focused + text view. The character literal may be any ASCII character, or one of the + following escape sequences: + + * `'\\'`: Type a backslash character. + * `'\n'`: Type a new line character (use this for ENTER / RETURN). + * `'\t'`: Type a TAB character. + * `'\''`: Type an apostrophe character. + * `'\"'`: Type a quote character. + * `'\uXXXX'`: Type the Unicode character whose code point is given in hex by XXXX. + +* `fallback` <Android key code name>: Perform a default action if the key is not + handled by the application. + + This behavior causes the system to simulate a different key press when an application + does not handle the specified key natively. It is used to support default behavior + for new keys that not all applications know how to handle, such as ESCAPE or + numeric keypad keys (when numlock is not pressed). + + When a fallback behavior is performed, the application will receive two key presses: + one for the original key and another for the fallback key that was selected. + If the application handles the original key during key up, then the fallback key + event will be canceled (`KeyEvent.isCanceled` will return `true`). + +The system reserves two Unicode characters to perform special functions: + +* `'\uef00'`: When this behavior is performed, the text view consumes and removes the + four characters preceding the cursor, interprets them as hex digits, and inserts the + corresponding Unicode code point. + +* `'\uef01'`: When this behavior is performed, the text view displays a + character picker dialog that contains miscellaneous symbols. + +The system recognizes the following Unicode characters as combining diacritical dead +key characters: + +* `'\u0300'`: Grave accent. +* `'\u0301'`: Acute accent. +* `'\u0302'`: Circumflex accent. +* `'\u0303'`: Tilde accent. +* `'\u0308'`: Umlaut accent. + +When a dead key is typed followed by another character, the dead key and the following +characters are composed. For example, when the user types a grave accent dead +key followed by the letter 'a', the result is 'à'. + +Refer to `KeyCharacterMap.getDeadChar` for more information about dead key handling. + +### Comments ### + +Comment lines begin with '#' and continue to the end of the line. Like this: + + # A comment! + +Blank lines are ignored. + +### How Key Combinations are Mapped to Behaviors ### + +When the user presses a key, the system looks up the behavior associated with +the combination of that key press and the currently pressed modifiers. + +#### SHIFT + A #### + +Suppose the user pressed A and SHIFT together. The system first locates +the set of properties and behaviors associated with `KEYCODE_A`. + + key A { + label: 'A' + base: 'a' + shift, capslock: 'A' + ctrl, alt, meta: none + } + +The system scans the properties from first to last and left to right, ignoring +the `label` and `number` properties, which are special. + +The first property encountered is `base`. The `base` property always applies to +a key, no matter what modifiers are pressed. It essentially specifies the default +behavior for the key unless it is overridden by following properties. +Since the `base` property applies to this key press, the system makes note +of the fact that its behavior is `'a'` (type the character `a`). + +The system then continues to scan subsequent properties in case any of them +are more specific than `base` and override it. It encounters `shift` which +also applies to the key press SHIFT + A. So the system decides to ignore +the `base` property's behavior and chooses the behavior associated with +the `shift` property, which is `'A'` (type the character `A`). + +It then continues to scan the table, however no other properties apply to this +key press (CAPS LOCK is not locked, neither CONTROL key is pressed, neither +ALT key is pressed and neither META key is pressed). + +So the resulting behavior for the key combination SHIFT + A is `'A'`. + +#### CONTROL + A #### + +Now consider what would happen if the user pressed A and CONTROL together. + +As before, the system would scan the table of properties. It would notice +that the `base` property applied but would also continue scanning until +it eventually reached the `control` property. As it happens, the `control` +property appears after `base` so its behavior overrides the `base` behavior. + +So the resulting behavior for the key combination CONTROL + A is `none`. + +#### ESCAPE #### + +Now suppose the user pressed ESCAPE. + + key ESCAPE { + base: fallback BACK + alt, meta: fallback HOME + ctrl: fallback MENU + } + +This time the system obtains the behavior `fallback BACK`, a fallback behavior. +Because no character literal appears, no character will be typed. + +When processing the key, the system will first deliver `KEYCODE_ESCAPE` to the +application. If the application does not handle it, then the system will try +again but this time it will deliver `KEYCODE_BACK` to the application as +requested by the fallback behavior. + +So applications that recognize and support `KEYCODE_ESCAPE` have the +opportunity to handle it as is, but other applications that do not can instead +perform the fallback action of treating the key as if it were `KEYCODE_BACK`. + +#### NUMPAD_0 with or without NUM LOCK #### + +The numeric keypad keys have very different interpretations depending on whether +the NUM LOCK key is locked. + +The following key declaration ensures that `KEYCODE_NUMPAD_0` types `0` +when NUM LOCK is pressed. When NUM LOCK is not pressed, the key is delivered +to the application as usual, and if it is not handled, then the fallback +key `KEYCODE_INSERT` is delivered instead. + + key NUMPAD_0 { + label, number: '0' + base: fallback INSERT + numlock: '0' + ctrl, alt, meta: none + } + +As we can see, fallback key declarations greatly improve compatibility +with older applications that do not recognize or directly support all of the keys +that are present on a full PC style keyboard. + +### Examples ### + +#### Full Keyboard #### + + # This is an example of part of a key character map file for a full keyboard + # include a few fallback behaviors for special keys that few applications + # handle themselves. + + type FULL + + key C { + label: 'C' + base: 'c' + shift, capslock: 'C' + alt: '\u00e7' + shift+alt: '\u00c7' + ctrl, meta: none + } + + key SPACE { + label: ' ' + base: ' ' + ctrl: none + alt, meta: fallback SEARCH + } + + key NUMPAD_9 { + label, number: '9' + base: fallback PAGE_UP + numlock: '9' + ctrl, alt, meta: none + } + +#### Alphanumeric Keyboard #### + + # This is an example of part of a key character map file for an alphanumeric + # thumb keyboard. Some keys are combined, such as `A` and `2`. Here we + # specify `number` labels to tell the system what to do when the user is + # typing a number into a dial pad. + # + # Also note the special character '\uef01' mapped to ALT+SPACE. + # Pressing this combination of keys invokes an on-screen character picker. + + type ALPHA + + key A { + label: 'A' + number: '2' + base: 'a' + shift, capslock: 'A' + alt: '#' + shift+alt, capslock+alt: none + } + + key SPACE { + label: ' ' + number: ' ' + base: ' ' + shift: ' ' + alt: '\uef01' + shift+alt: '\uef01' + } + +#### Game Pad #### + + # This is an example of part of a key character map file for a game pad. + # It defines fallback actions that enable the user to navigate the user interface + # by pressing buttons. + + type SPECIAL_FUNCTION + + key BUTTON_A { + base: fallback BACK + } + + key BUTTON_X { + base: fallback DPAD_CENTER + } + + key BUTTON_START { + base: fallback HOME + } + + key BUTTON_SELECT { + base: fallback MENU + } + +## Compatibility Note ## + +Prior to Android Honeycomb 3.0, the Android key character map was specified +using a very different syntax and was compiled into a binary file format +(`.kcm.bin`) at build time. + +Although the new format uses the same extension `.kcm`, the syntax is quite +different (and much more powerful). + +As of Android Honeycomb 3.0, all Android key character map files must use +the new syntax and plain text file format that is described in this document. +The old syntax is not supported and the old `.kcm.bin` files are not recognized +by the system. + +## Language Note ## + +Android does not currently support multilingual keyboards. Moreover, the +built-in generic key character map assumes a US English keyboard layout. + +OEMs are encouraged to provide custom key character maps for their keyboards +if they are designed for other languages. + +Future versions of Android may provide better support for multilingual keyboards +or user-selectable keyboard layouts. + +## Validation ## + +Make sure to validate your key character map files using the +[Validate Keymaps](/tech/input/validate-keymaps.html) tool.
diff --git a/src/tech/input/key-layout-files.md b/src/tech/input/key-layout-files.md new file mode 100644 index 0000000..9a2760d --- /dev/null +++ b/src/tech/input/key-layout-files.md
@@ -0,0 +1,332 @@ +<!-- + Copyright 2011 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. +--> + +# Key Layout Files # + +Key layout files (`.kl` files) are responsible for mapping Linux key codes +and axis codes to Android key codes and axis codes and specifying associated +policy flags. + +Device-specific key layout files are *required* for all internal (built-in) +input devices that have keys, including special keys such as volume, power +and headset media keys. + +Device-specific key layout files are *optional* for other input devices but +they are *recommended* for special-purpose keyboards and joysticks. + +If no device-specific key layout file is available, then the system will +choose a default instead. + +## Location ## + +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. + +* `/system/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl` +* `/system/usr/keylayout/Vendor_XXXX_Product_XXXX.kl` +* `/system/usr/keylayout/DEVICE_NAME.kl` +* `/data/system/devices/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl` +* `/data/system/devices/keylayout/Vendor_XXXX_Product_XXXX.kl` +* `/data/system/devices/keylayout/DEVICE_NAME.kl` +* `/system/usr/keylayout/Generic.kl` +* `/data/system/devices/keylayout/Generic.kl` + +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 '_'. + +## Generic Key Layout File ## + +The system provides a special built-in generic key layout file called `Generic.kl`. +This key layout is intended to support a variety of standard external +keyboards and joysticks. + +*Do not modify the generic key layout!* + +## Syntax ## + +A key layout file is a plain text file consisting of key or axis declarations +and flags. + +### Key Declarations ### + +Key declarations each consist of the keyword `key` followed by a Linux key code +number, an Android key code name, and optional set of whitespace delimited policy flags. + + key 1 ESCAPE + key 114 VOLUME_DOWN WAKE + key 16 Q VIRTUAL WAKE + +The following policy flags are recognized: + +* `WAKE`: The key should wake the device when it is asleep. For historical reasons, + this flag behaves in the same manner as `WAKE_DROPPED` below. +* `WAKE_DROPPED`: The key should wake the device when it is asleep but the key itself + should be dropped when the wake-up occurs. In a sense, the key's action was to + wake the device, but the key itself is not processed. +* `SHIFT`: The key should be interpreted as if the SHIFT key were also pressed. +* `CAPS_LOCK`: The key should be interpreted as if the CAPS LOCK key were also pressed. +* `ALT`: The key should be interpreted as if the ALT key were also pressed. +* `ALT_GR`: The key should be interpreted as if the RIGHT ALT key were also pressed. +* `FUNCTION`: The key should be interpreted as if the FUNCTION key were also pressed. +* `VIRTUAL`: The key is a virtual soft key (capacitive button) that is adjacent to + the main touch screen. This causes special debouncing logic to be enabled, see below. +* `MENU`: Deprecated. Do not use. +* `LAUNCHER`: Deprecated. Do not use. + +### Axis Declarations ### + +Axis declarations each consist of the keyword `axis` followed by a Linux axis code +number, and qualifiers that control the behavior of the axis including at least +one Android axis code name. + +#### Basic Axes #### + +A basic axis simply maps a Linux axis code to an Android axis code name. + +The following declaration maps `ABS_X` (indicated by `0x00`) to `AXIS_X` (indicated by `X`). + + axis 0x00 X + +In the above example, if the value of `ABS_X` is `5` then `AXIS_X` will be set to `5`. + +#### Split Axes #### + +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. + +The following declaration maps values of the `ABS_Y` axis (indicated by `0x01`) to +`AXIS_GAS` when less than `0x7f` or to `AXIS_BRAKE` when greater than `0x7f`. + + axis 0x01 split 0x7f GAS BRAKE + +In the above example, if the value of `ABS_Y` is `0x7d` then `AXIS_GAS` is set +to `2` (`0x7f - 0x7d`) and `AXIS_BRAKE` is set to `0`. Conversely, if the value of +`ABS_Y` is `0x83` then `AXIS_GAS` is set to `0` and `AXIS_BRAKE` is set to `4` +(`0x83 - 0x7f`). Finally, if the value of `ABS_Y` equals the split value of `0x7f` +then both `AXIS_GAS` and `AXIS_BRAKE` are set to `0`. + +#### Inverted Axes #### + +An inverted axis inverts the sign of the axis value. + +The following declaration maps `ABS_RZ` (indicated by `0x05`) to `AXIS_BRAKE` +(indicated by `BRAKE`), and inverts the output by negating it. + + axis 0x05 invert AXIS_RZ + +In the above example, if the value of `ABS_RZ` is `2` then `AXIS_RZ` is set to `-2`. + +#### Center Flat Position Option #### + +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. + +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. + +To resolve this issue, an axis declaration may be followed by a `flat` +option that specifies the value of the center flat position for the axis. + + axis 0x03 Z flat 4096 + +In the above example, the center flat position is set to `4096`. + +### Comments ### + +Comment lines begin with '#' and continue to the end of the line. Like this: + + # A comment! + +Blank lines are ignored. + +### Examples ### + +#### Keyboard #### + + # 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... + +#### System Controls #### + + # 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 that + # the device decodes into key presses. + + key 114 VOLUME_DOWN WAKE + key 115 VOLUME_UP WAKE + key 116 POWER WAKE + +#### Capacitive Buttons #### + + # 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 + +#### Headset Jack Media Controls #### + + # 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 WAKE + key 165 MEDIA_PREVIOUS WAKE + key 226 HEADSETHOOK WAKE + +#### Joystick #### + + # 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 out of a range from -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 + +## Wake Keys ## + +Wake keys are special keys that wake the device from sleep, such as the power key. + +By default, for internal keyboard devices, no key is a wake key. For external +keyboard device, all keys are wake keys. + +To make a key be a wake key, set the `WAKE_DROPPED` flag in the key layout file +for the keyboard device. + +Note that the `WindowManagerPolicy` component is responsible for implementing wake +key behavior. Moreover, the key guard may prevent certain keys from functioning +as wake keys. A good place to start understanding wake key behavior is +`PhoneWindowManager.interceptKeyBeforeQueueing`. + +## Virtual Soft Keys ## + +The input system provides special features for implementing virtual soft keys. + +There are three cases: + +1. If the virtual soft keys are displayed graphically on the screen, as on the + Galaxy Nexus, then 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. + +2. If the virtual soft keys are implemented as an extended touchable region + that is part of the main touch screen, as on the Nexus One, then 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. + + Refer to the section on [Touch Devices](/tech/input/touch-devices.html) + for more details about virtual key map files. + + The key layout file for the touch screen input device must specify the + appropriate key mapping and include the `VIRTUAL` flag for each key. + +3. If the virtual soft keys are implemented as capacitive buttons that are + separate from the main touch screen, as on the Nexus S, then 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 `VIRTUAL` flag for each key. + +When virtual soft key are located within or in close physical proximity of the +touch screen, it is easy for the user to accidentally press one of the buttons +when touching near the bottom of the screen or when sliding a finger from top +to bottom or from bottom to top on the screen. + +To prevent this from happening, 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. The delay is called the +virtual key quiet time. + +To enable virtual soft key debouncing, we must do two things. + +First, we provide a key layout file for the touch screen or capacitive button +input device with the `VIRTUAL` flag set for each key. + + key 139 MENU VIRTUAL + key 102 HOME VIRTUAL + key 158 BACK VIRTUAL + key 217 SEARCH VIRTUAL + +Then, we set the value of the virtual key quiet time in a resource overlay +for the framework `config.xml` resource. + + <!-- Specifies the amount of time to disable virtual keys after the screen is touched + in order 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> + +## Validation ## + +Make sure to validate your key layout files using the +[Validate Keymaps](/tech/input/validate-keymaps.html) tool.
diff --git a/src/tech/input/keyboard-devices.md b/src/tech/input/keyboard-devices.md new file mode 100644 index 0000000..76564d9 --- /dev/null +++ b/src/tech/input/keyboard-devices.md
@@ -0,0 +1,1002 @@ +<!-- + Copyright 2011 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. +--> + +# Keyboard Devices # + +Android supports a variety of keyboard devices including special function +keypads (volume and power controls), compact embedded QWERTY keyboards, +and fully featured PC-style external keyboards. + +This document decribes physical keyboards only. Refer to the Android SDK +for information about soft keyboards (Input Method Editors). + +## Keyboard Classification ## + +An input device is classified as a keyboard if either of the following +conditions hold: + +* The input device reports the presence of any Linux key codes used on keyboards + including `0` through `0xff` or `KEY_OK` through `KEY_MAX`. + +* The input device reports the presence of any Linux key codes used on joysticks + and gamepads including `BTN_0` through `BTN_9`, `BTN_TRIGGER` through `BTN_DEAD`, + or `BTN_A` through `BTN_THUMBR`. + +Joysticks are currently classified as keyboards because joystick and gamepad buttons +are reported by `EV_KEY` events in the same way keyboard keys are reported. Thus +joysticks and gamepads also make use of key map files for configuration. +Refer to the section on [Joystick Devices](/tech/input/joystick-devices.html) for +more information. + +Once an input device has been classified as a keyboard, the system loads the +input device configuration file and keyboard layout for the keyboard. + +The system then tries to determine additional characteristics of the device. + +* If the input device has any keys that are mapped to `KEYCODE_Q`, then the + device is considered to have an alphabetic keypad (as opposed to numeric). + The alphabetic keypad capability is reported in the resource `Configuration` + object as `KEYBOARD_QWERTY`. + +* If the input device has any keys that are mapped to `KEYCODE_DPAD_UP`, + `KEYCODE_DPAD_DOWN`, `KEYCODE_DPAD_LEFT`, `KEYCODE_DPAD_RIGHT`, and + `KEYCODE_DPAD_CENTER` (all must be present), then the device is considered + to have a directional keypad. + The directional keypad capability is reported in the resource `Configuration` + object as `NAVIGATION_DPAD`. + +* If the input device has any keys that are mapped to `KEYCODE_BUTTON_A` + or other gamepad related keys, then the device is considered to have a gamepad. + +## Keyboard Driver Requirements ## + +1. Keyboard drivers should only register key codes for the keys that they + actually support. Registering excess key codes may confuse the device + classification algorithm or cause the system to incorrectly detect + the supported keyboard capabilities of the device. + +2. Keyboard drivers should use `EV_KEY` to report key presses, using a value + of `0` to indicate that a key is released, a value of `1` to indicate that + a key is pressed, and a value greater than or equal to `2` to indicate that + the key is being repeated automatically. + +3. Android performs its own keyboard repeating. Auto-repeat functionality + should be disabled in the driver. + +4. Keyboard drivers may optionally indicate the HID usage or low-level scan + code by sending `EV_MSC` with `MSC_SCANCODE` and a valud indicating the usage + or scan code when the key is pressed. This information is not currently + used by Android. + +5. Keyboard drivers should support setting LED states when `EV_LED` is written + to the device. The `hid-input` driver handles this automatically. + At the time of this writing, Android uses `LED_CAPSLOCK`, `LED_SCROLLLOCK`, + and `LED_NUMLOCK`. These LEDs only need to be supported when the + keyboard actually has the associated indicator lights. + +6. Keyboard drivers for embedded keypads (for example, using a GPIO matrix) + should make sure to send `EV_KEY` events with a value of `0` for any keys that + are still pressed when the device is going to sleep. Otherwise keys might + get stuck down and will auto-repeat forever. + +## Keyboard Operation ## + +The following is a brief summary of the keyboard operation on Android. + +1. The `EventHub` reads raw events from the `evdev` driver and maps Linux key codes + (sometimes referred to as scan codes) into Android key codes using the + keyboard's key layout map. + +2. The `InputReader` consumes the raw events and updates the meta key state. + For example, if the left shift key is pressed or released, the reader will + set or reset the `META_SHIFT_LEFT_ON` and `META_SHIFT_ON` bits accordingly. + +3. The `InputReader` notifies the `InputDispatcher` about the key event. + +4. The `InputDispatcher` asks the `WindowManagerPolicy` what to do with the key + event by calling `WindowManagerPolicy.interceptKeyBeforeQueueing`. This method + is part of a critical path that is responsible for waking the device when + certain keys are pressed. The `EventHub` effectively holds a wake lock + along this critical path to ensure that it will run to completion. + +5. If an `InputFilter` is currently in use, the `InputDispatcher` gives it a + chance to consume or transform the key. The `InputFilter` may be used to implement + low-level system-wide accessibility policies. + +6. The `InputDispatcher` enqueues the key for processing on the dispatch thread. + +7. When the `InputDispatcher` dequeues the key, it gives the `WindowManagerPolicy` + a second chance to intercept the key event by calling + `WindowManagerPolicy.interceptKeyBeforeDispatching`. This method handles system + shortcuts and other functions. + +8. The `InputDispatcher` then identifies the key event target (the focused window) + and waits for them to become ready. Then, the `InputDispatcher` delivers the + key event to the application. + +9. Inside the application, the key event propagates down the view hierarchy to + the focused view for pre-IME key dispatch. + +10. If the key event is not handled in the pre-IME dispatch and an IME is in use, the + key event is delivered to the IME. + +11. If the key event was not consumed by the IME, then the key event propagates + down the view hierarchy to the focused view for standard key dispatch. + +12. The application reports back to the `InputDispatcher` as to whether the key + event was consumed. If the event was not consumed, the `InputDispatcher` + calls `WindowManagerPolicy.dispatchUnhandledKey` to apply "fallback" behavior. + Depending on the fallback action, the key event dispatch cycle may be restarted + using a different key code. For example, if an application does not handle + `KEYCODE_ESCAPE`, the system may redispatch the key event as `KEYCODE_BACK` instead. + +## Keyboard Configuration ## + +Keyboard behavior is determined by the keyboard's key layout, key character +map and input device configuration. + +Refer to the following sections for more details about the files that +participate in keyboard configuration: + +* [Key Layout Files](/tech/input/key-layout-files.html) +* [Key Character Map Files](/tech/input/key-character-map-files.html) +* [Input Device Configuration Files](/tech/input/input-device-configuration-files.html) + +### Properties ### + +The following input device configuration properties are used for keyboards. + +#### `keyboard.layout` #### + +*Definition:* `keyboard.layout` = <name> + +Specifies the name of the key layout file associated with the input device, +excluding the `.kl` extension. If this file is not found, the input system +will use the default key layout instead. + +Spaces in the name are converted to underscores during lookup. + +Refer to the key layout file documentation for more details. + +#### `keyboard.characterMap` #### + +*Definition:* `keyboard.characterMap` = <name> + +Specifies the name of the key character map file associated with the input device, +excluding the `.kcm` extension. If this file is not found, the input system +will use the default key character map instead. + +Spaces in the name are converted to underscores during lookup. + +Refer to the key character map file documentation for more details. + +#### `keyboard.orientationAware` #### + +*Definition:* `keyboard.orientationAware` = `0` | `1` + +Specifies whether the keyboard should react to display orientation changes. + +* If the value is `1`, the directional keypad keys are rotated when the + associated display orientation changes. + +* If the value is `0`, the keyboard is immune to display orientation changes. + +The default value is `0`. + +Orientation awareness is used to support rotation of directional keypad keys, +such as on the Motorola Droid. For example, when the device is rotated +clockwise 90 degrees from its natural orientation, `KEYCODE_DPAD_UP` is +remapped to produce `KEYCODE_DPAD_RIGHT` since the 'up' key ends up pointing +'right' when the device is held in that orientation. + +#### `keyboard.builtIn` #### + +*Definition:* `keyboard.builtIn` = `0` | `1` + +Specifies whether the keyboard is the built-in (physically attached) +keyboard. + +The default value is `1` if the device name ends with `-keypad`, `0` otherwise. + +The built-in keyboard is always assigned a device id of `0`. Other keyboards +that are not built-in are assigned unique non-zero device ids. + +Using an id of `0` for the built-in keyboard is important for maintaining +compatibility with the `KeyCharacterMap.BUILT_IN_KEYBOARD` field, which specifies +the id of the built-in keyboard and has a value of `0`. This field has been +deprecated in the API but older applications might still be using it. + +A special-function keyboard (one whose key character map specifies a +type of `SPECIAL_FUNCTION`) will never be registered as the built-in keyboard, +regardless of the setting of this property. This is because a special-function +keyboard is by definition not intended to be used for general purpose typing. + +### Example Configurations ### + + # This is an example input device configuration file for a built-in + # keyboard that has a DPad. + + # The keyboard is internal because it is part of the device. + device.internal = 1 + + # The keyboard is the default built-in keyboard so it should be assigned + # an id of 0. + keyboard.builtIn = 1 + + # The keyboard includes a DPad which is mounted on the device. As the device + # is rotated the orientation of the DPad rotates along with it, so the DPad must + # be aware of the display orientation. This ensures that pressing 'up' on the + # DPad always means 'up' from the perspective of the user, even when the entire + # device has been rotated. + keyboard.orientationAware = 1 + +### Compatibility Notes ### + +Prior to Honeycomb, the keyboard input mapper did not use any configuration properties. +All keyboards were assumed to be physically attached and orientation aware. The default +key layout and key character map was named `qwerty` instead of `Generic`. The key +character map format was also very different and the framework did not support +PC-style full keyboards or external keyboards. + +When upgrading devices to Honeycomb, make sure to create or update the necessary +configuration and key map files. + +## HID Usages, Linux Key Codes and Android Key Codes ## + +The system refers to keys using several different identifiers, depending on the +layer of abstraction. + +For HID devices, each key has an associated HID usage. The Linux `hid-input` +driver and related vendor and device-specific HID drivers are responsible +for parsing HID reports and mapping HID usages to Linux key codes. + +As Android reads `EV_KEY` events from the Linux kernel, it translates each +Linux key code into its corresponding Android key code according to the +key layout file of the device. + +When the key event is dispatched to an application, the `android.view.KeyEvent` +instance reports the Linux key code as the value of `getScanCode()` and the +Android key code as the value of `getKeyCode()`. For the purposes of the +framework, only the value of `getKeyCode()` is important. + +Note that the HID usage information is not used by Android itself or +passed to applications. + +## Code Tables ## + +The following tables show how HID usages, Linux key codes and Android +key codes are related to one another. + +The LKC column specifies the Linux key code in hexadecimal. + +The AKC column specifies the Android key code in hexadecimal. + +The Notes column refers to notes that are posted after the table. + +The Version column specifies the first version of the Android platform +to have included this key in its default key map. Multiple rows are +shown in cases where the default key map has changed between versions. +The oldest version indicated is 1.6. + +* In Gingerbread (2.3) and earlier releases, the default key map was + `qwerty.kl`. This key map was only intended for use with the Android + Emulator and was not intended to be used to support arbitrary + external keyboards. Nevertheless, a few OEMs added Bluetooth + keyboard support to the platform and relied on `qwerty.kl` to + provide the necessary keyboard mappings. Consequently these + older mappings may be of interest to OEMs who are building + peripherals for these particular devices. Note that the mappings + are substantially different from the current ones, particularly + with respect to the treatment of the `HOME` key. It is recommended + that all new peripherals be developed according to the Honeycomb or more + recent key maps (ie. standard HID). + +* As of Honeycomb (3.0), the default key map is `Generic.kl`. + This key map was designed to support full PC style keyboards. + Most functionality of standard HID keyboards should just work out + of the box. + +The key code mapping may vary across versions of the Linux kernel and Android. +When changes are known to have occurred in the Android default key maps, +they are indicated in the version column. + +Device-specific HID drivers and key maps may apply different mappings +than are indicated here. + +### HID Keyboard and Keypad Page (0x07) ### + +| HID Usage | HID Usage Name | LKC | Linux Key Code Name | Version | AKC | Android Key Code Name | Notes | +| ----------- | -------------------------------- | ------ | -------------------------------- | ------- | ------ | -------------------------------- | ----- | +| 0x07 0x0001 | Keyboard Error Roll Over | | | | | | | +| 0x07 0x0002 | Keyboard POST Fail | | | | | | | +| 0x07 0x0003 | Keyboard Error Undefined | | | | | | | +| 0x07 0x0004 | Keyboard a and A | 0x001e | KEY_A | 1.6 | 0x001d | KEYCODE_A | 1 | +| 0x07 0x0005 | Keyboard b and B | 0x0030 | KEY_B | 1.6 | 0x001e | KEYCODE_B | 1 | +| 0x07 0x0006 | Keyboard c and C | 0x002e | KEY_C | 1.6 | 0x001f | KEYCODE_C | 1 | +| 0x07 0x0007 | Keyboard d and D | 0x0020 | KEY_D | 1.6 | 0x0020 | KEYCODE_D | 1 | +| 0x07 0x0008 | Keyboard e and E | 0x0012 | KEY_E | 1.6 | 0x0021 | KEYCODE_E | 1 | +| 0x07 0x0009 | Keyboard f and F | 0x0021 | KEY_F | 1.6 | 0x0022 | KEYCODE_F | 1 | +| 0x07 0x000a | Keyboard g and G | 0x0022 | KEY_G | 1.6 | 0x0023 | KEYCODE_G | 1 | +| 0x07 0x000b | Keyboard h and H | 0x0023 | KEY_H | 1.6 | 0x0024 | KEYCODE_H | 1 | +| 0x07 0x000c | Keyboard i and I | 0x0017 | KEY_I | 1.6 | 0x0025 | KEYCODE_I | 1 | +| 0x07 0x000d | Keyboard j and J | 0x0024 | KEY_J | 1.6 | 0x0026 | KEYCODE_J | 1 | +| 0x07 0x000e | Keyboard k and K | 0x0025 | KEY_K | 1.6 | 0x0027 | KEYCODE_K | 1 | +| 0x07 0x000f | Keyboard l and L | 0x0026 | KEY_L | 1.6 | 0x0028 | KEYCODE_L | 1 | +| 0x07 0x0010 | Keyboard m and M | 0x0032 | KEY_M | 1.6 | 0x0029 | KEYCODE_M | 1 | +| 0x07 0x0011 | Keyboard n and N | 0x0031 | KEY_N | 1.6 | 0x002a | KEYCODE_N | 1 | +| 0x07 0x0012 | Keyboard o and O | 0x0018 | KEY_O | 1.6 | 0x002b | KEYCODE_O | 1 | +| 0x07 0x0013 | Keyboard p and P | 0x0019 | KEY_P | 1.6 | 0x002c | KEYCODE_P | 1 | +| 0x07 0x0014 | Keyboard q and Q | 0x0010 | KEY_Q | 1.6 | 0x002d | KEYCODE_Q | 1 | +| 0x07 0x0015 | Keyboard r and R | 0x0013 | KEY_R | 1.6 | 0x002e | KEYCODE_R | 1 | +| 0x07 0x0016 | Keyboard s and S | 0x001f | KEY_S | 1.6 | 0x002f | KEYCODE_S | 1 | +| 0x07 0x0017 | Keyboard t and T | 0x0014 | KEY_T | 1.6 | 0x0030 | KEYCODE_T | 1 | +| 0x07 0x0018 | Keyboard u and U | 0x0016 | KEY_U | 1.6 | 0x0031 | KEYCODE_U | 1 | +| 0x07 0x0019 | Keyboard v and V | 0x002f | KEY_V | 1.6 | 0x0032 | KEYCODE_V | 1 | +| 0x07 0x001a | Keyboard w and W | 0x0011 | KEY_W | 1.6 | 0x0033 | KEYCODE_W | 1 | +| 0x07 0x001b | Keyboard x and X | 0x002d | KEY_X | 1.6 | 0x0034 | KEYCODE_X | 1 | +| 0x07 0x001c | Keyboard y and Y | 0x0015 | KEY_Y | 1.6 | 0x0035 | KEYCODE_Y | 1 | +| 0x07 0x001d | Keyboard z and Z | 0x002c | KEY_Z | 1.6 | 0x0036 | KEYCODE_Z | 1 | +| 0x07 0x001e | Keyboard 1 and ! | 0x0002 | KEY_1 | 1.6 | 0x0008 | KEYCODE_1 | 1 | +| 0x07 0x001f | Keyboard 2 and @ | 0x0003 | KEY_2 | 1.6 | 0x0009 | KEYCODE_2 | 1 | +| 0x07 0x0020 | Keyboard 3 and # | 0x0004 | KEY_3 | 1.6 | 0x000a | KEYCODE_3 | 1 | +| 0x07 0x0021 | Keyboard 4 and $ | 0x0005 | KEY_4 | 1.6 | 0x000b | KEYCODE_4 | 1 | +| 0x07 0x0022 | Keyboard 5 and % | 0x0006 | KEY_5 | 1.6 | 0x000c | KEYCODE_5 | 1 | +| 0x07 0x0023 | Keyboard 6 and ^ | 0x0007 | KEY_6 | 1.6 | 0x000d | KEYCODE_6 | 1 | +| 0x07 0x0024 | Keyboard 7 and & | 0x0008 | KEY_7 | 1.6 | 0x000e | KEYCODE_7 | 1 | +| 0x07 0x0025 | Keyboard 8 and * | 0x0009 | KEY_8 | 1.6 | 0x000f | KEYCODE_8 | 1 | +| 0x07 0x0026 | Keyboard 9 and ( | 0x000a | KEY_9 | 1.6 | 0x0010 | KEYCODE_9 | 1 | +| 0x07 0x0027 | Keyboard 0 and ) | 0x000b | KEY_0 | 1.6 | 0x0007 | KEYCODE_0 | 1 | +| 0x07 0x0028 | Keyboard Return (ENTER) | 0x001c | KEY_ENTER | 1.6 | 0x0042 | KEYCODE_ENTER | 1 | +| 0x07 0x0029 | Keyboard ESCAPE | 0x0001 | KEY_ESC | 3.0 | 0x006f | KEYCODE_ESCAPE | | +| "" | "" | "" | "" | 2.3 | 0x0004 | KEYCODE_BACK | | +| 0x07 0x002a | Keyboard DELETE (Backspace) | 0x000e | KEY_BACKSPACE | 1.6 | 0x0043 | KEYCODE_DEL | | +| 0x07 0x002b | Keyboard Tab | 0x000f | KEY_TAB | 1.6 | 0x003d | KEYCODE_TAB | | +| 0x07 0x002c | Keyboard Spacebar | 0x0039 | KEY_SPACE | 1.6 | 0x003e | KEYCODE_SPACE | | +| 0x07 0x002d | Keyboard - and _ | 0x000c | KEY_MINUS | 1.6 | 0x0045 | KEYCODE_MINUS | 1 | +| 0x07 0x002e | Keyboard = and + | 0x000d | KEY_EQUAL | 1.6 | 0x0046 | KEYCODE_EQUALS | 1 | +| 0x07 0x002f | Keyboard \[ and \{ | 0x001a | KEY_LEFTBRACE | 1.6 | 0x0047 | KEYCODE_LEFT_BRACKET | 1 | +| 0x07 0x0030 | Keyboard \] and \} | 0x001b | KEY_RIGHTBRACE | 1.6 | 0x0048 | KEYCODE_RIGHT_BRACKET | 1 | +| 0x07 0x0031 | Keyboard \\ and | | 0x002b | KEY_BACKSLASH | 1.6 | 0x0049 | KEYCODE_BACKSLASH | 1 | +| 0x07 0x0032 | Keyboard Non-US # and ~ | 0x002b | KEY_BACKSLASH | 1.6 | 0x0049 | KEYCODE_BACKSLASH | 1 | +| 0x07 0x0033 | Keyboard ; and : | 0x0027 | KEY_SEMICOLON | 1.6 | 0x004a | KEYCODE_SEMICOLON | 1 | +| 0x07 0x0034 | Keyboard ' and " | 0x0028 | KEY_APOSTROPHE | 1.6 | 0x004b | KEYCODE_APOSTROPHE | 1 | +| 0x07 0x0035 | Keyboard \` and ~ | 0x0029 | KEY_GRAVE | 3.0 | 0x0044 | KEYCODE_GRAVE | 1 | +| 0x07 0x0036 | Keyboard , and < | 0x0033 | KEY_COMMA | 1.6 | 0x0037 | KEYCODE_COMMA | 1 | +| 0x07 0x0037 | Keyboard . and > | 0x0034 | KEY_DOT | 1.6 | 0x0038 | KEYCODE_PERIOD | 1 | +| 0x07 0x0038 | Keyboard / and ? | 0x0035 | KEY_SLASH | 1.6 | 0x004c | KEYCODE_SLASH | 1 | +| 0x07 0x0039 | Keyboard Caps Lock | 0x003a | KEY_CAPSLOCK | 3.0 | 0x0073 | KEYCODE_CAPS_LOCK | | +| 0x07 0x003a | Keyboard F1 | 0x003b | KEY_F1 | 3.0 | 0x0083 | KEYCODE_F1 | | +| "" | "" | "" | "" | 1.6 | 0x0052 | KEYCODE_MENU | | +| 0x07 0x003b | Keyboard F2 | 0x003c | KEY_F2 | 3.0 | 0x0084 | KEYCODE_F2 | | +| "" | "" | "" | "" | 1.6 | 0x0002 | KEYCODE_SOFT_RIGHT | | +| 0x07 0x003c | Keyboard F3 | 0x003d | KEY_F3 | 3.0 | 0x0085 | KEYCODE_F3 | | +| "" | "" | "" | "" | 1.6 | 0x0005 | KEYCODE_CALL | | +| 0x07 0x003d | Keyboard F4 | 0x003e | KEY_F4 | 3.0 | 0x0086 | KEYCODE_F4 | | +| "" | "" | "" | "" | 1.6 | 0x0006 | KEYCODE_ENDCALL | | +| 0x07 0x003e | Keyboard F5 | 0x003f | KEY_F5 | 3.0 | 0x0087 | KEYCODE_F5 | | +| 0x07 0x003f | Keyboard F6 | 0x0040 | KEY_F6 | 3.0 | 0x0088 | KEYCODE_F6 | | +| 0x07 0x0040 | Keyboard F7 | 0x0041 | KEY_F7 | 3.0 | 0x0089 | KEYCODE_F7 | | +| 0x07 0x0041 | Keyboard F8 | 0x0042 | KEY_F8 | 3.0 | 0x008a | KEYCODE_F8 | | +| 0x07 0x0042 | Keyboard F9 | 0x0043 | KEY_F9 | 3.0 | 0x008b | KEYCODE_F9 | | +| 0x07 0x0043 | Keyboard F10 | 0x0044 | KEY_F10 | 3.0 | 0x008c | KEYCODE_F10 | | +| "" | "" | "" | "" | 2.3 | 0x0052 | KEYCODE_MENU | | +| 0x07 0x0044 | Keyboard F11 | 0x0057 | KEY_F11 | 3.0 | 0x008d | KEYCODE_F11 | | +| 0x07 0x0045 | Keyboard F12 | 0x0058 | KEY_F12 | 3.0 | 0x008e | KEYCODE_F12 | | +| 0x07 0x0046 | Keyboard Print Screen | 0x0063 | KEY_SYSRQ | 3.0 | 0x0078 | KEYCODE_SYSRQ | | +| 0x07 0x0047 | Keyboard Scroll Lock | 0x0046 | KEY_SCROLLLOCK | 3.0 | 0x0074 | KEYCODE_SCROLL_LOCK | | +| 0x07 0x0048 | Keyboard Pause | 0x0077 | KEY_PAUSE | 3.0 | 0x0079 | KEYCODE_BREAK | | +| 0x07 0x0049 | Keyboard Insert | 0x006e | KEY_INSERT | 3.0 | 0x007c | KEYCODE_INSERT | | +| 0x07 0x004a | Keyboard Home | 0x0066 | KEY_HOME | 3.0 | 0x007a | KEYCODE_MOVE_HOME | | +| "" | "" | "" | "" | 1.6 | 0x0003 | KEYCODE_HOME | | +| 0x07 0x004b | Keyboard Page Up | 0x0068 | KEY_PAGEUP | 3.0 | 0x005c | KEYCODE_PAGE_UP | | +| 0x07 0x004c | Keyboard Delete Forward | 0x006f | KEY_DELETE | 3.0 | 0x0070 | KEYCODE_FORWARD_DEL | | +| 0x07 0x004d | Keyboard End | 0x006b | KEY_END | 3.0 | 0x007b | KEYCODE_MOVE_END | | +| "" | "" | "" | "" | 1.6 | 0x0006 | KEYCODE_ENDCALL | | +| 0x07 0x004e | Keyboard Page Down | 0x006d | KEY_PAGEDOWN | 3.0 | 0x005d | KEYCODE_PAGE_DOWN | | +| 0x07 0x004f | Keyboard Right Arrow | 0x006a | KEY_RIGHT | 1.6 | 0x0016 | KEYCODE_DPAD_RIGHT | | +| 0x07 0x0050 | Keyboard Left Arrow | 0x0069 | KEY_LEFT | 1.6 | 0x0015 | KEYCODE_DPAD_LEFT | | +| 0x07 0x0051 | Keyboard Down Arrow | 0x006c | KEY_DOWN | 1.6 | 0x0014 | KEYCODE_DPAD_DOWN | | +| 0x07 0x0052 | Keyboard Up Arrow | 0x0067 | KEY_UP | 1.6 | 0x0013 | KEYCODE_DPAD_UP | | +| 0x07 0x0053 | Keyboard Num Lock and Clear | 0x0045 | KEY_NUMLOCK | 3.0 | 0x008f | KEYCODE_NUM_LOCK | | +| 0x07 0x0054 | Keypad / | 0x0062 | KEY_KPSLASH | 3.0 | 0x009a | KEYCODE_NUMPAD_DIVIDE | | +| 0x07 0x0055 | Keypad * | 0x0037 | KEY_KPASTERISK | 3.0 | 0x009b | KEYCODE_NUMPAD_MULTIPLY | | +| 0x07 0x0056 | Keypad - | 0x004a | KEY_KPMINUS | 3.0 | 0x009c | KEYCODE_NUMPAD_SUBTRACT | | +| 0x07 0x0057 | Keypad + | 0x004e | KEY_KPPLUS | 3.0 | 0x009d | KEYCODE_NUMPAD_ADD | | +| 0x07 0x0058 | Keypad ENTER | 0x0060 | KEY_KPENTER | 3.0 | 0x00a0 | KEYCODE_NUMPAD_ENTER | | +| 0x07 0x0059 | Keypad 1 and End | 0x004f | KEY_KP1 | 3.0 | 0x0091 | KEYCODE_NUMPAD_1 | | +| 0x07 0x005a | Keypad 2 and Down Arrow | 0x0050 | KEY_KP2 | 3.0 | 0x0092 | KEYCODE_NUMPAD_2 | | +| 0x07 0x005b | Keypad 3 and PageDn | 0x0051 | KEY_KP3 | 3.0 | 0x0093 | KEYCODE_NUMPAD_3 | | +| 0x07 0x005c | Keypad 4 and Left Arrow | 0x004b | KEY_KP4 | 3.0 | 0x0094 | KEYCODE_NUMPAD_4 | | +| 0x07 0x005d | Keypad 5 | 0x004c | KEY_KP5 | 3.0 | 0x0095 | KEYCODE_NUMPAD_5 | | +| 0x07 0x005e | Keypad 6 and Right Arrow | 0x004d | KEY_KP6 | 3.0 | 0x0096 | KEYCODE_NUMPAD_6 | | +| 0x07 0x005f | Keypad 7 and Home | 0x0047 | KEY_KP7 | 3.0 | 0x0097 | KEYCODE_NUMPAD_7 | | +| 0x07 0x0060 | Keypad 8 and Up Arrow | 0x0048 | KEY_KP8 | 3.0 | 0x0098 | KEYCODE_NUMPAD_8 | | +| 0x07 0x0061 | Keypad 9 and Page Up | 0x0049 | KEY_KP9 | 3.0 | 0x0099 | KEYCODE_NUMPAD_9 | | +| 0x07 0x0062 | Keypad 0 and Insert | 0x0052 | KEY_KP0 | 3.0 | 0x0090 | KEYCODE_NUMPAD_0 | | +| 0x07 0x0063 | Keypad . and Delete | 0x0053 | KEY_KPDOT | 3.0 | 0x009e | KEYCODE_NUMPAD_DOT | | +| 0x07 0x0064 | Keyboard Non-US \\ and | | 0x0056 | KEY_102ND | 4.0 | 0x0049 | KEYCODE_BACKSLASH | 1 | +| 0x07 0x0065 | Keyboard Application | 0x007f | KEY_COMPOSE | 3.0 | 0x0052 | KEYCODE_MENU | | +| "" | "" | "" | "" | 1.6 | 0x0054 | KEYCODE_SEARCH | | +| 0x07 0x0066 | Keyboard Power | 0x0074 | KEY_POWER | 1.6 | 0x001a | KEYCODE_POWER | | +| 0x07 0x0067 | Keypad = | 0x0075 | KEY_KPEQUAL | 3.0 | 0x00a1 | KEYCODE_NUMPAD_EQUALS | | +| 0x07 0x0068 | Keyboard F13 | 0x00b7 | KEY_F13 | | | | | +| 0x07 0x0069 | Keyboard F14 | 0x00b8 | KEY_F14 | | | | | +| 0x07 0x006a | Keyboard F15 | 0x00b9 | KEY_F15 | | | | | +| 0x07 0x006b | Keyboard F16 | 0x00ba | KEY_F16 | | | | | +| 0x07 0x006c | Keyboard F17 | 0x00bb | KEY_F17 | | | | | +| 0x07 0x006d | Keyboard F18 | 0x00bc | KEY_F18 | | | | | +| 0x07 0x006e | Keyboard F19 | 0x00bd | KEY_F19 | | | | | +| 0x07 0x006f | Keyboard F20 | 0x00be | KEY_F20 | | | | | +| 0x07 0x0070 | Keyboard F21 | 0x00bf | KEY_F21 | | | | | +| 0x07 0x0071 | Keyboard F22 | 0x00c0 | KEY_F22 | | | | | +| 0x07 0x0072 | Keyboard F23 | 0x00c1 | KEY_F23 | | | | | +| 0x07 0x0073 | Keyboard F24 | 0x00c2 | KEY_F24 | | | | | +| 0x07 0x0074 | Keyboard Execute | 0x0086 | KEY_OPEN | | | | | +| 0x07 0x0075 | Keyboard Help | 0x008a | KEY_HELP | | | | | +| 0x07 0x0076 | Keyboard Menu | 0x0082 | KEY_PROPS | | | | | +| 0x07 0x0077 | Keyboard Select | 0x0084 | KEY_FRONT | | | | | +| 0x07 0x0078 | Keyboard Stop | 0x0080 | KEY_STOP | 3.0 | 0x0056 | KEYCODE_MEDIA_STOP | | +| 0x07 0x0079 | Keyboard Again | 0x0081 | KEY_AGAIN | | | | | +| 0x07 0x007a | Keyboard Undo | 0x0083 | KEY_UNDO | | | | | +| 0x07 0x007b | Keyboard Cut | 0x0089 | KEY_CUT | | | | | +| 0x07 0x007c | Keyboard Copy | 0x0085 | KEY_COPY | | | | | +| 0x07 0x007d | Keyboard Paste | 0x0087 | KEY_PASTE | | | | | +| 0x07 0x007e | Keyboard Find | 0x0088 | KEY_FIND | | | | | +| 0x07 0x007f | Keyboard Mute | 0x0071 | KEY_MUTE | 3.0 | 0x00a4 | KEYCODE_VOLUME_MUTE | | +| 0x07 0x0080 | Keyboard Volume Up | 0x0073 | KEY_VOLUMEUP | 1.6 | 0x0018 | KEYCODE_VOLUME_UP | | +| 0x07 0x0081 | Keyboard Volume Down | 0x0072 | KEY_VOLUMEDOWN | 1.6 | 0x0019 | KEYCODE_VOLUME_DOWN | | +| 0x07 0x0082 | Keyboard Locking Caps Lock | | | | | | | +| 0x07 0x0083 | Keyboard Locking Num Lock | | | | | | | +| 0x07 0x0084 | Keyboard Locking Scroll Lock | | | | | | | +| 0x07 0x0085 | Keypad Comma | 0x0079 | KEY_KPCOMMA | 3.0 | 0x009f | KEYCODE_NUMPAD_COMMA | | +| 0x07 0x0086 | Keypad Equal Sign | | | | | | | +| 0x07 0x0087 | Keyboard International1 | 0x0059 | KEY_RO | | | | | +| 0x07 0x0088 | Keyboard International2 | 0x005d | KEY_KATAKANAHIRAGANA | | | | | +| 0x07 0x0089 | Keyboard International3 | 0x007c | KEY_YEN | | | | | +| 0x07 0x008a | Keyboard International4 | 0x005c | KEY_HENKAN | | | | | +| 0x07 0x008b | Keyboard International5 | 0x005e | KEY_MUHENKAN | | | | | +| 0x07 0x008c | Keyboard International6 | 0x005f | KEY_KPJPCOMMA | | | | | +| 0x07 0x008d | Keyboard International7 | | | | | | | +| 0x07 0x008e | Keyboard International8 | | | | | | | +| 0x07 0x008f | Keyboard International9 | | | | | | | +| 0x07 0x0090 | Keyboard LANG1 | 0x007a | KEY_HANGEUL | | | | | +| 0x07 0x0091 | Keyboard LANG2 | 0x007b | KEY_HANJA | | | | | +| 0x07 0x0092 | Keyboard LANG3 | 0x005a | KEY_KATAKANA | | | | | +| 0x07 0x0093 | Keyboard LANG4 | 0x005b | KEY_HIRAGANA | | | | | +| 0x07 0x0094 | Keyboard LANG5 | 0x0055 | KEY_ZENKAKUHANKAKU | | | | | +| 0x07 0x0095 | Keyboard LANG6 | | | | | | | +| 0x07 0x0096 | Keyboard LANG7 | | | | | | | +| 0x07 0x0097 | Keyboard LANG8 | | | | | | | +| 0x07 0x0098 | Keyboard LANG9 | | | | | | | +| 0x07 0x0099 | Keyboard Alternate Erase | | | | | | | +| 0x07 0x009a | Keyboard SysReq/Attention | | | | | | | +| 0x07 0x009b | Keyboard Cancel | | | | | | | +| 0x07 0x009c | Keyboard Clear | | | | | | | +| 0x07 0x009d | Keyboard Prior | | | | | | | +| 0x07 0x009e | Keyboard Return | | | | | | | +| 0x07 0x009f | Keyboard Separator | | | | | | | +| 0x07 0x00a0 | Keyboard Out | | | | | | | +| 0x07 0x00a1 | Keyboard Oper | | | | | | | +| 0x07 0x00a2 | Keyboard Clear/Again | | | | | | | +| 0x07 0x00a3 | Keyboard CrSel/Props | | | | | | | +| 0x07 0x00a4 | Keyboard ExSel | | | | | | | +| 0x07 0x00b0 | Keypad 00 | | | | | | | +| 0x07 0x00b1 | Keypad 000 | | | | | | | +| 0x07 0x00b2 | Thousands Separator | | | | | | | +| 0x07 0x00b3 | Decimal Separator | | | | | | | +| 0x07 0x00b4 | Currency Unit | | | | | | | +| 0x07 0x00b5 | Currency Sub-unit | | | | | | | +| 0x07 0x00b6 | Keypad ( | 0x00b3 | KEY_KPLEFTPAREN | 3.0 | 0x00a2 | KEYCODE_NUMPAD_LEFT_PAREN | | +| 0x07 0x00b7 | Keypad ) | 0x00b4 | KEY_KPRIGHTPAREN | 3.0 | 0x00a3 | KEYCODE_NUMPAD_RIGHT_PAREN | | +| 0x07 0x00b8 | Keypad \{ | | | | | | | +| 0x07 0x00b9 | Keypad \} | | | | | | | +| 0x07 0x00ba | Keypad Tab | | | | | | | +| 0x07 0x00bb | Keypad Backspace | | | | | | | +| 0x07 0x00bc | Keypad A | | | | | | | +| 0x07 0x00bd | Keypad B | | | | | | | +| 0x07 0x00be | Keypad C | | | | | | | +| 0x07 0x00bf | Keypad D | | | | | | | +| 0x07 0x00c0 | Keypad E | | | | | | | +| 0x07 0x00c1 | Keypad F | | | | | | | +| 0x07 0x00c2 | Keypad XOR | | | | | | | +| 0x07 0x00c3 | Keypad ^ | | | | | | | +| 0x07 0x00c4 | Keypad % | | | | | | | +| 0x07 0x00c5 | Keypad < | | | | | | | +| 0x07 0x00c6 | Keypad > | | | | | | | +| 0x07 0x00c7 | Keypad & | | | | | | | +| 0x07 0x00c8 | Keypad && | | | | | | | +| 0x07 0x00c9 | Keypad | | | | | | | | +| 0x07 0x00ca | Keypad || | | | | | | | +| 0x07 0x00cb | Keypad : | | | | | | | +| 0x07 0x00cc | Keypad # | | | | | | | +| 0x07 0x00cd | Keypad Space | | | | | | | +| 0x07 0x00ce | Keypad @ | | | | | | | +| 0x07 0x00cf | Keypad ! | | | | | | | +| 0x07 0x00d0 | Keypad Memory Store | | | | | | | +| 0x07 0x00d1 | Keypad Memory Recall | | | | | | | +| 0x07 0x00d2 | Keypad Memory Clear | | | | | | | +| 0x07 0x00d3 | Keypad Memory Add | | | | | | | +| 0x07 0x00d4 | Keypad Memory Subtract | | | | | | | +| 0x07 0x00d5 | Keypad Memory Multiply | | | | | | | +| 0x07 0x00d6 | Keypad Memory Divide | | | | | | | +| 0x07 0x00d7 | Keypad +/- | | | | | | | +| 0x07 0x00d8 | Keypad Clear | | | | | | | +| 0x07 0x00d9 | Keypad Clear Entry | | | | | | | +| 0x07 0x00da | Keypad Binary | | | | | | | +| 0x07 0x00db | Keypad Octal | | | | | | | +| 0x07 0x00dc | Keypad Decimal | | | | | | | +| 0x07 0x00dd | Keypad Hexadecimal | | | | | | | +| 0x07 0x00e0 | Keyboard Left Control | 0x001d | KEY_LEFTCTRL | 3.0 | 0x0071 | KEYCODE_CTRL_LEFT | | +| 0x07 0x00e1 | Keyboard Left Shift | 0x002a | KEY_LEFTSHIFT | 1.6 | 0x003b | KEYCODE_SHIFT_LEFT | | +| 0x07 0x00e2 | Keyboard Left Alt | 0x0038 | KEY_LEFTALT | 1.6 | 0x0039 | KEYCODE_ALT_LEFT | | +| 0x07 0x00e3 | Keyboard Left GUI | 0x007d | KEY_LEFTMETA | 3.0 | 0x0075 | KEYCODE_META_LEFT | | +| 0x07 0x00e4 | Keyboard Right Control | 0x0061 | KEY_RIGHTCTRL | 3.0 | 0x0072 | KEYCODE_CTRL_RIGHT | | +| 0x07 0x00e5 | Keyboard Right Shift | 0x0036 | KEY_RIGHTSHIFT | 1.6 | 0x003c | KEYCODE_SHIFT_RIGHT | | +| 0x07 0x00e6 | Keyboard Right Alt | 0x0064 | KEY_RIGHTALT | 1.6 | 0x003a | KEYCODE_ALT_RIGHT | | +| 0x07 0x00e7 | Keyboard Right GUI | 0x007e | KEY_RIGHTMETA | 3.0 | 0x0076 | KEYCODE_META_RIGHT | | +| 0x07 0x00e8 | | 0x00a4 | KEY_PLAYPAUSE | 3.0 | 0x0055 | KEYCODE_MEDIA_PLAY_PAUSE | | +| 0x07 0x00e9 | | 0x00a6 | KEY_STOPCD | 3.0 | 0x0056 | KEYCODE_MEDIA_STOP | | +| 0x07 0x00ea | | 0x00a5 | KEY_PREVIOUSSONG | 3.0 | 0x0058 | KEYCODE_MEDIA_PREVIOUS | | +| 0x07 0x00eb | | 0x00a3 | KEY_NEXTSONG | 3.0 | 0x0057 | KEYCODE_MEDIA_NEXT | | +| 0x07 0x00ec | | 0x00a1 | KEY_EJECTCD | 3.0 | 0x0081 | KEYCODE_MEDIA_EJECT | | +| 0x07 0x00ed | | 0x0073 | KEY_VOLUMEUP | 1.6 | 0x0018 | KEYCODE_VOLUME_UP | | +| 0x07 0x00ee | | 0x0072 | KEY_VOLUMEDOWN | 1.6 | 0x0019 | KEYCODE_VOLUME_DOWN | | +| 0x07 0x00ef | | 0x0071 | KEY_MUTE | 3.0 | 0x00a4 | KEYCODE_VOLUME_MUTE | | +| 0x07 0x00f0 | | 0x0096 | KEY_WWW | 1.6 | 0x0040 | KEYCODE_EXPLORER | | +| 0x07 0x00f1 | | 0x009e | KEY_BACK | 1.6 | 0x0004 | KEYCODE_BACK | | +| 0x07 0x00f2 | | 0x009f | KEY_FORWARD | 3.0 | 0x007d | KEYCODE_FORWARD | | +| 0x07 0x00f3 | | 0x0080 | KEY_STOP | 3.0 | 0x0056 | KEYCODE_MEDIA_STOP | | +| 0x07 0x00f4 | | 0x0088 | KEY_FIND | | | | | +| 0x07 0x00f5 | | 0x00b1 | KEY_SCROLLUP | 3.0 | 0x005c | KEYCODE_PAGE_UP | | +| 0x07 0x00f6 | | 0x00b2 | KEY_SCROLLDOWN | 3.0 | 0x005d | KEYCODE_PAGE_DOWN | | +| 0x07 0x00f7 | | 0x00b0 | KEY_EDIT | | | | | +| 0x07 0x00f8 | | 0x008e | KEY_SLEEP | | | | | +| 0x07 0x00f9 | | 0x0098 | KEY_COFFEE | 4.0 | 0x001a | KEYCODE_POWER | | +| 0x07 0x00fa | | 0x00ad | KEY_REFRESH | | | | | +| 0x07 0x00fb | | 0x008c | KEY_CALC | | | | | + +### HID Generic Desktop Page (0x01) ### + +| HID Usage | HID Usage Name | LKC | Linux Key Code Name | Version | AKC | Android Key Code Name | Notes | +| ----------- | -------------------------------- | ------ | -------------------------------- | ------- | ------ | -------------------------------- | ----- | +| 0x01 0x0081 | System Power Down | 0x0074 | KEY_POWER | 1.6 | 0x001a | KEYCODE_POWER | | +| 0x01 0x0082 | System Sleep | 0x008e | KEY_SLEEP | 4.0 | 0x001a | KEYCODE_POWER | | +| 0x01 0x0083 | System Wake Up | 0x008f | KEY_WAKEUP | 4.0 | 0x001a | KEYCODE_POWER | | +| 0x01 0x0084 | System Context Menu | | | | | | | +| 0x01 0x0085 | System Main Menu | | | | | | | +| 0x01 0x0086 | System App Menu | | | | | | | +| 0x01 0x0087 | System Menu Help | | | | | | | +| 0x01 0x0088 | System Menu Exit | | | | | | | +| 0x01 0x0089 | System Menu Select | | | | | | | +| 0x01 0x008a | System Menu Right | | | | | | | +| 0x01 0x008b | System Menu Left | | | | | | | +| 0x01 0x008c | System Menu Up | | | | | | | +| 0x01 0x008d | System Menu Down | | | | | | | +| 0x01 0x008e | System Cold Restart | | | | | | | +| 0x01 0x008f | System Warm Restart | | | | | | | +| 0x01 0x00a0 | System Dock | | | | | | | +| 0x01 0x00a1 | System Undock | | | | | | | +| 0x01 0x00a2 | System Setup | | | | | | | +| 0x01 0x00a3 | System Break | | | | | | | +| 0x01 0x00a4 | System Debugger Break | | | | | | | +| 0x01 0x00a5 | Application Break | | | | | | | +| 0x01 0x00a6 | Application Debugger Break | | | | | | | +| 0x01 0x00a7 | System Speaker Mute | | | | | | | +| 0x01 0x00a8 | System Hibernate | | | | | | | +| 0x01 0x00b0 | System Display Invert | | | | | | | +| 0x01 0x00b1 | System Display Internal | | | | | | | +| 0x01 0x00b2 | System Display External | | | | | | | +| 0x01 0x00b3 | System Display Both | | | | | | | +| 0x01 0x00b4 | System Display Dual | | | | | | | +| 0x01 0x00b5 | System Display Toggle Int/Ext | | | | | | | +| 0x01 0x00b6 | System Display Swap Prim./Sec. | | | | | | | +| 0x01 0x00b7 | System Display LCD Autoscale | | | | | | | + +### HID Consumer Page (0x0c) ### + +| HID Usage | HID Usage Name | LKC | Linux Key Code Name | Version | AKC | Android Key Code Name | Notes | +| ----------- | -------------------------------- | ------ | -------------------------------- | ------- | ------ | -------------------------------- | ----- | +| 0x0c 0x0030 | Power | | | | | | | +| 0x0c 0x0031 | Reset | | | | | | | +| 0x0c 0x0032 | Sleep | | | | | | | +| 0x0c 0x0033 | Sleep After | | | | | | | +| 0x0c 0x0034 | Sleep Mode | 0x008e | KEY_SLEEP | 4.0 | 0x001a | KEYCODE_POWER | | +| 0x0c 0x0040 | Menu | 0x008b | KEY_MENU | 1.6 | 0x0052 | KEYCODE_MENU | | +| 0x0c 0x0041 | Menu Pick | | | | | | | +| 0x0c 0x0042 | Menu Up | | | | | | | +| 0x0c 0x0043 | Menu Down | | | | | | | +| 0x0c 0x0044 | Menu Left | | | | | | | +| 0x0c 0x0045 | Menu Right | 0x0181 | KEY_RADIO | | | | | +| 0x0c 0x0046 | Menu Escape | | | | | | | +| 0x0c 0x0047 | Menu Value Increase | | | | | | | +| 0x0c 0x0048 | Menu Value Decrease | | | | | | | +| 0x0c 0x0081 | Assign Selection | | | | | | | +| 0x0c 0x0082 | Mode Step | | | | | | | +| 0x0c 0x0083 | Recall Last | 0x0195 | KEY_LAST | | | | | +| 0x0c 0x0084 | Enter Channel | | | | | | | +| 0x0c 0x0085 | Order Movie | | | | | | | +| 0x0c 0x0088 | Media Select Computer | 0x0178 | KEY_PC | | | | | +| 0x0c 0x0089 | Media Select TV | 0x0179 | KEY_TV | 3.0 | 0x00aa | KEYCODE_TV | | +| 0x0c 0x008a | Media Select WWW | 0x0096 | KEY_WWW | 1.6 | 0x0040 | KEYCODE_EXPLORER | | +| 0x0c 0x008b | Media Select DVD | 0x0185 | KEY_DVD | | | | | +| 0x0c 0x008c | Media Select Telephone | 0x00a9 | KEY_PHONE | 3.0 | 0x0005 | KEYCODE_CALL | | +| 0x0c 0x008d | Media Select Program Guide | 0x016a | KEY_PROGRAM | 3.0 | 0x00ac | KEYCODE_GUIDE | | +| 0x0c 0x008e | Media Select Video Phone | 0x01a0 | KEY_VIDEOPHONE | | | | | +| 0x0c 0x008f | Media Select Games | 0x01a1 | KEY_GAMES | | | | | +| 0x0c 0x0090 | Media Select Messages | 0x018c | KEY_MEMO | | | | | +| 0x0c 0x0091 | Media Select CD | 0x017f | KEY_CD | | | | | +| 0x0c 0x0092 | Media Select VCR | 0x017b | KEY_VCR | | | | | +| 0x0c 0x0093 | Media Select Tuner | 0x0182 | KEY_TUNER | | | | | +| 0x0c 0x0094 | Quit | 0x00ae | KEY_EXIT | | | | | +| 0x0c 0x0095 | Help | 0x008a | KEY_HELP | | | | | +| 0x0c 0x0096 | Media Select Tape | 0x0180 | KEY_TAPE | | | | | +| 0x0c 0x0097 | Media Select Cable | 0x017a | KEY_TV2 | | | | | +| 0x0c 0x0098 | Media Select Satellite | 0x017d | KEY_SAT | | | | | +| 0x0c 0x0099 | Media Select Security | | | | | | | +| 0x0c 0x009a | Media Select Home | 0x016e | KEY_PVR | 3.0 | 0x00ad | KEYCODE_DVR | | +| 0x0c 0x009c | Channel Increment | 0x0192 | KEY_CHANNELUP | 3.0 | 0x00a6 | KEYCODE_CHANNEL_UP | | +| 0x0c 0x009d | Channel Decrement | 0x0193 | KEY_CHANNELDOWN | 3.0 | 0x00a7 | KEYCODE_CHANNEL_DOWN | | +| 0x0c 0x009e | Media Select SAP | | | | | | | +| 0x0c 0x00a0 | VCR Plus | 0x017c | KEY_VCR2 | | | | | +| 0x0c 0x00a1 | Once | | | | | | | +| 0x0c 0x00a2 | Daily | | | | | | | +| 0x0c 0x00a3 | Weekly | | | | | | | +| 0x0c 0x00a4 | Monthly | | | | | | | +| 0x0c 0x00b0 | Play | 0x00cf | KEY_PLAY | 3.0 | 0x007e | KEYCODE_MEDIA_PLAY | | +| 0x0c 0x00b1 | Pause | 0x0077 | KEY_PAUSE | 3.0 | 0x0079 | KEYCODE_BREAK | | +| 0x0c 0x00b2 | Record | 0x00a7 | KEY_RECORD | 3.0 | 0x0082 | KEYCODE_MEDIA_RECORD | | +| 0x0c 0x00b3 | Fast Forward | 0x00d0 | KEY_FASTFORWARD | 3.0 | 0x005a | KEYCODE_MEDIA_FAST_FORWARD | | +| 0x0c 0x00b4 | Rewind | 0x00a8 | KEY_REWIND | 3.0 | 0x0059 | KEYCODE_MEDIA_REWIND | | +| 0x0c 0x00b5 | Scan Next Track | 0x00a3 | KEY_NEXTSONG | 3.0 | 0x0057 | KEYCODE_MEDIA_NEXT | | +| 0x0c 0x00b6 | Scan Previous Track | 0x00a5 | KEY_PREVIOUSSONG | 3.0 | 0x0058 | KEYCODE_MEDIA_PREVIOUS | | +| 0x0c 0x00b7 | Stop | 0x00a6 | KEY_STOPCD | 3.0 | 0x0056 | KEYCODE_MEDIA_STOP | | +| 0x0c 0x00b8 | Eject | 0x00a1 | KEY_EJECTCD | 3.0 | 0x0081 | KEYCODE_MEDIA_EJECT | | +| 0x0c 0x00b9 | Random Play | | | | | | | +| 0x0c 0x00ba | Select Disc | | | | | | | +| 0x0c 0x00bb | Enter Disc | | | | | | | +| 0x0c 0x00bc | Repeat | 0x01b7 | KEY_MEDIA_REPEAT | | | | | +| 0x0c 0x00be | Track Normal | | | | | | | +| 0x0c 0x00c0 | Frame Forward | | | | | | | +| 0x0c 0x00c1 | Frame Back | | | | | | | +| 0x0c 0x00c2 | Mark | | | | | | | +| 0x0c 0x00c3 | Clear Mark | | | | | | | +| 0x0c 0x00c4 | Repeat From Mark | | | | | | | +| 0x0c 0x00c5 | Return To Mark | | | | | | | +| 0x0c 0x00c6 | Search Mark Forward | | | | | | | +| 0x0c 0x00c7 | Search Mark Backwards | | | | | | | +| 0x0c 0x00c8 | Counter Reset | | | | | | | +| 0x0c 0x00c9 | Show Counter | | | | | | | +| 0x0c 0x00ca | Tracking Increment | | | | | | | +| 0x0c 0x00cb | Tracking Decrement | | | | | | | +| 0x0c 0x00cc | Stop / Eject | | | | | | | +| 0x0c 0x00cd | Play / Pause | 0x00a4 | KEY_PLAYPAUSE | 3.0 | 0x0055 | KEYCODE_MEDIA_PLAY_PAUSE | | +| 0x0c 0x00ce | Play / Skip | | | | | | | +| 0x0c 0x00e2 | Mute | 0x0071 | KEY_MUTE | 3.0 | 0x00a4 | KEYCODE_VOLUME_MUTE | | +| 0x0c 0x00e5 | Bass Boost | 0x00d1 | KEY_BASSBOOST | | | | | +| 0x0c 0x00e6 | Surround Mode | | | | | | | +| 0x0c 0x00e7 | Loudness | | | | | | | +| 0x0c 0x00e8 | MPX | | | | | | | +| 0x0c 0x00e9 | Volume Increment | 0x0073 | KEY_VOLUMEUP | 1.6 | 0x0018 | KEYCODE_VOLUME_UP | | +| 0x0c 0x00ea | Volume Decrement | 0x0072 | KEY_VOLUMEDOWN | 1.6 | 0x0019 | KEYCODE_VOLUME_DOWN | | +| 0x0c 0x0181 | AL Launch Button Config. Tool | | | | | | | +| 0x0c 0x0182 | AL Programmable Button Config. | 0x009c | KEY_BOOKMARKS | 3.0 | 0x00ae | KEYCODE_BOOKMARK | | +| 0x0c 0x0183 | AL Consumer Control Config. | 0x00ab | KEY_CONFIG | | | | | +| 0x0c 0x0184 | AL Word Processor | 0x01a5 | KEY_WORDPROCESSOR | | | | | +| 0x0c 0x0185 | AL Text Editor | 0x01a6 | KEY_EDITOR | | | | | +| 0x0c 0x0186 | AL Spreadsheet | 0x01a7 | KEY_SPREADSHEET | | | | | +| 0x0c 0x0187 | AL Graphics Editor | 0x01a8 | KEY_GRAPHICSEDITOR | | | | | +| 0x0c 0x0188 | AL Presentation App | 0x01a9 | KEY_PRESENTATION | | | | | +| 0x0c 0x0189 | AL Database App | 0x01aa | KEY_DATABASE | | | | | +| 0x0c 0x018a | AL Email Reader | 0x009b | KEY_MAIL | 1.6 | 0x0041 | KEYCODE_ENVELOPE | | +| 0x0c 0x018b | AL Newsreader | 0x01ab | KEY_NEWS | | | | | +| 0x0c 0x018c | AL Voicemail | 0x01ac | KEY_VOICEMAIL | | | | | +| 0x0c 0x018d | AL Contacts / Address Book | 0x01ad | KEY_ADDRESSBOOK | | | | | +| 0x0c 0x018e | AL Calendar / Schedule | 0x018d | KEY_CALENDAR | | | | | +| 0x0c 0x018f | AL Task / Project Manager | | | | | | | +| 0x0c 0x0190 | AL Log / Journal / Timecard | | | | | | | +| 0x0c 0x0191 | AL Checkbook / Finance | 0x00db | KEY_FINANCE | | | | | +| 0x0c 0x0192 | AL Calculator | 0x008c | KEY_CALC | | | | | +| 0x0c 0x0193 | AL A/V Capture / Playback | | | | | | | +| 0x0c 0x0194 | AL Local Machine Browser | 0x0090 | KEY_FILE | | | | | +| 0x0c 0x0195 | AL LAN/WAN Browser | | | | | | | +| 0x0c 0x0196 | AL Internet Browser | 0x0096 | KEY_WWW | 1.6 | 0x0040 | KEYCODE_EXPLORER | | +| 0x0c 0x0197 | AL Remote Networking/ISP Connect | | | | | | | +| 0x0c 0x0198 | AL Network Conference | | | | | | | +| 0x0c 0x0199 | AL Network Chat | 0x00d8 | KEY_CHAT | | | | | +| 0x0c 0x019a | AL Telephony / Dialer | | | | | | | +| 0x0c 0x019b | AL Logon | | | | | | | +| 0x0c 0x019c | AL Logoff | 0x01b1 | KEY_LOGOFF | | | | | +| 0x0c 0x019d | AL Logon / Logoff | | | | | | | +| 0x0c 0x019e | AL Terminal Lock / Screensaver | 0x0098 | KEY_COFFEE | 4.0 | 0x001a | KEYCODE_POWER | | +| 0x0c 0x019f | AL Control Panel | | | | | | | +| 0x0c 0x01a0 | AL Command Line Processor / Run | | | | | | | +| 0x0c 0x01a1 | AL Process / Task Manager | | | | | | | +| 0x0c 0x01a2 | AL Select Task / Application | | | | | | | +| 0x0c 0x01a3 | AL Next Task / Application | | | | | | | +| 0x0c 0x01a4 | AL Previous Task / Application | | | | | | | +| 0x0c 0x01a5 | AL Preemptive Halt Task / App. | | | | | | | +| 0x0c 0x01a6 | AL Integrated Help Center | 0x008a | KEY_HELP | | | | | +| 0x0c 0x01a7 | AL Documents | 0x00eb | KEY_DOCUMENTS | | | | | +| 0x0c 0x01a8 | AL Thesaurus | | | | | | | +| 0x0c 0x01a9 | AL Dictionary | | | | | | | +| 0x0c 0x01aa | AL Desktop | | | | | | | +| 0x0c 0x01ab | AL Spell Check | 0x01b0 | KEY_SPELLCHECK | | | | | +| 0x0c 0x01ac | AL Grammar Check | | | | | | | +| 0x0c 0x01ad | AL Wireless Status | | | | | | | +| 0x0c 0x01ae | AL Keyboard Layout | | | | | | | +| 0x0c 0x01af | AL Virus Protection | | | | | | | +| 0x0c 0x01b0 | AL Encryption | | | | | | | +| 0x0c 0x01b1 | AL Screen Saver | | | | | | | +| 0x0c 0x01b2 | AL Alarms | | | | | | | +| 0x0c 0x01b3 | AL Clock | | | | | | | +| 0x0c 0x01b4 | AL File Browser | | | | | | | +| 0x0c 0x01b5 | AL Power Status | | | | | | | +| 0x0c 0x01b6 | AL Image Browser | 0x00e2 | KEY_MEDIA | | | | | +| 0x0c 0x01b7 | AL Audio Browser | 0x00d5 | KEY_SOUND | | | | | +| 0x0c 0x01b8 | AL Movie Browser | | | | | | | +| 0x0c 0x01b9 | AL Digital Rights Manager | | | | | | | +| 0x0c 0x01ba | AL Digital Wallet | | | | | | | +| 0x0c 0x01bc | AL Instant Messaging | 0x01ae | KEY_MESSENGER | | | | | +| 0x0c 0x01bd | AL OEM Features / Tips Browser | 0x0166 | KEY_INFO | | | | | +| 0x0c 0x01be | AL OEM Help | | | | | | | +| 0x0c 0x01bf | AL Online Community | | | | | | | +| 0x0c 0x01c0 | AL Entertainment Content Browser | | | | | | | +| 0x0c 0x01c1 | AL Online Shopping Browser | | | | | | | +| 0x0c 0x01c2 | AL SmartCard Information / Help | | | | | | | +| 0x0c 0x01c3 | AL Market / Finance Browser | | | | | | | +| 0x0c 0x01c4 | AL Customized Corp. News Browser | | | | | | | +| 0x0c 0x01c5 | AL Online Activity Browser | | | | | | | +| 0x0c 0x01c6 | AL Research / Search Browser | | | | | | | +| 0x0c 0x01c7 | AL Audio Player | | | | | | | +| 0x0c 0x0201 | AC New | 0x00b5 | KEY_NEW | | | | | +| 0x0c 0x0202 | AC Open | 0x0086 | KEY_OPEN | | | | | +| 0x0c 0x0203 | AC Close | 0x00ce | KEY_CLOSE | | | | | +| 0x0c 0x0204 | AC Exit | 0x00ae | KEY_EXIT | | | | | +| 0x0c 0x0205 | AC Maximize | | | | | | | +| 0x0c 0x0206 | AC Minimize | | | | | | | +| 0x0c 0x0207 | AC Save | 0x00ea | KEY_SAVE | | | | | +| 0x0c 0x0208 | AC Print | 0x00d2 | KEY_PRINT | | | | | +| 0x0c 0x0209 | AC Properties | 0x0082 | KEY_PROPS | | | | | +| 0x0c 0x021a | AC Undo | 0x0083 | KEY_UNDO | | | | | +| 0x0c 0x021b | AC Copy | 0x0085 | KEY_COPY | | | | | +| 0x0c 0x021c | AC Cut | 0x0089 | KEY_CUT | | | | | +| 0x0c 0x021d | AC Paste | 0x0087 | KEY_PASTE | | | | | +| 0x0c 0x021e | AC Select All | | | | | | | +| 0x0c 0x021f | AC Find | 0x0088 | KEY_FIND | | | | | +| 0x0c 0x0220 | AC Find and Replace | | | | | | | +| 0x0c 0x0221 | AC Search | 0x00d9 | KEY_SEARCH | 1.6 | 0x0054 | KEYCODE_SEARCH | | +| 0x0c 0x0222 | AC Go To | 0x0162 | KEY_GOTO | | | | | +| 0x0c 0x0223 | AC Home | 0x00ac | KEY_HOMEPAGE | 3.0 | 0x0003 | KEYCODE_HOME | | +| 0x0c 0x0224 | AC Back | 0x009e | KEY_BACK | 1.6 | 0x0004 | KEYCODE_BACK | | +| 0x0c 0x0225 | AC Forward | 0x009f | KEY_FORWARD | 3.0 | 0x007d | KEYCODE_FORWARD | | +| 0x0c 0x0226 | AC Stop | 0x0080 | KEY_STOP | 3.0 | 0x0056 | KEYCODE_MEDIA_STOP | | +| 0x0c 0x0227 | AC Refresh | 0x00ad | KEY_REFRESH | | | | | +| 0x0c 0x0228 | AC Previous Link | | | | | | | +| 0x0c 0x0229 | AC Next Link | | | | | | | +| 0x0c 0x022a | AC Bookmarks | 0x009c | KEY_BOOKMARKS | 3.0 | 0x00ae | KEYCODE_BOOKMARK | | +| 0x0c 0x022b | AC History | | | | | | | +| 0x0c 0x022c | AC Subscriptions | | | | | | | +| 0x0c 0x022d | AC Zoom In | 0x01a2 | KEY_ZOOMIN | | | | | +| 0x0c 0x022e | AC Zoom Out | 0x01a3 | KEY_ZOOMOUT | | | | | +| 0x0c 0x022f | AC Zoom | 0x01a4 | KEY_ZOOMRESET | | | | 2 | +| 0x0c 0x0230 | AC Full Screen View | | | | | | | +| 0x0c 0x0231 | AC Normal View | | | | | | | +| 0x0c 0x0232 | AC View Toggle | | | | | | | +| 0x0c 0x0233 | AC Scroll Up | 0x00b1 | KEY_SCROLLUP | 3.0 | 0x005c | KEYCODE_PAGE_UP | | +| 0x0c 0x0234 | AC Scroll Down | 0x00b2 | KEY_SCROLLDOWN | 3.0 | 0x005d | KEYCODE_PAGE_DOWN | | +| 0x0c 0x0236 | AC Pan Left | | | | | | | +| 0x0c 0x0237 | AC Pan Right | | | | | | | +| 0x0c 0x0239 | AC New Window | | | | | | | +| 0x0c 0x023a | AC Tile Horizontally | | | | | | | +| 0x0c 0x023b | AC Tile Vertically | | | | | | | +| 0x0c 0x023c | AC Format | | | | | | | +| 0x0c 0x023d | AC Edit | | | | | | | +| 0x0c 0x023e | AC Bold | | | | | | | +| 0x0c 0x023f | AC Italics | | | | | | | +| 0x0c 0x0240 | AC Underline | | | | | | | +| 0x0c 0x0241 | AC Strikethrough | | | | | | | +| 0x0c 0x0242 | AC Subscript | | | | | | | +| 0x0c 0x0243 | AC Superscript | | | | | | | +| 0x0c 0x0244 | AC All Caps | | | | | | | +| 0x0c 0x0245 | AC Rotate | | | | | | | +| 0x0c 0x0246 | AC Resize | | | | | | | +| 0x0c 0x0247 | AC Flip horizontal | | | | | | | +| 0x0c 0x0248 | AC Flip Vertical | | | | | | | +| 0x0c 0x0249 | AC Mirror Horizontal | | | | | | | +| 0x0c 0x024a | AC Mirror Vertical | | | | | | | +| 0x0c 0x024b | AC Font Select | | | | | | | +| 0x0c 0x024c | AC Font Color | | | | | | | +| 0x0c 0x024d | AC Font Size | | | | | | | +| 0x0c 0x024e | AC Justify Left | | | | | | | +| 0x0c 0x024f | AC Justify Center H | | | | | | | +| 0x0c 0x0250 | AC Justify Right | | | | | | | +| 0x0c 0x0251 | AC Justify Block H | | | | | | | +| 0x0c 0x0252 | AC Justify Top | | | | | | | +| 0x0c 0x0253 | AC Justify Center V | | | | | | | +| 0x0c 0x0254 | AC Justify Bottom | | | | | | | +| 0x0c 0x0255 | AC Justify Block V | | | | | | | +| 0x0c 0x0256 | AC Indent Decrease | | | | | | | +| 0x0c 0x0257 | AC Indent Increase | | | | | | | +| 0x0c 0x0258 | AC Numbered List | | | | | | | +| 0x0c 0x0259 | AC Restart Numbering | | | | | | | +| 0x0c 0x025a | AC Bulleted List | | | | | | | +| 0x0c 0x025b | AC Promote | | | | | | | +| 0x0c 0x025c | AC Demote | | | | | | | +| 0x0c 0x025d | AC Yes | | | | | | | +| 0x0c 0x025e | AC No | | | | | | | +| 0x0c 0x025f | AC Cancel | 0x00df | KEY_CANCEL | | | | | +| 0x0c 0x0260 | AC Catalog | | | | | | | +| 0x0c 0x0261 | AC Buy / Checkout | | | | | | | +| 0x0c 0x0262 | AC Add to Cart | | | | | | | +| 0x0c 0x0263 | AC Expand | | | | | | | +| 0x0c 0x0264 | AC Expand All | | | | | | | +| 0x0c 0x0265 | AC Collapse | | | | | | | +| 0x0c 0x0266 | AC Collapse All | | | | | | | +| 0x0c 0x0267 | AC Print Preview | | | | | | | +| 0x0c 0x0268 | AC Paste Special | | | | | | | +| 0x0c 0x0269 | AC Insert Mode | | | | | | | +| 0x0c 0x026a | AC Delete | | | | | | | +| 0x0c 0x026b | AC Lock | | | | | | | +| 0x0c 0x026c | AC Unlock | | | | | | | +| 0x0c 0x026d | AC Protect | | | | | | | +| 0x0c 0x026e | AC Unprotect | | | | | | | +| 0x0c 0x026f | AC Attach Comment | | | | | | | +| 0x0c 0x0270 | AC Delete Comment | | | | | | | +| 0x0c 0x0271 | AC View Comment | | | | | | | +| 0x0c 0x0272 | AC Select Word | | | | | | | +| 0x0c 0x0273 | AC Select Sentence | | | | | | | +| 0x0c 0x0274 | AC Select Paragraph | | | | | | | +| 0x0c 0x0275 | AC Select Column | | | | | | | +| 0x0c 0x0276 | AC Select Row | | | | | | | +| 0x0c 0x0277 | AC Select Table | | | | | | | +| 0x0c 0x0278 | AC Select Object | | | | | | | +| 0x0c 0x0279 | AC Redo / Repeat | 0x00b6 | KEY_REDO | | | | | +| 0x0c 0x027a | AC Sort | | | | | | | +| 0x0c 0x027b | AC Sort Ascending | | | | | | | +| 0x0c 0x027c | AC Sort Descending | | | | | | | +| 0x0c 0x027d | AC Filter | | | | | | | +| 0x0c 0x027e | AC Set Clock | | | | | | | +| 0x0c 0x027f | AC View Clock | | | | | | | +| 0x0c 0x0280 | AC Select Time Zone | | | | | | | +| 0x0c 0x0281 | AC Edit Time Zones | | | | | | | +| 0x0c 0x0282 | AC Set Alarm | | | | | | | +| 0x0c 0x0283 | AC Clear Alarm | | | | | | | +| 0x0c 0x0284 | AC Snooze Alarm | | | | | | | +| 0x0c 0x0285 | AC Reset Alarm | | | | | | | +| 0x0c 0x0286 | AC Synchronize | | | | | | | +| 0x0c 0x0287 | AC Send/Receive | | | | | | | +| 0x0c 0x0288 | AC Send To | | | | | | | +| 0x0c 0x0289 | AC Reply | 0x00e8 | KEY_REPLY | | | | | +| 0x0c 0x028a | AC Reply All | | | | | | | +| 0x0c 0x028b | AC Forward Msg | 0x00e9 | KEY_FORWARDMAIL | | | | | +| 0x0c 0x028c | AC Send | 0x00e7 | KEY_SEND | | | | | +| 0x0c 0x028d | AC Attach File | | | | | | | +| 0x0c 0x028e | AC Upload | | | | | | | +| 0x0c 0x028f | AC Download (Save Target As) | | | | | | | +| 0x0c 0x0290 | AC Set Borders | | | | | | | +| 0x0c 0x0291 | AC Insert Row | | | | | | | +| 0x0c 0x0292 | AC Insert Column | | | | | | | +| 0x0c 0x0293 | AC Insert File | | | | | | | +| 0x0c 0x0294 | AC Insert Picture | | | | | | | +| 0x0c 0x0295 | AC Insert Object | | | | | | | +| 0x0c 0x0296 | AC Insert Symbol | | | | | | | +| 0x0c 0x0297 | AC Save and Close | | | | | | | +| 0x0c 0x0298 | AC Rename | | | | | | | +| 0x0c 0x0299 | AC Merge | | | | | | | +| 0x0c 0x029a | AC Split | | | | | | | +| 0x0c 0x029b | AC Distribute Horizontally | | | | | | | +| 0x0c 0x029c | AC Distribute Vertically | | | | | | | + +### Additional non-HID Mappings ### + +These mappings describe functions that do not appear in HID but for which Linux +key codes exist. + +| LKC | Linux Key Code Name | Version | AKC | Android Key Code Name | Notes | +| ------ | -------------------------------- | ------- | ------ | -------------------------------- | ----- | +| 0x01d0 | KEY_FN | 3.0 | 0x0077 | KEYCODE_FUNCTION | | +| 0x01d1 | KEY_FN_ESC | 3.0 | 0x006f | KEYCODE_ESCAPE | 3 | +| 0x01d2 | KEY_FN_F1 | 3.0 | 0x0083 | KEYCODE_F1 | 3 | +| 0x01d3 | KEY_FN_F2 | 3.0 | 0x0084 | KEYCODE_F2 | 3 | +| 0x01d4 | KEY_FN_F3 | 3.0 | 0x0085 | KEYCODE_F3 | 3 | +| 0x01d5 | KEY_FN_F4 | 3.0 | 0x0086 | KEYCODE_F4 | 3 | +| 0x01d6 | KEY_FN_F5 | 3.0 | 0x0087 | KEYCODE_F5 | 3 | +| 0x01d7 | KEY_FN_F6 | 3.0 | 0x0088 | KEYCODE_F6 | 3 | +| 0x01d8 | KEY_FN_F7 | 3.0 | 0x0089 | KEYCODE_F7 | 3 | +| 0x01d9 | KEY_FN_F8 | 3.0 | 0x008a | KEYCODE_F8 | 3 | +| 0x01da | KEY_FN_F9 | 3.0 | 0x008b | KEYCODE_F9 | 3 | +| 0x01db | KEY_FN_F10 | 3.0 | 0x008c | KEYCODE_F10 | 3 | +| 0x01dc | KEY_FN_F11 | 3.0 | 0x008d | KEYCODE_F11 | 3 | +| 0x01dd | KEY_FN_F12 | 3.0 | 0x008e | KEYCODE_F12 | 3 | +| 0x01de | KEY_FN_1 | 3.0 | 0x0008 | KEYCODE_1 | 3 | +| 0x01df | KEY_FN_2 | 3.0 | 0x0009 | KEYCODE_2 | 3 | +| 0x01e0 | KEY_FN_D | 3.0 | 0x0020 | KEYCODE_D | 3 | +| 0x01e1 | KEY_FN_E | 3.0 | 0x0021 | KEYCODE_E | 3 | +| 0x01e2 | KEY_FN_F | 3.0 | 0x0022 | KEYCODE_F | 3 | +| 0x01e3 | KEY_FN_S | 3.0 | 0x002f | KEYCODE_S | 3 | +| 0x01e4 | KEY_FN_B | 3.0 | 0x001e | KEYCODE_B | 3 | + +### Legacy Unsupported Keys ### + +These mappings appeared in previous versions of Android but were inconsistent with +HID or used non-standard Linux key codes. They are no longer supported. + +| LKC | Linux Key Code Name | Version | AKC | Android Key Code Name | Notes | +| ------ | -------------------------------- | ------- | ------ | -------------------------------- | ----- | +| 0x00db | KEY_EMAIL | 1.6 | 0x004d | KEYCODE_AT | 4 | +| "" | "" | 4.0 | | | 4 | +| 0x00e3 | KEY_STAR | 1.6 | 0x0011 | KEYCODE_STAR | 4 | +| "" | "" | 4.0 | | | 4 | +| 0x00e4 | KEY_SHARP | 1.6 | 0x0012 | KEYCODE_POUND | 4 | +| "" | "" | 4.0 | | | 4 | +| 0x00e5 | KEY_SOFT1 | 1.6 | 0x0052 | KEYCODE_MENU | 4 | +| "" | "" | 4.0 | | | 4 | +| 0x00e6 | KEY_SOFT2 | 1.6 | 0x0002 | KEYCODE_SOFT_RIGHT | 4 | +| "" | "" | 4.0 | | | 4 | +| 0x00e7 | KEY_SEND | 1.6 | 0x0005 | KEYCODE_CALL | 4 | +| "" | "" | 4.0 | | | 4 | +| 0x00e8 | KEY_CENTER | 1.6 | 0x0017 | KEYCODE_DPAD_CENTER | 4 | +| "" | "" | 4.0 | | | 4 | +| 0x00e9 | KEY_HEADSETHOOK | 1.6 | 0x004f | KEYCODE_HEADSETHOOK | 4 | +| "" | "" | 4.0 | | | 4 | +| 0x00ea | KEY_0_5 | 1.6 | | | 4 | +| 0x00eb | KEY_2_5 | 1.6 | | | 4 | + +### Notes ### + +1. The Android key code associated with common alphanumeric and symbolic + keys may vary based on the keyboard layout and language. + For historical reasons, the physical scan codes and HID usages + associated with keys on a keyboard are often defined positionally + even though the labels printed on those keys may vary from one + language to another. + + On a US English (QWERTY) keyboard, the top-left alphabetic key is + labeled Q. On a French (AZERTY) keyboard, the key in the same + position is labeled A. Despite the label, on both keyboards the + top-left alphabetic key is referred to using the HID usage + 0x07 0x0014 which is mapped to the Linux key code KEY_Q. + + When Android is configured with a US English keyboard layout, then + the Linux key code KEY_Q will be mapped to the Android key code + KEYCODE_Q and will produce the characters 'Q' and 'q'. + However, when Android is configured with a French keyboard layout, + then the Linux key code KEY_Q will be mapped to the Android key code + KEYCODE_A and will produce the characters 'A' and 'a'. + + The Android key code typically reflects the language-specific + interpretation of the key, so a different Android key code may + be used for different languages. + +2. `0x0c 0x022f AC Zoom` is defined in the HID as a linear control but + the kernel maps it as a key, which is probably incorrect. + +3. The Linux function keys `KEY_FN_*` are mapped to simpler + key codes but are dispatched with the `META_FUNCTION` meta state + bit set to true. + +4. Prior to Android Ice Cream Sandwich 4.0, the default key layout + contained mappings for some extra key codes that were not defined + in the mainline Linux kernel headers. These mappings have since + been removed because these previously undefined key codes have + since been assigned different meanings in more recent versions + of the Linux kernel. + +### Sources ### + +1. [USB HID Usage Tables v1.12](http://www.usb.org/developers/devclass_docs/Hut1_12v2.pdf) +2. Linux 2.6.39 kernel: include/linux/input.h, drivers/hid/hid-input.c +3. Android ICS: qwerty.kl, Generic.kl, KeyEvent.java
diff --git a/src/tech/input/migration-guide.md b/src/tech/input/migration-guide.md new file mode 100644 index 0000000..e2aee60 --- /dev/null +++ b/src/tech/input/migration-guide.md
@@ -0,0 +1,71 @@ +<!-- + Copyright 2011 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. +--> + +# Migration Guide # + +This document contains a few helpful tips when migrating to new Android releases. + +## Migrating to Android Gingerbread 2.3 ## + +In Gingerbread, we added the concept of input device configuration files +(also referred to as input device calibration files in this release). + +Make sure to provide an input device configuration file for all touch screens. +In particular, it is worth spending time providing a calibration reference for +touch size information. + +## Migrating to Android Honeycomb 3.0 ## + +In Honeycomb, we revised the key character map file format and started making +greater use of input device configuration files. We also added support for full +PC-style keyboards and introduced a new "Generic" key map, which +replaced the older emulator-specific "qwerty" key map (which was never +intended to be used as a general-purpose key map.) + +Make sure to update all of your key character map files to use the new syntax. + +If your peripherals relied on the old "qwerty" key map, then you +may need to provide new device-specific key maps to emulate the old behavior. +You should create a new key map for each device identified either by +USB product id / vendor id or by device name. + +It is especially important to provide key character map files for all special +function input devices. These files should simple contain a line to set +the keyboard type to `SPECIAL_FUNCTION`. + +A good way to ensure that all built-in input devices are appropriately configured +is to run [Dumpsys](/tech/input/dumpsys.html) and look for devices that +are inappropriately using `Generic.kcm`. + +## Migrating to Android Honeycomb 3.2 ## + +In Honeycomb 3.2, we added support for joysticks and extended the key layout file +format to enable joystick axis mapping. + +## Migrating to Android Ice Cream Sandwich 4.0 ## + +In Ice Cream Sandwich 4.0, we changed the device driver requirements for touch screens +to follow the standard Linux multitouch input protocol and added support for +protocol "B". We also support digitizer tablets and stylus-based touch devices. + +You will probably need to update your input device driver to implement the Linux +multitouch input protocol correctly according to the standard. + +You will also need to update your input device configuration files because some +properties have been changed to be simpler and more systematic. + +Refer to [Touch Devices](/tech/input/touch-devices.html) for more details about +driver requirements.
diff --git a/src/tech/input/overview.md b/src/tech/input/overview.md new file mode 100644 index 0000000..79e3de7 --- /dev/null +++ b/src/tech/input/overview.md
@@ -0,0 +1,259 @@ +<!-- + Copyright 2011 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. +--> + +# Overview # + +The Android input subsystem nominally consists of an event pipeline +that traverses multiple layers of the system. + +## Input Pipeline ## + +At the lowest layer, the physical input device produces signals that +describe state changes such as key presses and touch contact points. +The device firmware encodes and transmits these signals in some way +such as by sending USB HID reports to the system or by producing +interrupts on an I2C bus. + +The signals are then decoded by a device driver in the Linux kernel. +The Linux kernel provides drivers for many standard peripherals, +particularly those that adhere to the HID protocol. However, an OEM +must often provide custom drivers for embedded devices that are +tightly integrated into the system at a low-level, such as touch screens. + +The input device drivers are responsible for translating device-specific +signals into a standard input event format, by way of the Linux +input protocol. The Linux input protocol defines a standard set of +event types and codes in the `linux/input.h` kernel header file. +In this way, components outside the kernel do not need to care about +the details such as physical scan codes, HID usages, I2C messages, +GPIO pins, and the like. + +Next, the Android `EventHub` component reads input events from the kernel +by opening the `evdev` driver associated with each input device. +The Android InputReader component then decodes the input events +according to the device class and produces a stream of Android input +events. As part of this process, the Linux input protocol event codes +are translated into Android event codes according to the +input device configuration, keyboard layout files, and various +mapping tables. + +Finally, the `InputReader` sends input events to the InputDispatcher +which forwards them to the appropriate window. + +## Control Points ## + +There are several stages in the input pipeline which effect control +over the behavior of the input device. + +### Driver and Firmware Configuration ### + +Input device drivers frequently configure the behavior of the input +device by setting parameters in registers or even uploading the +firmware itself. This is particularly the case for embedded +devices such as touch screens where a large part of the calibration +process involves tuning these parameters or fixing the firmware +to provide the desired accuracy and responsiveness and to suppress +noise. + +Driver configuration options are often specified as module parameters +in the kernel board support package (BSP) so that the same driver +can support multiple different hardware implementations. + +This documentation does attempt to describe driver or firmware +configuration, but it does offer guidance as to device calibration +in general. + +### Board Configuration Properties ### + +The kernel board support package (BSP) may export board configuration +properties via SysFS that are used by the Android InputReader component, +such as the placement of virtual keys on a touch screen. + +Refer to the device class sections for details about how different +devices use board configuration properties. + +### Resource Overlays ### + +A few input behaviors are configured by way of resource overlays +in `config.xml` such as the operation of lid switch. + +Here are a few examples: + +* `config_lidKeyboardAccessibility`: Specifies the effect of the + lid switch on whether the hardware keyboard is accessible or hidden. + +* `config_lidNavigationAccessibility`: Specifies the effect of the + lid switch on whether the trackpad is accessible or hidden. + +* `config_longPressOnPowerBehavior`: Specifies what should happen when + the user holds down the power button. + +* `config_lidOpenRotation`: Specifies the effect of the lid switch + on screen orientation. + +Refer to the documentation within `frameworks/base/core/res/res/values/config.xml` +for details about each configuration option. + +### Key Maps ### + +Key maps are used by the Android `EventHub` and `InputReader` components +to configure the mapping from Linux event codes to Android event codes +for keys, joystick buttons and joystick axes. The mapping may +be device or language dependent. + +Refer to the device class sections for details about how different +devices use key maps. + +### Input Device Configuration Files ### + +Input device configuration files are used by the Android `EventHub` and +`InputReader` components to configure special device characteristics +such as how touch size information is reported. + +Refer to the device class sections for details about how different +devices use input device configuration maps. + +## Understanding HID Usages and Event Codes ## + +There are often several different identifiers used to refer to any +given key on a keyboard, button on a game controller, joystick axis +or other control. The relationships between these identifiers +are not always the same: they are dependent on a set of mapping tables, +some of which are fixed, and some which vary based on characteristics +of the device, the device driver, the current locale, the system +configuration, user preferences and other factors. + +Physical Scan Code +: A physical scan code is a device-specific identifier that is associated + with each key, button or other control. Because physical scan codes + often vary from one device to another, the firmware or device driver + is responsible for mapping them to standard identifiers such as + HID Usages or Linux key codes. + + Scan codes are mainly of interest for keyboards. Other devices + typically communicate at a low-level using GPIO pins, I2C messages + or other means. Consequently, the upper layers of the software + stack rely on the device drivers to make sense of what is going on. + +HID Usage +: A HID usage is a standard identifier that is used to report the + state of a control such as a keyboard key, joystick axis, + mouse button, or touch contact point. Most USB and Bluetooth + input devices conform to the HID specification, which enables + the system to interface with them in a uniform manner. + + The Android Framework relies on the Linux kernel HID drivers to + translate HID usage codes into Linux key codes and other identifiers. + Therefore HID usages are mainly of interest to peripheral manufacturers. + +Linux Key Code +: A Linux key code is a standard identifier for a key or button. + Linux key codes are defined in the `linux/input.h` header file using + constants that begin with the prefix `KEY_` or `BTN_`. The Linux + kernel input drivers are responsible for translating physical + scan codes, HID usages and other device-specific signals into Linux + key codes and delivering information about them as part of + `EV_KEY` events. + + The Android API sometimes refers to the Linux key code associated + with a key as its "scan code". This is technically incorrect in + but it helps to distinguish Linux key codes from Android key codes + in the API. + +Linux Relative or Absolute Axis Code +: A Linux relative or absolute axis code is a standard identifier + for reporting relative movements or absolute positions along an + axis, such as the relative movements of a mouse along its X axis + or the absolute position of a joystick along its X axis. + Linux axis code are defined in the `linux/input.h` header file using + constants that begin with the prefix `REL_` or `ABS_`. The Linux + kernel input drivers are responsible for translating HID usages + and other device-specific signals into Linux axis codes and + delivering information about them as part of `EV_REL` and + `EV_ABS` events. + +Linux Switch Code +: A Linux switch code is a standard identifier for reporting the + state of a switch on a device, such as a lid switch. Linux + switch codes are defined in the `linux/input.h` header file + using constants that begin with the prefix `SW_`. The Linux + kernel input drivers report switch state changes as `EV_SW` events. + + Android applications generally do not receive events from switches, + but the system may use them interally to control various + device-specific functions. + +Android Key Code +: An Android key code is a standard identifier defined in the Android + API for indicating a particular key such as 'HOME'. Android key codes + are defined by the `android.view.KeyEvent` class as constants that + begin with the prefix `KEYCODE_`. + + The key layout specifies how Linux key codes are mapped to Android + key codes. Different key layouts may be used depending on the keyboard + model, language, country, layout, or special functions. + + Combinations of Android key codes are transformed into character codes + using a device and locale specific key character map. For example, + when the keys identified as `KEYCODE_SHIFT` and `KEYCODE_A` are both + pressed together, the system looks up the combination in the key + character map and finds the capital letter 'A', which is then inserted + into the currently focused text widget. + +Android Axis Code +: An Android axis code is a standard identifier defined in the Android + API for indicating a particular device axis. Android axis codes are + defined by the `android.view.MotionEvent` class as constants that + begin with the prefix `AXIS_`. + + The key layout specifies how Linux Axis Codes are mapped to Android + axis codes. Different key layouts may be used depending on the device + model, language, country, layout, or special functions. + +Android Meta State +: An Android meta state is a standard identifier defined in the Android + API for indicating which modifier keys are pressed. Android meta states + are defined by the `android.view.KeyEvent` class as constants that + begin with the prefix `META_`. + + The current meta state is determined by the Android InputReader + component which monitors when modifier keys such as `KEYCODE_SHIFT_LEFT` + are pressed / released and sets / resets the appropriate meta state flag. + + The relationship between modifier keys and meta states is hardcoded + but the key layout can alter how the modifier keys themselves are + mapped which in turns affects the meta states. + +Android Button State +: An Android button state is a standard identifier defined in the Android + API for indicating which buttons (on a mouse or stylus) are pressed. + Android button states are defined by the `android.view.MotionEvent` + class as constants that begin with the prefix `BUTTON_`. + + The current button state is determined by the Android InputReader + component which monitors when buttons (on a mouse or stylus) are + pressed / released and sets / resets appropriate button state flag. + + The relationship between buttons and button states is hardcoded. + +## Further Reading ## + +1. [Linux input event codes](http://www.kernel.org/doc/Documentation/input/event-codes.txt) +2. [Linux multi-touch protocol](http://www.kernel.org/doc/Documentation/input/multi-touch-protocol.txt) +3. [Linux input drivers](http://www.kernel.org/doc/Documentation/input/input.txt) +4. [Linux force feedback](http://www.kernel.org/doc/Documentation/input/ff.txt) +5. [HID information, including HID usage tables](http://www.usb.org/developers/hidpage) +
diff --git a/src/tech/input/sidebar2.md b/src/tech/input/sidebar2.md new file mode 100644 index 0000000..6746bcd --- /dev/null +++ b/src/tech/input/sidebar2.md
@@ -0,0 +1,18 @@ +# Input Concepts # + +- [Overview](/tech/input/overview.html) +- [Key Layout Files](/tech/input/key-layout-files.html) +- [Key Character Map Files](/tech/input/key-character-map-files.html) +- [Input Device Configuration Files](/tech/input/input-device-configuration-files.html) +- [Migration Guide](/tech/input/migration-guide.html) + +# Input Device Classes # + +- [Keyboard Devices](/tech/input/keyboard-devices.html) +- [Touch Devices](/tech/input/touch-devices.html) + +# Tools # + +- [Dumpsys](/tech/input/dumpsys.html) +- [Getevent](/tech/input/getevent.html) +- [Validate Keymaps](/tech/input/validate-keymaps.html)
diff --git a/src/tech/input/touch-devices.md b/src/tech/input/touch-devices.md new file mode 100644 index 0000000..234188f --- /dev/null +++ b/src/tech/input/touch-devices.md
@@ -0,0 +1,1186 @@ +<!-- + Copyright 2011 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. +--> + +# Touch Devices # + +Android supports a variety of touch screens and touch pads, including +stylus-based digitizer tablets. + +Touch screens are touch devices that are associated with a display such that +the user has the impression of directly manipulating items on screen. + +Touch pads are touch devices that are not associated with a display such as a +digitizer tablet. Touch pads are typically used for pointing or for +absolute indirect positioning or gesture-based control of a user interface. + +Touch devices may have buttons whose functions are similar to mouse buttons. + +Touch devices can sometimes be manipulated using a variety of different tools +such as fingers or a stylus depending on the underlying touch sensor technology. + +Touch devices are sometimes used to implement virtual keys. For example, on +some Android devices, the touch screen sensor area extends beyond the edge of +the display and serves dual purpose as part of a touch sensitive key pad. + +Due to the great variety of touch devices, Android relies on a large number of +configuration properties to describe the characteristics and desired behavior +of each device. + +## Touch Device Classification ## + +An input device is classified as a *multi-touch* device if both of +the following conditions hold: + +* The input device reports the presence of the `ABS_MT_POSITION_X` and + `ABS_MT_POSITION_Y` absolute axes. + +* The input device does not have any gamepad buttons. This condition + resolves an ambiguity with certain gamepads that report axes with codes + that overlaps those of the MT axes. + +An input device is classified as a *single-touch* device if both of the +following conditions hold: + +* The input device is not classified as a multi-touch device. An input device + is either classified as a single-touch device or as a multi-touch device, + never both. + +* The input device reports the presence of the `ABS_X` and `ABS_Y` absolute + axes, and the presence of the `BTN_TOUCH` key code. + +Once an input device has been classified as a touch device, the presence +of virtual keys is determined by attempting to load the virtual key map file +for the device. If a virtual key map is available, then the key layout +file for the device is also loaded. + +Refer to the section below about the location and format of virtual key map +files. + +Next, the system loads the input device configuration file for the touch device. + +**All built-in touch devices should have input device configuration files.** +If no input device configuration file is present, the system will +choose a default configuration that is appropriate for typical general-purpose +touch peripherals such as external USB or Bluetooth HID touch screens +or touch pads. These defaults are not designed for built-in touch screens and +will most likely result in incorrect behavior. + +After the input device configuration loaded, the system will classify the +input device as a *touch screen*, *touch pad* or *pointer* device. + +* A *touch screen* device is used for direct manipulation of objects on the + screen. Since the user is directly touching the screen, the system does + not require any additional affordances to indicate the objects being + manipulated. + +* A *touch pad* device is used to provide absolute positioning information + to an application about touches on a given sensor area. It may be useful + for digitizer tablets. + +* A *pointer* device is used for indirect manipulation of objects on the + screen using a cursor. Fingers are interpreted as multi-touch pointer + gestures. Other tools, such as styluses, are interpreted using + absolute positions. + + See [Indirect Multi-touch Pointer Gestures](#indirect-multi-touch-pointer-gestures) + for more information. + +The following rules are used to classify the input device as a *touch screen*, +*touch pad* or *pointer* device. + +* If the `touch.deviceType` property is set, then the device type will be + set as indicated. + +* If the input device reports the presence of the `INPUT_PROP_DIRECT` + input property (via the `EVIOCGPROP` ioctl), then the device type will + be set to *touch screen*. This condition assumes that direct input touch + devices are attached to a display that is also connected. + +* If the input device reports the presence of the `INPUT_PROP_POINTER` + input property (via the `EVIOCGPROP` ioctl), then the device type will + be set to *pointer*. + +* If the input device reports the presence of the `REL_X` or `REL_Y` relative + axes, then the device type will be set to *touch pad*. This condition + resolves an ambiguity for input devices that consist of both a mouse and + a touch pad. In this case, the touch pad will not be used to control + the pointer because the mouse already controls it. + +* Otherwise, the device type will be set to *pointer*. This default ensures + that touch pads that have not been designated any other special purpose + will serve to control the pointer. + +## Buttons ## + +Buttons are *optional* controls that may be used by applications to perform +additional functions. Buttons on touch devices behave similarly to mouse +buttons and are mainly of use with *pointer* type touch devices or with a +stylus. + +The following buttons are supported: + +* `BTN_LEFT`: mapped to `MotionEvent.BUTTON_PRIMARY`. + +* `BTN_RIGHT`: mapped to `MotionEvent.BUTTON_SECONDARY`. + +* `BTN_MIDDLE`: mapped to `MotionEvent.BUTTON_MIDDLE`. + +* `BTN_BACK` and `BTN_SIDE`: mapped to `MotionEvent.BUTTON_BACK`. + Pressing this button also synthesizes a key press with the key code + `KeyEvent.KEYCODE_BACK`. + +* `BTN_FORWARD` and `BTN_EXTRA`: mapped to `MotionEvent.BUTTON_FORWARD`. + Pressing this button also synthesizes a key press with the key code + `KeyEvent.KEYCODE_FORWARD`. + +* `BTN_STYLUS`: mapped to `MotionEvent.BUTTON_SECONDARY`. + +* `BTN_STYLUS2`: mapped to `MotionEvent.BUTTON_TERTIARY`. + +## Tools and Tool Types ## + +A *tool* is a finger, stylus or other apparatus that is used to interact with +the touch device. Some touch devices can distinguish between different +types of tools. + +Elsewhere in Android, as in the `MotionEvent` API, a *tool* is often referred +to as a *pointer*. + +The following tool types are supported: + +* `BTN_TOOL_FINGER` and `MT_TOOL_FINGER`: mapped to `MotionEvent.TOOL_TYPE_FINGER`. + +* `BTN_TOOL_PEN` and `MT_TOOL_PEN`: mapped to `MotionEvent.TOOL_TYPE_STYLUS`. + +* `BTN_TOOL_RUBBER`: mapped to `MotionEvent.TOOL_TYPE_ERASER`. + +* `BTN_TOOL_BRUSH`: mapped to `MotionEvent.TOOL_TYPE_STYLUS`. + +* `BTN_TOOL_PENCIL`: mapped to `MotionEvent.TOOL_TYPE_STYLUS`. + +* `BTN_TOOL_AIRBRUSH`: mapped to `MotionEvent.TOOL_TYPE_STYLUS`. + +* `BTN_TOOL_MOUSE`: mapped to `MotionEvent.TOOL_TYPE_MOUSE`. + +* `BTN_TOOL_LENS`: mapped to `MotionEvent.TOOL_TYPE_MOUSE`. + +* `BTN_TOOL_DOUBLETAP`, `BTN_TOOL_TRIPLETAP`, and `BTN_TOOL_QUADTAP`: + mapped to `MotionEvent.TOOL_TYPE_FINGER`. + +## Hovering vs. Touching Tools ## + +Tools can either be in contact with the touch device or in range and hovering +above it. Not all touch devices are able to sense the presence of a tool +hovering above the touch device. Those that do, such as RF-based stylus digitizers, +can often detect when the tool is within a limited range of the digitizer. + +The `InputReader` component takes care to distinguish touching tools from hovering +tools. Likewise, touching tools and hovering tools are reported to applications +in different ways. + +Touching tools are reported to applications as touch events +using `MotionEvent.ACTION_DOWN`, `MotionEvent.ACTION_MOVE`, `MotionEvent.ACTION_DOWN`, +`MotionEvent.ACTION_POINTER_DOWN` and `MotionEvent.ACTION_POINTER_UP`. + +Hovering tools are reported to applications as generic motion events using +`MotionEvent.ACTION_HOVER_ENTER`, `MotionEvent.ACTION_HOVER_MOVE` +and `MotionEvent.ACTION_HOVER_EXIT`. + +## Touch Device Driver Requirements ## + +1. Touch device drivers should only register axes and key codes for the axes + and buttons that they actually support. Registering excess axes or key codes + may confuse the device classification algorithm or cause the system to incorrectly + detect the capabilities of the device. + + For example, if the device reports the `BTN_TOUCH` key code, the system will + assume that `BTN_TOUCH` will always be used to indicate whether the tool is + actually touching the screen or is merely in range and hovering. + +2. Single-touch devices use the following Linux input events: + + * `ABS_X`: *(REQUIRED)* Reports the X coordinate of the tool. + + * `ABS_Y`: *(REQUIRED)* Reports the Y coordinate of the tool. + + * `ABS_PRESSURE`: *(optional)* Reports the physical pressure applied to the tip + of the tool or the signal strength of the touch contact. + + * `ABS_TOOL_WIDTH`: *(optional)* Reports the cross-sectional area or width of the + touch contact or of the tool itself. + + * `ABS_DISTANCE`: *(optional)* Reports the distance of the tool from the surface of + the touch device. + + * `ABS_TILT_X`: *(optional)* Reports the tilt of the tool from the surface of the + touch device along the X axis. + + * `ABS_TILT_Y`: *(optional)* Reports the tilt of the tool from the surface of the + touch device along the Y axis. + + * `BTN_TOUCH`: *(REQUIRED)* Indicates whether the tool is touching the device. + + * `BTN_LEFT`, `BTN_RIGHT`, `BTN_MIDDLE`, `BTN_BACK`, `BTN_SIDE`, `BTN_FORWARD`, + `BTN_EXTRA`, `BTN_STYLUS`, `BTN_STYLUS2`: + *(optional)* Reports [button](#buttons) states. + + * `BTN_TOOL_FINGER`, `BTN_TOOL_PEN`, `BTN_TOOL_RUBBER`, `BTN_TOOL_BRUSH`, + `BTN_TOOL_PENCIL`, `BTN_TOOL_AIRBRUSH`, `BTN_TOOL_MOUSE`, `BTN_TOOL_LENS`, + `BTN_TOOL_DOUBLETAP`, `BTN_TOOL_TRIPLETAP`, `BTN_TOOL_QUADTAP`: + *(optional)* Reports the [tool type](#tools-and-tool-types). + +3. Multi-touch devices use the following Linux input events: + + * `ABS_MT_POSITION_X`: *(REQUIRED)* Reports the X coordinate of the tool. + + * `ABS_MT_POSITION_Y`: *(REQUIRED)* Reports the Y coordinate of the tool. + + * `ABS_MT_PRESSURE`: *(optional)* Reports the physical pressure applied to the + tip of the tool or the signal strength of the touch contact. + + * `ABS_MT_TOUCH_MAJOR`: *(optional)* Reports the cross-sectional area of the + touch contact, or the length of the longer dimension of the touch contact. + + * `ABS_MT_TOUCH_MINOR`: *(optional)* Reports the length of the shorter dimension of the + touch contact. This axis should not be used if `ABS_MT_TOUCH_MAJOR` is reporting an + area measurement. + + * `ABS_MT_WIDTH_MAJOR`: *(optional)* Reports the cross-sectional area of the tool itself, + or the length of the longer dimension of the tool itself. + This axis should not be used if the dimensions of the tool itself are unknown. + + * `ABS_MT_WIDTH_MINOR`: *(optional)* Reports the length of the shorter dimension of + the tool itself. This axis should not be used if `ABS_MT_WIDTH_MAJOR` is reporting + an area measurement or if the dimensions of the tool itself are unknown. + + * `ABS_MT_ORIENTATION`: *(optional)* Reports the orientation of the tool. + + * `ABS_MT_DISTANCE`: *(optional)* Reports the distance of the tool from the + surface of the touch device. + + * `ABS_MT_TOOL_TYPE`: *(optional)* Reports the [tool type](#tools-and-tool-types) as + `MT_TOOL_FINGER` or `MT_TOOL_PEN`. + + * `ABS_MT_TRACKING_ID`: *(optional)* Reports the tracking id of the tool. + The tracking id is an arbitrary non-negative integer that is used to identify + and track each tool independently when multiple tools are active. For example, + when multiple fingers are touching the device, each finger should be assigned a distinct + tracking id that is used as long as the finger remains in contact. Tracking ids + may be reused when their associated tools move out of range. + + * `ABS_MT_SLOT`: *(optional)* Reports the slot id of the tool, when using the Linux + multi-touch protocol 'B'. Refer to the Linux multi-touch protocol documentation + for more details. + + * `BTN_TOUCH`: *(REQUIRED)* Indicates whether the tool is touching the device. + + * `BTN_LEFT`, `BTN_RIGHT`, `BTN_MIDDLE`, `BTN_BACK`, `BTN_SIDE`, `BTN_FORWARD`, + `BTN_EXTRA`, `BTN_STYLUS`, `BTN_STYLUS2`: + *(optional)* Reports [button](#buttons) states. + + * `BTN_TOOL_FINGER`, `BTN_TOOL_PEN`, `BTN_TOOL_RUBBER`, `BTN_TOOL_BRUSH`, + `BTN_TOOL_PENCIL`, `BTN_TOOL_AIRBRUSH`, `BTN_TOOL_MOUSE`, `BTN_TOOL_LENS`, + `BTN_TOOL_DOUBLETAP`, `BTN_TOOL_TRIPLETAP`, `BTN_TOOL_QUADTAP`: + *(optional)* Reports the [tool type](#tools-and-tool-types). + +4. If axes for both the single-touch and multi-touch protocol are defined, then + only the multi-touch axes will be used and the single-touch axes will be ignored. + +5. The minimum and maximum values of the `ABS_X`, `ABS_Y`, `ABS_MT_POSITION_X` + and `ABS_MT_POSITION_Y` axes define the bounds of the active area of the device + in device-specific surface units. In the case of a touch screen, the active area + describes the part of the touch device that actually covers the display. + + For a touch screen, the system automatically interpolates the reported touch + positions in surface units to obtain touch positions in display pixels according + to the following calculation: + + displayX = (x - minX) * displayWidth / (maxX - minX + 1) + displayY = (y - minY) * displayHeight / (maxY - minY + 1) + + A touch screen may report touches outside of the reported active area. + + Touches that are initiated outside the active area are not delivered to applications + but may be used for virtual keys. + + Touches that are initiated inside the active area, or that enter and exit the display + area are delivered to applications. Consequently, if a touch starts within the + bounds of an application and then moves outside of the active area, the application + may receive touch events with display coordinates that are negative or beyond the + bounds of the display. This is expected behavior. + + A touch device should never clamp touch coordinates to the bounds of the active + area. If a touch exits the active area, it should be reported as being outside of + the active area, or it should not be reported at all. + + For example, if the user's finger is touching near the top-left corner of the + touch screen, it may report a coordinate of (minX, minY). If the finger continues + to move further outside of the active area, the touch screen should either start + reporting coordinates with components less than minX and minY, such as + (minX - 2, minY - 3), or it should stop reporting the touch altogether. + In other words, the touch screen should *not* be reporting (minX, minY) + when the user's finger is really touching outside of the active area. + + Clamping touch coordinates to the display edge creates an artificial + hard boundary around the edge of the screen which prevents the system from + smoothly tracking motions that enter or exit the bounds of the display area. + +6. The values reported by `ABS_PRESSURE` or `ABS_MT_PRESSURE`, if they + are reported at all, must be non-zero when the tool is touching the device + and zero otherwise to indicate that the tool is hovering. + + Reporting pressure information is *optional* but strongly recommended. + Applications can use pressure information to implement pressure-sensitive drawing + and other effects. + +7. The values reported by `ABS_TOOL_WIDTH`, `ABS_MT_TOUCH_MAJOR`, `ABS_MT_TOUCH_MINOR`, + `ABS_MT_WIDTH_MAJOR`, or `ABS_MT_WIDTH_MINOR` should be non-zero when the tool + is touching the device and zero otherwise, but this is not required. + For example, the touch device may be able to measure the size of finger touch + contacts but not stylus touch contacts. + + Reporting size information is *optional* but strongly recommended. + Applications can use pressure information to implement size-sensitive drawing + and other effects. + +8. The values reported by `ABS_DISTANCE` or `ABS_MT_DISTANCE` should approach + zero when the tool is touching the device. The distance may remain non-zero + even when the tool is in direct contact. The exact values reported depend + on the manner in which the hardware measures distance. + + Reporting distance information is *optional* but recommended for + stylus devices. + +9. The values reported by `ABS_TILT_X` and `ABS_TILT_Y` should be zero when the + tool is perpendicular to the device. A non-zero tilt is taken as an indication + that the tool is held at an incline. + + The tilt angles along the X and Y axes are assumed to be specified in degrees + from perpendicular. The center point (perfectly perpendicular) is given + by `(max + min) / 2` for each axis. Values smaller than the center point + represent a tilt up or to the left, values larger than the center point + represent a tilt down or to the right. + + The `InputReader` converts the X and Y tilt components into a perpendicular + tilt angle ranging from 0 to `PI / 2` radians and a planar orientation angle + ranging from `-PI` to `PI` radians. This representation results in a + description of orientation that is compatible with what is used to describe + finger touches. + + Reporting tilt information is *optional* but recommended for stylus devices. + +10. If the tool type is reported by `ABS_MT_TOOL_TYPE`, it will supercede any tool + type information reported by `BTN_TOOL_*`. + If no tool type information is available at all, the tool type defaults to + `MotionEvent.TOOL_TYPE_FINGER`. + +11. A tool is determined to be active based on the following conditions: + + * When using the single-touch protocol, the tool is active if `BTN_TOUCH`, + or `BTN_TOOL_*` is 1. + + This condition implies that the `InputReader` needs to have at least some + information about the nature of the tool, either whether it is touching, + or at least its tool type. If no information is available, + then the tool is assumed to be inactive (out of range). + + * When using the multi-touch protocol 'A', the tool is active whenever it + appears in the most recent sync report. When the tool stops appearing in + sync reports, it ceases to exist. + + * When using the multi-touch protocol 'B', the tool is active as long as + it has an active slot. When the slot it cleared, the tool ceases to exist. + +12. A tool is determined to be hovering based on the following conditions: + + * If the tool is `BTN_TOOL_MOUSE` or `BTN_TOOL_LENS`, then the tool + is not hovering, even if either of the following conditions are true. + + * If the tool is active and the driver reports pressure information, + and the reported pressure is zero, then the tool is hovering. + + * If the tool is active and the driver supports the `BTN_TOUCH` key code and + `BTN_TOUCH` has a value of zero, then the tool is hovering. + +13. The `InputReader` supports both multi-touch protocol 'A' and 'B'. New drivers + should use the 'B' protocol but either will work. + +14. **As of Android Ice Cream Sandwich 4.0, touch screen drivers may need to be changed + to comply with the Linux input protocol specification.** + + The following changes may be required: + + * When a tool becomes inactive (finger goes "up"), it should stop appearing + in subsequent multi-touch sync reports. When all tools become inactive + (all fingers go "up"), the driver should send an empty sync report packet, + such as `SYN_MT_REPORT` followed by `SYN_REPORT`. + + Previous versions of Android expected "up" events to be reported by sending + a pressure value of 0. The old behavior was incompatible with the + Linux input protocol specification and is no longer supported. + + * Physical pressure or signal strength information should be reported using + `ABS_MT_PRESSURE`. + + Previous versions of Android retrieved pressure information from + `ABS_MT_TOUCH_MAJOR`. The old behavior was incompatible with the + Linux input protocol specification and is no longer supported. + + * Touch size information should be reported using `ABS_MT_TOUCH_MAJOR`. + + Previous versions of Android retrieved size information from + `ABS_MT_TOOL_MAJOR`. The old behavior was incompatible with the + Linux input protocol specification and is no longer supported. + + Touch device drivers no longer need Android-specific customizations. + By relying on the standard Linux input protocol, Android can support a + wider variety of touch peripherals, such as external HID multi-touch + touch screens, using unmodified drivers. + +## Touch Device Operation ## + +The following is a brief summary of the touch device operation on Android. + +1. The `EventHub` reads raw events from the `evdev` driver. + +2. The `InputReader` consumes the raw events and updates internal state about + the position and other characteristics of each tool. It also tracks + button states. + +3. If the BACK or FORWARD buttons were pressed or released, the `InputReader` + notifies the `InputDispatcher` about the key event. + +4. The `InputReader` determines whether a virtual key press occurred. If so, + it notifies the `InputDispatcher` about the key event. + +5. The `InputReader` determines whether the touch was initiated within the + bounds of the display. If so, it notifies the `InputDispatcher` about + the touch event. + +6. If there are no touching tools but there is at least one hovering tool, + the `InputReader` notifies the `InputDispatcher` about the hover event. + +7. If the touch device type is *pointer*, the `InputReader` performs pointer + gesture detection, moves the pointer and spots accordingly and notifies + the `InputDispatcher` about the pointer event. + +8. The `InputDispatcher` uses the `WindowManagerPolicy` to determine whether + the events should be dispatched and whether they should wake the device. + Then, the `InputDispatcher` delivers the events to the appropriate applications. + +## Touch Device Configuration ## + +Touch device behavior is determined by the device's axes, buttons, input properties, +input device configuration, virtual key map and key layout. + +Refer to the following sections for more details about the files that +participate in keyboard configuration: + +* [Input Device Configuration Files](/tech/input/input-device-configuration-files.html) +* [Virtual Key Map Files](#virtual-key-map-files) + +### Properties ### + +The system relies on many input device configuration properties to configure +and calibrate touch device behavior. + +One reason for this is that the device drivers for touch devices often report +the characteristics of touches using device-specific units. + +For example, many touch devices measure the touch contact area +using an internal device-specific scale, such as the total number of +sensor nodes that were triggered by the touch. This raw size value would +not be meaningful applications because they would need to know about the +physical size and other characteristics of the touch device sensor nodes. + +The system uses calibration parameters encoded in input device configuration +files to decode, transform, and normalize the values reported by the touch +device into a simpler standard representation that applications can understand. + +### Documentation Conventions ### + +For documentation purposes, we will use the following conventions to describe +the values used by the system during the calibration process. + +#### Raw Axis Values #### + +The following expressions denote the raw values reported by the touch +device driver as `EV_ABS` events. + +`raw.x` +: The value of the `ABS_X` or `ABS_MT_POSITION_X` axis. + +`raw.y` +: The value of the `ABS_Y` or `ABS_MT_POSITION_Y` axis. + +`raw.pressure` +: The value of the `ABS_PRESSURE` or `ABS_MT_PRESSURE` axis, or 0 if not available. + +`raw.touchMajor` +: The value of the `ABS_MT_TOUCH_MAJOR` axis, or 0 if not available. + +`raw.touchMinor` +: The value of the `ABS_MT_TOUCH_MINOR` axis, or `raw.touchMajor` if not available. + +`raw.toolMajor` +: The value of the `ABS_TOOL_WIDTH` or `ABS_MT_WIDTH_MAJOR` axis, or 0 if not available. + +`raw.toolMinor` +: The value of the `ABS_MT_WIDTH_MINOR` axis, or `raw.toolMajor` if not available. + +`raw.orientation` +: The value of the `ABS_MT_ORIENTATION` axis, or 0 if not available. + +`raw.distance` +: The value of the `ABS_DISTANCE` or `ABS_MT_DISTANCE` axis, or 0 if not available. + +`raw.tiltX` +: The value of the `ABS_TILT_X` axis, or 0 if not available. + +`raw.tiltY` +: The value of the `ABS_TILT_Y` axis, or 0 if not available. + +#### Raw Axis Ranges #### + +The following expressions denote the bounds of raw values. They are obtained +by calling `EVIOCGABS` ioctl for each axis. + +`raw.*.min` +: The inclusive minimum value of the raw axis. + +`raw.*.max` +: The inclusive maximum value of the raw axis. + +`raw.*.range` +: Equivalent to `raw.*.max - raw.*.min`. + +`raw.*.fuzz` +: The accuracy of the raw axis. eg. fuzz = 1 implies values are accurate to +/- 1 unit. + +`raw.width` +: The inclusive width of the touch area, equivalent to `raw.x.range + 1`. + +`raw.height` +: The inclusive height of the touch area, equivalent to `raw.y.range + 1`. + +#### Output Ranges #### + +The following expressions denote the characteristics of the output coordinate system. +The system uses linear interpolation to translate touch position information from +the surface units used by the touch device into the output units that will +be reported to applications such as display pixels. + +`output.width` +: The output width. For touch screens (associated with a display), this + is the display width in pixels. For touch pads (not associated with a display), + the output width equals `raw.width`, indicating that no interpolation will + be performed. + +`output.height` +: The output height. For touch screens (associated with a display), this + is the display height in pixels. For touch pads (not associated with a display), + the output height equals `raw.height`, indicating that no interpolation will + be performed. + +`output.diag` +: The diagonal length of the output coordinate system, equivalent to + `sqrt(output.width ^2 + output.height ^2)`. + +### Basic Configuration ### + +The touch input mapper uses many configuration properties in the input device +configuration file to specify calibration values. The following table describes +some general purpose configuration properties. All other properties are described +in the following sections along with the fields they are used to calibrate. + +#### `touch.deviceType` #### + +*Definition:* `touch.deviceType` = `touchScreen` | `touchPad` | `pointer` | `default` + +Specifies the touch device type. + +* If the value is `touchScreen`, the touch device is a touch screen associated + with a display. + +* If the value is `touchPad`, the touch device is a touch pad not associated + with a display. + +* If the value is `pointer`, the touch device is a touch pad not associated + with a display, and its motions are used for + [indirect multi-touch pointer gestures](#indirect-multi-touch-pointer-gestures). + +* If the value is `default`, the system automatically detects the device type + according to the classification algorithm. + +Refer to the [Classification](#touch-device-classification) section for more details +about how the device type influences the behavior of the touch device. + +Prior to Honeycomb, all touch devices were assumed to be touch screens. + +#### `touch.orientationAware` #### + +*Definition:* `touch.orientationAware` = `0` | `1` + +Specifies whether the touch device should react to display orientation changes. + +* If the value is `1`, touch positions reported by the touch device are rotated + whenever the display orientation changes. + +* If the value is `0`, touch positions reported by the touch device are immune + to display orientation changes. + +The default value is `1` if the device is a touch screen, `0` otherwise. + +The system distinguishes between internal and external touch screens and displays. +An orientation aware internal touch screen is rotated based on the orientation +of the internal display. An orientation aware external touch screen is rotated +based on the orientation of the external display. + +Orientation awareness is used to support rotation of touch screens on devices +like the Nexus One. For example, when the device is rotated clockwise 90 degrees +from its natural orientation, the absolute positions of touches are remapped such +that a touch in the top-left corner of the touch screen's absolute coordinate system +is reported as a touch in the top-left corner of the display's rotated coordinate system. +This is done so that touches are reported with the same coordinate system that +applications use to draw their visual elements. + +Prior to Honeycomb, all touch devices were assumed to be orientation aware. + +#### `touch.gestureMode` #### + +*Definition:* `touch.gestureMode` = `pointer` | `spots` | `default` + +Specifies the presentation mode for pointer gestures. This configuration property +is only relevant when the touch device is of type *pointer*. + +* If the value is `pointer`, the touch pad gestures are presented by way of a cursor + similar to a mouse pointer. + +* If the value is `spots`, the touch pad gestures are presented by an anchor + that represents the centroid of the gesture and a set of circular spots + that represent the position of individual fingers. + +The default value is `pointer` when the `INPUT_PROP_SEMI_MT` input property +is set, or `spots` otherwise. + +### `X` and `Y` Fields ### + +The X and Y fields provide positional information for the center of the contact area. + +#### Calculation #### + +The calculation is straightforward: positional information from the touch driver is +linearly interpolated to the output coordinate system. + + xScale = output.width / raw.width + yScale = output.height / raw.height + + If not orientation aware or screen rotation is 0 degrees: + output.x = (raw.x - raw.x.min) * xScale + output.y = (raw.y - raw.y.min) * yScale + Else If rotation is 90 degrees: + output.x = (raw.y - raw.y.min) * yScale + output.y = (raw.x.max - raw.x) * xScale + Else If rotation is 180 degrees: + output.x = (raw.x.max - raw.x) * xScale + output.y = (raw.y.max - raw.y) * yScale + Else If rotation is 270 degrees: + output.x = (raw.y.max - raw.y) * yScale + output.y = (raw.x - raw.x.min) * xScale + End If + +### `TouchMajor`, `TouchMinor`, `ToolMajor`, `ToolMinor`, `Size` Fields ### + +The `TouchMajor` and `TouchMinor` fields describe the approximate dimensions +of the contact area in output units (pixels). + +The `ToolMajor` and `ToolMinor` fields describe the approximate dimensions +of the [tool](#tools-and-tool-types) itself in output units (pixels). + +The `Size` field describes the normalized size of the touch relative to +the largest possible touch that the touch device can sense. The smallest +possible normalized size is 0.0 (no contact, or it is unmeasurable), and the largest +possible normalized size is 1.0 (sensor area is saturated). + +When both the approximate length and breadth can be measured, then the `TouchMajor` field +specifies the longer dimension and the `TouchMinor` field specifies the shorter dimension +of the contact area. When only the approximate diameter of the contact area can be measured, +then the `TouchMajor` and `TouchMinor` fields will be equal. + +Likewise, the `ToolMajor` field specifies the longer dimension and the `ToolMinor` +field specifies the shorter dimension of the tool's cross-sectional area. + +If the touch size is unavailable but the tool size is available, then the tool size +will be set equal to the touch size. Conversely, if the tool size is unavailable +but the touch size is available, then the touch size will be set equal to the tool size. + +Touch devices measure or report the touch size and tool size in various ways. +The current implementation supports three different kinds of measurements: +diameter, area, and geometric bounding box in surface units. + +#### `touch.size.calibration` #### + +*Definition:* `touch.size.calibration` = `none` | `geometric` | `diameter` +| `area` | `default` + +Specifies the kind of measurement used by the touch driver to report the +touch size and tool size. + +* If the value is `none`, the size is set to zero. + +* If the value is `geometric`, the size is assumed to be specified in the same + surface units as the position, so it is scaled in the same manner. + +* If the value is `diameter`, the size is assumed to be proportional to + the diameter (width) of the touch or tool. + +* If the value is `area`, the size is assumed to be proportional to the + area of the touch or tool. + +* If the value is `default`, the system uses the `geometric` calibration if the + `raw.touchMajor` or `raw.toolMajor` axis is available, otherwise it uses + the `none` calibration. + +#### `touch.size.scale` #### + +*Definition:* `touch.size.scale` = <a non-negative floating point number> + +Specifies a constant scale factor used in the calibration. + +The default value is `1.0`. + +#### `touch.size.bias` #### + +*Definition:* `touch.size.bias` = <a non-negative floating point number> + +Specifies a constant bias value used in the calibration. + +The default value is `0.0`. + +#### `touch.size.isSummed` #### + +*Definition:* `touch.size.isSummed` = `0` | `1` + +Specifies whether the size is reported as the sum of the sizes of all +active contacts, or is reported individually for each contact. + +* If the value is `1`, the reported size will be divided by the number + of contacts prior to use. + +* If the value is `0`, the reported size will be used as is. + +The default value is `0`. + +Some touch devices, particularly "Semi-MT" devices cannot distinguish the +individual dimensions of multiple contacts so they report a size measurement +that represents their total area or width. This property should only be set to +`1` for such devices. If in doubt, set this value to `0`. + +#### Calculation #### + +The calculation of the `TouchMajor`, `TouchMinor`, `ToolMajor`, `ToolMinor` +and `Size` fields depends on the specified calibration parameters. + + If raw.touchMajor and raw.toolMajor are available: + touchMajor = raw.touchMajor + touchMinor = raw.touchMinor + toolMajor = raw.toolMajor + toolMinor = raw.toolMinor + Else If raw.touchMajor is available: + toolMajor = touchMajor = raw.touchMajor + toolMinor = touchMinor = raw.touchMinor + Else If raw.toolMajor is available: + touchMajor = toolMajor = raw.toolMajor + touchMinor = toolMinor = raw.toolMinor + Else + touchMajor = toolMajor = 0 + touchMinor = toolMinor = 0 + size = 0 + End If + + size = avg(touchMajor, touchMinor) + + If touch.size.isSummed == 1: + touchMajor = touchMajor / numberOfActiveContacts + touchMinor = touchMinor / numberOfActiveContacts + toolMajor = toolMajor / numberOfActiveContacts + toolMinor = toolMinor / numberOfActiveContacts + size = size / numberOfActiveContacts + End If + + If touch.size.calibration == "none": + touchMajor = toolMajor = 0 + touchMinor = toolMinor = 0 + size = 0 + Else If touch.size.calibration == "geometric": + outputScale = average(output.width / raw.width, output.height / raw.height) + touchMajor = touchMajor * outputScale + touchMinor = touchMinor * outputScale + toolMajor = toolMajor * outputScale + toolMinor = toolMinor * outputScale + Else If touch.size.calibration == "area": + touchMajor = sqrt(touchMajor) + touchMinor = touchMajor + toolMajor = sqrt(toolMajor) + toolMinor = toolMajor + Else If touch.size.calibration == "diameter": + touchMinor = touchMajor + toolMinor = toolMajor + End If + + If touchMajor != 0: + output.touchMajor = touchMajor * touch.size.scale + touch.size.bias + Else + output.touchMajor = 0 + End If + + If touchMinor != 0: + output.touchMinor = touchMinor * touch.size.scale + touch.size.bias + Else + output.touchMinor = 0 + End If + + If toolMajor != 0: + output.toolMajor = toolMajor * touch.size.scale + touch.size.bias + Else + output.toolMajor = 0 + End If + + If toolMinor != 0: + output.toolMinor = toolMinor * touch.size.scale + touch.size.bias + Else + output.toolMinor = 0 + End If + + output.size = size + +### `Pressure` Field ### + +The `Pressure` field describes the approximate physical pressure applied to the +touch device as a normalized value between 0.0 (no touch) and 1.0 (full force). + +A zero pressure indicates that the tool is hovering. + +#### `touch.pressure.calibration` #### + +*Definition:* `touch.pressure.calibration` = `none` | `physical` | `amplitude` | `default` + +Specifies the kind of measurement used by the touch driver to report the pressure. + +* If the value is `none`, the pressure is unknown so it is set to 1.0 when + touching and 0.0 when hovering. + +* If the value is `physical`, the pressure axis is assumed to measure the actual + physical intensity of pressure applied to the touch pad. + +* If the value is `amplitude`, the pressure axis is assumed to measure the signal + amplitude, which is related to the size of the contact and the pressure applied. + +* If the value is `default`, the system uses the `physical` calibration if the + pressure axis available, otherwise uses `none`. + +#### `touch.pressure.scale` #### + +*Definition:* `touch.pressure.scale` = <a non-negative floating point number> + +Specifies a constant scale factor used in the calibration. + +The default value is `1.0 / raw.pressure.max`. + +#### Calculation #### + +The calculation of the `Pressure` field depends on the specified calibration parameters. + + If touch.pressure.calibration == "physical" or "amplitude": + output.pressure = raw.pressure * touch.pressure.scale + Else + If hovering: + output.pressure = 0 + Else + output.pressure = 1 + End If + End If + +### `Orientation` and `Tilt` Fields ### + +The `Orientation` field describes the orientation of the touch and tool as an +angular measurement. An orientation of `0` indicates that the major axis is +oriented vertically, `-PI/2` indicates that the major axis is oriented to the left, +`PI/2` indicates that the major axis is oriented to the right. When a stylus +tool is present, the orientation range may be described in a full circle range +from `-PI` or `PI`. + +The `Tilt` field describes the inclination of the tool as an angular measurement. +A tilt of `0` indicates that the tool is perpendicular to the surface. +A tilt of `PI/2` indicates that the tool is flat on the surface. + +#### `touch.orientation.calibration` #### + +*Definition:* `touch.orientation.calibration` = `none` | `interpolated` | `vector` | `default` + +Specifies the kind of measurement used by the touch driver to report the orientation. + +* If the value is `none`, the orientation is unknown so it is set to 0. + +* If the value is `interpolated`, the orientation is linearly interpolated such that a + raw value of `raw.orientation.min` maps to `-PI/2` and a raw value of + `raw.orientation.max` maps to `PI/2`. The center value of + `(raw.orientation.min + raw.orientation.max) / 2` maps to `0`. + +* If the value is `vector`, the orientation is interpreted as a packed vector consisiting + of two signed 4-bit fields. This representation is used on Atmel Object Based Protocol + parts. When decoded, the vector yields an orientation angle and confidence + magnitude. The confidence magnitude is used to scale the size information, + unless it is geometric. + +* If the value is `default`, the system uses the `interpolated` calibration if the + orientation axis available, otherwise uses `none`. + +#### Calculation #### + +The calculation of the `Orientation` and `Tilt` fields depends on the specified +calibration parameters and available input. + + If touch.tiltX and touch.tiltY are available: + tiltXCenter = average(raw.tiltX.min, raw.tiltX.max) + tiltYCenter = average(raw.tiltY.min, raw.tiltY.max) + tiltXAngle = (raw.tiltX - tiltXCenter) * PI / 180 + tiltYAngle = (raw.tiltY - tiltYCenter) * PI / 180 + output.orientation = atan2(-sin(tiltXAngle), sinf(tiltYAngle)) + output.tilt = acos(cos(tiltXAngle) * cos(tiltYAngle)) + Else If touch.orientation.calibration == "interpolated": + center = average(raw.orientation.min, raw.orientation.max) + output.orientation = PI / (raw.orientation.max - raw.orientation.min) + output.tilt = 0 + Else If touch.orientation.calibration == "vector": + c1 = (raw.orientation & 0xF0) >> 4 + c2 = raw.orientation & 0x0F + + If c1 != 0 or c2 != 0: + If c1 >= 8 Then c1 = c1 - 16 + If c2 >= 8 Then c2 = c2 - 16 + angle = atan2(c1, c2) / 2 + confidence = sqrt(c1*c1 + c2*c2) + + output.orientation = angle + + If touch.size.calibration == "diameter" or "area": + scale = 1.0 + confidence / 16 + output.touchMajor *= scale + output.touchMinor /= scale + output.toolMajor *= scale + output.toolMinor /= scale + End If + Else + output.orientation = 0 + End If + output.tilt = 0 + Else + output.orientation = 0 + output.tilt = 0 + End If + + If orientation aware: + If screen rotation is 90 degrees: + output.orientation = output.orientation - PI / 2 + Else If screen rotation is 270 degrees: + output.orientation = output.orientation + PI / 2 + End If + End If + +### `Distance` Field ### + +The `Distance` field describes the distance between the tool and the touch device +surface. A value of 0.0 indicates direct contact and larger values indicate +increasing distance from the surface. + +#### `touch.distance.calibration` #### + +*Definition:* `touch.distance.calibration` = `none` | `scaled` | `default` + +Specifies the kind of measurement used by the touch driver to report the distance. + +* If the value is `none`, the distance is unknown so it is set to 0. + +* If the value is `scaled`, the reported distance is multiplied by a + constant scale factor. + +* If the value is `default`, the system uses the `scaled` calibration if the + distance axis available, otherwise uses `none`. + +#### `touch.distance.scale` #### + +*Definition:* `touch.distance.scale` = <a non-negative floating point number> + +Specifies a constant scale factor used in the calibration. + +The default value is `1.0`. + +#### Calculation #### + +The calculation of the `Distance` field depends on the specified calibration parameters. + + If touch.distance.calibration == "scaled": + output.distance = raw.distance * touch.distance.scale + Else + output.distance = 0 + End If + +### Example ### + + # Input device configuration file for a touch screen that supports pressure, + # size and orientation. The pressure and size scale factors were obtained + # by measuring the characteristics of the device itself and deriving + # useful approximations based on the resolution of the touch sensor and the + # display. + # + # Note that these parameters are specific to a particular device model. + # Different parameters will need to be used for other devices. + + # Basic Parameters + touch.deviceType = touchScreen + touch.orientationAware = 1 + + # Size + # Based on empirical measurements, we estimate the size of the contact + # using size = sqrt(area) * 28 + 0. + touch.size.calibration = area + touch.size.scale = 28 + touch.size.bias = 0 + touch.size.isSummed = 0 + + # Pressure + # Driver reports signal strength as pressure. + # + # A normal index finger touch typically registers about 80 signal strength + # units although we don't expect these values to be accurate. + touch.pressure.calibration = amplitude + touch.pressure.scale = 0.0125 + + # Orientation + touch.orientation.calibration = vector + +### Compatibility Notes ### + +The configuration properties for touch devices changed significantly in +Android Ice Cream Sandwich 4.0. **All input device configuration files for touch +devices must be updated to use the new configuration properties.** + +Older touch device [drivers](#touch-device-driver-requirements) may also need to be +updated. + +## Virtual Key Map Files ## + +Touch devices are often used to implement virtual keys. + +There are several ways of doing this, depending on the capabilities of the +touch controller. Some touch controllers can be directly configured to implement +soft keys by setting firmware registers. Other times it is desirable to perform +the mapping from touch coordinates to key codes in software. + +When virtual keys are implemented in software, the kernel must export a virtual key map +file called `virtualkeys.<devicename>` as a board property. For example, +if the touch screen device drivers reports its name as "touchyfeely" then +the virtual key map file must have the path `/sys/board_properties/virtualkeys.touchyfeely`. + +A virtual key map file describes the coordinates and Linux key codes of virtual keys +on the touch screen. + +In addition to the virtual key map file, there must be a corresponding key layout +file and key character map file to map the Linux key codes to Android key codes and +to specify the type of the keyboard device (usually `SPECIAL_FUNCTION`). + +### Syntax ### + +A virtual key map file is a plain text file consisting of a sequence of virtual key +layout descriptions either separated by newlines or by colons. + +Comment lines begin with '#' and continue to the end of the line. + +Each virtual key is described by 6 colon-delimited components: + +* `0x01`: A version code. Must always be `0x01`. +* <Linux key code>: The Linux key code of the virtual key. +* <centerX>: The X pixel coordinate of the center of the virtual key. +* <centerY>: The Y pixel coordinate of the center of the virtual key. +* <width>: The width of the virtual key in pixels. +* <height>: The height of the virtual key in pixels. + +All coordinates and sizes are specified in terms of the display coordinate system. + +Here is a virtual key map file all written on one line. + + # All on one line + 0x01:158:55:835:90:55:0x01:139:172:835:125:55:0x01:102:298:835:115:55:0x01:217:412:835:95:55 + +The same virtual key map file can also be written on multiple lines. + + # One key per line + 0x01:158:55:835:90:55 + 0x01:139:172:835:125:55 + 0x01:102:298:835:115:55 + 0x01:217:412:835:95:55 + +In the above example, the touch screen has a resolution of 480x800. Accordingly, all of +the virtual keys have a <centerY> coordinate of 835, which is a little bit below +the visible area of the touch screen. + +The first key has a Linux scan code of `158` (`KEY_BACK`), centerX of `55`, +centerY of `835`, width of `90` and height of `55`. + +### Example ### + +Virtual key map file: `/sys/board_properties/virtualkeys.touchyfeely`. + + 0x01:158:55:835:90:55 + 0x01:139:172:835:125:55 + 0x01:102:298:835:115:55 + 0x01:217:412:835:95:55 + +Key layout file: `/system/usr/keylayout/touchyfeely.kl`. + + key 158 BACK + key 139 MENU + key 102 HOME + key 217 SEARCH + +Key character map file: `/system/usr/keychars/touchyfeely.kcm`. + + type SPECIAL_FUNCTION + +## Indirect Multi-touch Pointer Gestures ## + +In pointer mode, the system interprets the following gestures: + +1. Single finger tap: click. + +2. Single finger motion: move the pointer. + +3. Single finger motion plus button presses: drag the pointer. + +4. Two finger motion both fingers moving in the same direction: drag the area under the pointer + in that direction. The pointer itself does not move. + +5. Two finger motion both fingers moving towards each other or apart in + different directions: pan/scale/rotate the area surrounding the pointer. + The pointer itself does not move. + +6. Multiple finger motion: freeform gesture. + +## Further Reading ## + +1. [Linux multi-touch protocol](http://www.kernel.org/doc/Documentation/input/multi-touch-protocol.txt) +2. [ENAC list of available multitouch devices on Linux](http://lii-enac.fr/en/architecture/linux-input/multitouch-devices.html)
diff --git a/src/tech/input/validate-keymaps.md b/src/tech/input/validate-keymaps.md new file mode 100644 index 0000000..8d8df9a --- /dev/null +++ b/src/tech/input/validate-keymaps.md
@@ -0,0 +1,96 @@ +<!-- + Copyright 2011 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. +--> + +# Validate Keymaps Tool # + +The Android framework has a small tool called `validatekeymaps` to validate the +syntax of input device configuration files, key layout files, key character +maps files and virtual key definition files. + +## Compilation ## + +To compile `validatekeymaps`, set up the development environment, download +the Android source tree, compile it, then run: + + $ mmm frameworks/base/tools/validatekeymaps + +This command should compile a host tool called validatekeymaps into the +`out/host/<os>/bin` directory. + +## Usage ## + +If you ran `envsetup.sh` to set up your development environment, then the +`validatekeymaps` tool should already be on your path. You can verify +this by running `validatekeymaps`. + + $ validatekeymaps + + Keymap Validation Tool + + Usage: + validatekeymaps [*.kl] [*.kcm] [*.idc] [virtualkeys.*] [...] + Validates the specified key layouts, key character maps, + input device configurations, or virtual key definitions. + +Then all you need to do is run `validatekeymaps` an give it the path of +one or more files to validate. + + $ validatekeymaps frameworks/base/data/keyboards/Generic.kl + + Validating file 'frameworks/base/data/keyboards/Generic.kl'... + No errors. + + Success. + +And if there is an error... + + $ validatekeymaps Bad.kl + + Validating file 'Bad.kl'... + E/KeyLayoutMap(87688): Bad.kl:24: Expected keyword, got 'ke'. + Error -22 parsing key layout file. + + Failed! + +## Automation ## + +It is a *very* good idea to run `validatekeymaps` on all configuration files +before installing them on a device. + +The process can easily be automated as part of the build system by using a +script or a makefile. + +The following sample makefile is based on the contents of +`frameworks/base/data/keyboards/Android.mk`. + + # This makefile performs build time validation of framework keymap files. + + LOCAL_PATH := $(call my-dir) + + # Validate all key maps. + include $(CLEAR_VARS) + + validatekeymaps := $(HOST_OUT_EXECUTABLES)/validatekeymaps$(HOST_EXECUTABLE_SUFFIX) + files := MyKeyboard.kl MyKeyboard.kcm MyTouchScreen.idc + + LOCAL_MODULE := validate_framework_keymaps + LOCAL_MODULE_TAGS := optional + LOCAL_REQUIRED_MODULES := validatekeymaps + + validate_framework_keymaps: $(files) + $(hide) $(validatekeymaps) $(files) + + include $(BUILD_PHONY_PACKAGE)
diff --git a/src/tech/sidebar.md b/src/tech/sidebar.md index 67ec0a4..3f81124 100644 --- a/src/tech/sidebar.md +++ b/src/tech/sidebar.md
@@ -3,3 +3,4 @@ - [Debugging](/tech/debugging/index.html) - [Encryption](/tech/encryption/index.html) - [Security](/tech/security/index.html) +- [Input](/tech/input/index.html)