Documentation/input/multi-touch-protocol.txt

   1 Multi-touch (MT) Protocol
   2 -------------------------
   3         Copyright (C) 2009      Henrik Rydberg <rydberg@euromail.se>
   4
   5
   6 Introduction
   7 ------------
   8
   9 In order to utilize the full power of the new multi-touch devices, a way to
  10 report detailed finger data to user space is needed. This document
  11 describes the multi-touch (MT) protocol which allows kernel drivers to
  12 report details for an arbitrary number of fingers.
  13
  14
  15 Usage
  16 -----
  17
  18 Anonymous finger details are sent sequentially as separate packets of ABS
  19 events. Only the ABS_MT events are recognized as part of a finger
  20 packet. The end of a packet is marked by calling the input_mt_sync()
  21 function, which generates a SYN_MT_REPORT event. This instructs the
  22 receiver to accept the data for the current finger and prepare to receive
  23 another. The end of a multi-touch transfer is marked by calling the usual
  24 input_sync() function. This instructs the receiver to act upon events
  25 accumulated since last EV_SYN/SYN_REPORT and prepare to receive a new
  26 set of events/packets.
  27
  28 A set of ABS_MT events with the desired properties is defined. The events
  29 are divided into categories, to allow for partial implementation.  The
  30 minimum set consists of ABS_MT_POSITION_X and ABS_MT_POSITION_Y, which
  31 allows for multiple fingers to be tracked.  If the device supports it, the
  32 ABS_MT_TOUCH_MAJOR and ABS_MT_WIDTH_MAJOR may be used to provide the size
  33 of the contact area and approaching finger, respectively.
  34
  35 The TOUCH and WIDTH parameters have a geometrical interpretation; imagine
  36 looking through a window at someone gently holding a finger against the
  37 glass.  You will see two regions, one inner region consisting of the part
  38 of the finger actually touching the glass, and one outer region formed by
  39 the perimeter of the finger. The diameter of the inner region is the
  40 ABS_MT_TOUCH_MAJOR, the diameter of the outer region is
  41 ABS_MT_WIDTH_MAJOR. Now imagine the person pressing the finger harder
  42 against the glass. The inner region will increase, and in general, the
  43 ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR, which is always smaller than
  44 unity, is related to the finger pressure. For pressure-based devices,
  45 ABS_MT_PRESSURE may be used to provide the pressure on the contact area
  46 instead.
  47
  48 In addition to the MAJOR parameters, the oval shape of the finger can be
  49 described by adding the MINOR parameters, such that MAJOR and MINOR are the
  50 major and minor axis of an ellipse. Finally, the orientation of the oval
  51 shape can be describe with the ORIENTATION parameter.
  52
  53 The ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a
  54 finger or a pen or something else.  Devices with more granular information
  55 may specify general shapes as blobs, i.e., as a sequence of rectangular
  56 shapes grouped together by an ABS_MT_BLOB_ID. Finally, for the few devices
  57 that currently support it, the ABS_MT_TRACKING_ID event may be used to
  58 report finger tracking from hardware [5].
  59
  60 Here is what a minimal event sequence for a two-finger touch would look
  61 like:
  62
  63    ABS_MT_POSITION_X
  64    ABS_MT_POSITION_Y
  65    SYN_MT_REPORT
  66    ABS_MT_POSITION_X
  67    ABS_MT_POSITION_Y
  68    SYN_MT_REPORT
  69    SYN_REPORT
  70
  71 Here is the sequence after lifting one of the fingers:
  72
  73    ABS_MT_POSITION_X
  74    ABS_MT_POSITION_Y
  75    SYN_MT_REPORT
  76    SYN_REPORT
  77
  78 And here is the sequence after lifting the remaining finger:
  79
  80    SYN_MT_REPORT
  81    SYN_REPORT
  82
  83 If the driver reports one of BTN_TOUCH or ABS_PRESSURE in addition to the
  84 ABS_MT events, the last SYN_MT_REPORT event may be omitted. Otherwise, the
  85 last SYN_REPORT will be dropped by the input core, resulting in no
  86 zero-finger event reaching userland.
  87
  88 Event Semantics
  89 ---------------
  90
  91 The word "contact" is used to describe a tool which is in direct contact
  92 with the surface. A finger, a pen or a rubber all classify as contacts.
  93
  94 ABS_MT_TOUCH_MAJOR
  95
  96 The length of the major axis of the contact. The length should be given in
  97 surface units. If the surface has an X times Y resolution, the largest
  98 possible value of ABS_MT_TOUCH_MAJOR is sqrt(X^2 + Y^2), the diagonal [4].
  99
 100 ABS_MT_TOUCH_MINOR
 101
 102 The length, in surface units, of the minor axis of the contact. If the
 103 contact is circular, this event can be omitted [4].
 104
 105 ABS_MT_WIDTH_MAJOR
 106
 107 The length, in surface units, of the major axis of the approaching
 108 tool. This should be understood as the size of the tool itself. The
 109 orientation of the contact and the approaching tool are assumed to be the
 110 same [4].
 111
 112 ABS_MT_WIDTH_MINOR
 113
 114 The length, in surface units, of the minor axis of the approaching
 115 tool. Omit if circular [4].
 116
 117 The above four values can be used to derive additional information about
 118 the contact. The ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR approximates
 119 the notion of pressure. The fingers of the hand and the palm all have
 120 different characteristic widths [1].
 121
 122 ABS_MT_PRESSURE
 123
 124 The pressure, in arbitrary units, on the contact area. May be used instead
 125 of TOUCH and WIDTH for pressure-based devices or any device with a spatial
 126 signal intensity distribution.
 127
 128 ABS_MT_ORIENTATION
 129
 130 The orientation of the ellipse. The value should describe a signed quarter
 131 of a revolution clockwise around the touch center. The signed value range
 132 is arbitrary, but zero should be returned for a finger aligned along the Y
 133 axis of the surface, a negative value when finger is turned to the left, and
 134 a positive value when finger turned to the right. When completely aligned with
 135 the X axis, the range max should be returned.  Orientation can be omitted
 136 if the touching object is circular, or if the information is not available
 137 in the kernel driver. Partial orientation support is possible if the device
 138 can distinguish between the two axis, but not (uniquely) any values in
 139 between. In such cases, the range of ABS_MT_ORIENTATION should be [0, 1]
 140 [4].
 141
 142 ABS_MT_POSITION_X
 143
 144 The surface X coordinate of the center of the touching ellipse.
 145
 146 ABS_MT_POSITION_Y
 147
 148 The surface Y coordinate of the center of the touching ellipse.
 149
 150 ABS_MT_TOOL_TYPE
 151
 152 The type of approaching tool. A lot of kernel drivers cannot distinguish
 153 between different tool types, such as a finger or a pen. In such cases, the
 154 event should be omitted. The protocol currently supports MT_TOOL_FINGER and
 155 MT_TOOL_PEN [2].
 156
 157 ABS_MT_BLOB_ID
 158
 159 The BLOB_ID groups several packets together into one arbitrarily shaped
 160 contact. This is a low-level anonymous grouping, and should not be confused
 161 with the high-level trackingID [5]. Most kernel drivers will not have blob
 162 capability, and can safely omit the event.
 163
 164 ABS_MT_TRACKING_ID
 165
 166 The TRACKING_ID identifies an initiated contact throughout its life cycle
 167 [5]. There are currently only a few devices that support it, so this event
 168 should normally be omitted.
 169
 170
 171 Event Computation
 172 -----------------
 173
 174 The flora of different hardware unavoidably leads to some devices fitting
 175 better to the MT protocol than others. To simplify and unify the mapping,
 176 this section gives recipes for how to compute certain events.
 177
 178 For devices reporting contacts as rectangular shapes, signed orientation
 179 cannot be obtained. Assuming X and Y are the lengths of the sides of the
 180 touching rectangle, here is a simple formula that retains the most
 181 information possible:
 182
 183    ABS_MT_TOUCH_MAJOR := max(X, Y)
 184    ABS_MT_TOUCH_MINOR := min(X, Y)
 185    ABS_MT_ORIENTATION := bool(X > Y)
 186
 187 The range of ABS_MT_ORIENTATION should be set to [0, 1], to indicate that
 188 the device can distinguish between a finger along the Y axis (0) and a
 189 finger along the X axis (1).
 190
 191
 192 Finger Tracking
 193 ---------------
 194
 195 The kernel driver should generate an arbitrary enumeration of the set of
 196 anonymous contacts currently on the surface. The order in which the packets
 197 appear in the event stream is not important.
 198
 199 The process of finger tracking, i.e., to assign a unique trackingID to each
 200 initiated contact on the surface, is left to user space; preferably the
 201 multi-touch X driver [3]. In that driver, the trackingID stays the same and
 202 unique until the contact vanishes (when the finger leaves the surface). The
 203 problem of assigning a set of anonymous fingers to a set of identified
 204 fingers is a euclidian bipartite matching problem at each event update, and
 205 relies on a sufficiently rapid update rate.
 206
 207 There are a few devices that support trackingID in hardware. User space can
 208 make use of these native identifiers to reduce bandwidth and cpu usage.
 209
 210
 211 Gestures
 212 --------
 213
 214 In the specific application of creating gesture events, the TOUCH and WIDTH
 215 parameters can be used to, e.g., approximate finger pressure or distinguish
 216 between index finger and thumb. With the addition of the MINOR parameters,
 217 one can also distinguish between a sweeping finger and a pointing finger,
 218 and with ORIENTATION, one can detect twisting of fingers.
 219
 220
 221 Notes
 222 -----
 223
 224 In order to stay compatible with existing applications, the data
 225 reported in a finger packet must not be recognized as single-touch
 226 events. In addition, all finger data must bypass input filtering,
 227 since subsequent events of the same type refer to different fingers.
 228
 229 The first kernel driver to utilize the MT protocol is the bcm5974 driver,
 230 where examples can be found.
 231
 232 [1] With the extension ABS_MT_APPROACH_X and ABS_MT_APPROACH_Y, the
 233 difference between the contact position and the approaching tool position
 234 could be used to derive tilt.
 235 [2] The list can of course be extended.
 236 [3] Multitouch X driver project: http://bitmath.org/code/multitouch/.
 237 [4] See the section on event computation.
 238 [5] See the section on finger tracking.