Linux input subsystem: multi-touch protocol-multi-touch-protocol.txt

Multi-touch (MT) Protocol

-------------------------

Copyright (c) 2009-2010 Henrik Rydberg <rydberg@euromail.se>

Introduction

------------

To give full play to the powerful functions of recent multi-point touch and multi-user devices, we define a method for reporting Detailed data for multi-point touch (for example, multiple objects are directly exposed to the surface of the device ), is very necessary. This document describes the multi-touch (MT) protocol. The kernel driver can report detailed data for multiple random touch events.

Based on hardware capabilities, the Protocol is divided into two types. For devices that can only process anonymous contact (type A), this Protocol describes how to send all raw touch data to the recipient. For devices that have the ability to track and recognize each touch point (type B), the Protocol describes how to send a separate update of each touch point to the recipient through event slots.

 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This article by droidphone Translation: http://blog.csdn.net/droidphone
Kernel version: v3.7
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Protocol usage

--------------

Detailed touch information is divided into multiple abs_mt event data packets for sending in order. Only the abs_mt event information is recognized as part of the touch packet, because these events are ignored in the current single-touch (ST) application, we can implement the MT protocol based on the st protocol in the existing driver.

For the driver of the Type A device, use input_mt_sync () to separate multiple touch packets at the end of each packet, which generates a syn_mt_report event, it notifies the recipient to accept the current touch information and prepares to receive the next information.

For the drive of the Type B device, at the beginning of each data packet, call input_mt_slot () to split and bring a parameter: slot. This generates an abs_mt_slot event, which notifies the receiver to update the information of the given slot ..

The two types of drivers usually call the input_sync () function to mark the end of a multi-point touch data transfer. This notifies the recipient to respond to all the accumulated events since the previous ev_syn/syn_report, and prepare to receive a new group of events/packets.

The main difference between the stateless type a protocol and the stateful type B slot protocol is that the data volume sent to the user space is reduced by identifying the same contact points. The slot Protocol needs to use abs_mt_tracking_id, which is not provided by hardware or calculated through raw data [5 ].

For type A devices, the kernel driver should list all valid touch points on the device surface and generate events. The order of each touch point packet in the event stream is not important. The work of Event Filtering and finger tracking is left to the user space for [3 ].

For type B devices, the kernel driver should associate each recognized touch with a slot and use this slot to spread changes in the touch status. Modify the abs_mt_tracking_id of the associated slot to create, replace, and destroy a touch point. A non-Negative trace ID is interpreted as a valid touch.-1 indicates a slot that is no longer used. A trail ID that has not appeared before is considered as a new touchpoint. When a trail ID no longer appears, it is deemed that the contact point has been removed. Because only the changed part is transmitted, the status information of each started contact point must reside at the receiving end. Each time a MT event is received, you only need to perform a simple update on the attributes of the current slot.

Some devices can identify and/or track more contact points than they can report to the driver. The driver for such devices should associate each touch point reported by the hardware with a slot of type B. Once a contact point associated with the slot is identified, the driver should invalidate the slot by changing its abs_mt_tracking_id. If the hardware sends a notification that it has tracked more touchpoints than currently reported, the driver should use the btn_tool _ * tap event to notify the user space that the total number of touchpoints tracked by the hardware has changed at the moment. To do this, the driver should explicitly send the btn_tool _ * tap event and set use_count to false when calling input_mt_report_pointer_emulation. The driver should only advertise the number of slots that the hardware can report. The user space can note that the maximum supported btn_tool _ * tap events are greater than the type reported in the absinfo of the abs_mt_slot axis.
The total number of slots in B to detect whether the driver can report more touch points than the number of slots.

Protocol example

------------------

For a two-touch, the smallest Event Sequence of the Type A device looks like the following:

Abs_mt_position_x X [0]

Abs_mt_position_y y [0]

Syn_mt_report

Abs_mt_position_x X [1]

Abs_mt_position_y y [1]

Syn_mt_report

Syn_report

In fact, the reporting sequence after one touch point is moved looks the same, and all raw data with a touch point is sent, and syn_report is used between them for synchronization.

When the first contact point leaves, the event sequence is as follows:

Abs_mt_position_x X [1]

Abs_mt_position_y y [1]

Syn_mt_report

Syn_report

When the second contact point leaves, the event sequence is as follows:

Syn_mt_report

Syn_report

If the driver reports a btn_touch or abs_pressure event outside the abs_mt event, the last syn_mt_report can be omitted. Otherwise, the final syn_report will be thrown away by the input core layer, the result is that a 0-touch point event is uploaded to the user space.

Protocol example B

------------------

For a two-touch, the smallest Event Sequence of the Type B device looks like the following:

Abs_mt_slot 0

Abs_mt_tracking_id 45

Abs_mt_position_x X [0]

Abs_mt_position_y y [0]

Abs_mt_slot 1

Abs_mt_tracking_id 46

Abs_mt_position_x X [1]

Abs_mt_position_y y [1]

Syn_report

The event sequence after the touch point of ID 45 moves in the X direction is as follows:

Abs_mt_slot 0

Abs_mt_position_x X [0]

Syn_report

After the contact point corresponding to slot 0 leaves, the corresponding event sequence is as follows:

Abs_mt_tracking_id-1

Syn_report

The last modified slot is also 0, so the abs_mt_slot is omitted. This message removes the slot 0 associated with the contact point 45, so the contact point 45 is destroyed. After the slot 0 is released, it can be reused by another contact point.

Finally, the time sequence after the second contact point leaves is as follows:

Abs_mt_slot 1

Abs_mt_tracking_id-1

Syn_report

Event usage

-----------

A set of abs_mt event sets are defined according to the required features. These events are divided into several groups so that only one part of them can be implemented. The smallest set is composed of abs_mt_position_x and abs_mt_position_y, which is used to track multi-point contact. If the device supports this function, abs_mt_touch_major and abs_mt_width_major can be used to provide the contact area and corresponding contact tools.

The touch and width parameters have a geometric explanation. Imagine watching a person press a finger on the opposite glass through a window, and you will see two areas, the inner ring contains the actual part of the finger and the glass contact, the outer ring is the outer contour of the finger. The contact area (A) is abs_mt_position_x/y, and the center of the finger contour area (B) is abs_mt_tool_x/y. The diameter of the contact area is abs_mt_touch_major, and the diameter of the finger contour is abs_mt_width_major. Now imagine that this person points his hand closer to the glass and the contact area will increase. Generally, abs_mt_touch_major
The/abs_mt_width_major ratio is always less than 1, which is related to the contact pressure. However, for pressure-based devices, use abs_mt_pressure to provide the contact pressure value. The device that can detect the suspension can use abs_mt_distance to point out the distance from the surface.

Linux Mt Win8

_________________________________

/\ |

/\ |

/____ \ |

// \\| |

\ A \ | A |

\\____/\| |

\\| |

\ B \ | B |

\\| |

\\| |

\\| |

\/|

\/|

\/|

\ __________/| ___________________ |

In addition to the major parameter, a minor parameter can be added to the elliptical shape of the contact and finger areas. The major and minor parameters are equivalent to the long and short axes of the ellipse. The direction of the elliptic in the contact area can be described by the orientation parameter, and the direction of the elliptic in the finger area can be obtained through Vector Operation (a-B.

For type A devices, the future type may use abs_mt_blob_id to describe the contact shape.

Abs_mt_tool_type can be used to indicate whether the touch tool is a finger or a pen or other object. Finally, abs_mt_tracking_id should always be used to track recognized touchpoints [5 ].

In the type B Protocol, abs_mt_tool_type and abs_mt_tracking_id are hidden in the input core layer for processing.ProgramCall input_mt_report_slot_state () instead ().

Event Semantics

---------------

Abs_mt_touch_major

Length of the long axis of the contact area. The length should be provided in units of contact surfaces. If the surface resolution is X-Y, the maximum possible value of abs_mt_touch_major is SQRT (x ^ 2 + y ^ 2), and its diagonal line [4 ].

Abs_mt_touch_minor

The surface unit length of the short axis in the contact area. If the area is circular, ignore [4] for this event ].

Abs_mt_width_major

The surface unit length of the long axis of the tool contour area. This should be the size of the tool in this province. The direction of the contact surface and contour surface is assumed to be the same [4 ].

Abs_mt_width_minor

The surface unit length of the short axis in the tool profile area. If it is a circle, it can be ignored [4 ].

The preceding four values can be used to export additional contact information. Abs_mt_touch_major/abs_mt_width_major can be used as a close pressure. The finger and palm have unused feature widths.

Abs_mt_pressure

The pressure value of the contact area, which can be any unit. Stress-based devices should use this event instead of the touch and width events. It is also used for devices that can report spatial signal strength.

Abs_mt_distance

The surface unit distance from the contact to the contact surface. The distance is 0, indicating that the surface has been exposed. A positive value indicates that the contact is suspended on the surface.

Abs_mt_orientation

The contact direction of the elliptical area. This value describes the number of symbols that rotate around the touch center 1/4 clockwise. The range of this value is not limited, but 0 should be returned when the y direction of the elliptic and the surface is aligned, negative value should be returned when the elliptic is to the left turn, and positive value should be returned when the right turn. Returns the maximum value when it is fully aligned with the X axis.

By default, the contact ellipse is a symmetric point. For devices with 360 degrees of rotation, it is necessary to report that the rotation is beyond the maximum range to indicate that the rotation is more than 1/4 turns. For inverted fingers, it should be reported twice the maximum range.

If the contact surface is a circle or the direction information is not available in the kernel driver, the direction parameter can be ignored. If the device can identify two axis directions, it may only support some discontinuous directions. In this case, the range of abs_mt_orientation should be [] [4 ].

Abs_mt_position_x

The X coordinate of the contact center.

Abs_mt_position_y

Y coordinate of Contact Center

Abs_mt_tool_x

X coordinate of the contact tool contour center. If the device cannot distinguish the contact surface from the tool itself, you can ignore this event.

Abs_mt_tool_y

Y coordinate of the contact tool contour center. If the device cannot distinguish the contact surface from the tool itself, you can ignore this event.

These four position values can be used to separate the actual contact position from the Touch Tool Position. If both locations exist, the long axis of the Touch Tool points to the contact point. Otherwise, the axis of the tool and the contact plane is opposite to each other.

Abs_mt_tool_type

Similar to the tool type. Many kernel drivers cannot distinguish between touch tools, such as fingers and pens. In this case, the event can be ignored. The current protocol supports two types: mt_tool_finger and mt_tool_pen [2. For type B devices, the event is handled by the input core layer. The driver should use input_mt_report_slot_state () to report the event.

Abs_mt_blob_id

The blob_id event combines several data packets to form an arbitrary contact shape. A sequence composed of vertices defines the shape of a polygon. This is a combination of the underlying anonymous data of type A devices and should not be confused with the trace ID at the upper layer. Most type A devices do not have the blog capability, so the driver can safely ignore this event.

Abs_mt_tracking_id

Tracking_id identifies the entire lifecycle of a started touch point [5 ]. The range of tracking_id should be large enough to ensure that a unique value can be maintained within a long enough time. For type B devices, the event is handled by the input core layer. The driver should use input_mt_report_slot_state () to report the event.

Event computing

-----------------

A bunch of different hardware inevitably leads to some devices that are more suited to the MT protocol than others. This section describes how to calculate events in a simple and unified manner.

For devices that report contact shapes as rectangles, we cannot obtain signed direction values. Assume that X and Y are the two sides of the contact rectangle respectively, the following formulas can obtain 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], so that the device can distinguish whether the finger is along the Y axis or along the X axis [1 ].

For Win8 devices with coordinates T and C, the corresponding relationship between location information 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 determine the touch oval and the tool oval, so we have to resort to approximation.Algorithm. A simple solution compatible with earlier use methods 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)

The basic principle is: We don't have any information about the touch ellipse, so we use its inner tangent circle to approximate it. The ellipse of the touch tool should be aligned with the vector (t-c), so its diameter must increase the distance between (T, C. Finally, assuming that the diameter of the touch area is equal to the thickness of the touch tool, we can obtain the above formula.

Finger tracking

---------------

Tracking finger processing. For example, assigning a unique trackingid to each touch point started on the surface is a euclidean even matching problem. In each event synchronization, a set of actual touch points must match the previous synchronized touch point. For complete implementation, see [3 ].

Gesture

--------

In some special applications that can generate gesture events, you can use the touch and width parameters, for example, approximate finger pressure or distinguish between the forefoot and the thumb. The extra minor parameter can be used to determine whether the entire finger is pressed or just a point pressed by the finger. Using the orientation parameter, we can detect the twisting of the finger.

Notes

------------

To be compatible with existing applications, the data reported in a finger packet cannot be identified as a single touch event.

For the type A device, all finger data must be omitted from the input filter algorithm, because the next event of the same type points to different fingers.

For an example of a device using the type A protocol, see drive bcm5974. For the example of the type B protocol, see the driver of HID-egalax.

 

[1] also, the difference (tool_x-position_x) can be used to model tilt.

[2] The list can of course be extended.

[3] mtdev projects: http://bitmath.org/code/mtdev.

[4] See the event Computing Section.

[5] refer to the finger tracking section.