How to use Atmel TSADCC Sysfs Interface

Revision as of 10:52, 27 December 2013 by Mgloff (talk | contribs) (Created page with "==How to Use the Atmel TSADCC Sysfs Interface == This guide will demonstrate how to use the sysfs interface for the Atmel touchscreen driver. There are two basic files used ...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

==How to Use the Atmel TSADCC Sysfs Interface ==

This guide will demonstrate how to use the sysfs interface for the Atmel touchscreen driver.

There are two basic files used to interface with the touchscreen driver:


The /sys/class/gpio/indexed_tsopt/index controls which aspect of the touchscreen driver is to be modified and /sys/class/gpio/indexed_tsopt/data controls the value to be modified.

There are also two basic command forms that are recommended for modifying /sys/class/gpio/indexed_tsopt/index and /sys/class/gpio/indexed_tsopt/data. Those are:

$ echo INDEX_VALUE > /sys/class/gpio/indexed_tsopt/index $ echo DATA_VALUE > /sys/class/gpio/indexed_tsopt/data


$ cat /sys/class/gpio/indexed_tsopt/index $ cat /sys/class/gpio/indexed_tsopt/data

The 'echo' command form allows one to modify the current value of the file whereas the 'cat' command form allows one to view the current value of the file. A common workflow may be to 'echo' an INDEX_VALUE into /sys/class/gpio/indexed_tsopt/index then 'cat' the /sys/class/gpio/indexed_tsopt/data to view on the command line.

The following touch screen parameters may be modified through the use of the above commands:

Touchscreen Mode

Sample and Hold Time
DATA_VALUE recommended default: 0xf
 A minimal sample and hold time are necessary for the touchscreen controller to
 provide the best converted value between two channels. This can be set to
 between 1 and 16 clock cycles. The default value provided by EMAC is typically
 16 clock cyles which we have found to provide the best accuracy during
 testing; however, it may be that altering this value to be lower may produce a
 more responsive interface.
Pen Debounce Time
DATA_VALUE recommended default: 0xf
 The Atmel TSADCC driver for Linux uses the touchscreen controller's Pen Detect
 Method to begin triggering conversions. In order for this to happen, a
 programmable debouncer determines how long current must flow before an
 interrupt is generated to indicate that conversions should start taking place
 in the controller. The debouncer is programmable from 1 ADC clock period to
 2^15 ADC clock periods depending on the value of PENDBC.
Touchscreen ADC Prescalar
DATA_VALUE recommended default: 0x6e
 This value controls the ADC clock used to convert the touchscreen analog
 readings to digital values inside the Atmel TSADCC Controller. Acceptable
 values for the DATA_VALUE range from 0x00 to 0xff. The SoM-9g45 Master Clock
 has a frequency of 133.3 MHz. The formula used to determine the ADC clock
 frequence uses this value:
 The default value provided by EMAC varies greatly between different
 touchscreens as a part of the optimization process for each product. 

Touchscreen X-Panel Resistance INDEX_VALUE=0xfff8 DATA_VALUE recommended default: 0x279 for 12-inch display

The X-Panel Resistance measurement is a constant coefficient in the equation
that determines the touch pressure from the values measured by the touchscreen
controller which varies from touchscreen to touchscreen and should be kept in mind
when modifying the Touchscreen Pressure Sensitivity since the two are closely

Touchscreen Pressure Sensitivity INDEX_VALUE=0xfffc DATA_VALUE recommended default: 0x200

This value refers to the pressure filter in the Atmel driver that EMAC set up
to provide a threshold over which no touchscreen measurements will be passed to
the Linux input driver. 
To understand how this works, it is necessary to know that the harder one
presses on the touch screen, the LOWER the value of the pressure reading. So
the threshold set by using this INDEX_VALUE is the largest measurement value
that the driver will accept as a true touch representing the weakest physical
contact with the touchscreen panel.
The effect of increasing this value is to make the touchscreen more sensitive
to light touches. The effect of decreasing this value is to make the
touchscreen require harder touches to actually register as a touch in the first
place. Requiring a greater touch pressure will help when light touches produce
ambiguous readings which manifest as inaccurate and sometimes spurious values
sent to userspace from the driver. The downside of course is that harder, more
intentional presses are needed to register the touch.
Note that there is a linear relationship between the Touchscreen Pressure
Sensitivity and the Touchscreen X-Panel Resistance.

Touchscreen Filter INDEX_VALUE=0xffff DATA_VALUE recommended default: 0x14

This value determines how many measurement samples are used by the touch screen
driver to provide an average value that gets reported to the Linux input
subsystem which is then available for userspace applications to accept as
input. By default, EMAC has set a maximum of 30 filter samples so if the
DATA_VALUE passed to /sys/class/gpio/indexed_tsopt/data is greater than 0x1e,
the value will simply be 30. This can be changed by editing the
"atmel_tsadcc.c" file line that says "#define COUNT_MAX 30".

A Note Regarding TSLIB

EMAC OpenEmbedded filesystems ship with a utility known as tslib which includes
a number of userspace touchscreen drivers and modules that are intended to
improve the performance of the touchscreen. Settings for this file can be found
in /etc/ts.conf. In it, there are four lines:
module pthres pmin=1
module variance delta=30
module dejiter delta=100
module linear
If you are experiencing a touchscreen problem in which the mouse cursor jitters
around the screen and "pre-clicks" a point other than where you intended, it
may be necessary to change the settings in this file. While testing at EMAC, we
have found that disabling the "variance" module will prevent the pre-clicks,
although this will not prevent the mouse from jittering across the screen. To
disable this module, either delete the line or comment it out with a hash
  1. module variance delta=30