HID: ntrig: add documention
The doctumentation includes a brief introduction to the driver and explanations of the filtering parameters as well as a discussion of the need for and working of the filters. Signed-off-by: Rafi Rubin <rafi@seas.upenn.edu> Signed-off-by: Jiri Kosina <jkosina@suse.cz>
This commit is contained in:
parent
763008c435
commit
29cf28ae8d
126
Documentation/input/ntrig.txt
Normal file
126
Documentation/input/ntrig.txt
Normal file
@ -0,0 +1,126 @@
|
||||
N-Trig touchscreen Driver
|
||||
-------------------------
|
||||
Copyright (c) 2008-2010 Rafi Rubin <rafi@seas.upenn.edu>
|
||||
Copyright (c) 2009-2010 Stephane Chatty
|
||||
|
||||
This driver provides support for N-Trig pen and multi-touch sensors. Single
|
||||
and multi-touch events are translated to the appropriate protocols for
|
||||
the hid and input systems. Pen events are sufficiently hid compliant and
|
||||
are left to the hid core. The driver also provides additional filtering
|
||||
and utility functions accessible with sysfs and module parameters.
|
||||
|
||||
This driver has been reported to work properly with multiple N-Trig devices
|
||||
attached.
|
||||
|
||||
|
||||
Parameters
|
||||
----------
|
||||
|
||||
Note: values set at load time are global and will apply to all applicable
|
||||
devices. Adjusting parameters with sysfs will override the load time values,
|
||||
but only for that one device.
|
||||
|
||||
The following parameters are used to configure filters to reduce noise:
|
||||
|
||||
activate_slack number of fingers to ignore before processing events
|
||||
|
||||
activation_height size threshold to activate immediately
|
||||
activation_width
|
||||
|
||||
min_height size threshold bellow which fingers are ignored
|
||||
min_width both to decide activation and during activity
|
||||
|
||||
deactivate_slack the number of "no contact" frames to ignore before
|
||||
propagating the end of activity events
|
||||
|
||||
When the last finger is removed from the device, it sends a number of empty
|
||||
frames. By holding off on deactivation for a few frames we can tolerate false
|
||||
erroneous disconnects, where the sensor may mistakenly not detect a finger that
|
||||
is still present. Thus deactivate_slack addresses problems where a users might
|
||||
see breaks in lines during drawing, or drop an object during a long drag.
|
||||
|
||||
|
||||
Additional sysfs items
|
||||
----------------------
|
||||
|
||||
These nodes just provide easy access to the ranges reported by the device.
|
||||
sensor_logical_height the range for positions reported during activity
|
||||
sensor_logical_width
|
||||
|
||||
sensor_physical_height internal ranges not used for normal events but
|
||||
sensor_physical_width useful for tuning
|
||||
|
||||
All N-Trig devices with product id of 1 report events in the ranges of
|
||||
X: 0-9600
|
||||
Y: 0-7200
|
||||
However not all of these devices have the same physical dimensions. Most
|
||||
seem to be 12" sensors (Dell Latitude XT and XT2 and the HP TX2), and
|
||||
at least one model (Dell Studio 17) has a 17" sensor. The ratio of physical
|
||||
to logical sizes is used to adjust the size based filter parameters.
|
||||
|
||||
|
||||
Filtering
|
||||
---------
|
||||
|
||||
With the release of the early multi-touch firmwares it became increasingly
|
||||
obvious that these sensors were prone to erroneous events. Users reported
|
||||
seeing both inappropriately dropped contact and ghosts, contacts reported
|
||||
where no finger was actually touching the screen.
|
||||
|
||||
Deactivation slack helps prevent dropped contact for single touch use, but does
|
||||
not address the problem of dropping one of more contacts while other contacts
|
||||
are still active. Drops in the multi-touch context require additional
|
||||
processing and should be handled in tandem with tacking.
|
||||
|
||||
As observed ghost contacts are similar to actual use of the sensor, but they
|
||||
seem to have different profiles. Ghost activity typically shows up as small
|
||||
short lived touches. As such, I assume that the longer the continuous stream
|
||||
of events the more likely those events are from a real contact, and that the
|
||||
larger the size of each contact the more likely it is real. Balancing the
|
||||
goals of preventing ghosts and accepting real events quickly (to minimize
|
||||
user observable latency), the filter accumulates confidence for incoming
|
||||
events until it hits thresholds and begins propagating. In the interest in
|
||||
minimizing stored state as well as the cost of operations to make a decision,
|
||||
I've kept that decision simple.
|
||||
|
||||
Time is measured in terms of the number of fingers reported, not frames since
|
||||
the probability of multiple simultaneous ghosts is expected to drop off
|
||||
dramatically with increasing numbers. Rather than accumulate weight as a
|
||||
function of size, I just use it as a binary threshold. A sufficiently large
|
||||
contact immediately overrides the waiting period and leads to activation.
|
||||
|
||||
Setting the activation size thresholds to large values will result in deciding
|
||||
primarily on activation slack. If you see longer lived ghosts, turning up the
|
||||
activation slack while reducing the size thresholds may suffice to eliminate
|
||||
the ghosts while keeping the screen quite responsive to firm taps.
|
||||
|
||||
Contacts continue to be filtered with min_height and min_width even after
|
||||
the initial activation filter is satisfied. The intent is to provide
|
||||
a mechanism for filtering out ghosts in the form of an extra finger while
|
||||
you actually are using the screen. In practice this sort of ghost has
|
||||
been far less problematic or relatively rare and I've left the defaults
|
||||
set to 0 for both parameters, effectively turning off that filter.
|
||||
|
||||
I don't know what the optimal values are for these filters. If the defaults
|
||||
don't work for you, please play with the parameters. If you do find other
|
||||
values more comfortable, I would appreciate feedback.
|
||||
|
||||
The calibration of these devices does drift over time. If ghosts or contact
|
||||
dropping worsen and interfere with the normal usage of your device, try
|
||||
recalibrating it.
|
||||
|
||||
|
||||
Calibration
|
||||
-----------
|
||||
|
||||
The N-Trig windows tools provide calibration and testing routines. Also an
|
||||
unofficial unsupported set of user space tools including a calibrator is
|
||||
available at:
|
||||
http://code.launchpad.net/~rafi-seas/+junk/ntrig_calib
|
||||
|
||||
|
||||
Tracking
|
||||
--------
|
||||
|
||||
As of yet, all tested N-Trig firmwares do not track fingers. When multiple
|
||||
contacts are active they seem to be sorted primarily by Y position.
|
Loading…
Reference in New Issue
Block a user