Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Marcussacapuces91/doc-TFT_eSPI/llms.txt

Use this file to discover all available pages before exploring further.

TFT_eSPI is configured at compile time through a User_Setup.h file, but you can read those settings back at runtime — without any impact on code size unless you actually call the retrieval function — by using getSetup(). This populates a setup_t struct with every configured parameter: library version, display driver code, pin assignments, SPI frequencies, and more. The primary use-case is diagnostics: print the struct fields to Serial to confirm that the build-time configuration matches your hardware without digging through header files.

​
Header constants

These constants are defined in TFT_eSPI.h and are always available after #include <TFT_eSPI.h>.
ConstantValueDescription
TFT_ESPI_VERSION"2.5.43"Library version string.
TFT_ESPI_FEATURES1Bit-level feature flags. Bit 0 set = viewport capability enabled.
TAB_COLOUR0Default ST7735 tab colour. Override in your user setup if your module uses a coloured tab.
SPI_FREQUENCY20000000Default TFT write SPI clock (20 MHz).
SPI_READ_FREQUENCY10000000Default TFT read SPI clock (10 MHz).
SPI_TOUCH_FREQUENCY2500000Default XPT2046 touch controller SPI clock (2.5 MHz).
SPI_FREQUENCY, SPI_READ_FREQUENCY, and SPI_TOUCH_FREQUENCY are default fallbacks. If you define them in your own User_Setup.h, your values take precedence.

​
getSetup()

Populates a caller-supplied setup_t struct with the current compile-time configuration. 
void TFT_eSPI::getSetup(setup_t &tft_settings);

setup_t cfg;
tft.getSetup(cfg);

Serial.println(cfg.version);          // e.g. "2.5.43"
Serial.println(cfg.tft_driver, HEX);  // e.g. 0x7789 for ST7789
Serial.println(cfg.tft_width);        // e.g. 240
Serial.println(cfg.tft_height);       // e.g. 320
Calling getSetup() has zero impact on code size unless you actually use it — the compiler can dead-strip the function if it is unreferenced.

​
setup_t struct fields

typedef struct {
  String   version;       // TFT_ESPI_VERSION string
  String   setup_info;    // Optional reference name from user setup
  uint32_t setup_id;      // Optional ID from user setup

  int32_t  esp;           // Processor code
  uint8_t  trans;         // SPI transaction support flag
  uint8_t  serial;        // 1 = serial (SPI), 0 = parallel
  uint8_t  port;          // SPI port number (not present on GENERIC_PROCESSOR)
  uint8_t  overlap;       // ESP8266 SPI overlap mode flag
  uint8_t  interface;     // Interface type code

  uint16_t tft_driver;    // Display driver ID in hexadecimal (e.g. 0x9341 = ILI9341)
  uint16_t tft_width;     // Native width  at rotation 0, in pixels
  uint16_t tft_height;    // Native height at rotation 0, in pixels

  // Display offsets for each of the 4 rotations
  uint8_t r0_x_offset;
  uint8_t r0_y_offset;
  uint8_t r1_x_offset;
  uint8_t r1_y_offset;
  uint8_t r2_x_offset;
  uint8_t r2_y_offset;
  uint8_t r3_x_offset;
  uint8_t r3_y_offset;

  // SPI pins
  int8_t pin_tft_mosi;
  int8_t pin_tft_miso;
  int8_t pin_tft_clk;
  int8_t pin_tft_cs;

  // Control pins
  int8_t pin_tft_dc;
  int8_t pin_tft_rd;
  int8_t pin_tft_wr;
  int8_t pin_tft_rst;

  // Parallel port data pins (D0–D7)
  int8_t pin_tft_d0;
  int8_t pin_tft_d1;
  int8_t pin_tft_d2;
  int8_t pin_tft_d3;
  int8_t pin_tft_d4;
  int8_t pin_tft_d5;
  int8_t pin_tft_d6;
  int8_t pin_tft_d7;

  // Backlight pin
  int8_t pin_tft_led;
  int8_t pin_tft_led_on;   // Logic level that turns the backlight ON

  // Touch controller
  int8_t pin_tch_cs;       // Touch chip-select pin

  // SPI frequencies (stored as kHz / 10 for compactness)
  int16_t tft_spi_freq;    // TFT write SPI frequency
  int16_t tft_rd_freq;     // TFT read  SPI frequency
  int16_t tch_spi_freq;    // Touch controller SPI frequency
} setup_t;

​
Field reference

​
getColorCallback typedef

Defines the function signature for a smooth-font pixel color source callback. When rendering smooth (anti-aliased) fonts, TFT_eSPI can call back into your code to retrieve the background color at each pixel position — enabling correct anti-aliasing over any background image. 
typedef uint16_t (*getColorCallback)(uint16_t x, uint16_t y);
ParameterTypeDescription
xuint16_tScreen x coordinate of the pixel being rendered.
yuint16_tScreen y coordinate of the pixel being rendered.
Returnsuint16_t16-bit RGB565 color of the background at (x, y).
// Example: flat-color background callback
uint16_t myBgColor(uint16_t x, uint16_t y) {
  (void)x; (void)y;          // position unused for a solid background
  return TFT_NAVY;
}

// Pass the callback to the smooth-font draw function
tft.setTextColor(TFT_WHITE);
tft.drawString("Smooth text", 20, 60);  // uses registered callback for bg blending

​
Complete diagnostics example

#include <TFT_eSPI.h>
#include <SPI.h>

TFT_eSPI tft = TFT_eSPI();

void setup() {
  Serial.begin(115200);
  tft.init();

  // Retrieve and print full configuration
  setup_t cfg;
  tft.getSetup(cfg);

  Serial.print("TFT_eSPI version : "); Serial.println(cfg.version);
  Serial.print("Driver (hex)     : 0x");
  Serial.println(cfg.tft_driver, HEX);
  Serial.print("Resolution       : ");
  Serial.print(cfg.tft_width);  Serial.print(" x ");
  Serial.println(cfg.tft_height);
  Serial.print("MOSI pin         : "); Serial.println(cfg.pin_tft_mosi);
  Serial.print("MISO pin         : "); Serial.println(cfg.pin_tft_miso);
  Serial.print("CLK  pin         : "); Serial.println(cfg.pin_tft_clk);
  Serial.print("CS   pin         : "); Serial.println(cfg.pin_tft_cs);
  Serial.print("DC   pin         : "); Serial.println(cfg.pin_tft_dc);
  Serial.print("RST  pin         : "); Serial.println(cfg.pin_tft_rst);
  Serial.print("Touch CS pin     : "); Serial.println(cfg.pin_tch_cs);
  Serial.print("SPI write freq   : "); Serial.println(cfg.tft_spi_freq);
  Serial.print("SPI read  freq   : "); Serial.println(cfg.tft_rd_freq);
  Serial.print("Touch SPI freq   : "); Serial.println(cfg.tch_spi_freq);
}

void loop() {}
Run this diagnostics sketch first whenever you port your project to a new board or display module. Seeing the actual pin assignments and driver code in Serial Monitor is the fastest way to confirm that User_Setup.h is correct.

Build docs developers (and LLMs) love

Get started for freeTalk to us