TFT display ILI9341 con TFT_eSPI: configurazione e primo sketch

I display ILI9341 SPI a 2.4"/2.8" costano pochi euro e trasformano un ESP32 in un mini-dashboard. La libreria di riferimento e' TFT_eSPI: veloce, ben mantenuta, con font grandi inclusi.

1. Cablaggio tipico

Display   ESP32
VCC       3V3
GND       GND
CS        GPIO 15
RESET     GPIO 4
DC        GPIO 2
MOSI      GPIO 23
SCK       GPIO 18
MISO      GPIO 19
LED       3V3 (o via GPIO+resistore per dimming)

2. platformio.ini

La cosa piu' importante: passare la config dei pin via build_flags invece che modificare User_Setup.h della libreria (piu' portabile e sopravvive agli update).

[env:esp32dev]
platform  = espressif32
board     = esp32dev
framework = arduino
lib_deps  = bodmer/TFT_eSPI
build_flags =
    -DUSER_SETUP_LOADED=1
    -DILI9341_2_DRIVER=1
    -DTFT_WIDTH=240
    -DTFT_HEIGHT=320
    -DTFT_MISO=19
    -DTFT_MOSI=23
    -DTFT_SCLK=18
    -DTFT_CS=15
    -DTFT_DC=2
    -DTFT_RST=4
    -DTFT_BL=-1
    -DLOAD_GLCD=1
    -DLOAD_FONT2=1
    -DLOAD_FONT4=1
    -DLOAD_FONT6=1
    -DLOAD_FONT7=1
    -DLOAD_GFXFF=1
    -DSPI_FREQUENCY=40000000

3. Primo sketch

#include <TFT_eSPI.h>
TFT_eSPI tft;

void setup() {
  tft.init();
  tft.setRotation(1);
  tft.fillScreen(TFT_BLACK);
  tft.setTextColor(TFT_WHITE);
  tft.setCursor(20, 20);
  tft.setTextFont(4);
  tft.println("Hello ESP32");
}

void loop() {
  static int y = 60;
  tft.drawFastHLine(0, y, 320, TFT_CYAN);
  y = (y + 1) % 240;
}

4. Font e grafica avanzata

• drawString(str, x, y, font_num) testo veloce a font fisso (2/4/6/7/8)
• setFreeFont(&FreeSansBold24pt7b) per Adafruit GFX fonts (belli grandi)
• fillRect, drawLine, fillCircle, drawRoundRect per shape
• drawXBitmap per bitmap monocromatiche
• pushImage per sprite 16-bit dal PROGMEM

5. Trucchi anti-flicker

Ridisegnare tutto ogni frame produce sfarfallio. Usa Sprite (framebuffer off-screen):

TFT_eSprite spr = TFT_eSprite(&tft);

spr.createSprite(320, 60);
spr.fillSprite(TFT_BLACK);
spr.setTextColor(TFT_WHITE);
spr.drawString("Temp: 24.5", 10, 10, 4);
spr.pushSprite(0, 20);       // singolo push atomico

6. Problemi tipici

• Schermo bianco: driver sbagliato. Prova -DST7789_DRIVER=1 al posto di -DILI9341_2_DRIVER=1
• Colori invertiti: aggiungi -DTFT_RGB_ORDER=TFT_BGR
• Display molto lento: alza SPI_FREQUENCY a 27000000 o 40000000
• Testo tagliato: setRotation(0..3) per l'orientamento giusto (0 e 2 = portrait, 1 e 3 = landscape)