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.

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

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.

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

= Manufacturers =

Elan
Elan Microelectronics Corporation

Focaltech
Link

Goodix
Link

Situation with Goodix touchscreen drivers is very messy - not a single driver has yet been ported to upstream (as of version 3.17) and 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

GT911
No mainline support. No driver in sunxi-3.4

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 =