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 =

ChipOne

 * Mainline kernel driver: icn8138
 * WIP drivers:
 * icn85xx - WIP branch (announcement)

Elan
Elan Microelectronics Corporation

Focaltech
Link

Support is available for sunxi-3.4.

FT5301
Supported in sunxi-3.4

FT5302
???

FT5402DQT
Supported in sunxi-3.4

FT5x06
Supported in mainline kernel.


 * FT5206GE1
 * FT5306DE4
 * FT5406EE8

sunxi-3.4
Supported, but the driver does not load on A20 without the following patch. See this conversation for more information. diff --git a/drivers/input/touchscreen/ft5x_ts.c b/drivers/input/touchscreen/ft5x_ts.c index 5d8dc97..3d88694 100644 --- a/drivers/input/touchscreen/ft5x_ts.c +++ b/drivers/input/touchscreen/ft5x_ts.c @@ -1762,7 +1762,7 @@ ft5x_ts_probe(struct i2c_client *client, const struct i2c_device_id *id) pr_info("%s:ctp_ops.set_irq_mode err.\n", __func__); goto exit_set_irq_mode; } -      err = request_irq(SW_INT_IRQNO_PIO, ft5x_ts_interrupt, IRQF_TRIGGER_FALLING | IRQF_SHARED, "ft5x_ts", ft5x_ts); +      err = request_irq(SW_INT_IRQNO_PIO, ft5x_ts_interrupt, IRQF_SHARED, "ft5x_ts", ft5x_ts);

if (err < 0) { dev_err(&client->dev, "ft5x_ts_probe: request irq failed\n");

This driver does not support transformations (e.g. x-revert), but generates events complying to the multi touch protocol.

Goodix
Manufacturer's website

Datasheets for various GT9xx devices.

Driver for most of the Goodix 9xx chips (see below) is available in mainline. It is quite possible that all the 9xx-series chips are supported by this driver because they seem to have a common register layout. Goodix 8xx is currently unsupported by mainline.

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.

GT801
No mainline support. Driver available in sunxi-3.4

GT801 2+1
No mainline support. RFC patch that needs to be adapted to work alongside gt9xx chips.

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

GT9xx
Support for various Goodix GT9xx chips is available since Linux-4.1 via common goodix driver:
 * gt911
 * gt9110
 * gt912
 * gt927
 * gt9271
 * gt928
 * gt967

For sunxi-3.4, there's WIP driver.

Silead
WiP driver for mainline supporting: gsl1680, gsl1688, gsl3670, gsl3675, gsl3692 and mssl1680 variants.

Please note that you still need firmware supporting your device.

Datasheet for GSL3680: http://dl.linux-sunxi.org/touchscreen/GSL3680_touch-screen-controller-ic-DataSheet_Chinese_RevA1.2.pdf

See also:
 * GSL1680 - capacitive, multitactile touchscreen controller

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

zet6221
Mainline WIP driver: https://github.com/jelly/linux-zet62xx currently only supports the zet6223 model which doesn't seem to be requiring firmware support. Working on supporting the zet6221 with firmware support. Upstream patch submitted: http://www.spinics.net/lists/linux-input/msg46738.html
 * 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 =