esphome-docs/components/spi.rst
BerlinJoker afed1384bf
add note about default SPI pin usage for stability/performance (#2921)
The current SPI documentation doesn't mention that there is a difference in how ESPs work depending on which GPIOs are chosen for the SPI setup. While in theory all regular GPIOs can be used (and might work for a lot of people/setups), using the dedicated default SPI pins can be the missing puzzle piece for unstable ESP/device combinations

https://techoverflow.net/2021/07/26/what-is-the-spi-pinout-of-the-esp32-esp-wroom-32/

https://randomnerdtutorials.com/esp8266-pinout-reference-gpios/
2023-05-15 20:30:58 +02:00

54 lines
2.4 KiB
ReStructuredText

.. _spi:
SPI Bus
=======
.. seo::
:description: Instructions for setting up an SPI bus in ESPHome
:image: spi.svg
:keywords: SPI
SPI is a very common high-speed protocol for a lot of devices. 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** (also DIN): Is used to send data from the master (the ESP) to the receiving device. All devices on the bus can
share this line.
- **MISO** (also DOUT): Is used to receive data. All devices on the bus can
share this line.
In some cases one of **MOSI** or **MISO** do not exist as the receiving device only accepts data or sends data.
To set up SPI devices in ESPHome, you first need to place a top-level SPI hub like below which defines what pins to
use for the functions described above. The **CS** pins are then individually managed by the components. The ``spi:``
component also accepts a list of buses if you want to have multiple SPI buses with your ESP (though this should
rarely be necessary, as the SPI bus can be shared by the devices).
.. code-block:: yaml
# Example configuration entry
spi:
clk_pin: GPIO14
mosi_pin: GPIO13
miso_pin: GPIO12
Configuration variables:
------------------------
- **clk_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin used for the clock line of the SPI bus.
- **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.
- **force_sw** (*Optional*, boolean): Whether software implementation should be used even if hardware one is available.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this SPI hub if you need multiple SPI hubs.
**Please note:** while both ESP8266 and ESP32 support the reassignment of the default SPI pins to other GPIO pins, using the dedicated SPI pins can improve performance and stability for certain ESP/device combinations.
See Also
--------
- :apiref:`spi/spi.h`
- :ghedit:`Edit`