The touchscreen driver is used to power on its integrated circuit \(IC\), configure and initialize hardware pins, register interrupts, configure Inter-Integrated Circuit \(I2C\) or SPI APIs, set input-related configurations, and download and update firmware.
### Function Introduction
The touchscreen driver powers on its integrated circuit (IC), initializes hardware pins, registers interrupts, configures the communication (I2C or SPI) interface, sets input configurations, and downloads and updates firmware.
-**Layers of the Touchscreen driver**
The touchscreen driver is developed based on the OpenHarmony input driver model, which applies basic APIs of the operating system abstraction layer (OSAL) and platform interface layer on the OpenHarmony Hardware Driver Foundation [(HDF)](../driver/driver-hdf-development.md). Common APIs include the bus communication APIs and OS native APIs (such as memory, lock, thread, and timer APIs). The OSAL and platform APIs shield the differences of underlying hardware. This allows the use of the touchscreen driver across platforms and OSs. In this regard, you can develop the touchscreen driver only once and deploy it on multiple devices.
This section describes how to develop the touchscreen driver based on the input driver model. [Figure 1](#fig6251184817261) shows an overall architecture of the touchscreen driver.
### Working Principles
The input driver is developed based on the hardware driver foundation \(HDF\), platform APIs, and operating system abstraction layer \(OSAL\) APIs. It provides hardware driver capabilities through the input Hardware Device Interfaces \(HDIs\) for upper-layer input services to control the touchscreen.
The input driver model is developed based on the HDF and APIs of the platform and OSAL. It provides hardware driver capabilities through the input Hardware Driver Interface (HDI) for upper-layer input services to control the touchscreen. The following figure shows the architecture of the input driver model.
**Figure 1** Input driver model
**Figure 1** Architecture of the input driver model<aname="fig6251184817261"></a>
The input driver model mainly consists of the device manager, common drivers, and chip drivers. The platform data channel provides capabilities for sending data generated by the touchscreen from the kernel to the user space. The driver model adapts to different touchscreen devices and hardware platforms via the configuration file, improving the efficiency of the touchscreen development. The description for each part of the input driver model is as follows:
- Input Device Manager: provides APIs for input device drivers to register and deregister input devices and manages the input device list in a unified manner.
- Common input drivers: provide common APIs that are applicable to different input devices (such as the common driver APIs for touchscreens). The APIs can be used to initialize board-specific hardware, handle hardware interrupts, and register input devices with the Input Device Manager.
- Input chip drivers: provide differentiated APIs for the drivers form different vendors. You can use these APIs to develop your drivers with minimum modification.
- Event Hub: provides a unified channel for different input devices to report input events.
- HDF input config: parses and manages the board-specific and private configuration of input devices.
- Input device manager: provides input device drivers with the APIs for registering or unregistering input devices and manages the input device list.
The input driver model provides configuration files to help you quickly develop your drivers.
- Input common driver: provides common abstract drivers \(such as the touchscreen common driver\) of various input devices for initializing the board-level hardware, processing hardware interrupts, and registering input devices with the input device manager.
- Input chip driver: provides different chip drivers of each vendor. You can minimize the workload for the input chip driver development by calling differentiated APIs reserved by the input platform driver.
## How to Develop
- Event hub: provides a unified data reporting channel, which enables input devices to report input events.
### When to Use
- HDF input config: parses and manages the board-level configuration as well as the private configuration of input devices.
The input module provides APIs for powering on the touchscreen driver IC, configuring and initializing hardware pins, registering interrupts, configuring the communication (I2C or SPI) interface, setting input configurations, and downloading and updating firmware.
### Available APIs
-**Advantages of developing drivers based on the HDF**
#### Hardware Interfaces
The touchscreen driver is developed based on the [HDF](driver-hdf-development.md) and is implemented via calls to the OSAL and platform APIs, including bus APIs and OS native APIs \(such as memory, lock, thread, and timer\). The OSAL and platform APIs hide the differences of underlying hardware, so that the touchscreen driver can be migrated across platforms and OSs. In this regard, you can develop the touchscreen driver only once but deploy it on multiple devices.
The hardware interfaces for touchscreens can be classified into the following types based on the pin attributes:
- Power interfaces
## Available APIs<a name="section105459441659"></a>
- I/O control interfaces
Based on the attributes of the pins, interfaces on the touchscreens can be classified into the following types:
- Communication interfaces
- Power interfaces
- I/O control interfaces
- Communications interfaces
**Figure 2** Common touchscreen pins
**Figure 2** Common pins of the touchscreen<aname="fig1290384314416"></a>
The interfaces shown in the figure are described as follows:
The interfaces shown in the preceding figure are described as follows:
-**Power interfaces**
- LDO\_1P8: 1.8 V digital circuits
- LDO\_3P3: 3.3 V analog circuits
1.**Power interfaces**
Generally, the touchscreen driver IC is separated from the LCD driver IC. In this case, the touchscreen driver IC requires both 1.8 V and 3.3 V power supplies. Nowadays, the touchscreen driver IC and LCD driver IC can be integrated. Therefore, the touchscreen, requires only the 1.8 V power supply, and the 3.3 V power required internally is supplied by the LCD VSP power \(typical value: 5.5 V\) in the driver IC.
-**LDO_1P8**: 1.8 V digital circuit
-**LDO_3P3**: 3.3 V analog circuit
-**I/O control interfaces**
- RESET: reset pin, which is used to reset the driver IC on the host when suspending or resuming the system.
- INT: interrupt pin, which needs to be set to the input direction and pull-up status during driver initialization. After detecting an external touch signal, the driver triggers the interrupt by operating the interrupt pin. The driver reads the touch reporting data in the ISR function.
If the touchscreen driver and ICD driver have its own IC, the touchscreen driver IC requires 1.8 V and 3.3 V power supplies. If the touchscreen driver and LCD driver have an integrated IC, you only need to care about the 1.8 V power supply for the touchscreen. The 3.3 V power supply required can be provided by the LCD VSP power (typically 5.5 V) in the driver IC.
-**Communications interfaces**
- I2C: Since only a small amount of touch data is reported by the touchscreen, I2C is used to transmit the reported data. For details about the I2C protocol and interfaces, see [I2C](driver-platform-i2c-des.md#section5361140416).
- SPI: In addition to touch reporting data coordinates, some vendors need to obtain basic capacitance data. Therefore, Serial Peripheral Interface \(SPI\) is used to transmit such huge amount of data. For details about the SPI protocol and interfaces, see [SPI](driver-platform-spi-des.md#overview).
2.**I/O control interfaces**
-**RESET**: pin used to reset the driver IC on the host when the kernel is put into hibernation or waken up.
-**INT**: interrupt pin, which must be set to the input pull-up state during driver initialization. After detecting an external touch signal, the driver triggers an interrupt by operating the interrupt pin. Then, the driver reads the touch reporting data in an interrupt handler.
## How to Develop<a name="section65745222184"></a>
3.**Communication interfaces**
Regardless of the OS and system on a chip \(SoC\), the input driver is developed based on the HDF, platform, and OSAL APIs to provide a unified driver model for touchscreen devices.
- I2C: I2C is used if a small amount of data is reported by the touchscreen. For details about the I2C protocol and related operation APIs, see [I2C](../driver/driver-platform-i2c-des.md).
- SPI: SPI is used if a large amount of data is reported by the touchscreen. For details about the SPI protocol and related operation APIs, see [SPI](../driver/driver-platform-spi-des.md).
The following uses the touchscreen driver as an example to describe the loading process of the input driver model:
#### Software Interfaces
1. Complete the device description configuration, such as the loading priority, board-level hardware information, and private data, by referring to the existing template.
The HDI driver APIs provided for the input service can be classified into the input manager module, input reporter module, and input controller module. The following tables describe the available APIs.
2. Load the input device management driver. The input management driver is loaded automatically by the HDF to create and initialize the device manager.
- input_manager.h
3. Load the platform driver. The platform driver is loaded automatically by the HDF to parse the board-level configuration, initialize the hardware, and provide the API for registering the touchscreen.
4. Load the touchscreen driver. The touchscreen driver is loaded automatically by the HDF to instantiate the touchscreen device, parse the private data, and implement differentiated APIs provided by the platform.
- input_reporter.h
5. Register the instantiated touchscreen device with the platform driver. Then bind this device to the platform driver, and complete touchscreen initialization such as interrupt registration and power-on and power-off.
| int32_t (*RegisterReportCallback)(uint32_t devIndex, InputReportEventCb *callback); | Registers a callback for an input device.|
| int32_t (*UnregisterReportCallback)(uint32_t devIndex); | Unregisters the callback for an input device.|
| void (*ReportEventPkgCallback)(const EventPackage **pkgs, uint32_t count); | Called to report input event data. |
6. Instantiate the input device and register it with the input manager after the touchscreen is initialized.
Perform the following steps:
1. Add the touchscreen driver-related descriptions.
Currently, the input driver is developed based on the HDF and is loaded and started by the HDF. Register the driver information, such as whether to load the driver and the loading priority in the configuration file. Then, the HDF starts the registered driver modules one by one. For details about the driver configuration, see [How to Develop](driver-hdf-development.md).
2. Complete the board-level configuration and private data configuration of the touchscreen.
Configure the required I/O pins. For example, configure a register for the I2C pin reserved for the touchscreen to use I2C for transmitting data.
3. Implement differentiated adaptation APIs of the touchscreen.
Use the platform APIs to perform operations for the reset pins, interrupt pins, and power based on the communications interfaces designed for boards. For details about the GPIO-related operations, see [GPIO](driver-platform-gpio-des.md#overview).
## Development Example<a name="section263714411191"></a>
This example describes how to develop the touchscreen driver.
### Adding the Touchscreen Driver-related Description<a name="section18249155619195"></a>
The information about modules of the input driver model is shown as follows and enables the HDF to load the modules in sequence. For details, see [Driver Development](driver-hdf-development.md).
```
input :: host {
hostName = "input_host";
priority = 100;
device_input_manager :: device {
device0 :: deviceNode {
policy = 2; // Publish services externally.
priority = 100; // Loading priority. The input device manager in the input driver has the highest priority.
preload = 0; // Value 0 indicates that the driver is to be loaded, and value 1 indicates the opposite.
permission = 0660;
moduleName = "HDF_INPUT_MANAGER";
serviceName = "input_dev_manager";
deviceMatchAttr = "";
}
}
device_hdf_touch :: device {
device0 :: deviceNode {
policy = 2;
priority = 120;
preload = 0;
permission = 0660;
moduleName = "HDF_TOUCH";
serviceName = "event1";
deviceMatchAttr = "touch_device1";
}
}
device_touch_chip :: device {
device0 :: deviceNode {
policy = 0;
priority = 130;
preload = 0;
permission = 0660;
moduleName = "HDF_TOUCH_SAMPLE";
serviceName = "hdf_touch_sample_service";
deviceMatchAttr = "zsj_sample_5p5";
}
}
}
```
### Adding Board Configuration and Touchscreen Private Configuration<a name="section3571192072014"></a>
The following describes the configuration of the board-level hardware and private data of the touchscreen. You can modify the configuration based on service requirements.
```
root {
input_config {
touchConfig {
touch0 {
boardConfig {
match_attr = "touch_device1";
inputAttr {
inputType = 0; // Value 0 indicates that the input device is a touchscreen.
solutionX = 480;
solutionY = 960;
devName = "main_touch"; // Device name
}
busConfig {
busType = 0; // Value 0 indicates the I2C bus.
busNum = 6;
clkGpio = 86;
dataGpio = 87;
i2cClkIomux = [0x114f0048, 0x403]; // Register configuration of the i2c_clk pin
i2cDataIomux = [0x114f004c, 0x403]; // Register configuration of the i2c_data pin
}
pinConfig {
rstGpio = 3;
intGpio = 4;
rstRegCfg = [0x112f0094, 0x400]; // Register configuration of the reset pin
intRegCfg = [0x112f0098, 0x400]; // Register configuration of the interrupt pin
}
powerConfig {
vccType = 2; // Values 1, 2, and 3 indicate the low-dropout regulator (LDO), GPIO, and PMIC, respectively.
vccNum = 20; // The GPIO number is 20.
vccValue = 1800; // The voltage amplitude is 1800 mV.
vciType = 1;
vciNum = 12;
vciValue = 3300;
}
featureConfig {
capacitanceTest = 0;
gestureMode = 0;
gloverMOde = 0;
coverMode = 0;
chargerMode = 0;
knuckleMode = 0;
}
}
chipConfig {
template touchChip {
match_attr = "";
chipName = "sample";
vendorName = "zsj";
chipInfo = "AAAA11222"; // The first four characters indicate the product name. The fifth and sixth characters indicate the IC model. The last three characters indicate the chip model.
busType = 0;
deviceAddr = 0x5D;
irqFlag = 2; // Values 1 and 2 indicate that the interrupt is triggered on the rising and falling edges, respectively. Values 4 and 8 indicate that the interrupt is triggered by the high and low levels, respectively.
maxSpeed = 400;
chipVersion = 0;
powerSequence {
/* Power-on sequence is described as follows:
[Type, status, direction, delay]
<type> Value 0 indicates the power or pin is empty. Values 1 and 2 indicate the VCC (1.8 V) and VCI (3.3 V) power, respectively. Values 3 and 4 indicate the reset and interrupt pins, respectively.
<status> Values 0 and 1 indicate the power-off or pull-down, and the power-on or pull-up, respectively. Value 2 indicates that no operation is performed.
<dir> Values 0 and 1 indicate the input and output directions, respectively. Value 2 indicates that no operation is performed.
<delay> Delay time, in milliseconds.
*/
powerOnSeq = [4, 0, 1, 0,
3, 0, 1, 10,
3, 1, 2, 60,
4, 2, 0, 0];
suspendSeq = [3, 0, 2, 10];
resumeSeq = [3, 1, 2, 10];
powerOffSeq = [3, 0, 2, 10,
1, 0, 2, 20];
}
}
chip0 :: touchChip {
match_attr = "zsj_sample_5p5";
chipInfo = "ZIDN45100";
chipVersion = 0;
}
}
}
}
}
}
```
### Adding the Touchscreen Driver<a name="section6356758162015"></a>
The following example shows how to implement the differentiated APIs provided by the platform driver to obtain and parse the touchscreen data. You can adjust the development process based on the board and touchscreen in use.
```
/* Parse the touch reporting data read from the touchscreen into coordinates. */
For more information, see [input](https://gitee.com/openharmony/drivers_peripheral/tree/master/input).
### Development Procedure
The load process of the input driver model (for the touchscreen driver) is as follows:
1. The device configuration, including the driver loading priority, board-specific hardware information, and private data, is complete.
2. The HDF driver loads the input device manager driver to create and initialize the device manager.
3. The HDF loads the platform driver to parse the board-specific configuration, initialize the hardware, and provide the API for registering the touchscreen.
4. The HDF loads the touchscreen driver to instantiate the touchscreen device, parse the private data, and implement the differentiated APIs for the platform.
5. The instantiated touchscreen device registers with the platform driver to bind the device and the driver and complete the device initialization, including interrupt registration and device power-on and power-off.
6. The instantiated input device registers with the input device manager for unified management.
The development process of the touchscreen driver is as follows:
1. Configure device information. <br>The input driver is developed based on the HDF. The HDF loads and starts the driver in a unified manner. You need to configure the driver information, such as whether to load the driver and the loading priority, in the configuration file. Then, the HDF starts the registered driver modules one by one. For details about how to configure the driver, see [Driver Development](../driver/driver-hdf-development.md#how-to-develop).
2. Configure board-specific information and touchscreen private information.<br>Configure the I/O pin functions. For example, set registers for the I2C pins on the board for the touchscreen to enable I2C communication.
3. Implement device-specific APIs.<br>Based on the communication interfaces designed for the board, use the pin operation APIs provided by the platform interface layer to configure the corresponding reset pin, interrupt pin, and power operations. For details about GPIO operations, see [GPIO](../driver/driver-platform-gpio-des.md).
### Development Example
The following example describes how to develop the touchscreen driver for an RK3568 development board.
1. Configure device information.
Configure the modules of the input driver model in **drivers/adapter/khdf/linux/hcs/device_info/device_info.hcs**. For details, see [Driver Development](../driver/driver-hdf-development.md). Then, the HDF loads the modules of the input model in sequence based on the configuration information.
```c
input::host{
hostName="input_host";
priority=100;
device_input_manager::device{
device0::deviceNode{
policy=2;// The driver provides services externally.
priority=100;// Loading priority. In the input model, the manager module has the highest priority.
preload=0;// Whether to load the driver. The value 0 means to load the driver; 1 means the opposite.
permission=0660;
moduleName="HDF_INPUT_MANAGER";
serviceName="input_dev_manager";
deviceMatchAttr="";
}
}
device_hdf_touch::device{
device0::deviceNode{
policy=2;
priority=120;
preload=0;
permission=0660;
moduleName="HDF_TOUCH";
serviceName="event1";
deviceMatchAttr="touch_device1";
}
}
device_touch_chip::device{
device0::deviceNode{
policy=0;
priority=130;
preload=0;
permission=0660;
moduleName="HDF_TOUCH_SAMPLE";
serviceName="hdf_touch_sample_service";
deviceMatchAttr="zsj_sample_5p5";
}
}
}
```
2. Configure board-specific and private data for the touchscreen.
Configure the data in **drivers/adapter/khdf/linux/hcs/input/input_config.hcs**. The following is an example. You can modify the configuration as required.
```c
root{
input_config{
touchConfig{
touch0{
boardConfig{
match_attr="touch_device1";
inputAttr{
inputType=0;// 0 indicates touchscreen.
solutionX=480;
solutionY=960;
devName="main_touch";// Device name.
}
busConfig{
busType=0;// 0 indicates I2C.
busNum=6;
clkGpio=86;
dataGpio=87;
i2cClkIomux=[0x114f0048,0x403];// Register of the I2C_CLK pin.
i2cDataIomux=[0x114f004c,0x403];// Register of the I2C_DATA pin.
}
pinConfig{
rstGpio=3;
intGpio=4;
rstRegCfg=[0x112f0094,0x400];// Register of the reset pin.
intRegCfg=[0x112f0098,0x400];// Register of the interrupt pin.
}
powerConfig{
vccType=2;// The value 1 stands for LDO, 2 for GPIO, and 3 for PMIC.
vccNum=20;// Set the GPIO number to 20.
vccValue=1800;// Set the voltage amplitude to 1800 mV.
vciType=1;
vciNum=12;
vciValue=3300;
}
featureConfig{
capacitanceTest=0;
gestureMode=0;
gloverMOde=0;
coverMode=0;
chargerMode=0;
knuckleMode=0;
}
}
chipConfig{
templatetouchChip{
match_attr="";
chipName="sample";
vendorName="zsj";
chipInfo="AAAA11222";// The first four characters indicate the product name. The fifth and sixth characters indicate the IC model. The last three characters indicate the model number.
busType=0;
deviceAddr=0x5D;
irqFlag=2;// The value 1 means to trigger an interrupt on the rising edge, 2 means to trigger an interrupt on the falling edge, 4 means to trigger an interrupt by the high level, and 8 means to trigger an interrupt by the low level.
maxSpeed=400;
chipVersion=0;
powerSequence{
/* Description of the power-on sequence:
[type, status, direction, delay]
<type> 0 stands for null; 1 for VCC power (1.8 V); 2 for VCI power (3.3 V); 3 for reset pin; 4 for interrupt pin.
<status> 0 stands for power-off or pull-down; 1 for power-on or pull-up; 2 for no operation.
<dir> 0 stands for input; 1 for output; 2 for no operation.
<delay> indicates the delay, in milliseconds. For example, 20 indicates 20 ms delay.
*/
powerOnSeq=[4,0,1,0,
3,0,1,10,
3,1,2,60,
4,2,0,0];
suspendSeq=[3,0,2,10];
resumeSeq=[3,1,2,10];
powerOffSeq=[3,0,2,10,
1,0,2,20];
}
}
chip0::touchChip{
match_attr="zsj_sample_5p5";
chipInfo="ZIDN45100";
chipVersion=0;
}
}
}
}
}
}
```
3. Add the touchscreen driver.
Implement the touchscreen-specific APIs in **divers/framework/model/input/driver/touchscreen/touch_gt911.c**. The following uses the APIs for obtaining and parsing device data as an example. You can implement the related APIs to match your development.
```c
/* Parse the touch reporting data read from the touchscreen into coordinates. */
