How to use Atmel TSADCC Sysfs Interface

TODO: {{#todo:FinalDraft;(12.16.13-12:00->MG+);(01.02.14-12:35->KY+);(01.02.14-14:00->MD-);(01.02.14-14:40->MG+)|Michael Gloff|oe 4,oe 5,md,mg,ky,FinalDraft}}

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 /sys/class/gpio/indexed_tsopt/index virtual file 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 two common command forms that are recommended for modifying the values exported by the virtual files /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

and

$ 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 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, printf can be used to write values:

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

Similarly, the value can be read with the more 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, fopen can be used with fprintf 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
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 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
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 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
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 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
DATA_VALUE recommended default: 0x279 for 12-inch display
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
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 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. 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