feat(multi-touch): Add track id reading to GT911 driver

PetrESP · PetrESP · commit e3ed08eab3ce · 2025-11-28T15:10:23.000+01:00
diff --git a/components/lcd_touch/esp_lcd_touch_gt911/README.md b/components/lcd_touch/esp_lcd_touch_gt911/README.md
@@ -56,13 +56,11 @@ Read data from the touch controller and store it in RAM memory. It should be cal
     esp_lcd_touch_read_data(tp);
 ```
 
-Get one X and Y coordinates with strength of touch.
+Get attributes of a single touch point.
 
 ```
-    uint16_t touch_x[1];
-    uint16_t touch_y[1];
-    uint16_t touch_strength[1];
+    esp_lcd_touch_point_data_t touch_point_data[1];
     uint8_t touch_cnt = 0;
 
-    bool touchpad_pressed = esp_lcd_touch_get_coordinates(tp, touch_x, touch_y, touch_strength, &touch_cnt, 1);
+    ESP_ERROR_CHECK(esp_lcd_touch_get_data(tp, touch_point_data, &touch_cnt, 1));
 ```
diff --git a/components/lcd_touch/esp_lcd_touch_gt911/esp_lcd_touch_gt911.c b/components/lcd_touch/esp_lcd_touch_gt911/esp_lcd_touch_gt911.c
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -34,6 +34,7 @@ static const char *TAG = "GT911";
 *******************************************************************************/
 static esp_err_t esp_lcd_touch_gt911_read_data(esp_lcd_touch_handle_t tp);
 static bool esp_lcd_touch_gt911_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);
+static esp_err_t esp_lcd_touch_gt911_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)
 static esp_err_t esp_lcd_touch_gt911_get_button_state(esp_lcd_touch_handle_t tp, uint8_t n, uint8_t *state);
 #endif
@@ -60,9 +61,9 @@ esp_err_t esp_lcd_touch_new_i2c_gt911(const esp_lcd_panel_io_handle_t io, const
 {
     esp_err_t ret = ESP_OK;
 
-    assert(io != NULL);
-    assert(config != NULL);
-    assert(out_touch != NULL);
+    ESP_RETURN_ON_FALSE(io != NULL, ESP_ERR_INVALID_ARG, TAG, "Touch panel handler pointer can't be NULL");
+    ESP_RETURN_ON_FALSE(config != NULL, ESP_ERR_INVALID_ARG, TAG, "Config pointer can't be NULL");
+    ESP_RETURN_ON_FALSE(out_touch != NULL, ESP_ERR_INVALID_ARG, TAG, "Touch handler pointer can't be NULL");
 
     /* Prepare main structure */
     esp_lcd_touch_handle_t esp_lcd_touch_gt911 = heap_caps_calloc(1, sizeof(esp_lcd_touch_t), MALLOC_CAP_DEFAULT);
@@ -74,6 +75,7 @@ esp_err_t esp_lcd_touch_new_i2c_gt911(const esp_lcd_panel_io_handle_t io, const
     /* Only supported callbacks are set */
     esp_lcd_touch_gt911->read_data = esp_lcd_touch_gt911_read_data;
     esp_lcd_touch_gt911->get_xy = esp_lcd_touch_gt911_get_xy;
+    esp_lcd_touch_gt911->get_track_id = esp_lcd_touch_gt911_get_track_id;
 #if (CONFIG_ESP_LCD_TOUCH_MAX_BUTTONS > 0)
     esp_lcd_touch_gt911->get_button_state = esp_lcd_touch_gt911_get_button_state;
 #endif
@@ -214,7 +216,7 @@ static esp_err_t esp_lcd_touch_gt911_read_data(esp_lcd_touch_handle_t tp)
     uint8_t clear = 0;
     size_t i = 0;
 
-    assert(tp != NULL);
+    ESP_RETURN_ON_FALSE(tp != NULL, ESP_ERR_INVALID_ARG, TAG, "Touch point handler pointer can't be NULL");
 
     err = touch_gt911_i2c_read(tp, ESP_LCD_TOUCH_GT911_READ_XY_REG, buf, 1);
     ESP_RETURN_ON_ERROR(err, TAG, "I2C read error!");
@@ -277,9 +279,10 @@ static esp_err_t esp_lcd_touch_gt911_read_data(esp_lcd_touch_handle_t tp)
 
         /* Fill all coordinates */
         for (i = 0; i < touch_cnt; i++) {
-            tp->data.coords[i].x = ((uint16_t)buf[(i * 8) + 3] << 8) + buf[(i * 8) + 2];
-            tp->data.coords[i].y = (((uint16_t)buf[(i * 8) + 5] << 8) + buf[(i * 8) + 4]);
-            tp->data.coords[i].strength = (((uint16_t)buf[(i * 8) + 7] << 8) + buf[(i * 8) + 6]);
+            tp->data.points_data[i].track_id = buf[(i * 8) + 1];
+            tp->data.points_data[i].x = ((uint16_t)buf[(i * 8) + 3] << 8) + buf[(i * 8) + 2];
+            tp->data.points_data[i].y = (((uint16_t)buf[(i * 8) + 5] << 8) + buf[(i * 8) + 4]);
+            tp->data.points_data[i].strength = (((uint16_t)buf[(i * 8) + 7] << 8) + buf[(i * 8) + 6]);
         }
 
         portEXIT_CRITICAL(&tp->data.lock);
@@ -290,23 +293,23 @@ static esp_err_t esp_lcd_touch_gt911_read_data(esp_lcd_touch_handle_t tp)
 
 static bool esp_lcd_touch_gt911_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)
 {
-    assert(tp != NULL);
-    assert(x != NULL);
-    assert(y != NULL);
-    assert(point_num != NULL);
-    assert(max_point_num > 0);
+    ESP_RETURN_ON_FALSE(tp != NULL, false, TAG, "Touch point handler pointer can't be NULL");
+    ESP_RETURN_ON_FALSE(x != NULL, false, TAG, "Data array pointer can't be NULL");
+    ESP_RETURN_ON_FALSE(y != NULL, false, TAG, "Data array pointer can't be NULL");
+    ESP_RETURN_ON_FALSE(point_num != NULL, false, TAG, "Pointer to number of touch points can't be NULL");
+    ESP_RETURN_ON_FALSE(max_point_num > 0, false, TAG, "Array size must be at least 1");
 
     portENTER_CRITICAL(&tp->data.lock);
 
     /* Count of points */
     *point_num = (tp->data.points > max_point_num ? max_point_num : tp->data.points);
 
     for (size_t i = 0; i < *point_num; i++) {
-        x[i] = tp->data.coords[i].x;
-        y[i] = tp->data.coords[i].y;
+        x[i] = tp->data.points_data[i].x;
+        y[i] = tp->data.points_data[i].y;
 
         if (strength) {
-            strength[i] = tp->data.coords[i].strength;
+            strength[i] = tp->data.points_data[i].strength;
         }
     }
 
@@ -315,12 +318,29 @@ static bool esp_lcd_touch_gt911_get_xy(esp_lcd_touch_handle_t tp, uint16_t *x, u
     return (*point_num > 0);
 }
 
+static esp_err_t esp_lcd_touch_gt911_get_track_id(esp_lcd_touch_handle_t tp, uint8_t *track_id, uint8_t max_point_num)
+{
+    ESP_RETURN_ON_FALSE(tp != NULL, ESP_ERR_INVALID_ARG, TAG, "Touch point handler pointer can't be NULL");
+    ESP_RETURN_ON_FALSE(track_id != NULL, ESP_ERR_INVALID_ARG, TAG, "Track ID array pointer can't be NULL");
+    ESP_RETURN_ON_FALSE(max_point_num > 0, ESP_ERR_INVALID_ARG, TAG, "Array size must be at least 1");
+
+    portENTER_CRITICAL(&tp->data.lock);
+
+    for (int i = 0; i < max_point_num; i++) {
+        track_id[i] = tp->data.points_data[i].track_id;
+    }
+
+    portEXIT_CRITICAL(&tp->data.lock);
+
+    return ESP_OK;
+}
+
 #if (CONFIG_ESP_LCD_TOUCH_MAX_BUTTONS > 0)
 static esp_err_t esp_lcd_touch_gt911_get_button_state(esp_lcd_touch_handle_t tp, uint8_t n, uint8_t *state)
 {
     esp_err_t err = ESP_OK;
-    assert(tp != NULL);
-    assert(state != NULL);
+    ESP_RETURN_ON_FALSE(tp != NULL, ESP_ERR_INVALID_ARG, TAG, "Touch point handler pointer can't be NULL");
+    ESP_RETURN_ON_FALSE(state != NULL, ESP_ERR_INVALID_ARG, TAG, "State array pointer can't be NULL");
 
     *state = 0;
 
@@ -340,7 +360,7 @@ static esp_err_t esp_lcd_touch_gt911_get_button_state(esp_lcd_touch_handle_t tp,
 
 static esp_err_t esp_lcd_touch_gt911_del(esp_lcd_touch_handle_t tp)
 {
-    assert(tp != NULL);
+    ESP_RETURN_ON_FALSE(tp != NULL, ESP_ERR_INVALID_ARG, TAG, "Touch point handler pointer can't be NULL");
 
     /* Reset GPIO pin settings */
     if (tp->config.int_gpio_num != GPIO_NUM_NC) {
@@ -367,7 +387,7 @@ static esp_err_t esp_lcd_touch_gt911_del(esp_lcd_touch_handle_t tp)
 /* Reset controller */
 static esp_err_t touch_gt911_reset(esp_lcd_touch_handle_t tp)
 {
-    assert(tp != NULL);
+    ESP_RETURN_ON_FALSE(tp != NULL, ESP_ERR_INVALID_ARG, TAG, "Touch point handler pointer can't be NULL");
 
     if (tp->config.rst_gpio_num != GPIO_NUM_NC) {
         ESP_RETURN_ON_ERROR(gpio_set_level(tp->config.rst_gpio_num, tp->config.levels.reset), TAG, "GPIO set level error!");
@@ -383,7 +403,7 @@ static esp_err_t touch_gt911_read_cfg(esp_lcd_touch_handle_t tp)
 {
     uint8_t buf[4];
 
-    assert(tp != NULL);
+    ESP_RETURN_ON_FALSE(tp != NULL, ESP_ERR_INVALID_ARG, TAG, "Touch point handler pointer can't be NULL");
 
     ESP_RETURN_ON_ERROR(touch_gt911_i2c_read(tp, ESP_LCD_TOUCH_GT911_PRODUCT_ID_REG, (uint8_t *)&buf[0], 3), TAG, "GT911 read error!");
     ESP_RETURN_ON_ERROR(touch_gt911_i2c_read(tp, ESP_LCD_TOUCH_GT911_CONFIG_REG, (uint8_t *)&buf[3], 1), TAG, "GT911 read error!");
@@ -396,16 +416,16 @@ static esp_err_t touch_gt911_read_cfg(esp_lcd_touch_handle_t tp)
 
 static esp_err_t touch_gt911_i2c_read(esp_lcd_touch_handle_t tp, uint16_t reg, uint8_t *data, uint8_t len)
 {
-    assert(tp != NULL);
-    assert(data != NULL);
+    ESP_RETURN_ON_FALSE(tp != NULL, ESP_ERR_INVALID_ARG, TAG, "Touch point handler pointer can't be NULL");
+    ESP_RETURN_ON_FALSE(data != NULL, ESP_ERR_INVALID_ARG, TAG, "Data array pointer can't be NULL");
 
     /* Read data */
     return esp_lcd_panel_io_rx_param(tp->io, reg, data, len);
 }
 
 static esp_err_t touch_gt911_i2c_write(esp_lcd_touch_handle_t tp, uint16_t reg, uint8_t data)
 {
-    assert(tp != NULL);
+    ESP_RETURN_ON_FALSE(tp != NULL, ESP_ERR_INVALID_ARG, TAG, "Touch point handler pointer can't be NULL");
 
     // *INDENT-OFF*
     /* Write data */
diff --git a/components/lcd_touch/esp_lcd_touch_gt911/idf_component.yml b/components/lcd_touch/esp_lcd_touch_gt911/idf_component.yml
@@ -1,9 +1,9 @@
-version: "1.1.3"
+version: "1.2.0"
 description: ESP LCD Touch GT911 - touch controller GT911
 url: https://github.com/espressif/esp-bsp/tree/master/components/lcd_touch/esp_lcd_touch_gt911
 dependencies:
   idf: ">=4.4.2"
   esp_lcd_touch:
-    version: "^1.1.0"
+    version: "^1.2.0"
     public: true
     override_path: ../esp_lcd_touch
