172 lines
7.2 KiB
ReStructuredText
172 lines
7.2 KiB
ReStructuredText
.. _spi:
|
|
|
|
SPI Bus
|
|
=======
|
|
|
|
.. seo::
|
|
:description: Instructions for setting up SPI components in ESPHome
|
|
:image: spi.svg
|
|
:keywords: SPI
|
|
|
|
SPI is a very common high-speed protocol for a lot of devices. The ESPHome SPI component implements only the host controller
|
|
role, where it controls the bus, and writes or reads data from peripherals attached to the bus.
|
|
|
|
The SPI bus usually consists of 4 wires:
|
|
|
|
- **CLK**: Is used to tell the receiving device when to read data. All devices on the bus can
|
|
share this line. Sometimes also called ``SCK``.
|
|
- **CS** (chip select): Is used to tell the receiving device when it should listen for data. Each device has
|
|
an individual CS line. Sometimes also called ``SS``. If the SPI bus has a single device, its CS pin
|
|
can sometimes be connected to ground to tell it that it is always selected.
|
|
- **MOSI** (aka SDO - Serial Data Out): Is used to send data from the controller (the ESP) to the peripheral device.
|
|
All devices on the bus share this line.
|
|
- **MISO** (also SDI - Serial Data In): Is used to receive data. All devices on the bus share this line.
|
|
|
|
In some cases one of **MOSI** or **MISO** does not exist as the receiving device only accepts data or sends data.
|
|
It is also possible to configure a quad SPI interface using 4 output data lines. This is required only for
|
|
use with certain components.
|
|
|
|
To set up SPI devices in ESPHome, you first need to place a top-level SPI component which defines the pins to
|
|
use for the functions described above. The **CS** pins are individually managed by the other components that
|
|
reference the ``spi`` component.
|
|
This component also accepts a list of controllers if you want to implement multiple SPI buses.
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry - single controller
|
|
spi:
|
|
clk_pin: GPIO14
|
|
mosi_pin: GPIO13
|
|
miso_pin: GPIO12
|
|
|
|
# Example configuration entry - three controllers, one using quad SPI
|
|
spi:
|
|
- id: spi_bus0
|
|
clk_pin: GPIO18
|
|
mosi_pin: GPIO23
|
|
miso_pin: GPIO19
|
|
interface: hardware
|
|
- id: spi_bus1
|
|
clk_pin: GPIO14
|
|
mosi_pin: GPIO27
|
|
miso_pin: GPIO26
|
|
interface: any
|
|
- id: quad_spi_bus
|
|
type: quad
|
|
clk_pin: GPIO47
|
|
data_pins:
|
|
- 40
|
|
- 41
|
|
- 42
|
|
- 43
|
|
|
|
Configuration variables:
|
|
------------------------
|
|
|
|
- **type** (*Optional*): Choose between ``single`` for standard 1 bit bus SPI (the default) or ``quad`` for quad SPI.
|
|
- **clk_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin used for the clock line of the SPI bus.
|
|
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this SPI hub if you need multiple SPI hubs.
|
|
- **interface** (*Optional*): Controls which hardware or software SPI implementation should be used.
|
|
Value may be one of ``any`` (default), ``software``, ``hardware``, ``spi``, ``spi2`` or ``spi3``, depending on
|
|
the type and the particular chip used. See discussion below.
|
|
|
|
For the conventional ``single`` bit bus at least one of ``miso_pin`` or ``mosi_pin`` is required.
|
|
|
|
- **mosi_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The pin used for the MOSI line of the SPI bus.
|
|
- **miso_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The pin used for the MISO line of the SPI bus.
|
|
|
|
For ``quad`` type instead specify ``data_pins``:
|
|
|
|
- **data_pins** (*Required*, :ref:`Pin Schema <config-pin_schema>`): Must be a list of exactly 4 pins to be used
|
|
for the quad SPI output data lines.
|
|
|
|
|
|
Interface selection:
|
|
--------------------
|
|
|
|
ESP32 and ESP8266 chips have several hardware SPI controller implementations - usually the first one or two
|
|
are reserved for use to access
|
|
the flash and PSRAM memories, leaving one or two user-accessible controllers. SPI controller instances configured in
|
|
ESPHome can be assigned to one of these with the ``interface:`` configuration option.
|
|
|
|
By default (``interface: any``) the first available hardware controller will be assigned, a second if available then
|
|
any further instances configured will use software mode. You can choose a specific controller with ``spi`` (meaning
|
|
the first or only available controller) or one of ``spi2`` and ``spi3`` for ESP32 chips with two available SPI
|
|
controllers. Note that SPI0 and SPI1 are typically not available, being reserved for accessing flash and PSRAM.
|
|
|
|
If the ``software`` option is chosen, or you configure more SPI instances than there are available hardware controllers,
|
|
the remaining instances will use a software implementation, which is unable to achieve data rates above a few hundred
|
|
kHz. This is acceptable for sensors or other devices not transferring large amounts of data, but will be too slow
|
|
to drive a display for example.
|
|
|
|
While the ESP32 supports the reassignment of the default SPI pins to most other GPIO pins, using the dedicated SPI pins
|
|
can improve performance and stability for certain ESP/device combinations.
|
|
ESP8266 has a more limited selection of pins that can be used; check the datasheet for more information.
|
|
|
|
Quad mode requires a hardware interface, so ``software`` and ``any`` are not permitted values.
|
|
|
|
Generic SPI device component:
|
|
-----------------------------
|
|
.. _spi_device:
|
|
|
|
Other components that depend on the SPI component will reference it, typically to communicate with specific
|
|
peripheral devices. There is also a general-purpose SPI device component that can be used to communicate with hardware not
|
|
supported by a specific component. It allows selection of the SPI mode, data_rate, CS pin and bit order.
|
|
Reads and writes on the device can be performed with lambdas. For example:
|
|
|
|
.. code-block:: yaml
|
|
|
|
spi:
|
|
clk_pin: GPIO14
|
|
mosi_pin: GPIO27
|
|
miso_pin: GPIO26
|
|
interface: hardware
|
|
|
|
spi_device:
|
|
id: spidev
|
|
cs_pin: GPIO13
|
|
data_rate: 2MHz
|
|
mode: 3
|
|
bit_order: lsb_first
|
|
|
|
on...:
|
|
then:
|
|
- lambda: !lambda |-
|
|
id(spidev).enable();
|
|
id(spidev).write_byte(0x4F);
|
|
id(spidev).disable();
|
|
|
|
|
|
Configuration variables:
|
|
------------------------
|
|
|
|
- **data_rate** (*Optional*): Set the data rate of the controller. One of ``80MHz``, ``40MHz``, ``20MHz``, ``10MHz``,
|
|
``5MHz``, ``4MHz``, ``2MHz``, ``1MHz`` (default), ``200kHz``, ``75kHz`` or ``1kHz``. A numeric value in Hz can alternatively
|
|
be specified.
|
|
- **mode** (*Optional*): Set the controller mode - one of ``mode0``, ``mode1``, ``mode2``, ``mode3``. The default is ``mode3``.
|
|
See table below for more information
|
|
- **bit_order** (*Optional*): Set the bit order - choose one of ``msb_first`` (default) or ``lsb_first``.
|
|
- **cs_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The CS pin.
|
|
|
|
SPI modes:
|
|
----------
|
|
|
|
SPI devices operate in one of four modes as per the table below. The choice of mode is dictated by the requirements
|
|
of the speficic peripheral chip.
|
|
|
|
.. csv-table:: Supported Modes
|
|
:header: "Mode", "Clock Idle Polarity", "Clock Phase", "Data shifted on", "Data sampled on"
|
|
|
|
"0", "low", "leading", "/CS activation and falling CLK", "rising CLK"
|
|
"1", "low", "trailing", "rising CLK", "falling CLK"
|
|
"2", "high", "leading", "/CS activation and rising CLK", "falling CLK"
|
|
"3", "high", "trailing", "falling CLK", "rising CLK"
|
|
|
|
|
|
|
|
See Also
|
|
--------
|
|
|
|
- :apiref:`spi/spi.h`
|
|
- :ghedit:`Edit`
|