Touchscreen

This page collects all the information about the various touch screen controllers in use on sunxi hardware.

= General information =

In general touchscreens are configured by the ctp_para in the fex file. There's also support for resistive touch panels by setting rtp_para in the fex. An example for built in RTP (resistive touch panel) built in controller can be found in the Fex Guide.

An example (for ft5x) would be: [ctp_para] ctp_used = 1 #enable or disable the touchscreen ctp_name = "ft5x_ts" #model of the touchscreen ctp_twi_id = 2 #I2C Interface ctp_twi_addr = 0x70 #I2C Address ctp_screen_max_x = 800 #X Settings ctp_screen_max_y = 480 #Y Settings ctp_revert_x_flag = 0 #Set this and ctp_revert_y_flag to 1 to flip x and y axis ctp_revert_y_flag = 0 ctp_exchange_x_y_flag = 0 ctp_int_port = port:PH21<6>  #INT port settings ctp_wakeup = port:PB13<1> <1> #Wakeup port settings ctp_io_port = port:PH21<0>  #IO Port Settings rst_port = port:PH20<1>  #RST port settings

Example for built in RTP: [rtp_para] rtp_used = 0 rtp_screen_size = 7 rtp_regidity_level = 7 rtp_press_threshold_enable = 0 rtp_press_threshold = 0x1f40 rtp_sensitive_level = 0xf rtp_exchange_x_y_flag = 0

Hardware
In general a capacitive touchscreen hardware consists of 6 Pins:
 * RST - Reset Pin (Input), Used by the CPU to reset the touchscreen.
 * SDA - I2C SDA (IO)
 * SCL - I2C SDL (Input)
 * INT - Interrupt Pin (Output, can be input during startup), used by the Touchscreen to indicate to the CPU that there are new events
 * VCC - Power Supply
 * GND - GND

Some touchscreen have wakeup pins to allow the touchscreen to go to sleep mode to save battery.

Mainly the I2C pins are connected to any i2c port on the CPU and is used to communicate with the touchscreen.

In the other way a resistive touchscreen has 4 wires. Details can be found in the user manuals for Allwinner chips, in the section TP (touch panel). The interesting thing is that sun4i, sun6i and sun7i have essentially the same RTP controllers so the sun4i_ts driver can work for all of them. Testing was done on an A20 platform and gave exceptionally good results.

Startup Procedure
Usually any touchscreen has a startup procedure during which resets are sent to the touchscreen by the cpu to indicate this procedure. During the reset/startup procedure usually the touchscreen profile data is sent to the touchscreen. Also in some cases the I2C address is set by this rest procedure (for instance, GT911).

The interrupt Pin can be part of the startup procedure for handshakes or indications. In some cases the interrupt pin is also used as input to read additional data from the cpu during reset.

Touchscreen profiles
Some touchscreen (for instance, GT911) require a so call Touchscreen Profile/Configuration. This configuration is sent during or right after the reset procedure of the touchscreen and is usually written to the controller memory (in some cases selectable persistent in eeprom). The Profile/Config defines the parameters of the touchscreen (such as physical size, active area(s). also it can include touchscreen button areas, touchscreen mode and more.

THIS CONFIGURATION MUST BE PROVIDED BY THE TOUCHSCREEN PRODUCER!

Example: 0x00,0x58,0x02,0x00,0x04,0x05,0x30,0x08,0x03,0x9F,0x14,\ 0x0F,0x8C,0x64,0x03,0x05,0x00,0x00,0x00,0x00,0x00,0x00,\ 0x00,0x18,0x1A,0x1E,0x14,0x8C,0x28,0x0C,0x18,0x14,0xD1,\ 0x0B,0x00,0x00,0x01,0x9C,0x02,0x35,0x00,0x00,0x00,0x00,\ 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x14,0x64,0x94,0x85,\ 0x02,0x08,0x00,0x00,0xCD,0x07,0x16,0xBF,0x09,0x19,0xFC,\ 0x0C,0x1B,0xE7,0x0D,0x22,0x77,0x0E,0x2D,0x00,0x00,0x00,\ 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,\ 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,\ 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,\ 0x00,0x00,0x02,0x04,0x06,0x08,0x0A,0x0C,0x0E,0x10,0x12,\ 0x14,0x16,0x18,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,\ 0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0x00,\ 0x02,0x04,0x06,0x08,0x0A,0x0C,0x0F,0x10,0x12,0x13,0x14,\ 0x16,0x18,0x1C,0x1D,0x1E,0x1F,0x20,0x21,0xFF,0xFF,0xFF,\ 0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,\ 0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0x7C,0x01\ }
 * 1) define CTP_CFG_GROUP1 {\

Touchscreen modes
There is 2 modes a touchscreen can work in:
 * Polling Mode
 * Interrupt Mode

This mode is usually defined by the Touchscreen profile/config or the startup/reset procedure.

The preferred mode a capacitive touchscreen should work in is always interrupt mode. In Interrupt mode every time an event on the touchscreen occurs the INT pin triggers and notifies the CPU. the cpu then read the new event from the touchscreen.

In Polling mode the cpu periodically requests the touchscreen data from the touchscreen. This means that there will be a lot of communication on the i2c port since this has to happen once every few ms.

As stated above whenever possible use interrupt mode!

Hardware Configuration and Fex
It is very important to configure the FEX file correctly for your touchscreen.

Step 1
In your hardware schematics identify the I2C pins of your touchscreen and see which I2C it is connected to and set the ctp_twi_id to the id of i2c port. Now you need to find our your i2c address of your touchscreen. this is something you can get out of the chip datasheet or your touchscreen manufacture.

Remember that the address of the touchscreen might be changed when sending the profile/config or via the reset procedure.

Step 2
In your schematics find out which GPIO Pin the INT Pin is connected to.

Define: ctp_int_port = port: PH21 <6>

please also note the <6> part in the line above. Verify that the Interrupt setting of your Int pin is Function number 6 of the mux setting or modify the  according.

Note that on some touchscreens (ft5x) it is required to define another port called the IO port on the same port as the interrupt port: ctp_io_port = port: PH21<0> This setting will define the same port with mux setting 0 as output to allow the driver to switch to IO mode.

Step 3
In your schematics find out which GPIO Pin the RST Pin is connected to.

rst_port = port:PH20<1>  #RST port settings Note that <1> sets the port as an output.

It might be required to define additional pins for your touchscreen

Software Calibration
Calibration of a touchscreen device can be done with the xinput_calibrator. The xinput_calibrator is very simple tool which enables you to go through standard calibration procedure (press a few points on the screen) and then produces a snippet for xorg.conf.

There can be problems with produced configuration so it's good to test and see what's actually happening. Try to move your finger over the screen and see if there's some sings of miscalibration. Produced config actually scales values from touchscreen controller to map to the screen so it may happen that one axis works ok and another doesn't. Anyways, xinput_calibrator can give you good hint for start and you can tweak it further manually. Detailed list of options can be found in the evdev manual page.

= Manufacturers =

Elan
Elan Microelectronics Corporation

Focaltech
Link

Support is available for sunxi-3.4.

FT5301
Supported in sunxi-3.4

FT5402DQT
Supported in sunxi-3.4

FT5x06

 * FT5206GE1
 * FT5306DE4
 * FT5406EE8

Supported in sunxi-3.4

FocalTech FR5x06 chips are also supported in Linux upstream as of 2014-03-28.

Device Tree binding documentation:

Goodix
Link

Situation with Goodix touchscreen drivers is very messy - not a single driver with devicetree support has been included upstream (as of version 3.6.19), though there's a cleaned up version of GT911 driver available (supporting ACPI).

For older chips there are various driver sources targeting older kernel versions (linux-3.3 or linux-3.4) scattered around in different vendor-provided source trees or SDKs.

Also, no datasheets for this hardware and to make things even harder, firmware also seems to contain calibration data which is device-specific.

GT801
No mainline support. Driver available in sunxi-3.4

GT801 2+1
No mainline support. Driver available in sunxi-3.4

GT811
No mainline support. Driver available in sunxi-3.4

GT818
No mainline support. Driver available in sunxi-3.4

GT828
No mainline support. No driver in sunxi-3.4, WIP patch

GT911
Upstream has initial driver for GT911 (since 3.6.19), though it currently only uses ACPI and lacks devicetree support.

No driver in sunxi-3.4, WIP driver

Datasheet(chinese): Goodix GT911 Datasheet.pdf

GSL1680

 * GSL1680 - capacitive, multitactile touchscreen controller

Solomon Systech Limited
This Hong Kong based company creates various LCD/OLED driver and touchscreen chips.

zet6221

 * Datasheet: http://linux-sunxi.org/images/2/22/ZP-HW-PS-0003_ZET6221_Product_Spec_v1_2.pdf
 * Driver: https://github.com/wingrime/zet6221-ts-drv

= See also =