/Documentation/input/multi-touch-protocol.txt

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