diff options
Diffstat (limited to 'Documentation/input')
| -rw-r--r-- | Documentation/input/alps.txt | 71 | ||||
| -rw-r--r-- | Documentation/input/edt-ft5x06.txt | 54 | ||||
| -rw-r--r-- | Documentation/input/elantech.txt | 5 | ||||
| -rw-r--r-- | Documentation/input/event-codes.txt | 24 | ||||
| -rw-r--r-- | Documentation/input/gamepad.txt | 159 | ||||
| -rw-r--r-- | Documentation/input/input.txt | 2 | ||||
| -rw-r--r-- | Documentation/input/joystick-api.txt | 38 | ||||
| -rw-r--r-- | Documentation/input/joystick.txt | 8 | ||||
| -rw-r--r-- | Documentation/input/multi-touch-protocol.txt | 120 |
9 files changed, 421 insertions, 60 deletions
diff --git a/Documentation/input/alps.txt b/Documentation/input/alps.txt index ae8ba9a74ce..90bca6f988e 100644 --- a/Documentation/input/alps.txt +++ b/Documentation/input/alps.txt @@ -3,10 +3,26 @@ ALPS Touchpad Protocol Introduction ------------ - -Currently the ALPS touchpad driver supports four protocol versions in use by -ALPS touchpads, called versions 1, 2, 3, and 4. Information about the various -protocol versions is contained in the following sections. +Currently the ALPS touchpad driver supports five protocol versions in use by +ALPS touchpads, called versions 1, 2, 3, 4 and 5. + +Since roughly mid-2010 several new ALPS touchpads have been released and +integrated into a variety of laptops and netbooks. These new touchpads +have enough behavior differences that the alps_model_data definition +table, describing the properties of the different versions, is no longer +adequate. The design choices were to re-define the alps_model_data +table, with the risk of regression testing existing devices, or isolate +the new devices outside of the alps_model_data table. The latter design +choice was made. The new touchpad signatures are named: "Rushmore", +"Pinnacle", and "Dolphin", which you will see in the alps.c code. +For the purposes of this document, this group of ALPS touchpads will +generically be called "new ALPS touchpads". + +We experimented with probing the ACPI interface _HID (Hardware ID)/_CID +(Compatibility ID) definition as a way to uniquely identify the +different ALPS variants but there did not appear to be a 1:1 mapping. +In fact, it appeared to be an m:n mapping between the _HID and actual +hardware type. Detection --------- @@ -20,9 +36,13 @@ If the E6 report is successful, the touchpad model is identified using the "E7 report" sequence: E8-E7-E7-E7-E9. The response is the model signature and is matched against known models in the alps_model_data_array. -With protocol versions 3 and 4, the E7 report model signature is always -73-02-64. To differentiate between these versions, the response from the -"Enter Command Mode" sequence must be inspected as described below. +For older touchpads supporting protocol versions 3 and 4, the E7 report +model signature is always 73-02-64. To differentiate between these +versions, the response from the "Enter Command Mode" sequence must be +inspected as described below. + +The new ALPS touchpads have an E7 signature of 73-03-50 or 73-03-0A but +seem to be better differentiated by the EC Command Mode response. Command Mode ------------ @@ -47,6 +67,14 @@ address of the register being read, and the third contains the value of the register. Registers are written by writing the value one nibble at a time using the same encoding used for addresses. +For the new ALPS touchpads, the EC command is used to enter command +mode. The response in the new ALPS touchpads is significantly different, +and more important in determining the behavior. This code has been +separated from the original alps_model_data table and put in the +alps_identify function. For example, there seem to be two hardware init +sequences for the "Dolphin" touchpads as determined by the second byte +of the EC response. + Packet Format ------------- @@ -66,7 +94,7 @@ PS/2 packet format Note that the device never signals overflow condition. -ALPS Absolute Mode - Protocol Verion 1 +ALPS Absolute Mode - Protocol Version 1 -------------------------------------- byte 0: 1 0 0 0 1 x9 x8 x7 @@ -133,7 +161,7 @@ number of contacts (f1 and f0 in the table below). This packet only appears after a position packet with the mt bit set, and usually only appears when there are two or more contacts (although -occassionally it's seen with only a single contact). +occasionally it's seen with only a single contact). The final v3 packet type is the trackstick packet. @@ -187,3 +215,28 @@ There are several things worth noting here. well. So far no v4 devices with tracksticks have been encountered. + +ALPS Absolute Mode - Protocol Version 5 +--------------------------------------- +This is basically Protocol Version 3 but with different logic for packet +decode. It uses the same alps_process_touchpad_packet_v3 call with a +specialized decode_fields function pointer to correctly interpret the +packets. This appears to only be used by the Dolphin devices. + +For single-touch, the 6-byte packet format is: + + byte 0: 1 1 0 0 1 0 0 0 + byte 1: 0 x6 x5 x4 x3 x2 x1 x0 + byte 2: 0 y6 y5 y4 y3 y2 y1 y0 + byte 3: 0 M R L 1 m r l + byte 4: y10 y9 y8 y7 x10 x9 x8 x7 + byte 5: 0 z6 z5 z4 z3 z2 z1 z0 + +For mt, the format is: + + byte 0: 1 1 1 n3 1 n2 n1 x24 + byte 1: 1 y7 y6 y5 y4 y3 y2 y1 + byte 2: ? x2 x1 y12 y11 y10 y9 y8 + byte 3: 0 x23 x22 x21 x20 x19 x18 x17 + byte 4: 0 x9 x8 x7 x6 x5 x4 x3 + byte 5: 0 x16 x15 x14 x13 x12 x11 x10 diff --git a/Documentation/input/edt-ft5x06.txt b/Documentation/input/edt-ft5x06.txt new file mode 100644 index 00000000000..2032f0b7a8f --- /dev/null +++ b/Documentation/input/edt-ft5x06.txt @@ -0,0 +1,54 @@ +EDT ft5x06 based Polytouch devices +---------------------------------- + +The edt-ft5x06 driver is useful for the EDT "Polytouch" family of capacitive +touch screens. Note that it is *not* suitable for other devices based on the +focaltec ft5x06 devices, since they contain vendor-specific firmware. In +particular this driver is not suitable for the Nook tablet. + +It has been tested with the following devices: + * EP0350M06 + * EP0430M06 + * EP0570M06 + * EP0700M06 + +The driver allows configuration of the touch screen via a set of sysfs files: + +/sys/class/input/eventX/device/device/threshold: + allows setting the "click"-threshold in the range from 20 to 80. + +/sys/class/input/eventX/device/device/gain: + allows setting the sensitivity in the range from 0 to 31. Note that + lower values indicate higher sensitivity. + +/sys/class/input/eventX/device/device/offset: + allows setting the edge compensation in the range from 0 to 31. + +/sys/class/input/eventX/device/device/report_rate: + allows setting the report rate in the range from 3 to 14. + + +For debugging purposes the driver provides a few files in the debug +filesystem (if available in the kernel). In /sys/kernel/debug/edt_ft5x06 +you'll find the following files: + +num_x, num_y: + (readonly) contains the number of sensor fields in X- and + Y-direction. + +mode: + allows switching the sensor between "factory mode" and "operation + mode" by writing "1" or "0" to it. In factory mode (1) it is + possible to get the raw data from the sensor. Note that in factory + mode regular events don't get delivered and the options described + above are unavailable. + +raw_data: + contains num_x * num_y big endian 16 bit values describing the raw + values for each sensor field. Note that each read() call on this + files triggers a new readout. It is recommended to provide a buffer + big enough to contain num_x * num_y * 2 bytes. + +Note that reading raw_data gives a I/O error when the device is not in factory +mode. The same happens when reading/writing to the parameter files when the +device is not in regular operation mode. diff --git a/Documentation/input/elantech.txt b/Documentation/input/elantech.txt index 5602eb71ad5..e1ae127ed09 100644 --- a/Documentation/input/elantech.txt +++ b/Documentation/input/elantech.txt @@ -504,9 +504,12 @@ byte 5: * reg_10 bit 7 6 5 4 3 2 1 0 - 0 0 0 0 0 0 0 A + 0 0 0 0 R F T A A: 1 = enable absolute tracking + T: 1 = enable two finger mode auto correct + F: 1 = disable ABS Position Filter + R: 1 = enable real hardware resolution 6.2 Native absolute mode 6 byte packet format ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/input/event-codes.txt b/Documentation/input/event-codes.txt index 53305bd0818..c587a966413 100644 --- a/Documentation/input/event-codes.txt +++ b/Documentation/input/event-codes.txt @@ -196,6 +196,17 @@ EV_MSC: EV_MSC events are used for input and output events that do not fall under other categories. +A few EV_MSC codes have special meaning: + +* MSC_TIMESTAMP: + - Used to report the number of microseconds since the last reset. This event + should be coded as an uint32 value, which is allowed to wrap around with + no special consequence. It is assumed that the time difference between two + consecutive events is reliable on a reasonable time scale (hours). + A reset to zero can happen, in which case the time since the last event is + unknown. If the device does not provide this information, the driver must + not provide it to user space. + EV_LED: ---------- EV_LED events are used for input and output to set and query the state of @@ -270,6 +281,19 @@ gestures can normally be extracted from it. If INPUT_PROP_SEMI_MT is not set, the device is assumed to be a true MT device. +INPUT_PROP_TOPBUTTONPAD: +----------------------- +Some laptops, most notably the Lenovo *40 series provide a trackstick +device but do not have physical buttons associated with the trackstick +device. Instead, the top area of the touchpad is marked to show +visual/haptic areas for left, middle, right buttons intended to be used +with the trackstick. + +If INPUT_PROP_TOPBUTTONPAD is set, userspace should emulate buttons +accordingly. This property does not affect kernel behavior. +The kernel does not provide button emulation for such devices but treats +them as any other INPUT_PROP_BUTTONPAD device. + Guidelines: ========== The guidelines below ensure proper single-touch and multi-finger functionality. diff --git a/Documentation/input/gamepad.txt b/Documentation/input/gamepad.txt new file mode 100644 index 00000000000..3f6d8a5e9cd --- /dev/null +++ b/Documentation/input/gamepad.txt @@ -0,0 +1,159 @@ + Linux Gamepad API +---------------------------------------------------------------------------- + +1. Intro +~~~~~~~~ +Linux provides many different input drivers for gamepad hardware. To avoid +having user-space deal with different button-mappings for each gamepad, this +document defines how gamepads are supposed to report their data. + +2. Geometry +~~~~~~~~~~~ +As "gamepad" we define devices which roughly look like this: + + ____________________________ __ + / [__ZL__] [__ZR__] \ | + / [__ TL __] [__ TR __] \ | Front Triggers + __/________________________________\__ __| + / _ \ | + / /\ __ (N) \ | + / || __ |MO| __ _ _ \ | Main Pad + | <===DP===> |SE| |ST| (W) -|- (E) | | + \ || ___ ___ _ / | + /\ \/ / \ / \ (S) /\ __| + / \________ | LS | ____ | RS | ________/ \ | + | / \ \___/ / \ \___/ / \ | | Control Sticks + | / \_____/ \_____/ \ | __| + | / \ | + \_____/ \_____/ + + |________|______| |______|___________| + D-Pad Left Right Action Pad + Stick Stick + + |_____________| + Menu Pad + +Most gamepads have the following features: + - Action-Pad + 4 buttons in diamonds-shape (on the right side). The buttons are + differently labeled on most devices so we define them as NORTH, + SOUTH, WEST and EAST. + - D-Pad (Direction-pad) + 4 buttons (on the left side) that point up, down, left and right. + - Menu-Pad + Different constellations, but most-times 2 buttons: SELECT - START + Furthermore, many gamepads have a fancy branded button that is used as + special system-button. It often looks different to the other buttons and + is used to pop up system-menus or system-settings. + - Analog-Sticks + Analog-sticks provide freely moveable sticks to control directions. Not + all devices have both or any, but they are present at most times. + Analog-sticks may also provide a digital button if you press them. + - Triggers + Triggers are located on the upper-side of the pad in vertical direction. + Not all devices provide them, but the upper buttons are normally named + Left- and Right-Triggers, the lower buttons Z-Left and Z-Right. + - Rumble + Many devices provide force-feedback features. But are mostly just + simple rumble motors. + +3. Detection +~~~~~~~~~~~~ +All gamepads that follow the protocol described here map BTN_GAMEPAD. This is +an alias for BTN_SOUTH/BTN_A. It can be used to identify a gamepad as such. +However, not all gamepads provide all features, so you need to test for all +features that you need, first. How each feature is mapped is described below. + +Legacy drivers often don't comply to these rules. As we cannot change them +for backwards-compatibility reasons, you need to provide fixup mappings in +user-space yourself. Some of them might also provide module-options that +change the mappings so you can advise users to set these. + +All new gamepads are supposed to comply with this mapping. Please report any +bugs, if they don't. + +There are a lot of less-featured/less-powerful devices out there, which re-use +the buttons from this protocol. However, they try to do this in a compatible +fashion. For example, the "Nintendo Wii Nunchuk" provides two trigger buttons +and one analog stick. It reports them as if it were a gamepad with only one +analog stick and two trigger buttons on the right side. +But that means, that if you only support "real" gamepads, you must test +devices for _all_ reported events that you need. Otherwise, you will also get +devices that report a small subset of the events. + +No other devices, that do not look/feel like a gamepad, shall report these +events. + +4. Events +~~~~~~~~~ +Gamepads report the following events: + +Action-Pad: + Every gamepad device has at least 2 action buttons. This means, that every + device reports BTN_SOUTH (which BTN_GAMEPAD is an alias for). Regardless + of the labels on the buttons, the codes are sent according to the + physical position of the buttons. + Please note that 2- and 3-button pads are fairly rare and old. You might + want to filter gamepads that do not report all four. + 2-Button Pad: + If only 2 action-buttons are present, they are reported as BTN_SOUTH and + BTN_EAST. For vertical layouts, the upper button is BTN_EAST. For + horizontal layouts, the button more on the right is BTN_EAST. + 3-Button Pad: + If only 3 action-buttons are present, they are reported as (from left + to right): BTN_WEST, BTN_SOUTH, BTN_EAST + If the buttons are aligned perfectly vertically, they are reported as + (from top down): BTN_WEST, BTN_SOUTH, BTN_EAST + 4-Button Pad: + If all 4 action-buttons are present, they can be aligned in two + different formations. If diamond-shaped, they are reported as BTN_NORTH, + BTN_WEST, BTN_SOUTH, BTN_EAST according to their physical location. + If rectangular-shaped, the upper-left button is BTN_NORTH, lower-left + is BTN_WEST, lower-right is BTN_SOUTH and upper-right is BTN_EAST. + +D-Pad: + Every gamepad provides a D-Pad with four directions: Up, Down, Left, Right + Some of these are available as digital buttons, some as analog buttons. Some + may even report both. The kernel does not convert between these so + applications should support both and choose what is more appropriate if + both are reported. + Digital buttons are reported as: + BTN_DPAD_* + Analog buttons are reported as: + ABS_HAT0X and ABS_HAT0Y + (for ABS values negative is left/up, positive is right/down) + +Analog-Sticks: + The left analog-stick is reported as ABS_X, ABS_Y. The right analog stick is + reported as ABS_RX, ABS_RY. Zero, one or two sticks may be present. + If analog-sticks provide digital buttons, they are mapped accordingly as + BTN_THUMBL (first/left) and BTN_THUMBR (second/right). + (for ABS values negative is left/up, positive is right/down) + +Triggers: + Trigger buttons can be available as digital or analog buttons or both. User- + space must correctly deal with any situation and choose the most appropriate + mode. + Upper trigger buttons are reported as BTN_TR or ABS_HAT1X (right) and BTN_TL + or ABS_HAT1Y (left). Lower trigger buttons are reported as BTN_TR2 or + ABS_HAT2X (right/ZR) and BTN_TL2 or ABS_HAT2Y (left/ZL). + If only one trigger-button combination is present (upper+lower), they are + reported as "right" triggers (BTN_TR/ABS_HAT1X). + (ABS trigger values start at 0, pressure is reported as positive values) + +Menu-Pad: + Menu buttons are always digital and are mapped according to their location + instead of their labels. That is: + 1-button Pad: Mapped as BTN_START + 2-button Pad: Left button mapped as BTN_SELECT, right button mapped as + BTN_START + Many pads also have a third button which is branded or has a special symbol + and meaning. Such buttons are mapped as BTN_MODE. Examples are the Nintendo + "HOME" button, the XBox "X"-button or Sony "PS" button. + +Rumble: + Rumble is advertised as FF_RUMBLE. + +---------------------------------------------------------------------------- + Written 2013 by David Herrmann <dh.herrmann@gmail.com> diff --git a/Documentation/input/input.txt b/Documentation/input/input.txt index 666c06c5ab0..0acfddbe202 100644 --- a/Documentation/input/input.txt +++ b/Documentation/input/input.txt @@ -226,7 +226,7 @@ And so on up to js31. ~~~~~~~~~~~ evdev is the generic input event interface. It passes the events generated in the kernel straight to the program, with timestamps. The -API is still evolving, but should be useable now. It's described in +API is still evolving, but should be usable now. It's described in section 5. This should be the way for GPM and X to get keyboard and mouse diff --git a/Documentation/input/joystick-api.txt b/Documentation/input/joystick-api.txt index c507330740c..943b18eac91 100644 --- a/Documentation/input/joystick-api.txt +++ b/Documentation/input/joystick-api.txt @@ -16,14 +16,14 @@ joystick. By default, the device is opened in blocking mode. - int fd = open ("/dev/js0", O_RDONLY); + int fd = open ("/dev/input/js0", O_RDONLY); 2. Event Reading ~~~~~~~~~~~~~~~~ struct js_event e; - read (fd, &e, sizeof(struct js_event)); + read (fd, &e, sizeof(e)); where js_event is defined as @@ -34,8 +34,8 @@ where js_event is defined as __u8 number; /* axis/button number */ }; -If the read is successful, it will return sizeof(struct js_event), unless -you wanted to read more than one event per read as described in section 3.1. +If the read is successful, it will return sizeof(e), unless you wanted to read +more than one event per read as described in section 3.1. 2.1 js_event.type @@ -99,9 +99,9 @@ may work well if you handle JS_EVENT_INIT events separately, if ((js_event.type & ~JS_EVENT_INIT) == JS_EVENT_BUTTON) { if (js_event.value) - buttons_state |= (1 << js_event.number); - else - buttons_state &= ~(1 << js_event.number); + buttons_state |= (1 << js_event.number); + else + buttons_state &= ~(1 << js_event.number); } is much safer since it can't lose sync with the driver. As you would @@ -144,14 +144,14 @@ all events on the queue (that is, until you get a -1). For example, while (1) { - while (read (fd, &e, sizeof(struct js_event)) > 0) { - process_event (e); - } - /* EAGAIN is returned when the queue is empty */ - if (errno != EAGAIN) { - /* error */ - } - /* do something interesting with processed events */ + while (read (fd, &e, sizeof(e)) > 0) { + process_event (e); + } + /* EAGAIN is returned when the queue is empty */ + if (errno != EAGAIN) { + /* error */ + } + /* do something interesting with processed events */ } One reason for emptying the queue is that if it gets full you'll start @@ -181,7 +181,7 @@ at a time using the typical read(2) functionality. For that, you would replace the read above with something like struct js_event mybuffer[0xff]; - int i = read (fd, mybuffer, sizeof(struct mybuffer)); + int i = read (fd, mybuffer, sizeof(mybuffer)); In this case, read would return -1 if the queue was empty, or some other value in which the number of events read would be i / @@ -269,9 +269,9 @@ The driver offers backward compatibility, though. Here's a quick summary: struct JS_DATA_TYPE js; while (1) { if (read (fd, &js, JS_RETURN) != JS_RETURN) { - /* error */ - } - usleep (1000); + /* error */ + } + usleep (1000); } As you can figure out from the example, the read returns immediately, diff --git a/Documentation/input/joystick.txt b/Documentation/input/joystick.txt index 304262bb661..8d027dc86c1 100644 --- a/Documentation/input/joystick.txt +++ b/Documentation/input/joystick.txt @@ -116,7 +116,7 @@ your needs: For testing the joystick driver functionality, there is the jstest program in the utilities package. You run it by typing: - jstest /dev/js0 + jstest /dev/input/js0 And it should show a line with the joystick values, which update as you move the stick, and press its buttons. The axes should all be zero when the @@ -136,7 +136,7 @@ joystick should be autocalibrated by the driver automagically. However, with some analog joysticks, that either do not use linear resistors, or if you want better precision, you can use the jscal program - jscal -c /dev/js0 + jscal -c /dev/input/js0 included in the joystick package to set better correction coefficients than what the driver would choose itself. @@ -145,7 +145,7 @@ what the driver would choose itself. calibration using the jstest command, and if you do, you then can save the correction coefficients into a file - jscal -p /dev/js0 > /etc/joystick.cal + jscal -p /dev/input/js0 > /etc/joystick.cal And add a line to your rc script executing that file @@ -556,7 +556,7 @@ interface, and "old" for the "0.x" interface. You run it by typing: 5. FAQ ~~~~~~ -Q: Running 'jstest /dev/js0' results in "File not found" error. What's the +Q: Running 'jstest /dev/input/js0' results in "File not found" error. What's the cause? A: The device files don't exist. Create them (see section 2.2). diff --git a/Documentation/input/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.txt index 543101c5bf2..7b4f59c09ee 100644 --- a/Documentation/input/multi-touch-protocol.txt +++ b/Documentation/input/multi-touch-protocol.txt @@ -80,6 +80,8 @@ Userspace can detect that a driver can report more total contacts than slots by noting that the largest supported BTN_TOOL_*TAP event is larger than the total number of type B slots reported in the absinfo for the ABS_MT_SLOT axis. +The minimum value of the ABS_MT_SLOT axis must be 0. + Protocol Example A ------------------ @@ -162,26 +164,48 @@ are divided into categories, to allow for partial implementation. The minimum set consists of ABS_MT_POSITION_X and ABS_MT_POSITION_Y, which allows for multiple contacts to be tracked. If the device supports it, the ABS_MT_TOUCH_MAJOR and ABS_MT_WIDTH_MAJOR may be used to provide the size -of the contact area and approaching contact, respectively. +of the contact area and approaching tool, respectively. The TOUCH and WIDTH parameters have a geometrical interpretation; imagine looking through a window at someone gently holding a finger against the glass. You will see two regions, one inner region consisting of the part of the finger actually touching the glass, and one outer region formed by -the perimeter of the finger. The diameter of the inner region is the -ABS_MT_TOUCH_MAJOR, the diameter of the outer region is -ABS_MT_WIDTH_MAJOR. Now imagine the person pressing the finger harder -against the glass. The inner region will increase, and in general, the -ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR, which is always smaller than -unity, is related to the contact pressure. For pressure-based devices, +the perimeter of the finger. The center of the touching region (a) is +ABS_MT_POSITION_X/Y and the center of the approaching finger (b) is +ABS_MT_TOOL_X/Y. The touch diameter is ABS_MT_TOUCH_MAJOR and the finger +diameter is ABS_MT_WIDTH_MAJOR. Now imagine the person pressing the finger +harder against the glass. The touch region will increase, and in general, +the ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR, which is always smaller +than unity, is related to the contact pressure. For pressure-based devices, ABS_MT_PRESSURE may be used to provide the pressure on the contact area instead. Devices capable of contact hovering can use ABS_MT_DISTANCE to indicate the distance between the contact and the surface. -In addition to the MAJOR parameters, the oval shape of the contact can be -described by adding the MINOR parameters, such that MAJOR and MINOR are the -major and minor axis of an ellipse. Finally, the orientation of the oval -shape can be describe with the ORIENTATION parameter. + + Linux MT Win8 + __________ _______________________ + / \ | | + / \ | | + / ____ \ | | + / / \ \ | | + \ \ a \ \ | a | + \ \____/ \ | | + \ \ | | + \ b \ | b | + \ \ | | + \ \ | | + \ \ | | + \ / | | + \ / | | + \ / | | + \__________/ |_______________________| + + +In addition to the MAJOR parameters, the oval shape of the touch and finger +regions can be described by adding the MINOR parameters, such that MAJOR +and MINOR are the major and minor axis of an ellipse. The orientation of +the touch ellipse can be described with the ORIENTATION parameter, and the +direction of the finger ellipse is given by the vector (a - b). For type A devices, further specification of the touch shape is possible via ABS_MT_BLOB_ID. @@ -224,7 +248,7 @@ tool. Omit if circular [4]. The above four values can be used to derive additional information about the contact. The ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR approximates the notion of pressure. The fingers of the hand and the palm all have -different characteristic widths [1]. +different characteristic widths. ABS_MT_PRESSURE @@ -240,17 +264,24 @@ the contact is hovering above the surface. ABS_MT_ORIENTATION -The orientation of the ellipse. The value should describe a signed quarter -of a revolution clockwise around the touch center. The signed value range -is arbitrary, but zero should be returned for a finger aligned along the Y -axis of the surface, a negative value when finger is turned to the left, and -a positive value when finger turned to the right. When completely aligned with -the X axis, the range max should be returned. Orientation can be omitted -if the touching object is circular, or if the information is not available -in the kernel driver. Partial orientation support is possible if the device -can distinguish between the two axis, but not (uniquely) any values in -between. In such cases, the range of ABS_MT_ORIENTATION should be [0, 1] -[4]. +The orientation of the touching ellipse. The value should describe a signed +quarter of a revolution clockwise around the touch center. The signed value +range is arbitrary, but zero should be returned for an ellipse aligned with +the Y axis of the surface, a negative value when the ellipse is turned to +the left, and a positive value when the ellipse is turned to the +right. When completely aligned with the X axis, the range max should be +returned. + +Touch ellipsis are symmetrical by default. For devices capable of true 360 +degree orientation, the reported orientation must exceed the range max to +indicate more than a quarter of a revolution. For an upside-down finger, +range max * 2 should be returned. + +Orientation can be omitted if the touch area is circular, or if the +information is not available in the kernel driver. Partial orientation +support is possible if the device can distinguish between the two axis, but +not (uniquely) any values in between. In such cases, the range of +ABS_MT_ORIENTATION should be [0, 1] [4]. ABS_MT_POSITION_X @@ -260,6 +291,23 @@ ABS_MT_POSITION_Y The surface Y coordinate of the center of the touching ellipse. +ABS_MT_TOOL_X + +The surface X coordinate of the center of the approaching tool. Omit if +the device cannot distinguish between the intended touch point and the +tool itself. + +ABS_MT_TOOL_Y + +The surface Y coordinate of the center of the approaching tool. Omit if the +device cannot distinguish between the intended touch point and the tool +itself. + +The four position values can be used to separate the position of the touch +from the position of the tool. If both positions are present, the major +tool axis points towards the touch point [1]. Otherwise, the tool axes are +aligned with the touch axes. + ABS_MT_TOOL_TYPE The type of approaching tool. A lot of kernel drivers cannot distinguish @@ -305,6 +353,28 @@ The range of ABS_MT_ORIENTATION should be set to [0, 1], to indicate that the device can distinguish between a finger along the Y axis (0) and a finger along the X axis (1). +For win8 devices with both T and C coordinates, the position mapping is + + ABS_MT_POSITION_X := T_X + ABS_MT_POSITION_Y := T_Y + ABS_MT_TOOL_X := C_X + ABS_MT_TOOL_X := C_Y + +Unfortunately, there is not enough information to specify both the touching +ellipse and the tool ellipse, so one has to resort to approximations. One +simple scheme, which is compatible with earlier usage, is: + + ABS_MT_TOUCH_MAJOR := min(X, Y) + ABS_MT_TOUCH_MINOR := <not used> + ABS_MT_ORIENTATION := <not used> + ABS_MT_WIDTH_MAJOR := min(X, Y) + distance(T, C) + ABS_MT_WIDTH_MINOR := min(X, Y) + +Rationale: We have no information about the orientation of the touching +ellipse, so approximate it with an inscribed circle instead. The tool +ellipse should align with the vector (T - C), so the diameter must +increase with distance(T, C). Finally, assume that the touch diameter is +equal to the tool thickness, and we arrive at the formulas above. Finger Tracking --------------- @@ -338,9 +408,7 @@ subsequent events of the same type refer to different fingers. For example usage of the type A protocol, see the bcm5974 driver. For example usage of the type B protocol, see the hid-egalax driver. -[1] With the extension ABS_MT_APPROACH_X and ABS_MT_APPROACH_Y, the -difference between the contact position and the approaching tool position -could be used to derive tilt. +[1] Also, the difference (TOOL_X - POSITION_X) can be used to model tilt. [2] The list can of course be extended. [3] The mtdev project: http://bitmath.org/code/mtdev/. [4] See the section on event computation. |