diff options
author | Rafi Rubin <rafi@seas.upenn.edu> | 2010-08-26 00:54:54 -0400 |
---|---|---|
committer | Jiri Kosina <jkosina@suse.cz> | 2010-08-30 09:25:18 -0400 |
commit | 29cf28ae8dc244f89e213dc198f2286659d521b5 (patch) | |
tree | 0847ad5ba46f3e47103da044433ea93623837854 /Documentation | |
parent | 763008c4357b73c8d18396dfd8d79dc58fa3f99d (diff) |
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>
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/input/ntrig.txt | 126 |
1 files changed, 126 insertions, 0 deletions
diff --git a/Documentation/input/ntrig.txt b/Documentation/input/ntrig.txt new file mode 100644 index 000000000000..be1fd981f73f --- /dev/null +++ b/Documentation/input/ntrig.txt | |||
@@ -0,0 +1,126 @@ | |||
1 | N-Trig touchscreen Driver | ||
2 | ------------------------- | ||
3 | Copyright (c) 2008-2010 Rafi Rubin <rafi@seas.upenn.edu> | ||
4 | Copyright (c) 2009-2010 Stephane Chatty | ||
5 | |||
6 | This driver provides support for N-Trig pen and multi-touch sensors. Single | ||
7 | and multi-touch events are translated to the appropriate protocols for | ||
8 | the hid and input systems. Pen events are sufficiently hid compliant and | ||
9 | are left to the hid core. The driver also provides additional filtering | ||
10 | and utility functions accessible with sysfs and module parameters. | ||
11 | |||
12 | This driver has been reported to work properly with multiple N-Trig devices | ||
13 | attached. | ||
14 | |||
15 | |||
16 | Parameters | ||
17 | ---------- | ||
18 | |||
19 | Note: values set at load time are global and will apply to all applicable | ||
20 | devices. Adjusting parameters with sysfs will override the load time values, | ||
21 | but only for that one device. | ||
22 | |||
23 | The following parameters are used to configure filters to reduce noise: | ||
24 | |||
25 | activate_slack number of fingers to ignore before processing events | ||
26 | |||
27 | activation_height size threshold to activate immediately | ||
28 | activation_width | ||
29 | |||
30 | min_height size threshold bellow which fingers are ignored | ||
31 | min_width both to decide activation and during activity | ||
32 | |||
33 | deactivate_slack the number of "no contact" frames to ignore before | ||
34 | propagating the end of activity events | ||
35 | |||
36 | When the last finger is removed from the device, it sends a number of empty | ||
37 | frames. By holding off on deactivation for a few frames we can tolerate false | ||
38 | erroneous disconnects, where the sensor may mistakenly not detect a finger that | ||
39 | is still present. Thus deactivate_slack addresses problems where a users might | ||
40 | see breaks in lines during drawing, or drop an object during a long drag. | ||
41 | |||
42 | |||
43 | Additional sysfs items | ||
44 | ---------------------- | ||
45 | |||
46 | These nodes just provide easy access to the ranges reported by the device. | ||
47 | sensor_logical_height the range for positions reported during activity | ||
48 | sensor_logical_width | ||
49 | |||
50 | sensor_physical_height internal ranges not used for normal events but | ||
51 | sensor_physical_width useful for tuning | ||
52 | |||
53 | All N-Trig devices with product id of 1 report events in the ranges of | ||
54 | X: 0-9600 | ||
55 | Y: 0-7200 | ||
56 | However not all of these devices have the same physical dimensions. Most | ||
57 | seem to be 12" sensors (Dell Latitude XT and XT2 and the HP TX2), and | ||
58 | at least one model (Dell Studio 17) has a 17" sensor. The ratio of physical | ||
59 | to logical sizes is used to adjust the size based filter parameters. | ||
60 | |||
61 | |||
62 | Filtering | ||
63 | --------- | ||
64 | |||
65 | With the release of the early multi-touch firmwares it became increasingly | ||
66 | obvious that these sensors were prone to erroneous events. Users reported | ||
67 | seeing both inappropriately dropped contact and ghosts, contacts reported | ||
68 | where no finger was actually touching the screen. | ||
69 | |||
70 | Deactivation slack helps prevent dropped contact for single touch use, but does | ||
71 | not address the problem of dropping one of more contacts while other contacts | ||
72 | are still active. Drops in the multi-touch context require additional | ||
73 | processing and should be handled in tandem with tacking. | ||
74 | |||
75 | As observed ghost contacts are similar to actual use of the sensor, but they | ||
76 | seem to have different profiles. Ghost activity typically shows up as small | ||
77 | short lived touches. As such, I assume that the longer the continuous stream | ||
78 | of events the more likely those events are from a real contact, and that the | ||
79 | larger the size of each contact the more likely it is real. Balancing the | ||
80 | goals of preventing ghosts and accepting real events quickly (to minimize | ||
81 | user observable latency), the filter accumulates confidence for incoming | ||
82 | events until it hits thresholds and begins propagating. In the interest in | ||
83 | minimizing stored state as well as the cost of operations to make a decision, | ||
84 | I've kept that decision simple. | ||
85 | |||
86 | Time is measured in terms of the number of fingers reported, not frames since | ||
87 | the probability of multiple simultaneous ghosts is expected to drop off | ||
88 | dramatically with increasing numbers. Rather than accumulate weight as a | ||
89 | function of size, I just use it as a binary threshold. A sufficiently large | ||
90 | contact immediately overrides the waiting period and leads to activation. | ||
91 | |||
92 | Setting the activation size thresholds to large values will result in deciding | ||
93 | primarily on activation slack. If you see longer lived ghosts, turning up the | ||
94 | activation slack while reducing the size thresholds may suffice to eliminate | ||
95 | the ghosts while keeping the screen quite responsive to firm taps. | ||
96 | |||
97 | Contacts continue to be filtered with min_height and min_width even after | ||
98 | the initial activation filter is satisfied. The intent is to provide | ||
99 | a mechanism for filtering out ghosts in the form of an extra finger while | ||
100 | you actually are using the screen. In practice this sort of ghost has | ||
101 | been far less problematic or relatively rare and I've left the defaults | ||
102 | set to 0 for both parameters, effectively turning off that filter. | ||
103 | |||
104 | I don't know what the optimal values are for these filters. If the defaults | ||
105 | don't work for you, please play with the parameters. If you do find other | ||
106 | values more comfortable, I would appreciate feedback. | ||
107 | |||
108 | The calibration of these devices does drift over time. If ghosts or contact | ||
109 | dropping worsen and interfere with the normal usage of your device, try | ||
110 | recalibrating it. | ||
111 | |||
112 | |||
113 | Calibration | ||
114 | ----------- | ||
115 | |||
116 | The N-Trig windows tools provide calibration and testing routines. Also an | ||
117 | unofficial unsupported set of user space tools including a calibrator is | ||
118 | available at: | ||
119 | http://code.launchpad.net/~rafi-seas/+junk/ntrig_calib | ||
120 | |||
121 | |||
122 | Tracking | ||
123 | -------- | ||
124 | |||
125 | As of yet, all tested N-Trig firmwares do not track fingers. When multiple | ||
126 | contacts are active they seem to be sorted primarily by Y position. | ||