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 和 -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 (Optional): 选择 single 用于标准 1 位总线 SPI（默认），quad 或 octal。
clk_pin (Required, Pin Schema): 用于 SPI 总线时钟线的引脚。
id (Optional, ID): 如果需要多个 SPI 集线器，手动为此 SPI 集线器指定 ID。
interface (Optional): 控制应使用哪个硬件或软件 SPI 实现。值可以是 any（默认）、software、hardware、spi、spi2 或 spi3 之一，具体取决于类型和所使用的特定芯片。请参阅下面的讨论。

对于常规 single 位总线，至少需要 miso_pin 或 mosi_pin 之一。

mosi_pin (Optional, Pin Schema): 用于 SPI 总线 MOSI 线的引脚。
miso_pin (Optional, Pin Schema): 用于 SPI 总线 MISO 线的引脚。

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

data_pins (Required, Pin Schema): 必须是正好 4 个引脚的列表，用于四线 SPI 输出数据线，或八线模式正好 8 个引脚。单线模式不使用。

接口选择

ESP32 和 ESP8266 芯片有几个硬件 SPI 控制器实现 - 通常前一个或两个保留用于访问闪存和 PSRAM 内存，剩下一个或两个用户可访问的控制器。在 ESPHome 中配置的 SPI 控制器实例可以通过 interface: 配置选项分配给这些控制器之一。

默认情况下（interface: any）将分配第一个可用的硬件控制器，如果可用则分配第二个，然后配置的任何其他实例将使用软件模式。您可以使用 spi（意味着第一个或唯一可用的控制器）选择特定控制器，或者对于有两个可用 SPI 控制器的 ESP32 芯片选择 spi2 和 spi3 之一。请注意，SPI0 和 SPI1 通常不可用，保留用于访问闪存和 PSRAM。

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

虽然 ESP32 支持将默认 SPI 引脚重新分配到大多数其他 GPIO 引脚，但使用专用 SPI 引脚可以提高某些 ESP/设备组合的性能和稳定性。 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 (Optional): 设置控制器的数据速率。这可以是 Hz 为单位的数值或带有单位后缀的字符串，例如 “100kHz” 或 “20MHz”。必须至少为 1000Hz，请参阅下面的其他约束。
spi_mode (Optional): 设置控制器模式 - mode0、mode1、mode2、mode3 之一。默认为 mode3。有关更多信息，请参阅下表
bit_order (Optional): 设置位顺序 - 选择 msb_first（默认）或 lsb_first 之一。
cs_pin (Optional, Pin Schema): CS 引脚。
release_device (Optional, boolean): 对于 ESP32，在事务之间释放总线设备。默认为 False。将此设置为 True 将允许超过 6 个设备连接到硬件 SPI 总线。
interface (Optional): 控制应使用哪个硬件或软件 SPI 实现。

数据速率

可以设置任何高于 1000Hz、低于目标平台可用的最大值，并且可以通过 SPI 时钟源的整数除法实现的数据速率。时钟源频率为：

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

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

SPI 模式

SPI 设备按下表所示以四种模式之一运行。模式的选择取决于特定外围芯片的要求。

支持的模式

模式	时钟空闲极性	时钟相位	数据移位时机	数据采样时机
0	低	前沿	/CS 激活和下降沿 CLK	上升沿 CLK
1	低	后沿	上升沿 CLK	下降沿 CLK
2	高	前沿	/CS 激活和上升沿 CLK	下降沿 CLK
3	高	后沿	下降沿 CLK	上升沿 CLK

ESP32 总线设备限制

ESP32 有一个软件限制，即最多 6 个设备可以连接到硬件 SPI 总线。此限制不能轻易更改，但可以通过在事务之间释放总线设备来绕过，这样一次配置的设备不超过 6 个。release_device 选项可用于按设备启用此功能。这会增加 SPI 事务的时间，因此应该仅用于不需要频繁事务的设备。

另见

API Reference: spi.h