SPI TFT Display Wiring and Protocol Primer: ILI9341 vs ST7789

If you need to push high-resolution graphics from a microcontroller, the SPI TFT display is your default choice. SPI (Serial Peripheral Interface) bypasses the strict speed limits of I2C by using a dedicated push-pull data line, allowing clock speeds up to 80MHz on modern MCUs. For a standard 240x320 pixel screen, this means you can achieve 30+ frames per second, provided your physical wiring and library configurations are optimized for the bus capacitance.

SPI Bus Mechanics and Physical Layer for TFTs

Unlike I2C, which relies on open-drain lines and mandatory pull-up resistors, SPI uses a push-pull architecture. The master (MCU) actively drives the clock (SCK) and data (MOSI) lines high and low. This eliminates the RC time-constant delays caused by pull-up resistors charging parasitic capacitance, which is exactly why SPI can hit 80MHz while I2C struggles past 3.4MHz.

Here is how SPI stacks up against other common embedded protocols when driving high-throughput peripherals like TFT LCDs:

Physical Wiring and Pull-Up Requirements

Because SPI is push-pull, you do not need pull-up resistors on SCK, MOSI, or MISO. However, the Chip Select (CS) line requires careful management. If you are sharing the SPI bus with an SD card or an SPI flash chip, each device must have its own dedicated CS line. Leaving a CS line floating when a device is inactive can cause the TFT controller to interpret bus noise as commands, resulting in screen tearing or ghosting.

Popular SPI TFT Display Drivers: ILI9341 vs ST7789

When sourcing an SPI TFT display, you are rarely buying just a screen; you are buying a specific driver IC bonded to the glass. The two dominant drivers in the maker space are the ILI9341 and the ST7789. Choosing between them dictates your library setup, memory footprint, and maximum refresh rate.

Which protocol fits your constraints? SPI is the undisputed king for short-distance (< 30cm), high-speed, low-device-count applications. If you need to wire a display more than a meter away, SPI will fail due to signal ringing on the SCK line; you would need to switch to an LVDS or MIPI-DSI interface. If you need to daisy-chain 10 devices, SPI becomes a wiring nightmare due to individual CS lines, making I2C or a multiplexed UART backplane more appropriate.

Wiring, Minimal Exchange, and Classic Failures

Let's wire an ESP32-WROOM-32 to a 2.4-inch ILI9341 SPI TFT display using the hardware VSPI bus. Using hardware SPI is mandatory for acceptable frame rates; software (bit-banged) SPI will bottleneck your refresh rate to under 5 FPS.

Minimal Working Exchange (Arduino/ESP32)

For ESP32 development in 2026, the TFT_eSPI library is vastly superior to Adafruit_GFX for SPI TFT displays because it utilizes the ESP32's DMA (Direct Memory Access) controller to push pixels in the background. Below is a minimal initialization and pixel-push sequence.

#include <TFT_eSPI.h>

// Note: Pin definitions are handled in the library's User_Setup.h file,
// not in the sketch. Set ILI9341 driver and ESP32 VSPI pins there.
TFT_eSPI tft = TFT_eSPI();

void setup() {
  // Initialize the SPI bus and TFT controller
  tft.init();
  tft.setRotation(1); // Landscape mode
  tft.fillScreen(TFT_BLACK);
  
  // Push a simple gradient to verify bus speed
  for (int i = 0; i < 240; i++) {
    tft.drawFastVLine(i, 0, 320, tft.color565(i, 255 - i, 128));
  }
}

void loop() {
  // Main UI loop
}

The Classic Failures

• Baud Mismatch (The White Screen): If your screen powers on but remains stark white or shows garbled static, your SPI clock is too high for the physical wire length. The ILI9341 datasheet claims 62.5MHz, but on a breadboard with 10cm jumper wires, parasitic capacitance will cause bit errors. Drop the SPI clock to 40MHz or 27MHz in your library configuration.
• Missing CS Management (Ghosting): If you have an SD card and a TFT on the same SPI bus, and you don't explicitly set the SD card's CS pin to HIGH before talking to the TFT, the SD card will try to interpret the TFT's pixel data as FAT32 commands, crashing the bus.
• Backlight Current Draw: The LED pin on a 2.4-inch TFT can draw up to 150mA. Do not wire this directly to an ESP32 GPIO pin (max 40mA). Use a logic-level MOSFET like the IRLZ44N or a 2N7000 to switch the backlight from the 3.3V/5V rail.

Sniffing and Debugging the SPI Bus

When your SPI TFT display refuses to initialize, a multimeter is nearly useless because the SCK and MOSI lines are toggling too fast for the meter's sampling rate. You need to look at the physical layer.

Using a Logic Analyzer

Connect a logic analyzer (like a Saleae Logic Pro or a budget DSLogic Plus) to SCK, MOSI, and CS. Set the trigger to the falling edge of the CS line. When analyzing the capture, verify the SPI Mode. The ILI9341 and ST7789 typically require SPI Mode 0 (CPOL=0, CPHA=0), meaning the clock idles LOW and data is sampled on the rising edge. If your MCU is configured for Mode 3, the display will read every byte backward or shifted by one bit, resulting in a corrupted initialization sequence.

Oscilloscope Measurements

If the logic analyzer shows valid data but the screen still fails, hook up an oscilloscope to the SCK line. Look at the rise and fall times of the square wave. If the edges look like 'shark fins' (slow RC charging curves) rather than sharp vertical lines, your wire capacitance is too high. Fix: Shorten the wires, switch to a lower AWG (thicker wire has less resistance, though capacitance is largely geometry-dependent, keeping ground wires away from SCK reduces parasitic capacitance), or insert a 74HC125 bus buffer to actively drive the capacitive load.

For deeper library-level debugging on the ESP32, enable the ESP-IDF SPI Master debug logs by setting the core debug level to 'Verbose' in the Arduino IDE board manager. This will output the exact DMA transfer sizes and clock divider calculations to the serial monitor, confirming whether the hardware peripheral is actually handing off data to the bus.