Touch Panel

[中文]

Touch panels are now standard components in display applications. ESP-IoT-Solution provides drivers for common types of touch panels and currently supports the following controllers:

Resistive Touch Panel	Capacitive Touch Panel
XPT2046	FT5216
NS2016	FT5436
	FT6336
	FT5316

The capacitive touch panel controllers listed above can usually be driven by FT5x06.

Similar to the screen driver, some common functions are encapsulated in the touch_panel_driver_t structure, in order to port them to different GUI libraries easily. After initializing the touch panel, users can conduct operations by calling functions inside the structure, without paying attention to specific touch panel models.

Touch Panel Calibration

In actual applications, resistive touch panels must be calibrated before use, while capacitive touch panels are usually calibrated by controllers and do not require extra calibration steps. A calibration algorithm is integrated in the resistive touch panel driver. During the process, three points are used to calibrate, in which one point is used for verification. If the verified error exceeds a certain threshold value, it means the calibration has failed and a new round of calibration is started automatically until it succeeds.

The calibration process will be started by calling calibration_run(). After finished, the parameters are stored in NVS for next initialization to avoid repetitive work.

Press Touch Panel

Generally, there is an interrupt pin inside the touch panel controller (both resistive and capacitive) to signal touch events. However, this is not used in the touch panel driver, because IOs should be saved for other peripherals in screen applications as much as possible; on the other hand the information in this signal is not as accurate as data in registers.

For resistive touch panels, when the pressure in the Z direction exceeds the configured threshold, it is considered as pressed; for capacitive touch panels, the detection of over one touch point will be considered as pressed.

Touch Panel Rotation

A touch panel has eight directions, like the screen, defined in touch_panel_dir_t. The rotation of a touch panel is achieved by software, which usually sets the direction of a touch panel and a screen as the same. But this should not be fixed, for example, when using a capacitive touch panel, the inherent direction of the touch panel may not fit with the original display direction of the screen. Simply setting these two directions as the same may not show the desired contents. Therefore, please adjust the directions according to the actual situation.

On top of that, the configuration of its resolution is also important since the converted display after a touch panel being rotated relies on the resolution of its width and height. An incorrect configuration of the resolution may give you a distorted display.

Note

If you are using a resistive touch panel, the touch position can become inaccurate after it being rotated, since the resistance value in each direction may not be distributed uniformly. It is recommended to not rotate a resistive touch panel after it being calibrated.

Application Example

Initialize a Touch Panel

touch_panel_driver_t touch; // a touch panel driver

i2c_config_t i2c_conf = {
    .mode = I2C_MODE_MASTER,
    .sda_io_num = 35,
    .sda_pullup_en = GPIO_PULLUP_ENABLE,
    .scl_io_num = 36,
    .scl_pullup_en = GPIO_PULLUP_ENABLE,
    .master.clk_speed = 100000,
};
i2c_bus_handle_t i2c_bus = i2c_bus_create(I2C_NUM_0, &i2c_conf);

touch_panel_config_t touch_cfg = {
    .interface_i2c = {
        .i2c_bus = i2c_bus,
        .clk_freq = 100000,
        .i2c_addr = 0x38,
    },
    .interface_type = TOUCH_PANEL_IFACE_I2C,
    .pin_num_int = -1,
    .direction = TOUCH_DIR_LRTB,
    .width = 800,
    .height = 480,
};

/* Initialize touch panel controller FT5x06 */
touch_panel_find_driver(TOUCH_PANEL_CONTROLLER_FT5X06, &touch);
touch.init(&touch_cfg);

/* start to run calibration */
touch.calibration_run(&lcd, false);

Note

When using a capacitive touch panel, the call to the calibration function will return ESP_OK directly.
By default, only FT5x06 touch panel driver is enabled, please go to menuconfig -> Component config -> Touch Screen Driver -> Choose Touch Screen Driver to do configurations if you need to enable other drivers.

To Know If a Touch Panel is Pressed and Its Corresponding Position

touch_panel_points_t points;
touch.read_point_data(&points);
int32_t x = points.curx[0];
int32_t y = points.cury[0];
if(TOUCH_EVT_PRESS == points.event) {
    ESP_LOGI(TAG, "Pressed, Touch point at (%d, %d)", x, y);
}

API Reference

Header File

components/display/touch_panel/touch_panel.h

Functions

esp_err_t touch_panel_find_driver(touch_panel_controller_t controller, touch_panel_driver_t *out_driver)

Find a touch panel controller driver.

Parameters

controller – Touch panel controller to initialize
out_driver – Pointer to a touch driver

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG Arguments is NULL.
ESP_ERR_NOT_FOUND: Touch panel controller was not found.

Structures

struct touch_panel_points_t

Information of touch panel.

Public Members

touch_panel_event_t event: Event of touch

uint8_t point_num: Touch point number

uint16_t curx[TOUCH_MAX_POINT_NUMBER]: Current x coordinate

uint16_t cury[TOUCH_MAX_POINT_NUMBER]: Current y coordinate

struct touch_panel_config_t

Configuration of touch panel.

Public Members

i2c_bus_handle_t i2c_bus: Handle of i2c bus

int clk_freq

i2c clock frequency

spi clock frequency

uint8_t i2c_addr: screen i2c slave adddress

struct touch_panel_config_t::[anonymous]::[anonymous] interface_i2c: I2c interface

spi_bus_handle_t spi_bus: Handle of spi bus

int8_t pin_num_cs: SPI Chip Select Pin

struct touch_panel_config_t::[anonymous]::[anonymous] interface_spi: SPI interface

union touch_panel_config_t::[anonymous] [anonymous]: Interface configuration

touch_panel_interface_type_t interface_type: Interface bus type, see touch_interface_type_t struct

int8_t pin_num_int: Interrupt pin of touch panel. NOTE: You can set to -1 for no connection with hardware. If PENIRQ is connected, set this to pin number.

touch_panel_dir_t direction: Rotate direction

uint16_t width: touch panel width

uint16_t height: touch panel height

struct touch_panel_driver_t

Define screen common function.

Public Members

esp_err_t (*init)(const touch_panel_config_t *config)

Initial touch panel.

Attention: If you have been called function touch_panel_init() that will call this function automatically, and should not be called it again.

Param config

Pointer to a structure with touch config arguments.

Return

ESP_OK Success
ESP_FAIL Fail

esp_err_t (*deinit)(void)

Deinitial touch panel.

Return

ESP_OK Success
ESP_FAIL Fail

esp_err_t (*calibration_run)(const scr_driver_t *screen, bool recalibrate)

Start run touch panel calibration.

Param screen

Screen driver for display prompts

Param recalibrate

Is mandatory, set true to force calibrate

Return

ESP_OK Success
ESP_FAIL Fail

esp_err_t (*set_direction)(touch_panel_dir_t dir)

Set touch rotate rotation.

Param dir

rotate direction

Return

ESP_OK Success
ESP_FAIL Fail

esp_err_t (*read_point_data)(touch_panel_points_t *point)

Get current touch information, see struct touch_panel_points_t.

Param point

a pointer of touch_panel_points_t contained touch information.

Return

ESP_OK Success
ESP_FAIL Fail

Macros

TOUCH_MAX_POINT_NUMBER: max point number on touch panel

Enumerations

enum touch_panel_event_t

Touch events.

Values:

enumerator TOUCH_EVT_RELEASE: Release event

enumerator TOUCH_EVT_PRESS: Press event

enum touch_panel_dir_t

Define all screen direction.

Values:

enumerator TOUCH_DIR_LRTB: From left to right then from top to bottom, this consider as the original direction of the touch panel

enumerator TOUCH_DIR_LRBT: From left to right then from bottom to top

enumerator TOUCH_DIR_RLTB: From right to left then from top to bottom

enumerator TOUCH_DIR_RLBT: From right to left then from bottom to top

enumerator TOUCH_DIR_TBLR: From top to bottom then from left to right

enumerator TOUCH_DIR_BTLR: From bottom to top then from left to right

enumerator TOUCH_DIR_TBRL: From top to bottom then from right to left

enumerator TOUCH_DIR_BTRL: From bottom to top then from right to left

enumerator TOUCH_DIR_MAX

enumerator TOUCH_MIRROR_X: Mirror X-axis

enumerator TOUCH_MIRROR_Y: Mirror Y-axis

enumerator TOUCH_SWAP_XY: Swap XY axis

enum touch_panel_interface_type_t

Values:

enumerator TOUCH_PANEL_IFACE_I2C: I2C interface

enumerator TOUCH_PANEL_IFACE_SPI: SPI interface

enum touch_panel_controller_t

All supported touch panel controllers.

Values:

enumerator TOUCH_PANEL_CONTROLLER_FT5X06

enumerator TOUCH_PANEL_CONTROLLER_XPT2046

enumerator TOUCH_PANEL_CONTROLLER_NS2016

Provide feedback about this document