How to Wire, Code, and Debug Any SPI Device on ESP32 and Arduino

An SPI (Serial Peripheral Interface) device communicates via a 4-wire synchronous bus capable of pushing 10 to 50+ MHz. Unlike I2C, which relies on open-drain lines and pull-up resistors, SPI uses push-pull logic for high-speed, full-duplex data transfer. If you are interfacing TFT displays, external flash memory (like the W25Q32), or high-resolution ADCs, SPI is your default choice. The direct answer to wiring one successfully lies in managing the Chip Select (CS) line during microcontroller boot and matching the exact SPI Mode (CPOL/CPHA) dictated by the sensor's datasheet.

The Physical Layer: Wiring an SPI Device for Reliable Data

Before writing a single line of code, you must establish a clean physical layer. SPI is not a forgiving bus when it comes to parasitic capacitance and trace length. At 10 MHz, keep your jumper wires or PCB traces under 10 cm. Beyond that, signal reflections will corrupt your clock edges.

The bus relies on four primary lines: SCK (Clock), MOSI (Master Out Slave In), MISO (Master In Slave Out), and CS (Chip Select). Because SCK, MOSI, and MISO are actively driven (push-pull) by the master or the selected slave, they do not require pull-up resistors. Adding pull-ups to data lines will actually degrade your rise times and limit your maximum baud rate.

SPI Bus Mechanics Specification

Protocol Showdown: When to Choose SPI Over I2C or UART

Choosing the right protocol depends entirely on your constraints regarding distance, speed, and device count. Here is the decision framework for the bench:

Choose SPI when you need to push raw pixel data to an ILI9341 display or dump logs to an SD card. Choose I2C when you are daisy-chaining five BME280 environmental sensors and are out of GPIO pins. Choose UART when talking to an ESP8266 Wi-Fi bridge or a NMEA GPS module.

Minimal Working Exchange: ESP32 to W25Q32 Flash

Let's look at a concrete, minimal exchange. We will read the JEDEC Manufacturer ID from a W25Q32 SPI flash chip using an ESP32-WROOM-32 DevKit v1. This verifies the physical wiring and SPI Mode before integrating a heavy filesystem library like LittleFS.

Physical Wiring Map

Arduino Framework Code

#include <SPI.h>

// VSPI hardware pins on ESP32 are default, but we define CS explicitly
const int CS_PIN = 5;

void setup() {
  Serial.begin(115200);
  pinMode(CS_PIN, OUTPUT);
  digitalWrite(CS_PIN, HIGH); // Deselect chip immediately

  // Initialize hardware SPI at 1MHz for safe initial probing
  SPI.begin(); 
  delay(100);

  Serial.println('Probing W25Q32 JEDEC ID...');
  
  // W25Q32 requires SPI Mode 0 (CPOL=0, CPHA=0)
  SPI.beginTransaction(SPISettings(1000000, MSBFIRST, SPI_MODE0));
  
  digitalWrite(CS_PIN, LOW); // Assert Chip Select
  SPI.transfer(0x9F);        // Send Read JEDEC ID command
  
  uint8_t manufacturer = SPI.transfer(0x00);
  uint8_t mem_type = SPI.transfer(0x00);
  uint8_t capacity = SPI.transfer(0x00);
  
  digitalWrite(CS_PIN, HIGH); // Deassert Chip Select
  SPI.endTransaction();

  Serial.print('Manufacturer: 0x'); Serial.println(manufacturer, HEX);
  Serial.print('Memory Type: 0x'); Serial.println(mem_type, HEX);
  Serial.print('Capacity: 0x'); Serial.println(capacity, HEX);
  // Expected Winbond output: 0xEF, 0x40, 0x16
}

void loop() {
  // Minimal exchange complete
}

Bench Debugging: Sniffing the Bus and Fixing Classic Failures

When your SPI.transfer() returns 0xFF or 0x00 endlessly, do not guess. Sniff the bus. Connect a logic analyzer (a $15 Saleae Logic clone running PulseView/Sigrok) to SCK, MOSI, MISO, and CS. Set your trigger to the falling edge of CS. This captures the exact transaction and decodes the hex bytes, immediately revealing where the master and slave disagree.

According to SparkFun's SPI design guidelines and standard silicon datasheets, 90% of SPI failures on the bench fall into three categories:

1. Baud Rate and SPI Mode Mismatch: SPI has four modes based on Clock Polarity (CPOL) and Clock Phase (CPHA). Mode 0 (idle low, sample on leading edge) and Mode 3 (idle high, sample on trailing edge) are the most common. If your logic analyzer shows the clock idling high but your code initializes SPI_MODE0, the slave will read garbage. Always check the sensor datasheet's timing diagram.
2. The Missing CS Pull-Up (Boot Glitch):strong> As mentioned, if the CS line floats during ESP32 boot, the flash chip or display controller might latch into a write-protect or sleep state. If your code works perfectly after a soft-reset via the EN button, but fails on a hard power-cycle, you are missing a 10kΩ pull-up on CS.
3. MISO Contention: If you wire multiple SPI devices to the same MISO line, you must ensure that only the device with an active (LOW) CS drives the MISO pin. If a secondary device fails to tri-state its MISO output when its CS is HIGH, it will short-circuit the bus, dragging the voltage down and corrupting data from the active device.