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

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 address

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