SPI displays are widely used in Arduino, ESP32, ESP8266, RP2040 and embedded projects. They include small OLED displays, TFT displays, ST7567 graphic LCDs, ST7920 graphic LCDs, ILI9341 TFTs, ST7735 / ST7789 displays and many other modules.
Compared with I2C displays, SPI displays can be faster and more flexible. But they also need more wires, more correct pin definitions and the right display driver settings. A small mistake can result in a blank screen, white screen, random pixels, shifted graphics or a display that works only sometimes.
In most cases, the display is not defective. The problem is usually wrong wiring, wrong controller type, wrong library constructor, wrong reset pin, missing chip select, incorrect voltage level, poor power, or SPI speed that is too high for the wiring.
Typical Symptoms
- The display stays completely blank.
- A TFT display shows only a white screen.
- The display shows random pixels or corrupted graphics.
- Text appears shifted, mirrored or rotated incorrectly.
- The display works with one example but not another.
- The display works on Arduino Uno but not on ESP32.
- The display works at low speed but fails at high speed.
- The display only works when reset is pressed manually.
First Important Point: SPI Is Not Just One Wire
I2C displays usually need VCC, GND, SDA and SCL. SPI displays usually need more signals.
A typical SPI display may need:
- VCC: power supply
- GND: ground
- SCK / CLK: SPI clock
- MOSI / SDA / DIN: data from microcontroller to display
- CS / SS: chip select
- DC / A0 / RS: data/command select
- RESET / RST: display reset
- BL / LED: backlight control on some TFTs
- MISO / SDO: sometimes used for reading data back, often not needed
If even one required signal is wrong, the display may not initialize.
Common Cause: MOSI and MISO Are Confused
Many SPI display modules only need data from the microcontroller to the display. That means MOSI is important, while MISO may not be used at all.
MOSI means “Master Out, Slave In.” In a typical Arduino project, the microcontroller is the master and the display is the slave. So MOSI is the data line going from the controller to the display.
Display modules may label this pin differently:
- MOSI
- DIN
- SDA
- SDI
- DATA
This can be confusing because some SPI displays label the data input as SDA, even though the display is not using I2C.
Common Cause: Wrong SPI Pins
Classic Arduino boards have fixed hardware SPI pins. ESP32 and RP2040 boards are more flexible, but the sketch must match the wiring.
| Board | Typical Hardware SPI Pins | Important Note |
|---|---|---|
| Arduino Uno / Nano | SCK 13, MISO 12, MOSI 11, SS 10 | Many shields expect these pins |
| Arduino Mega 2560 | SCK 52, MISO 50, MOSI 51, SS 53 | Different from Uno/Nano |
| ESP8266 | Board-specific labels such as D5/D6/D7/D8 | Check GPIO numbers and board labels carefully |
| ESP32 | Common defaults include SCK 18, MISO 19, MOSI 23, CS 5 | Pins can often be changed, but code must match |
| RP2040 / XIAO-style boards | Board-specific | Use the exact board pinout, not a generic diagram |
If an example uses default SPI pins but the display is wired to different pins, the display will not work unless the constructor or SPI setup is changed.
Common Cause: Wrong Display Controller
Many displays look similar but use different controller chips. The library must match the controller, not just the screen size.
Examples:
- ST7735 and ST7789 TFTs are not the same.
- ILI9341 and ILI9488 TFTs need different drivers.
- SSD1306 and SH1106 OLEDs need different handling.
- ST7565 and ST7567 graphic LCDs may need different initialization.
- ST7920 graphic LCDs are different from common TFTs and OLEDs.
If the display controller is wrong, the display may show a white screen, random pixels, shifted graphics or nothing at all.
Common Cause: Wrong Library Constructor
Many display libraries use constructors that define the controller pins. If the constructor does not match the wiring, the sketch may compile but the display will not work.
A constructor may define:
- Chip select pin.
- Data/command pin.
- Reset pin.
- SPI bus object.
- Software SPI pins.
- Display size or controller variant.
Do not only copy the example. Compare every pin in the constructor with the actual wiring.
Common Cause: Missing or Wrong CS Pin
The chip select pin tells the display when it should listen. Some simple projects tie CS permanently active, but many libraries expect a real CS pin.
If CS is missing, floating or assigned to the wrong GPIO, the display may ignore commands or behave randomly.
For reliable troubleshooting, connect CS to a real GPIO and define it in the sketch.
Common Cause: DC / A0 / RS Pin Is Wrong
Most SPI displays need a data/command select pin. It may be labeled:
- DC
- D/C
- A0
- RS
This pin tells the display whether the SPI byte is a command or display data.
If DC is wired wrong, the display may receive pixel data as commands or commands as pixel data. The result is usually a blank screen or garbage.
Common Cause: Reset Pin Is Wrong or Floating
Many SPI displays need a reset signal during startup. Some modules connect reset to a resistor/capacitor circuit. Others expose a reset pin that must be controlled by the microcontroller.
If reset is floating or not handled by the library, the display may start in an unknown state.
Possible fixes:
- Connect display RST to a defined GPIO and set it in the constructor.
- Connect display RST to the microcontroller reset line if suitable.
- Use
-1in the constructor only if the library supports no reset pin. - Power-cycle the display if it gets stuck in a bad state.
Common Cause: TFT Backlight Is Not Powered
Many TFT displays have a separate backlight pin. The display controller may work, but the screen appears black because the backlight is off.
The backlight pin may be labeled:
- LED
- BL
- BLA / BLK
- Backlight
Some modules need this pin connected to VCC. Others allow PWM dimming through a transistor. Check the module design before connecting it directly.
A white screen usually means the backlight is on but the display controller is not initialized correctly. A completely dark screen may mean the backlight is off or the display has no power.
Common Cause: Wrong Voltage Level
Many modern displays are 3.3V devices. Some modules include regulators and level shifters for 5V Arduino use. Others do not.
Problems happen when:
- A 3.3V-only display is connected to 5V Arduino signals.
- A 5V module does not recognize 3.3V logic reliably.
- Backlight is powered from the wrong voltage.
- The display module has a regulator but the logic pins are not level-shifted.
ESP32, ESP8266, RP2040 and most modern controllers use 3.3V logic. Classic Arduino Uno and Nano use 5V logic.
Never assume a display is 5V-safe just because the power pin is labeled VCC.
Common Cause: SPI Speed Too High
SPI can run much faster than I2C, but high speed requires clean wiring. Breadboards, long jumper wires and poor grounding can make high-speed SPI unreliable.
Symptoms of excessive SPI speed include:
- Random pixels.
- Corrupted graphics.
- Display works sometimes but not always.
- Works with short wires but not long wires.
- Works on one board but not another.
Try reducing SPI speed in the library settings or constructor if supported. Many displays do not need maximum SPI speed during troubleshooting.
Common Cause: Breadboard Wiring Is Too Long or Loose
SPI signals are faster than many beginner breadboard setups are comfortable with. Long wires, loose contacts and messy routing can create signal problems.
For troubleshooting:
- Use short wires.
- Keep GND close to signal wires.
- Avoid routing SPI wires near motors, relays or LED power wiring.
- Do not run display power through weak breadboard rails if the backlight draws current.
- Try a lower SPI clock speed.
Common Cause: Software SPI vs Hardware SPI Confusion
Some libraries support both hardware SPI and software SPI.
Hardware SPI uses the microcontroller’s SPI peripheral and usually fixed or preferred pins. Software SPI can use almost any pins but is slower and must be configured correctly.
If the example uses hardware SPI but the display is wired to arbitrary pins, it may not work. If the example uses software SPI but the constructor pins are wrong, it also will not work.
Check whether your example is using hardware SPI or software SPI.
Common Cause: Multiple SPI Devices Share the Bus Incorrectly
SPI can share SCK, MOSI and MISO between multiple devices, but each device needs its own chip select line.
Problems happen when:
- Two devices use the same CS pin.
- A device’s CS line is left floating.
- One device does not release MISO when not selected.
- Different devices require different SPI modes or speeds.
- One library changes SPI settings and does not restore them properly.
If a display works alone but not with an SD card or another SPI device, test the devices separately and check all CS lines.
Common Cause: SD Card and Display Conflict
Many TFT modules include an SD card socket on the same SPI bus. The display and SD card usually share SCK, MOSI and MISO, but need separate CS pins.
If the SD card CS pin is floating or held active, it may interfere with the display. The same can happen if the display CS is not controlled correctly.
When using a display with an SD slot:
- Define separate CS pins for display and SD card.
- Set unused CS pins HIGH when not used.
- Test display alone first.
- Test SD card alone second.
- Only then test both together.
Common Cause: Wrong Rotation or Offset
Some displays work but show graphics shifted, clipped, mirrored or rotated. This may not be a wiring problem. The display may need the correct rotation, offset or tab-color setting in the library.
This is common with small ST7735 and ST7789 TFT modules, where different PCB versions have different memory offsets.
Try the library examples for different display variants if the screen is mostly working but the image position is wrong.
Recommended Troubleshooting Steps
- Confirm the exact display controller chip and resolution.
- Check whether the display is 3.3V-only or 5V-compatible.
- Connect only the display, no other SPI devices.
- Use short wires and stable power.
- Check SCK, MOSI, CS, DC and RESET carefully.
- Power the backlight correctly if using a TFT.
- Use the simplest example for the exact display library.
- Lower SPI speed if possible.
- Test hardware SPI and software SPI settings if supported.
- Add other SPI devices only after the display works alone.
Quick Diagnostic Table
| Symptom | Likely Cause | First Thing to Try |
|---|---|---|
| TFT shows white screen | Backlight on, controller not initialized | Check driver, CS, DC, RESET and SPI wiring |
| Screen completely dark | No power or backlight off | Check VCC, GND and BL/LED pin |
| Random pixels or corrupted graphics | Wrong driver, poor wiring or SPI speed too high | Lower SPI speed and confirm controller type |
| Works alone, fails with SD card | Chip select conflict | Check separate CS pins and set inactive CS HIGH |
| Image shifted or clipped | Wrong display variant, offset or rotation setting | Try correct library variant or tab setting |
| Works on Uno, fails on ESP32 | Wrong ESP32 pins, voltage or constructor | Use explicit ESP32 pin definitions and check 3.3V logic |
Example SPI Display Pin Checklist
| Display Pin | Meaning | Common Mistake |
|---|---|---|
| VCC | Power supply | Using 5V on a 3.3V-only display or too weak supply |
| GND | Ground reference | Missing common ground |
| SCK / CLK | SPI clock | Connected to wrong board pin |
| MOSI / DIN / SDA | Data into display | Confused with MISO or I2C SDA |
| CS | Chip select | Left floating or not matching constructor |
| DC / A0 / RS | Data/command select | Wrong pin prevents correct initialization |
| RST | Reset | Floating or wrong constructor value |
| BL / LED | Backlight | Backlight not powered or overpowered |
What Not to Do
- Do not assume every display with the same size uses the same controller.
- Do not confuse SPI “SDA” labels with I2C SDA.
- Do not leave CS, DC or RESET floating.
- Do not connect 5V logic to a 3.3V-only display.
- Do not start troubleshooting with multiple SPI devices connected.
- Do not run long jumper wires at high SPI speed and expect perfect results.
CANABLOX Practical Note
CANABLOX is mainly built around clean modular I2C connections, but many projects also use SPI displays or SPI peripherals. When combining SPI displays with a CANABLOX controller setup, keep the SPI wiring short and direct, and treat the display as a separate high-speed peripheral.
If a CANABLOX project uses a XIAO-style ESP32, RP2040, RP2350 or other controller with an SPI display, always check the exact controller pinout and define the SPI display pins clearly in the sketch. Do not assume that an Arduino Uno SPI example maps directly to a modern compact controller board.
Conclusion
If an SPI display does not work, start with the physical and configuration basics: correct controller chip, correct library, correct pins, stable power, proper voltage level, and a defined reset and chip select signal.
A blank display, white screen or random pixels usually means the display was not initialized correctly or the SPI signal is not reaching it cleanly.
Test the display alone with a simple example, reduce SPI speed if needed, and add other SPI devices only after the display works reliably by itself.