Update touch handler

Added new function that sketch can call to convert raw ADC x and y
values to calibrated screen coordinates:
tft.convertRawXY(&x, &y);

Redunced required number of SPI transfers needed to read raw values.
Changed mode so PENIRQ pin is enabled so users sketch can read this
signal (if needed).

See issue #279.

Extensions/Touch.cpp

@@ -22,24 +22,18 @@ uint8_t TFT_eSPI::getTouchRaw(uint16_t *x, uint16_t *y){
 
   T_CS_L;
   
-  // Dummy transfer
-  SPI.transfer(0xd0);
-  SPI.transfer(0);
-  SPI.transfer(0);
-
-  // Start bit + YP sample request for x position
-  SPI.transfer(0xd0);
-  tmp = SPI.transfer(0);
+  // Start YP sample request for x position
+  SPI.transfer(0xd0);                    // Start new YP conversion
+  tmp = SPI.transfer(0);                 // Read first 8 bits
   tmp = tmp <<5;
-  tmp |= 0x1f & (SPI.transfer(0)>>3);
+  tmp |= 0x1f & (SPI.transfer(0x90)>>3); // Read last 8 bits and start new XP conversion
 
   *x = tmp;
 
-  // Start bit + XP sample request for y position
-  SPI.transfer(0x90);
-  tmp = SPI.transfer(0);
+  // Start XP sample request for y position
+  tmp = SPI.transfer(0);                 // Read first 8 bits
   tmp = tmp <<5;
-  tmp |= 0x1f & (SPI.transfer(0)>>3);
+  tmp |= 0x1f & (SPI.transfer(0)>>3);    // Read last 8 bits
 
   *y = tmp;
 
@@ -61,11 +55,11 @@ uint16_t TFT_eSPI::getTouchRawZ(void){
 
   T_CS_L;
 
-  // Z sample request
+  // Calculate Z
   int16_t tz = 0xFFF;
-  SPI.transfer(0xb1);
-  tz += SPI.transfer16(0xc1) >> 3;
-  tz -= SPI.transfer16(0x91) >> 3;
+  SPI.transfer(0xb0);               // Start new Z1 conversion
+  tz += SPI.transfer16(0xc0) >> 3;  // Read Z1 and start Z2 conversion
+  tz -= SPI.transfer16(0x00) >> 3;  // Read Z2
 
   T_CS_H;
 
@@ -78,11 +72,11 @@ uint16_t TFT_eSPI::getTouchRawZ(void){
 ** Function name:           validTouch
 ** Description:             read validated position. Return false if not pressed. 
 ***************************************************************************************/
-#define _RAWERR 10 // Deadband in position samples
+#define _RAWERR 10 // Deadband error allowed in successive position samples
 uint8_t TFT_eSPI::validTouch(uint16_t *x, uint16_t *y, uint16_t threshold){
   uint16_t x_tmp, y_tmp, x_tmp2, y_tmp2;
 
-  // Wait until pressure stops increasing
+  // Wait until pressure stops increasing to debounce pressure
   uint16_t z1 = 1;
   uint16_t z2 = 0;
   while (z1 > z2)
@@ -125,7 +119,7 @@ uint8_t TFT_eSPI::validTouch(uint16_t *x, uint16_t *y, uint16_t threshold){
 ***************************************************************************************/
 #define Z_THRESHOLD 350 // Touch pressure threshold for validating touches
 uint8_t TFT_eSPI::getTouch(uint16_t *x, uint16_t *y, uint16_t threshold){
-  uint16_t x_tmp, y_tmp, xx, yy;
+  uint16_t x_tmp, y_tmp;
   
   if (threshold<20) threshold = 20;
   if (_pressTime > millis()) threshold=20;
@@ -141,6 +135,25 @@ uint8_t TFT_eSPI::getTouch(uint16_t *x, uint16_t *y, uint16_t threshold){
   
   _pressTime = millis() + 50;
 
+  convertRawXY(&x_tmp, &y_tmp);
+
+  if (x_tmp >= _width || y_tmp >= _height) return valid;
+
+  _pressX = x_tmp;
+  _pressY = y_tmp;
+  *x = _pressX;
+  *y = _pressY;
+  return valid;
+}
+
+/***************************************************************************************
+** Function name:           convertRawXY
+** Description:             convert raw touch x,y values to screen coordinates 
+***************************************************************************************/
+void TFT_eSPI::convertRawXY(uint16_t *x, uint16_t *y)
+{
+  uint16_t x_tmp = *x, y_tmp = *y, xx, yy;
+
   if(!touchCalibration_rotate){
     xx=(x_tmp-touchCalibration_x0)*_width/touchCalibration_x1;
     yy=(y_tmp-touchCalibration_y0)*_height/touchCalibration_y1;
@@ -156,14 +169,8 @@ uint8_t TFT_eSPI::getTouch(uint16_t *x, uint16_t *y, uint16_t threshold){
     if(touchCalibration_invert_y)
       yy = _height - yy;
   }
-
-  if (xx >= _width || yy >= _height) return valid;
-
-  _pressX = xx;
-  _pressY = yy;
-  *x = _pressX;
-  *y = _pressY;
-  return valid;
+  *x = xx;
+  *y = yy;
 }
 
 /***************************************************************************************

Extensions/Touch.h

@@ -2,23 +2,32 @@
  // This is part of the TFT_eSPI class and is associated with the Touch Screen handlers
 
  public:
-
+           // Get raw x,y ADC values from touch controller
   uint8_t  getTouchRaw(uint16_t *x, uint16_t *y);
+           // Get raw z (i.e. pressure) ADC value from touch controller
   uint16_t getTouchRawZ(void);
+           // Convert raw x,y values to calibrated and correctly rotated screen coordinates
+  void     convertRawXY(uint16_t *x, uint16_t *y);
+           // Get the screen touch coordinates, returns true if screen has been touched
+           // if the touch cordinates are off screen then x and y are not updated
   uint8_t  getTouch(uint16_t *x, uint16_t *y, uint16_t threshold = 600);
 
+           // Run screen calibration and test, report calibration values to the serial port
   void     calibrateTouch(uint16_t *data, uint32_t color_fg, uint32_t color_bg, uint8_t size);
+           // Set the screen calibration values
   void     setTouch(uint16_t *data);
 
  private:
-
+           // Handlers for the SPI settings and clock speed change
   inline void spi_begin_touch() __attribute__((always_inline));
   inline void spi_end_touch()   __attribute__((always_inline));
 
-           // These are associated with the Touch Screen handlers
+           // Private function to validate a touch, allow settle time and reduce spurious coordinates
   uint8_t  validTouch(uint16_t *x, uint16_t *y, uint16_t threshold = 600);
+
            // Initialise with example calibration values so processor does not crash if setTouch() not called in setup()
   uint16_t touchCalibration_x0 = 300, touchCalibration_x1 = 3600, touchCalibration_y0 = 300, touchCalibration_y1 = 3600;
   uint8_t  touchCalibration_rotate = 1, touchCalibration_invert_x = 2, touchCalibration_invert_y = 0;
-  uint32_t _pressTime;
-  uint16_t _pressX, _pressY;
+
+  uint32_t _pressTime;        // Press and hold time-out
+  uint16_t _pressX, _pressY;  // For future use (last sampled calibrated coordinates)

library.json

 {
   "name": "TFT_eSPI",
-  "version": "1.3.9",
+  "version": "1.3.10",
   "keywords": "tft, ePaper, display, ESP8266, NodeMCU, ESP32, M5Stack, ILI9341, ST7735, ILI9163, S6D02A1, ILI9486, ST7789",
   "description": "A TFT and ePaper SPI graphics library for ESP8266 and ESP32",
   "repository":

library.properties

 name=TFT_eSPI
-version=1.3.9
+version=1.3.10
 author=Bodmer
 maintainer=Bodmer
 sentence=A fast TFT graphics library for ESP8266 and ESP32 processors for the Arduino IDE