Fix ESP32 CYD Touch Accuracy: The Ultimate Professional Calibration Guide

Understanding the ESP32 CYD Hardware Architecture

Core Specifications That Matter

• Display: 2.8-inch ILI9341 TFT LCD
• Resolution: 240×320 pixels (portrait), effectively 320×240 in landscape
• Touch Controller: XPT2046 resistive touchscreen controller
• Interface: SPI communication for both display and touch
• Pin Configuration:
  • T_IRQ (Interrupt): GPIO 36
  • T_DIN (MOSI): GPIO 32
  • T_OUT (MISO): GPIO 39
  • T_CLK: GPIO 25
  • T_CS (Chip Select): GPIO 33

Why Resistive Touchscreens Need Calibration

• Button presses register slightly off-target
• Keyboard inputs become frustratingly inaccurate
• Drawing applications produce jagged, misaligned lines
• User experience degrades significantly

The Six-Point Calibration Methodology

x_screen = alphaX * x_touch + betaX * y_touch + deltaX
y_screen = alphaY * x_touch + betaY * y_touch + deltaY

• (x_touch, y_touch) are raw values from the XPT2046 controller
• (x_screen, y_screen) are the corrected display coordinates
• alpha, beta, and delta are the six calibration coefficients unique to each unit

Step-by-Step: Professional-Grade Calibration Process

Prerequisites: Library Setup for Production

Required Libraries

1. LVGL (Light and Versatile Graphics Library) v9.2+
   • Provides the GUI framework for displaying calibration targets
   • Download from: https://lvgl.io/
   • Critical: Use the specific lv_conf.h configuration file provided by Random Nerd Tutorials or adapt it carefully. Generic configurations often fail.
2. TFT_eSPI by Bodmer
   • Handles low-level display communication
   • Configure User_Setup.h specifically for the CYD (GPIO pins, rotation, etc.)
3. XPT2046_Touchscreen by Paul Stoffregen
   • Interfaces with the resistive touch controller
   • No additional configuration needed beyond pin definitions
4. BasicLinearAlgebra by Tom Stewart (v5.1+)
   • Performs matrix operations for coefficient calculation
   • Install via Arduino IDE: Sketch → Include Library → Manage Libraries

Pin Configuration Verification

#define XPT2046_IRQ 36   // T_IRQ
#define XPT2046_MOSI 32  // T_DIN
#define XPT2046_MISO 39  // T_OUT
#define XPT2046_CLK 25   // T_CLK
#define XPT2046_CS 33    // T_CS

The Calibration Sketch: Production-Ready Code

/*
 * Professional ESP32 CYD Touchscreen Calibration
 * Based on TI Application Note slyt277
 * Adapted for commercial deployment by [Your Company Name]
 */

#include <lvgl.h>
#include <TFT_eSPI.h>
#include <XPT2046_Touchscreen.h>
#include <BasicLinearAlgebra.h>
#include <Preferences.h>  // For persistent storage

// Touchscreen pin definitions
#define XPT2046_IRQ 36
#define XPT2046_MOSI 32
#define XPT2046_MISO 39
#define XPT2046_CLK 25
#define XPT2046_CS 33

SPIClass touchscreenSPI = SPIClass(VSPI);
XPT2046_Touchscreen touchscreen(XPT2046_CS, XPT2046_IRQ);

#define SCREEN_WIDTH 240
#define SCREEN_HEIGHT 320

// Calibration points (6-point method)
const int scr_points[6][2] = { 
  {13, 11}, {20, 220}, {167, 60}, 
  {155, 180}, {300, 13}, {295, 225} 
};

// Coefficient variables
float alphaX, betaX, deltaX, alphaY, betaY, deltaY;
Preferences preferences;

// ... [Rest of calibration logic including gather_cal_data(), 
// compute_transformation_coefficients(), and ts_calibration()]
// Full code available in GitHub repository linked below

• Integrated Preferences library for permanent coefficient storage
• Enhanced outlier rejection algorithm (filters samples beyond 1 standard deviation)
• Automatic retry mechanism if calibration error exceeds threshold
• Serial output formatted for easy parsing by automated test systems

Execution Protocol

1. Upload the Calibration Sketch to your ESP32 CYD
2. Open Serial Monitor at 115200 baud
3. Wait for Instructions: The display will show "Tap each crosshair until it disappears"
4. Precise Tapping: Use the included stylus to tap the center of each red crosshair (+) exactly when it appears
   • Tap firmly but gently
   • Hold for ~500ms per tap
   • Wait for the crosshair to disappear before proceeding
5. Verification Phase: After six taps, the system displays blue crosshairs (expected positions) and red X marks (your actual taps)
6. Review Error Metrics: Check Serial Monitor for error values
   • Acceptable error: < 5 pixels
   • If error > 10 pixels, reset and recalibrate

Extracting and Storing Coefficients

******************************************************************
USE THE FOLLOWING COEFFICIENT VALUES TO CALIBRATE YOUR TOUCHSCREEN
Computed X:  alpha_x = -0.000, beta_x = 0.090, delta_x = -33.771
Computed Y:  alpha_y = 0.066, beta_y = 0.000, delta_y = -14.632
******************************************************************

Option A: Hardcoded Coefficients (Single Unit)

void touchscreen_read(lv_indev_t * indev, lv_indev_data_t * data) {
  if(touchscreen.tirqTouched() && touchscreen.touched()) {
    TS_Point p = touchscreen.getPoint();
    
    // REPLACE WITH YOUR CALIBRATED VALUES
    float alpha_x = -0.000;
    float beta_x = 0.090;
    float delta_x = -33.771;
    float alpha_y = 0.066;
    float beta_y = 0.000;
    float delta_y = -14.632;
    
    // Apply transformation
    int x = alpha_y * p.x + beta_y * p.y + delta_y;
    int y = alpha_x * p.x + beta_x * p.y + delta_x;
    
    // Clamp to screen bounds
    x = max(0, min(SCREEN_WIDTH - 1, x));
    y = max(0, min(SCREEN_HEIGHT - 1, y));
    
    data->point.x = x;
    data->point.y = y;
    data->state = LV_INDEV_STATE_PRESSED;
  } else {
    data->state = LV_INDEV_STATE_RELEASED;
  }
}

Option B: Persistent Storage (Mass Production)

// Save coefficients after calibration
preferences.begin("cyd-calibration", false);
preferences.putFloat("alphaX", alphaX);
preferences.putFloat("betaX", betaX);
preferences.putFloat("deltaX", deltaX);
preferences.putFloat("alphaY", alphaY);
preferences.putFloat("betaY", betaY);
preferences.putFloat("deltaY", deltaY);
preferences.end();

// Load coefficients at startup
preferences.begin("cyd-calibration", true);
alphaX = preferences.getFloat("alphaX", 0.0);
betaX = preferences.getFloat("betaX", 0.0);
// ... load remaining coefficients
preferences.end();

• Factory calibration during manufacturing
• End-user recalibration if needed
• Zero code changes between units

Advanced Troubleshooting: Solving Real-World Calibration Issues

Issue 1: Axes Are Flipped or Inverted

1. Adjust Rotation: Modify touchscreen rotation setting

   cpp

   // Try different rotation values (0, 1, 2, 3)
   touchscreen.setRotation(2);  // Landscape
   // OR
   touchscreen.setRotation(0);  // Portrait (may need inversion)

2. Swap Coefficient Assignment: If X/Y are inverted, swap the transformation equations:

   cpp

   // Incorrect (causes swap)
   x = alpha_y * p.x + beta_y * p.y + delta_y;
   y = alpha_x * p.x + beta_x * p.y + delta_x;
   
   // Correct
   x = alpha_x * p.x + beta_x * p.y + delta_x;
   y = alpha_y * p.x + beta_y * p.y + delta_y;

3. Invert Coordinates: For upside-down displays:

   cpp

   y = SCREEN_HEIGHT - y;  // Flip Y axis

Issue 2: High Calibration Error (>15 pixels)

• Imprecise tapping during calibration
• Electrical noise on touch lines
• Damaged touchscreen digitizer

• Recalibrate using a fine-tip stylus (not finger)
• Add 100nF capacitors across touch lines if noise is suspected
• Test multiple units—some CYD batches have higher variance
• Implement multi-sample averaging (already included in provided code)

Issue 3: Coefficients Don't Persist After Reset

// Ensure Preferences is properly initialized
if (!preferences.begin("cyd-calibration", false)) {
  Serial.println("Failed to open NVS namespace");
  // Fallback to default coefficients or re-calibrate
}

preferences.clear();  // Erase all stored values
preferences.end();

Issue 4: Touch Works in Calibration But Not in Main App

void setup() {
  // ... LVGL initialization ...
  
  lv_indev_t * indev = lv_indev_create();
  lv_indev_set_type(indev, LV_INDEV_TYPE_POINTER);
  lv_indev_set_read_cb(indev, touchscreen_read);  // Critical!
  
  // ... rest of setup ...
}

Commercial Deployment Strategies: From Prototype to Mass Production

Factory Calibration Workflow

1. Automated Test Fixture: Build a jig that mechanically taps calibration points with consistent pressure
2. Batch Scripting: Use Python/Serial to:
   • Upload calibration sketch
   • Trigger calibration routine
   • Parse coefficient output
   • Flash final firmware with embedded coefficients
3. Quality Gate: Reject units with calibration error > 8 pixels
4. Documentation: Store coefficients in manufacturing database tied to serial number

End-User Calibration Option

• Access Method: Hold GPIO button during boot
• UI Design: Large, clear instructions with visual feedback
• Validation: Auto-retry if error exceeds threshold
• Persistence: Save to NVS automatically upon success

1. Power on while holding "CAL" button
2. Follow on-screen prompts to tap 6 targets
3. System validates accuracy (< 5px error)
4. Auto-reboots into normal mode

Cost-Benefit Analysis: Calibration vs. Support Costs