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