Difference between revisions of "How to use Atmel TSADCC Sysfs Interface"

From wiki.emacinc.com
Jump to: navigation, search
(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 ...")
 
Line 1: Line 1:
==How to Use the Atmel TSADCC Sysfs Interface
+
==How to Use the Atmel TSADCC Sysfs Interface==
==
 
  
This guide will demonstrate how to use the sysfs interface for the Atmel
+
This guide will demonstrate how to use the sysfs interface for the Atmel touchscreen driver.
touchscreen driver.
 
  
 
There are two basic files used to interface with the touchscreen driver:
 
There are two basic files used to interface with the touchscreen driver:
Line 9: Line 7:
 
  /sys/class/gpio/indexed_tsopt/data
 
  /sys/class/gpio/indexed_tsopt/data
  
The /sys/class/gpio/indexed_tsopt/index controls which aspect of the touchscreen
+
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
+
driver is to be modified and '''/sys/class/gpio/indexed_tsopt/data''' controls the
 
value to be modified.  
 
value to be modified.  
  
 
There are also two basic command forms that are recommended for modifying
 
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.
+
'''/sys/class/gpio/indexed_tsopt/index''' and '''/sys/class/gpio/indexed_tsopt/data'''.
 
Those are:
 
Those are:
  
$ echo INDEX_VALUE > /sys/class/gpio/indexed_tsopt/index
+
$ echo INDEX_VALUE > /sys/class/gpio/indexed_tsopt/index
$ echo DATA_VALUE > /sys/class/gpio/indexed_tsopt/data
+
$ echo DATA_VALUE > /sys/class/gpio/indexed_tsopt/data
  
 
and
 
and
  
$ cat /sys/class/gpio/indexed_tsopt/index
+
$ cat /sys/class/gpio/indexed_tsopt/index
$ cat /sys/class/gpio/indexed_tsopt/data
+
$ cat /sys/class/gpio/indexed_tsopt/data
  
The 'echo' command form allows one to modify the current value of the file
+
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.
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
 
The following touch screen parameters may be modified through the use of the
 
above commands:
 
above commands:
  
Touchscreen Mode
+
==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
 
  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
+
===Sample and Hold Time===
INDEX_VALUE=0xfff0
+
INDEX_VALUE=0xffef <br />
DATA_VALUE recommended default: 0xf
+
DATA_VALUE recommended default: 0xf<br />
  The Atmel TSADCC driver for Linux uses the touchscreen controller's Pen Detect
+
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.
  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
+
===Pen Debounce Time===
INDEX_VALUE=0xfff4
+
INDEX_VALUE=0xfff0<br />
DATA_VALUE recommended default: 0x6e
+
DATA_VALUE recommended default: 0xf<br />
  This value controls the ADC clock used to convert the touchscreen analog
+
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
  readings to digital values inside the Atmel TSADCC Controller. Acceptable
+
programmable debouncer determines how long current must flow before an interrupt is generated to indicate that conversions should start taking place
  values for the DATA_VALUE range from 0x00 to 0xff. The SoM-9g45 Master Clock
+
in the controller. The debouncer is programmable from 1 ADC clock period to 2^15 ADC clock periods depending on the value of PENDBC.
  has a frequency of 133.3 MHz. The formula used to determine the ADC clock
 
  frequence uses this value:
 
  
  ADCCLK = MASTERCLK/((PRESCALAR +1)*2).  
+
===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:
  
  The default value provided by EMAC varies greatly between different
+
ADCCLK = MASTERCLK/((PRESCALAR +1)*2).  
  touchscreens as a part of the optimization process for each product.  
 
  
Touchscreen X-Panel Resistance
+
The default value provided by EMAC varies greatly between different touchscreens as a part of the optimization process for each product.  
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
 
related.
 
  
Touchscreen Pressure Sensitivity
+
===Touchscreen X-Panel Resistance===
INDEX_VALUE=0xfffc
+
INDEX_VALUE=0xfff8<br />
DATA_VALUE recommended default: 0x200
+
DATA_VALUE recommended default: 0x279 for 12-inch display<br />
This value refers to the pressure filter in the Atmel driver that EMAC set up
+
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 related.
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
+
===Touchscreen Pressure Sensitivity===
presses on the touch screen, the LOWER the value of the pressure reading. So
+
INDEX_VALUE=0xfffc<br />
the threshold set by using this INDEX_VALUE is the largest measurement value
+
DATA_VALUE recommended default: 0x200<br />
that the driver will accept as a true touch representing the weakest physical
+
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.  
contact with the touchscreen panel.
 
  
The effect of increasing this value is to make the touchscreen more sensitive
+
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
to light touches. The effect of decreasing this value is to make the
+
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.
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
+
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
Sensitivity and the Touchscreen X-Panel Resistance.
+
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.
  
Touchscreen Filter
+
Note that there is a linear relationship between the Touchscreen Pressure Sensitivity and the Touchscreen X-Panel Resistance.
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
+
===Touchscreen Filter===
module variance delta=30
+
INDEX_VALUE=0xffff<br />
module dejiter delta=100
+
DATA_VALUE recommended default: 0x14<br />
module linear
+
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".
  
If you are experiencing a touchscreen problem in which the mouse cursor jitters
+
===A Note Regarding TSLIB===
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
+
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

Revision as of 12:13, 27 December 2013

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 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

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 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

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 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

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 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

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

#module variance delta=30