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. The end of multi-touch
  22 transfer is marked by calling the usual input_sync() function.
  23
  24 A set of ABS_MT events with the desired properties is defined. The events
  25 are divided into categories, to allow for partial implementation.  The
  26 minimum set consists of ABS_MT_TOUCH_MAJOR, ABS_MT_POSITION_X and
  27 ABS_MT_POSITION_Y, which allows for multiple fingers to be tracked.  If the
  28 device supports it, the ABS_MT_WIDTH_MAJOR may be used to provide the size
  29 of the approaching finger. Anisotropy and direction may be specified with
  30 ABS_MT_TOUCH_MINOR, ABS_MT_WIDTH_MINOR and ABS_MT_ORIENTATION. Devices with
  31 more granular information may specify general shapes as blobs, i.e., as a
  32 sequence of rectangular shapes grouped together by an
  33 ABS_MT_BLOB_ID. Finally, the ABS_MT_TOOL_TYPE may be used to specify
  34 whether the touching tool is a finger or a pen or something else.
  35
  36
  37 Event Semantics
  38 ---------------
  39
  40 The word "contact" is used to describe a tool which is in direct contact
  41 with the surface. A finger, a pen or a rubber all classify as contacts.
  42
  43 ABS_MT_TOUCH_MAJOR
  44
  45 The length of the major axis of the contact. The length should be given in
  46 surface units. If the surface has an X times Y resolution, the largest
  47 possible value of ABS_MT_TOUCH_MAJOR is sqrt(X^2 + Y^2), the diagonal.
  48
  49 ABS_MT_TOUCH_MINOR
  50
  51 The length, in surface units, of the minor axis of the contact. If the
  52 contact is circular, this event can be omitted.
  53
  54 ABS_MT_WIDTH_MAJOR
  55
  56 The length, in surface units, of the major axis of the approaching
  57 tool. This should be understood as the size of the tool itself. The
  58 orientation of the contact and the approaching tool are assumed to be the
  59 same.
  60
  61 ABS_MT_WIDTH_MINOR
  62
  63 The length, in surface units, of the minor axis of the approaching
  64 tool. Omit if circular.
  65
  66 The above four values can be used to derive additional information about
  67 the contact. The ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR approximates
  68 the notion of pressure. The fingers of the hand and the palm all have
  69 different characteristic widths [1].
  70
  71 ABS_MT_ORIENTATION
  72
  73 The orientation of the ellipse. The value should describe half a revolution
  74 clockwise around the touch center. The scale of the value is arbitrary, but
  75 zero should be returned for an ellipse aligned along the Y axis of the
  76 surface. As an example, an index finger placed straight onto the axis could
  77 return zero orientation, something negative when twisted to the left, and
  78 something positive when twisted to the right. This value can be omitted if
  79 the touching object is circular, or if the information is not available in
  80 the kernel driver.
  81
  82 ABS_MT_POSITION_X
  83
  84 The surface X coordinate of the center of the touching ellipse.
  85
  86 ABS_MT_POSITION_Y
  87
  88 The surface Y coordinate of the center of the touching ellipse.
  89
  90 ABS_MT_TOOL_TYPE
  91
  92 The type of approaching tool. A lot of kernel drivers cannot distinguish
  93 between different tool types, such as a finger or a pen. In such cases, the
  94 event should be omitted. The protocol currently supports MT_TOOL_FINGER and
  95 MT_TOOL_PEN [2].
  96
  97 ABS_MT_BLOB_ID
  98
  99 The BLOB_ID groups several packets together into one arbitrarily shaped
 100 contact. This is a low-level anonymous grouping, and should not be confused
 101 with the high-level contactID, explained below. Most kernel drivers will
 102 not have this capability, and can safely omit the event.
 103
 104
 105 Finger Tracking
 106 ---------------
 107
 108 The kernel driver should generate an arbitrary enumeration of the set of
 109 anonymous contacts currently on the surface. The order in which the packets
 110 appear in the event stream is not important.
 111
 112 The process of finger tracking, i.e., to assign a unique contactID to each
 113 initiated contact on the surface, is left to user space; preferably the
 114 multi-touch X driver [3]. In that driver, the contactID stays the same and
 115 unique until the contact vanishes (when the finger leaves the surface). The
 116 problem of assigning a set of anonymous fingers to a set of identified
 117 fingers is a euclidian bipartite matching problem at each event update, and
 118 relies on a sufficiently rapid update rate.
 119
 120 Notes
 121 -----
 122
 123 In order to stay compatible with existing applications, the data
 124 reported in a finger packet must not be recognized as single-touch
 125 events. In addition, all finger data must bypass input filtering,
 126 since subsequent events of the same type refer to different fingers.
 127
 128 The first kernel driver to utilize the MT protocol is the bcm5974 driver,
 129 where examples can be found.
 130
 131 [1] With the extension ABS_MT_APPROACH_X and ABS_MT_APPROACH_Y, the
 132 difference between the contact position and the approaching tool position
 133 could be used to derive tilt.
 134 [2] The list can of course be extended.
 135 [3] The multi-touch X driver is currently in the prototyping stage. At the
 136 time of writing (April 2009), the MT protocol is not yet merged, and the
 137 prototype implements finger matching, basic mouse support and two-finger
 138 scrolling. The project aims at improving the quality of current multi-touch
 139 functionality available in the synaptics X driver, and in addition
 140 implement more advanced gestures.