SPI 总线

SPI 是一种非常常见的高速协议，用于大量设备。ESPHome 的 SPI 组件仅实现了主机控制器角色，即控制总线，并从连接到总线的设备中写入或读取数据。

SPI 总线通常由 4 根导线组成：

CLK：用于告知接收设备何时读取数据。总线上的所有设备都可以共享此线路。有时也称为 SCK。
CS（芯片选择）：用于告知接收设备何时应监听数据。每个设备都有自己单独的 CS 线路。有时也称为 SS。如果 SPI 总线只有单个设备，其 CS 引脚有时可以直接接地，以告知它始终处于被选中状态。
MOSI（也叫 SDO - 串行数据输出）：用于从控制器（ESP）向设备发送数据。总线上的所有设备共享此线路。
MISO（也叫 SDI - 串行数据输入）：用于接收数据。总线上的所有设备共享此线路。

在某些情况下，MOSI 或 MISO 其中之一不存在，因为接收设备只接受数据或只发送数据。也可以配置使用 4 条输出数据线的四线 SPI 接口，以及使用 8 条数据输出线的八线接口。这仅在与某些组件配合使用时需要。

NOTE

软件模式仅支持单比特 SPI。
四线 SPI 模式仅在 ESP32 设备（所有变体）上可用。
八线模式仅在 ESP32-S3、-S2、-S31 和 -P4 变体上可用。

要在 ESPHome 中设置 SPI 设备，首先需要在顶级放置一个 SPI 组件，定义用于上述功能的引脚。CS 引脚由引用 spi 组件的其他组件单独管理。该组件还接受一个控制器列表，以便你实现多个 SPI 总线。

# 示例配置条目 - 单个控制器
spi:
  clk_pin: GPIOXX
  mosi_pin: GPIOXX
  miso_pin: GPIOXX

# 示例配置条目 - 三个控制器，其中一个使用四线 SPI
spi:
  - id: spi_bus0
    clk_pin: GPIOXX
    mosi_pin: GPIOXX
    miso_pin: GPIOXX
    interface: hardware
  - id: spi_bus1
    clk_pin: GPIOXX
    mosi_pin: GPIOXX
    miso_pin: GPIOXX
    interface: any
   - id: quad_spi_bus
    type: quad
    clk_pin: GPIOXX
    data_pins:
      - GPIOXX
      - GPIOXX
      - GPIOXX
      - GPIOXX

配置变量

type (可选): 在标准的 1 比特总线 SPI（默认）的 single、quad 和 octal 之间选择。
clk_pin (必选, Pin Schema): 用作 SPI 总线时钟线的引脚。
id (可选, ID): 如果你需要多个 SPI 中心，可手动指定该 SPI 中心的 ID。
interface (可选): 控制应使用哪种硬件或软件 SPI 实现。取值可以是 any（默认）、software、hardware、spi、spi2 或 spi3，具体取决于类型和所使用的特定芯片。详见下文讨论。

对于传统的 single 比特总线，至少需要指定 miso_pin 或 mosi_pin 之一。

mosi_pin (可选, Pin Schema): 用作 SPI 总线 MOSI 线的引脚。
miso_pin (可选, Pin Schema): 用作 SPI 总线 MISO 线的引脚。

对于 quad 或 octal 类型，改为指定 data_pins：

data_pins (必选, Pin Schema): 必须是一个由恰好 4 个引脚组成的列表，用于四线 SPI 输出数据线；对于八线模式则为恰好 8 个引脚。单线模式不使用。

接口选择

ESP32 和 ESP8266 芯片具有多个硬件 SPI 控制器实现——通常第一、第二个保留用于访问 Flash 和 PSRAM，因此剩下一个或两个可供用户使用的控制器。在 ESPHome 中配置的 SPI 控制器实例可以通过 interface: 配置选项分配给其中之一。

默认情况下（interface: any）将分配第一个可用的硬件控制器；如果有第二个可用则分配第二个，然后任何进一步配置的实例都将使用软件模式。你可以使用 spi（意为第一个或唯一可用的控制器）选择特定控制器，或使用 spi2 和 spi3 中的一个用于具有两个可用 SPI 控制器的 ESP32 芯片。请注意，SPI0 和 SPI1 通常不可用，因为它们被保留用于访问 Flash 和 PSRAM。

如果选择了 software 选项，或者你配置的 SPI 实例多于可用的硬件控制器，剩余实例将使用软件实现，其无法达到几百 kHz 以上的数据速率。这对于传感器或其他不传输大量数据的设备是可以接受的，但对于驱动显示器等用途则过慢。

尽管 ESP32 支持将默认 SPI 引脚重新分配给大多数其他 GPIO 引脚，但对于某些 ESP/设备组合，使用专用 SPI 引脚可以提高性能和稳定性。 ESP8266 可用的引脚选择更为有限；请查阅数据手册获取更多信息。

四线和八线模式需要硬件接口，因此 software 和 any 不是有效的取值。

通用 SPI 设备组件

其他依赖 SPI 组件的组件会引用它，通常用于与特定设备通信。还有一个通用的 SPI 设备组件，可用于与未被特定组件支持的硬件进行通信。它允许选择 SPI 模式、data_rate、CS 引脚和位顺序。设备的读写操作可以通过 lambda 进行。例如：

spi:
    clk_pin: GPIOXX
    mosi_pin: GPIOXX
    miso_pin: GPIOXX
    interface: hardware

spi_device:
    id: spidev
    cs_pin: GPIOXX
    data_rate: 2MHz
    spi_mode: 3
    bit_order: lsb_first

 on...:
 then:
   - lambda: !lambda |-
       id(spidev).enable();
       id(spidev).write_byte(0x4F);
       id(spidev).disable();

配置变量

data_rate (可选): 设置控制器的数据速率。这可以是 Hz 单位的数值，也可以是带有单位后缀的字符串，例如 “100kHz” 或 “20MHz”。必须至少为 1000Hz，其他限制见下文。
spi_mode (可选): 设置控制器模式——可选 mode0、mode1、mode2、mode3。默认为 mode3。更多信息见下表。
bit_order (可选): 设置位顺序——选择 msb_first（默认）或 lsb_first 之一。
cs_pin (可选, Pin Schema): CS 引脚。
release_device (可选, boolean): 针对 ESP32，在两次事务之间释放总线设备。默认为 False。将其设置为 True 将使连接到硬件 SPI 总线的设备数量可以超过 6 个。
interface (可选): 控制应使用哪种硬件或软件 SPI 实现。

数据速率

可以设置任何高于 1000Hz、低于目标平台可用的最大速率、并且可以通过从 SPI 时钟源分频获得的速率。时钟源频率为：

平台	时钟源
ESP32	80MHz
ESP8266	40MHz
RP2040	62.5MHz

请求的速率必须能够从时钟源通过整数分频生成，允许有 5% 的误差。

SPI 模式

SPI 设备按下表工作在四种模式之一。模式的选择取决于特定设备芯片的要求。

支持的模式

模式	时钟空闲极性	时钟相位	数据移位时	数据采样时
0	low	leading	/CS 激活和 CLK 下降沿	CLK 上升沿
1	low	trailing	CLK 上升沿	CLK 下降沿
2	high	leading	/CS 激活和 CLK 上升沿	CLK 下降沿
3	high	trailing	CLK 下降沿	CLK 上升沿

ESP32 总线设备数量限制

ESP32 对连接到硬件 SPI 总线的设备数量存在 6 个的软件限制。此限制不易更改，但可以通过在两次事务之间释放总线设备来绕过，使任何时候配置的设备不超过 6 个。release_device 选项可以在每个设备级别启用此功能。它会在 SPI 事务上增加额外时间，因此应仅在与不需要频繁事务的设备一起使用时使用。

参见

API 参考：spi.h