TFT_eSPI Constructor, Initialization, and Setup Methods

Before any drawing can occur the TFT_eSPI object must be constructed and initialized. The constructor accepts optional width and height overrides (defaulting to the values set in User_Setup.h), and initialization is performed by calling either begin() or init() — both are equivalent, with begin() retained for backwards compatibility. After initialization you can set the display orientation, invert the panel colours, and read back the full compile-time configuration via getSetup().

TFT_eSPI() — Constructor

TFT_eSPI(int16_t _W = TFT_WIDTH, int16_t _H = TFT_HEIGHT)

Constructs a TFT_eSPI instance. The width and height default to the values defined in User_Setup.h as TFT_WIDTH and TFT_HEIGHT. You only need to supply values when overriding the configured panel dimensions.

int16_t

Display width in pixels. Defaults to the TFT_WIDTH macro defined in User_Setup.h.

int16_t

Display height in pixels. Defaults to the TFT_HEIGHT macro defined in User_Setup.h.

#include <TFT_eSPI.h>

TFT_eSPI tft = TFT_eSPI();          // use dimensions from User_Setup.h
TFT_eSPI tft2 = TFT_eSPI(320, 240); // explicit 320×240 override

begin() — Initialize Display

void begin(uint8_t tc = TAB_COLOUR)

Initializes the TFT display hardware. This is an alias for init() and is provided for backwards compatibility with older code. Either function may be used; they perform identical work.

uint8_t

Tab colour option for ST7735 displays only. Encodes the colour of the protective tab on the display’s flexible cable. Defaults to TAB_COLOUR (0). Ignored for all other display drivers.

void setup() {
  tft.begin(); // initialize with default tab colour
}

init() — Initialize Display

void init(uint8_t tc = TAB_COLOUR)

Initializes the TFT display hardware, configures the SPI bus (or parallel interface), and sends the driver startup command sequence. Must be called once in setup() before any drawing operations.

uint8_t

Tab colour option for ST7735 displays only. Defaults to TAB_COLOUR (0).

#include <TFT_eSPI.h>

TFT_eSPI tft = TFT_eSPI();

void setup() {
  tft.init();
  tft.setRotation(1);
  tft.fillScreen(TFT_BLACK);
}

setRotation() — Set Display Orientation

void setRotation(uint8_t r)

Rotates the display coordinate system. The physical pixel buffer is not moved; instead the x/y mapping is remapped so that (0, 0) is always the top-left of the rotated view. Values 4–7 are used internally for BMP drawing and mirror the 0–3 orientations.

uint8_t

Rotation value:

0 — Portrait, no rotation
1 — Landscape, 90° clockwise
2 — Portrait, 180° (upside-down)
3 — Landscape, 270° clockwise (90° counter-clockwise)

tft.setRotation(1); // landscape

getRotation() — Read Current Orientation

uint8_t getRotation(void)

Returns the current rotation value set by setRotation(). Returns: uint8_t — current rotation (0–3).

uint8_t r = tft.getRotation();
Serial.println(r); // prints 0, 1, 2, or 3

invertDisplay() — Invert Panel Colours

void invertDisplay(bool i)

Sends the hardware invert-display command to the driver IC. When enabled every pixel colour is bitwise-inverted at the panel level (no CPU cost). Useful for switching between light and dark modes.

bool

true to invert display colours; false to restore normal colour output.

tft.invertDisplay(true);  // invert all colours
tft.invertDisplay(false); // restore normal

verifySetupID() — Check Setup ID

bool verifySetupID(uint32_t id)

Compares the given id against the setup_id compiled into the library via User_Setup.h. Use this in diagnostic sketches to confirm that the correct hardware configuration is active.

uint32_t

The expected setup ID value to verify against the compiled configuration.

Returns: bool — true if id matches the compiled setup ID.

if (!tft.verifySetupID(0x9341)) {
  Serial.println("Wrong display driver configured!");
}

getSetup() — Retrieve Compile-Time Configuration

void getSetup(setup_t& tft_settings)

Populates a setup_t struct with the full set of compile-time configuration values: driver code, pin assignments, SPI frequencies, interface type, and more. This has zero impact on code size unless actually called and is intended for diagnostic sketches.

tft_settings

setup_t&

Reference to a setup_t struct that will be populated with the current configuration. The caller must declare and own the struct instance.

setup_t cfg;
tft.getSetup(cfg);

Serial.print("Driver: 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);

The setup_t struct includes fields for the library version string, SPI pin numbers, parallel bus pins, touch controller pins, SPI frequencies, display offsets for all four rotations, and the interface type. See the Overview page for the full struct definition.

TFT_eSPI Class

TFT_eSPI_Button Class

Constants & Types

TFT_eSPI Constructor, Initialization, and Setup Methods