View source for How to use Atmel TSADCC Sysfs Interface

{{todo|Complete;(12.16.13-12:00->MG+);(01.02.14-12:35->KY+);(01.02.14-14:00->MD-);(01.02.14-14:40->MG+);(01.02.14-14:55->KY+)|Michael Gloff|project=oe 4,oe 5,md,mg,ky,complete}}
==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:
 /sys/class/gpio/indexed_tsopt/index
 /sys/class/gpio/indexed_tsopt/data

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

There are two common command forms that are recommended for modifying the values exported by the virtual files 
<code>/sys/class/gpio/indexed_tsopt/index</code> and <code>/sys/class/gpio/indexed_tsopt/data</code>.
Those are:

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

and

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

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

Although the above two methods are the most commonly used command line methods for interacting with these virtual files, other methods will work as well.  For instance, <code>printf</code> can be used to write values:

 $ printf $INDEX_VALUE > /sys/class/gpio/indexed_tsopt/index

Similarly, the value can be read with the <code>more</code> command:

 $ more /sys/class/gpio/indexed_tsopt/index

Any method of writing ASCII text or reading ASCII text can be used to interact with these virtual files.  In a C program, <code>fopen</code> can be used with <code>fprintf</code> to write to one of these files.

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

==Touchscreen Mode==

===Sample and Hold Time===
INDEX_VALUE=0xffef <br />
DATA_VALUE recommended default: 0xf<br />
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 a value in the range of 1 through 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===
INDEX_VALUE=0xfff0<br />
DATA_VALUE recommended default: 0xf<br />
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 many sequential clock periods with a touch detected must occur 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===
INDEX_VALUE=0xfff4<br />
DATA_VALUE recommended default: 0x6e<br />
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
frequency uses this value:

 ADCCLK = MASTERCLK/((PRESCALAR + 1)*2). 

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<br />
DATA_VALUE recommended default: 0x279 for 12-inch display<br />
The X-Panel Resistance measurement is a constant coefficient in the equation which determines the touch pressure from the values measured by the touchscreen controller.   This value varies from touchscreen to touchscreen and should be kept in mind when modifying the Touchscreen Pressure Sensitivity since the two are closely related.

===Touchscreen Pressure Sensitivity===
INDEX_VALUE=0xfffc<br />
DATA_VALUE recommended default: 0x200<br />
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 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<br />
DATA_VALUE recommended default: 0x14<br />
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 <code>/sys/class/gpio/indexed_tsopt/data</code> is greater than 0x1e, the value will simply be 30. This can be changed by editing the
<code>atmel_tsadcc.c</code> file line that says <code>#define COUNT_MAX 30</code>.  Larger values will provide improved noise rejection at the expense of causing the input to lag.

===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 symbol:

 #module variance delta=30