feat(multi-touch): Add get_data API to esp_lcd_touch

Author: PetrESP

components/lcd_touch/esp_lcd_touch/esp_lcd_touch.c

@@ -1,10 +1,11 @@
 /*
- * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
 
 #include <stdlib.h>
+#include <string.h>
 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"
 #include "driver/gpio.h"
@@ -30,7 +31,8 @@ static const char *TAG = "TP";
 
 esp_err_t esp_lcd_touch_enter_sleep(esp_lcd_touch_handle_t tp)
 {
-    assert(tp != NULL);
+    ESP_RETURN_ON_FALSE(tp != NULL, ESP_ERR_INVALID_ARG, TAG, "Touch point handler can't be NULL");
+
     if (tp->enter_sleep == NULL) {
         ESP_LOGE(TAG, "Sleep mode not supported!");
         return ESP_FAIL;
@@ -41,7 +43,8 @@ esp_err_t esp_lcd_touch_enter_sleep(esp_lcd_touch_handle_t tp)
 
 esp_err_t esp_lcd_touch_exit_sleep(esp_lcd_touch_handle_t tp)
 {
-    assert(tp != NULL);
+    ESP_RETURN_ON_FALSE(tp != NULL, ESP_ERR_INVALID_ARG, TAG, "Touch point handler can't be NULL");
+
     if (tp->exit_sleep == NULL) {
         ESP_LOGE(TAG, "Sleep mode not supported!");
         return ESP_FAIL;
@@ -52,7 +55,7 @@ esp_err_t esp_lcd_touch_exit_sleep(esp_lcd_touch_handle_t tp)
 
 esp_err_t esp_lcd_touch_read_data(esp_lcd_touch_handle_t tp)
 {
-    assert(tp != NULL);
+    ESP_RETURN_ON_FALSE(tp != NULL, ESP_ERR_INVALID_ARG, TAG, "Touch point handler can't be NULL");
     assert(tp->read_data != NULL);
 
     return tp->read_data(tp);
@@ -62,10 +65,10 @@ bool esp_lcd_touch_get_coordinates(esp_lcd_touch_handle_t tp, uint16_t *x, uint1
 {
     bool touched = false;
 
-    assert(tp != NULL);
-    assert(x != NULL);
-    assert(y != NULL);
-    assert(tp->get_xy != NULL);
+    ESP_RETURN_ON_FALSE(tp != NULL, false, TAG, "Touch point handler can't be NULL");
+    ESP_RETURN_ON_FALSE(x != NULL, false, TAG, "X coordinates data array can't be NULL");
+    ESP_RETURN_ON_FALSE(y != NULL, false, TAG, "Y coordinates data array can't be NULL");
+    ESP_RETURN_ON_FALSE(tp->get_xy != NULL, false, TAG, "Touch driver must be initialized");
 
     touched = tp->get_xy(tp, x, y, strength, point_num, max_point_num);
     if (!touched) {
@@ -106,11 +109,79 @@ bool esp_lcd_touch_get_coordinates(esp_lcd_touch_handle_t tp, uint16_t *x, uint1
     return touched;
 }
 
+esp_err_t esp_lcd_touch_get_data(esp_lcd_touch_handle_t tp, esp_lcd_touch_point_data_t *data, uint8_t *point_cnt, uint8_t max_point_cnt)
+{
+    ESP_RETURN_ON_FALSE(tp != NULL, ESP_ERR_INVALID_ARG, TAG, "Touch point handler can't be NULL");
+    ESP_RETURN_ON_FALSE(data != NULL, ESP_ERR_INVALID_ARG, TAG, "Data array can't be NULL");
+    ESP_RETURN_ON_FALSE(tp->get_xy != NULL, ESP_ERR_INVALID_STATE, TAG, "Touch driver must be initialized");
+
+    uint16_t x[max_point_cnt];
+    uint16_t y[max_point_cnt];
+    uint16_t strength[max_point_cnt];
+    uint8_t track_id[max_point_cnt];
+
+    bool touched = tp->get_xy(tp, x, y, strength, point_cnt, max_point_cnt);
+
+    if (!touched) {
+        return ESP_OK;
+    }
+
+    /* Process coordinates by user */
+    if (tp->config.process_coordinates != NULL) {
+        tp->config.process_coordinates(tp, x, y, strength, point_cnt, max_point_cnt);
+    }
+
+    /* Software coordinates adjustment needed */
+    bool sw_adj_needed = ((tp->config.flags.mirror_x && (tp->set_mirror_x == NULL)) ||
+                          (tp->config.flags.mirror_y && (tp->set_mirror_y == NULL)) ||
+                          (tp->config.flags.swap_xy && (tp->set_swap_xy == NULL)));
+
+    /* Adjust all coordinates */
+    for (int i = 0; (sw_adj_needed && i < *point_cnt); i++) {
+
+        /*  Mirror X coordinates (if not supported by HW) */
+        if (tp->config.flags.mirror_x && tp->set_mirror_x == NULL) {
+            x[i] = tp->config.x_max - x[i];
+        }
+
+        /*  Mirror Y coordinates (if not supported by HW) */
+        if (tp->config.flags.mirror_y && tp->set_mirror_y == NULL) {
+            y[i] = tp->config.y_max - y[i];
+        }
+
+        /* Swap X and Y coordinates (if not supported by HW) */
+        if (tp->config.flags.swap_xy && tp->set_swap_xy == NULL) {
+            uint16_t tmp = x[i];
+            x[i] = y[i];
+            y[i] = tmp;
+        }
+    }
+
+    /* Process read track IDs */
+    if (tp->get_track_id != NULL && touched) {
+        tp->get_track_id(tp, track_id, *point_cnt);
+    }
+
+    /* Initialize the struct array since some features might not be available */
+    memset(data, 0, sizeof(esp_lcd_touch_point_data_t) * max_point_cnt);
+
+    for (int i = 0; i < *point_cnt; i++) {
+        data[i].x = x[i];
+        data[i].y = y[i];
+        data[i].strength = strength[i];
+        if (tp->get_track_id != NULL) {
+            data[i].track_id = track_id[i];
+        }
+    }
+
+    return ESP_OK;
+}
+
 #if (CONFIG_ESP_LCD_TOUCH_MAX_BUTTONS > 0)
 esp_err_t esp_lcd_touch_get_button_state(esp_lcd_touch_handle_t tp, uint8_t n, uint8_t *state)
 {
-    assert(tp != NULL);
-    assert(state != NULL);
+    ESP_RETURN_ON_FALSE(tp != NULL, ESP_ERR_INVALID_ARG, TAG, "Touch point handler can't be NULL");
+    ESP_RETURN_ON_FALSE(state != NULL, ESP_ERR_INVALID_ARG, TAG, "Pointer to an argument can't be NULL");
 
     *state = 0;
 
@@ -140,8 +211,8 @@ esp_err_t esp_lcd_touch_set_swap_xy(esp_lcd_touch_handle_t tp, bool swap)
 
 esp_err_t esp_lcd_touch_get_swap_xy(esp_lcd_touch_handle_t tp, bool *swap)
 {
-    assert(tp != NULL);
-    assert(swap != NULL);
+    ESP_RETURN_ON_FALSE(tp != NULL, ESP_ERR_INVALID_ARG, TAG, "Touch point handler can't be NULL");
+    ESP_RETURN_ON_FALSE(swap != NULL, ESP_ERR_INVALID_ARG, TAG, "Pointer to an argument can't be NULL");
 
     /* Is swap supported by HW? */
     if (tp->get_swap_xy) {
@@ -155,7 +226,7 @@ esp_err_t esp_lcd_touch_get_swap_xy(esp_lcd_touch_handle_t tp, bool *swap)
 
 esp_err_t esp_lcd_touch_set_mirror_x(esp_lcd_touch_handle_t tp, bool mirror)
 {
-    assert(tp != NULL);
+    ESP_RETURN_ON_FALSE(tp != NULL, ESP_ERR_INVALID_ARG, TAG, "Touch point handler can't be NULL");
 
     tp->config.flags.mirror_x = mirror;
 
@@ -169,8 +240,8 @@ esp_err_t esp_lcd_touch_set_mirror_x(esp_lcd_touch_handle_t tp, bool mirror)
 
 esp_err_t esp_lcd_touch_get_mirror_x(esp_lcd_touch_handle_t tp, bool *mirror)
 {
-    assert(tp != NULL);
-    assert(mirror != NULL);
+    ESP_RETURN_ON_FALSE(tp != NULL, ESP_ERR_INVALID_ARG, TAG, "Touch point handler can't be NULL");
+    ESP_RETURN_ON_FALSE(mirror != NULL, ESP_ERR_INVALID_ARG, TAG, "Pointer to an argument can't be NULL");
 
     /* Is swap supported by HW? */
     if (tp->get_mirror_x) {
@@ -184,7 +255,7 @@ esp_err_t esp_lcd_touch_get_mirror_x(esp_lcd_touch_handle_t tp, bool *mirror)
 
 esp_err_t esp_lcd_touch_set_mirror_y(esp_lcd_touch_handle_t tp, bool mirror)
 {
-    assert(tp != NULL);
+    ESP_RETURN_ON_FALSE(tp != NULL, ESP_ERR_INVALID_ARG, TAG, "Touch point handler can't be NULL");
 
     tp->config.flags.mirror_y = mirror;
 
@@ -198,8 +269,8 @@ esp_err_t esp_lcd_touch_set_mirror_y(esp_lcd_touch_handle_t tp, bool mirror)
 
 esp_err_t esp_lcd_touch_get_mirror_y(esp_lcd_touch_handle_t tp, bool *mirror)
 {
-    assert(tp != NULL);
-    assert(mirror != NULL);
+    ESP_RETURN_ON_FALSE(tp != NULL, ESP_ERR_INVALID_ARG, TAG, "Touch point handler can't be NULL");
+    ESP_RETURN_ON_FALSE(mirror != NULL, ESP_ERR_INVALID_ARG, TAG, "Pointer to an argument can't be NULL");
 
     /* Is swap supported by HW? */
     if (tp->get_mirror_y) {
@@ -213,7 +284,7 @@ esp_err_t esp_lcd_touch_get_mirror_y(esp_lcd_touch_handle_t tp, bool *mirror)
 
 esp_err_t esp_lcd_touch_del(esp_lcd_touch_handle_t tp)
 {
-    assert(tp != NULL);
+    ESP_RETURN_ON_FALSE(tp != NULL, ESP_ERR_INVALID_ARG, TAG, "Touch point handler can't be NULL");
 
     if (tp->del != NULL) {
         return tp->del(tp);
@@ -225,7 +296,7 @@ esp_err_t esp_lcd_touch_del(esp_lcd_touch_handle_t tp)
 esp_err_t esp_lcd_touch_register_interrupt_callback(esp_lcd_touch_handle_t tp, esp_lcd_touch_interrupt_callback_t callback)
 {
     esp_err_t ret = ESP_OK;
-    assert(tp != NULL);
+    ESP_RETURN_ON_FALSE(tp != NULL, ESP_ERR_INVALID_ARG, TAG, "Touch point handler can't be NULL");
 
     /* Interrupt pin is not selected */
     if (tp->config.int_gpio_num == GPIO_NUM_NC) {
@@ -259,7 +330,7 @@ esp_err_t esp_lcd_touch_register_interrupt_callback(esp_lcd_touch_handle_t tp, e
 
 esp_err_t esp_lcd_touch_register_interrupt_callback_with_data(esp_lcd_touch_handle_t tp, esp_lcd_touch_interrupt_callback_t callback, void *user_data)
 {
-    assert(tp != NULL);
+    ESP_RETURN_ON_FALSE(tp != NULL, ESP_ERR_INVALID_ARG, TAG, "Touch point handler can't be NULL");
 
     tp->config.user_data = user_data;
     return esp_lcd_touch_register_interrupt_callback(tp, callback);

components/lcd_touch/esp_lcd_touch/idf_component.yml

@@ -1,4 +1,4 @@
-version: "1.1.2"
+version: "1.2.0"
 description: ESP LCD Touch - main component for using touch screen controllers
 url: https://github.com/espressif/esp-bsp/tree/master/components/lcd_touch/esp_lcd_touch
 dependencies:

components/lcd_touch/esp_lcd_touch/include/esp_lcd_touch.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -69,13 +69,15 @@ typedef struct {
 } esp_lcd_touch_config_t;
 
 typedef struct {
-    uint8_t points; /*!< Count of touch points saved */
+    uint8_t track_id;
+    uint16_t x; /*!< X coordinate */
+    uint16_t y; /*!< Y coordinate */
+    uint16_t strength; /*!< Strength */
+} esp_lcd_touch_point_data_t;
 
-    struct {
-        uint16_t x; /*!< X coordinate */
-        uint16_t y; /*!< Y coordinate */
-        uint16_t strength; /*!< Strength */
-    } coords[CONFIG_ESP_LCD_TOUCH_MAX_POINTS];
+typedef struct {
+    uint8_t points; /*!< Count of touch points saved */
+    esp_lcd_touch_point_data_t points_data[CONFIG_ESP_LCD_TOUCH_MAX_POINTS];
 
 #if (CONFIG_ESP_LCD_TOUCH_MAX_BUTTONS > 0)
     uint8_t buttons; /*!< Count of buttons states saved */
@@ -145,6 +147,18 @@ struct esp_lcd_touch_s {
      */
     bool (*get_xy)(esp_lcd_touch_handle_t tp, uint16_t *x, uint16_t *y, uint16_t *strength, uint8_t *point_num, uint8_t max_point_num);
 
+    /**
+     * @brief Get track ids of touch points
+     *
+     * @param tp: Touch handler
+     * @param track_id: Array of track ids
+     * @param point_num: Count of touched points to return
+     *
+     * @return
+     *      - ESP_OK on success, otherwise returns ESP_ERR_xxx
+     */
+    esp_err_t (*get_track_id)(esp_lcd_touch_handle_t tp, uint8_t *track_id, uint8_t point_num);
+
 
 #if (CONFIG_ESP_LCD_TOUCH_MAX_BUTTONS > 0)
     /**
@@ -271,6 +285,21 @@ struct esp_lcd_touch_s {
  */
 esp_err_t esp_lcd_touch_read_data(esp_lcd_touch_handle_t tp);
 
+/**
+ * @brief Get each touch point data from touch controller
+ *
+ * @param tp: Touch handler
+ * @param data: Array of data structures to be filled out
+ * @param point_cnt: Count of points touched (equals with count of items in x and y array)
+ * @param max_point_cnt: Maximum count of touched points to return (equals with max size of x and y array)
+ *
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_INVALID_ARG if parameter is invalid
+ *      - ESP_ERR_INVALID_STATE if parameter is uninitialized
+ */
+esp_err_t esp_lcd_touch_get_data(esp_lcd_touch_handle_t tp, esp_lcd_touch_point_data_t *data, uint8_t *point_cnt, uint8_t max_point_cnt);
+
 /**
  * @brief Read coordinates from touch controller
  *
@@ -284,9 +313,9 @@ esp_err_t esp_lcd_touch_read_data(esp_lcd_touch_handle_t tp);
  * @return
  *      - Returns true, when touched and coordinates readed. Otherwise returns false.
  */
+[[deprecated("This API will be removed in version 2.0.0. Use esp_lcd_touch_get_data instead!")]]
 bool esp_lcd_touch_get_coordinates(esp_lcd_touch_handle_t tp, uint16_t *x, uint16_t *y, uint16_t *strength, uint8_t *point_num, uint8_t max_point_num);
 
-
 #if (CONFIG_ESP_LCD_TOUCH_MAX_BUTTONS > 0)
 /**
  * @brief Get button state