Thư viện TFT_eSPI: driver TFT tốc độ cao trên ESP32

TFT_eSPI của Bodmer là thư viện TFT nhanh nhất cho ESP32/ESP8266 — viết ASM tối ưu hardware SPI và DMA, vẽ gấp 2–3 lần Adafruit_ILI9341. Hỗ trợ ILI9341, ILI9488, ST7735, ST7789 và nhiều driver khác. Bài này hướng dẫn cấu hình và API chính.

1. Cài đặt

Library Manager → "TFT_eSPI" by Bodmer. Không cài dependency — TFT_eSPI tự đứng độc lập, không cần Adafruit_GFX.

2. Cấu hình — bước quan trọng nhất

TFT_eSPI không config động bằng code — phải sửa file User_Setup.h trong thư mục library trước khi compile.

Đường dẫn (Windows):

C:\Users\<you>\Documents\Arduino\libraries\TFT_eSPI\User_Setup.h

Linux/Mac: ~/Arduino/libraries/TFT_eSPI/User_Setup.h.

Mở file, comment hết các driver, chỉ uncomment driver của bạn. Ví dụ ILI9341:

#define ILI9341_DRIVER
#define TFT_WIDTH  240
#define TFT_HEIGHT 320

// ESP32 DevKit
#define TFT_MOSI 23
#define TFT_SCLK 18
#define TFT_CS   15
#define TFT_DC   2
#define TFT_RST  4
#define TFT_BL   32     // backlight (optional)

// Font
#define LOAD_GLCD     // font 6x8 mặc định
#define LOAD_FONT2    // font 16 pixel
#define LOAD_FONT4    // font 26 pixel
#define LOAD_FONT6    // font 48 pixel (số)
#define LOAD_FONT7    // 7-segment 48 pixel
#define LOAD_FONT8    // 75 pixel (số)
#define LOAD_GFXFF    // Adafruit GFX font
#define SMOOTH_FONT

#define SPI_FREQUENCY 40000000
#define SPI_READ_FREQUENCY 20000000
#define SPI_TOUCH_FREQUENCY 2500000

Lưu, restart Arduino IDE.

3. Cấu hình thay thế (PlatformIO)

Trong platformio.ini:

build_flags =
  -DILI9341_DRIVER
  -DTFT_WIDTH=240
  -DTFT_HEIGHT=320
  -DTFT_MOSI=23
  -DTFT_SCLK=18
  -DTFT_CS=15
  -DTFT_DC=2
  -DTFT_RST=4
  -DLOAD_GLCD
  -DLOAD_FONT2
  -DLOAD_FONT4
  -DLOAD_GFXFF
  -DSMOOTH_FONT
  -DSPI_FREQUENCY=40000000

Cách này sạch hơn — không phải sửa file thư viện.

4. Hello world

#include 
TFT_eSPI tft;

void setup() {
  tft.init();
  tft.setRotation(1);
  tft.fillScreen(TFT_BLACK);
  tft.setTextColor(TFT_WHITE, TFT_BLACK);
  tft.setTextSize(2);
  tft.drawString("ArduinoVN", 20, 20, 4);   // font index 4
}

void loop() {}

Khác Adafruit: drawString(text, x, y, font) thay vì setCursor() + print(). Font là index số (2, 4, 6, 7, 8).

5. Drawing primitives

tft.drawPixel(x, y, TFT_RED);
tft.drawLine(x0, y0, x1, y1, TFT_GREEN);
tft.drawRect(x, y, w, h, TFT_BLUE);
tft.fillRect(x, y, w, h, TFT_YELLOW);
tft.drawCircle(x, y, r, TFT_CYAN);
tft.fillCircle(x, y, r, TFT_MAGENTA);
tft.drawRoundRect(x, y, w, h, r, TFT_WHITE);
tft.fillTriangle(x0, y0, x1, y1, x2, y2, TFT_ORANGE);
tft.drawEllipse(x, y, rx, ry, TFT_PINK);

API tương tự GFX nhưng nhanh hơn ~3 lần do dùng hardware SPI DMA.

6. Hằng số màu

TFT_eSPI có sẵn 17 màu: TFT_BLACK, WHITE, RED, GREEN, BLUE, CYAN, MAGENTA, YELLOW, ORANGE, PINK, PURPLE, BROWN, NAVY, MAROON, DARKGREEN, DARKCYAN, OLIVE.

Custom màu RGB565:

uint16_t color = tft.color565(255, 128, 0);   // orange

7. Sprite — buffer riêng trong RAM

Sprite là canvas RAM, vẽ vào sprite không hiện ngay → khi xong push lên TFT — tránh flicker:

TFT_eSprite spr = TFT_eSprite(&tft);

void setup() {
  tft.init();
  spr.createSprite(160, 80);     // 160x80 pixel buffer
  spr.fillSprite(TFT_BLACK);
  spr.setTextColor(TFT_WHITE);
  spr.drawString("Sprite!", 0, 0, 4);
  spr.pushSprite(20, 20);        // hiện lên TFT tại (20, 20)
}

Hữu ích cho UI có nhiều update — vẽ sprite xong push 1 lần = không nháy.

8. Hiển thị ảnh JPG

Cài thêm TJpg_Decoder by Bodmer. Lưu ảnh JPG < 100KB vào SPIFFS/SD card:

#include 

bool tft_output(int16_t x, int16_t y, uint16_t w, uint16_t h, uint16_t* bitmap) {
  if (y >= tft.height()) return 0;
  tft.pushImage(x, y, w, h, bitmap);
  return 1;
}

void setup() {
  tft.init();
  SPIFFS.begin();
  TJpgDec.setJpgScale(1);
  TJpgDec.setCallback(tft_output);
  TJpgDec.drawFsJpg(0, 0, "/photo.jpg");
}

9. Smooth font (anti-aliased)

Smooth font cho chữ mượt như macOS:

tft.loadFont("NotoSansBold20");   // file .vlw trong SPIFFS
tft.setTextColor(TFT_WHITE, TFT_BLACK);
tft.drawString("Smooth!", 20, 20);
tft.unloadFont();

Tạo file .vlw bằng processing sketch trong thư mục TFT_eSPI/Tools.

10. So sánh hiệu năng với Adafruit

11. Nhược điểm

• Cấu hình phức tạp — sửa file thư viện.
• 1 cấu hình cho 1 board — đa project cùng máy nhưng khác TFT → phải đổi liên tục.
• API khác Adafruit — code không portable.
• Smooth font setup hơi rắc rối.

Liên quan

Đọc LVGL: UI đẹp trên TFT ESP32 — LVGL dùng TFT_eSPI làm driver. Bài TFT ILI9341 2.4" cảm ứng dùng Adafruit cho người mới.