Espressif ESP32-S2 User Manual

Chapter 2. API Reference
spi_transaction_t::flags are not set, the driver automatically sets the length of these phases to
default values during Device initialization.
If the lengths of the command and address phases need to be variable, declare the
struct spi_transaction_ext_t, set the flags SPI_TRANS_VARIABLE_CMD and/or
SPI_TRANS_VARIABLE_ADDR in the member spi_transaction_ext_t::base and configure the
rest of base as usual. Then the length of each phase will be equal to command_bits and address_bits set in
the struct spi_transaction_ext_t.
If the command and address phase need to be as the same number of lines as data phase, you need to
set SPI_TRANS_MULTILINE_CMD and/or SPI_TRANS_MULTILINE_ADDR to the flags member in the struct
spi_transaction_t. Also see Transaction Line Mode.
Write and Read Phases Normally, the data that needs to be transferred to or from a Device will be read from
or written to a chunk of memory indicated by the members rx_buffer and tx_buffer of the structure
spi_transaction_t. If DMA is enabled for transfers, the buffers are required to be:
1. Allocated in DMA-capable internal memory. If external PSRAM is enabled, this means using pvPortMal-
locCaps(size, MALLOC_CAP_DMA).
2. 32-bit aligned (staring from a 32-bit boundary and having a length of multiples of 4 bytes).
If these requirements are not satisfied, the transaction efficiency will be affected due to the allocation and copying of
temporary buffers.
If using more than one data lines to transmit, please set SPI_DEVICE_HALFDUPLEX flag for the member flags in the
struct spi_device_interface_config_t. And the member flags in the struct spi_transaction_t
should be set as described in Transaction Line Mode.
Bus Acquiring Sometimes you might want to send SPI transactions exclusively and continuously so that it
takes as little time as possible. For this, you can use bus acquiring, which helps to suspend transactions (both
polling or interrupt) to other devices until the bus is released. To acquire and release a bus, use the functions
spi_device_acquire_bus() and spi_device_release_bus().
Driver Usage
• Initialize an SPI bus by calling the function spi_bus_initialize(). Make sure to set the correct I/O
pins in the struct spi_bus_config_t. Set the signals that are not needed to -1.
• Register a Device connected to the bus with the driver by calling the function spi_bus_add_device().
Make sure to configure any timing requirements the device might need with the parameter dev_config.
You should now have obtained the Device’s handle which will be used when sending a transaction to it.
• To interact with the Device, fill one or more spi_transaction_t structs with any transaction parameters
required. Then send the structs either using a polling transaction or an interrupt transaction:
– Interrupt Either queue all transactions by calling the function spi_device_queue_trans() and,
at a later time, query the result using the function spi_device_get_trans_result(), or
handle all requests synchronously by feeding them into spi_device_transmit().
– Polling Call the function spi_device_polling_transmit() to send polling transactions.
Alternatively, if you want to insert something in between, send the transactions by using
spi_device_polling_start() and spi_device_polling_end().
• (Optional) To perform back-to-back transactions with a Device, call the function
spi_device_acquire_bus() before sending transactions and spi_device_release_bus()
after the transactions have been sent.
• (Optional) To unload the driver for a certain Device, call spi_bus_remove_device() with the Device
handle as an argument.
• (Optional) To remove the driver for a bus, make sure no more drivers are attached and call
spi_bus_free().
The example code for the SPI master driver can be found in the peripherals/spi_master directory of ESP-IDF exam-
ples.
Espressif Systems 368
Submit Document Feedback
Release v4.4

Espressif ESP32-S2 Specifications

General

Brand	Espressif
Model	ESP32-S2
Category	Single board computers
Language	English