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
-
touch_panel_event_t event
-
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
-
i2c_bus_handle_t i2c_bus
-
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
-
esp_err_t (*init)(const touch_panel_config_t *config)
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
-
enumerator TOUCH_EVT_RELEASE
-
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
-
enumerator TOUCH_DIR_LRTB