Sensors and I/O

SPI Master

Bus for displays, external flash and fast ADCs.

Sensors and I/O SPI display / flash ESP32 family

Official path: examples/peripherals/spi_master

01 Overview

SPI master shifts clock and data to a slave. The ESP32's SPI2 and SPI3 peripherals can act as masters, supporting 4-wire (MOSI/MISO/SCLK/CS) and 3-wire (no MISO) modes.

Typical uses: driving TFT panels (e.g., ST7789), external flash, SD cards, and high-speed ADCs.

Compared to I2C, SPI is faster and more flexible but requires more pins and has no built-in acknowledgment.

If you only need two wires and low speed, consider I2C first; SPI suits high-throughput and high-refresh-rate scenarios.

This example demonstrates how to initialize the SPI bus, add devices, queue transactions, and use DMA for large payloads.

02 Hardware

Peripheral: ESP32 has SPI2 and SPI3, both configurable as master.
Pins: Typical connections: MOSI, MISO, SCLK, CS (one per slave). See schematic for exact pins.
CS polarity: Most slaves are active-low, but check the datasheet.
Clock polarity/phase: Modes 0–3, must match the slave.
Signal integrity: Trace length, impedance, and return path affect edges; pay attention at high speeds.
Extra control pins: Some panels need DC (data/command) and RST (reset) pins, requiring additional GPIOs.
Level matching: If the slave is 3.3V, ESP32 can drive directly; if 5V, level shifting is needed.

03 Software flow

1. Call spi_bus_initialize() to set up the bus, pins, clock source, and DMA channel.

2. Call spi_bus_add_device() to add a slave device, configuring mode, clock speed, CS polarity, etc.

3. Prepare transmit data, optionally allocating DMA buffers.

4. Call spi_device_transmit() to send a transaction and wait for completion.

5. For large payloads, use DMA to avoid CPU spinning.

6. Error handling: check return values; retry or reset on timeout or failure.

7. Low power: disable the SPI peripheral clock after transfers complete.

04 Core points

Wrong mode or CS polarity looks like “waveforms but no data”.
Custom work: panel driver, extra flash, layout.
Note: Different slaves have different timing requirements; consult the datasheet.
Do not copy SPI init code from other chips directly; pins and registers differ.
At high speeds, watch signal integrity; reduce clock or add termination if needed.

中文

传感器与外设

SPI Master

屏幕、外置 Flash、高速 ADC 的总线。

传感器与外设 SPI 屏 / 存储 ESP32 family

官方路径: examples/peripherals/spi_master

01 项目概述

SPI 主机向从机移时钟和数据。ESP32 的 SPI2/SPI3 可作主机，支持 4 线（MOSI/MISO/SCLK/CS）和 3 线（无 MISO）模式。

典型用途：驱动 TFT 屏（如 ST7789）、外置 Flash、SD 卡、高速 ADC。

相比 I2C，SPI 更快、更灵活，但需要更多引脚，且没有内置应答机制。

如果只需要两根线且速率不高，优先考虑 I2C；SPI 适合大数据量、高刷新率场景。

本示例演示如何初始化 SPI 总线、添加设备、发送事务，以及使用 DMA 传输大块数据。

02 项目硬件描述

总线外设： ESP32 有 SPI2 和 SPI3，均可配置为主机。
引脚： 典型接法：MOSI、MISO、SCLK、CS（每从机一个）。具体引脚见原理图。
CS 极性： 多数从机低有效，但需确认数据手册。
时钟极性/相位： 模式 0–3，必须与从机匹配。
信号完整性： 走线长度、阻抗、接地回流影响边沿，高速时需注意。
额外控制脚： 部分屏需要 DC（数据/命令）和 RST（复位）引脚，需额外 GPIO 控制。
电平匹配： 若从机为 3.3V，ESP32 可直接驱动；若为 5V，需电平转换。

03 项目软件流程描述

1. 调用 spi_bus_initialize() 初始化总线，设置引脚、时钟源和 DMA 通道。

2. 调用 spi_bus_add_device() 添加从机设备，配置模式、时钟频率、CS 极性等。

3. 准备发送数据，可分配 DMA 缓冲区。

4. 调用 spi_device_transmit() 发送事务，等待完成。

5. 对于大块数据，使用 DMA 传输，避免 CPU 空转。

6. 错误处理：检查返回值，超时或失败时重试或复位。

7. 低功耗：传输完成后可关闭 SPI 外设时钟。

04 项目核心点

模式和 CS 极性抄错就会「有波形没数据」。
可定制： 屏驱、外置存储、布局。
注意： 不同从机对时序要求不同，需查阅数据手册。
不要直接复制其他芯片的 SPI 初始化代码，引脚和寄存器不同。
高速时注意信号完整性，必要时降低时钟或加端接。