Multi-touch (MT) Protocol ------------------------- Copyright (C) 2009 Henrik Rydberg Introduction ------------ In order to utilize the full power of the new multi-touch devices, a way to report detailed finger data to user space is needed. This document describes the multi-touch (MT) protocol which allows kernel drivers to report details for an arbitrary number of fingers. Usage ----- Anonymous finger details are sent sequentially as separate packets of ABS events. Only the ABS_MT events are recognized as part of a finger packet. The end of a packet is marked by calling the input_mt_sync() function, which generates a SYN_MT_REPORT event. This instructs the receiver to accept the data for the current finger and prepare to receive another. The end of a multi-touch transfer is marked by calling the usual input_sync() function. This instructs the receiver to act upon events accumulated since last EV_SYN/SYN_REPORT and prepare to receive a new set of events/packets. A set of ABS_MT events with the desired properties is defined. The events are divided into categories, to allow for partial implementation. The minimum set consists of ABS_MT_TOUCH_MAJOR, ABS_MT_POSITION_X and ABS_MT_POSITION_Y, which allows for multiple fingers to be tracked. If the device supports it, the ABS_MT_WIDTH_MAJOR may be used to provide the size of the approaching finger. Anisotropy and direction may be specified with ABS_MT_TOUCH_MINOR, ABS_MT_WIDTH_MINOR and ABS_MT_ORIENTATION. The ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a finger or a pen or something else. Devices with more granular information may specify general shapes as blobs, i.e., as a sequence of rectangular shapes grouped together by an ABS_MT_BLOB_ID. Finally, for the few devices that currently support it, the ABS_MT_TRACKING_ID event may be used to report finger tracking from hardware [5]. Here is what a minimal event sequence for a two-finger touch would look like: ABS_MT_TOUCH_MAJOR ABS_MT_POSITION_X ABS_MT_POSITION_Y SYN_MT_REPORT ABS_MT_TOUCH_MAJOR ABS_MT_POSITION_X ABS_MT_POSITION_Y SYN_MT_REPORT SYN_REPORT Event Semantics --------------- The word "contact" is used to describe a tool which is in direct contact with the surface. A finger, a pen or a rubber all classify as contacts. ABS_MT_TOUCH_MAJOR The length of the major axis of the contact. The length should be given in surface units. If the surface has an X times Y resolution, the largest possible value of ABS_MT_TOUCH_MAJOR is sqrt(X^2 + Y^2), the diagonal [4]. ABS_MT_TOUCH_MINOR The length, in surface units, of the minor axis of the contact. If the contact is circular, this event can be omitted [4]. ABS_MT_WIDTH_MAJOR The length, in surface units, of the major axis of the approaching tool. This should be understood as the size of the tool itself. The orientation of the contact and the approaching tool are assumed to be the same [4]. ABS_MT_WIDTH_MINOR The length, in surface units, of the minor axis of the approaching 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]. 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]. ABS_MT_POSITION_X The surface X coordinate of the center of the touching ellipse. ABS_MT_POSITION_Y The surface Y coordinate of the center of the touching ellipse. ABS_MT_TOOL_TYPE The type of approaching tool. A lot of kernel drivers cannot distinguish between different tool types, such as a finger or a pen. In such cases, the event should be omitted. The protocol currently supports MT_TOOL_FINGER and MT_TOOL_PEN [2]. ABS_MT_BLOB_ID The BLOB_ID groups several packets together into one arbitrarily shaped contact. This is a low-level anonymous grouping, and should not be confused with the high-level trackingID [5]. Most kernel drivers will not have blob capability, and can safely omit the event. ABS_MT_TRACKING_ID The TRACKING_ID identifies an initiated contact throughout its life cycle [5]. There are currently only a few devices that support it, so this event should normally be omitted. Event Computation ----------------- The flora of different hardware unavoidably leads to some devices fitting better to the MT protocol than others. To simplify and unify the mapping, this section gives recipes for how to compute certain events. For devices reporting contacts as rectangular shapes, signed orientation cannot be obtained. Assuming X and Y are the lengths of the sides of the touching rectangle, here is a simple formula that retains the most information possible: ABS_MT_TOUCH_MAJOR := max(X, Y) ABS_MT_TOUCH_MINOR := min(X, Y) ABS_MT_ORIENTATION := bool(X > Y) 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). Finger Tracking --------------- The kernel driver should generate an arbitrary enumeration of the set of anonymous contacts currently on the surface. The order in which the packets appear in the event stream is not important. The process of finger tracking, i.e., to assign a unique trackingID to each initiated contact on the surface, is left to user space; preferably the multi-touch X driver [3]. In that driver, the trackingID stays the same and unique until the contact vanishes (when the finger leaves the surface). The problem of assigning a set of anonymous fingers to a set of identified fingers is a euclidian bipartite matching problem at each event update, and relies on a sufficiently rapid update rate. There are a few devices that support trackingID in hardware. User space can make use of these native identifiers to reduce bandwidth and cpu usage. Notes ----- In order to stay compatible with existing applications, the data reported in a finger packet must not be recognized as single-touch events. In addition, all finger data must bypass input filtering, since subsequent events of the same type refer to different fingers. The first kernel driver to utilize the MT protocol is the bcm5974 driver, where examples can be found. [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. [2] The list can of course be extended. [3] The multi-touch X driver is currently in the prototyping stage. At the time of writing (April 2009), the MT protocol is not yet merged, and the prototype implements finger matching, basic mouse support and two-finger scrolling. The project aims at improving the quality of current multi-touch functionality available in the Synaptics X driver, and in addition implement more advanced gestures. [4] See the section on event computation. [5] See the section on finger tracking.