spi_bus

How to Use spi_bus

Create a bus: use spi_bus_create() to create a bus object. During the process, you need to specify the SPI port number (can choose between SPI2_HOST and SPI3_HOST) and the bus configuration option spi_config_t, which includes the pin numbers of MOSI, MISO and SCLK, as these are determined when the system is designed and normally will not be changed at runtime. The bus configuration option also includes max_transfer_sz to configure the maximum data size during a transmission. When max_transfer_sz is configured to 0, it means the maximum size will be the default value 4096.
Create a device: use spi_bus_device_create() to create a device on the bus object created in the first step. During the process, you need to specify the bus handle, the CS pin number of the device, device operation mode, the clock frequency when the device is running. The device mode and frequency will be dynamically changed during SPI transmissions based on device configuration options.
Data transmission: use spi_bus_transfer_byte(), spi_bus_transfer_bytes(), spi_bus_transfer_reg16() or spi_bus_transfer_reg32() to transfer data directly. Data send and receive can be operated at the same time since SPI communication is a full-duplex communication. During the process, you only need to pass in the device handle, data to be transmitted, a buffer to hold the read data, transmission length, etc.
Delete device and bus: if all spi_bus communication has been completed, you can free your system resources by deleting devices and bus objects. Use spi_bus_device_delete() to delete created devices respectively, then use spi_bus_delete() to delete bus resources. If the bus is deleted with the device not being deleted yet, this operation will not take effect.

Example:

spi_bus_handle_t bus_handle = NULL;
spi_bus_device_handle_t device_handle = NULL;
uint8_t data8_in = 0;
uint8_t data8_out = 0xff;
uint16_t data16_in = 0;
uint32_t data32_in = 0;

spi_config_t bus_conf = {
    .miso_io_num = 19,
    .mosi_io_num = 23,
    .sclk_io_num = 18,
}; // spi_bus configurations

spi_device_config_t device_conf = {
    .cs_io_num = 19,
    .mode = 0,
    .clock_speed_hz = 20 * 1000 * 1000,
}; // spi_device configurations

bus_handle = spi_bus_create(SPI2_HOST, &bus_conf); // create spi bus
device_handle = spi_bus_device_create(bus_handle, &device_conf); // create spi device

spi_bus_transfer_bytes(device_handle, &data8_out, &data8_in, 1); // transfer 1 byte with spi device
spi_bus_transfer_bytes(device_handle, NULL, &data8_in, 1); // only read 1 byte with spi device
spi_bus_transfer_bytes(device_handle, &data8_out, NULL, 1); // only write 1 byte with spi device
spi_bus_transfer_reg16(device_handle, 0x1020, &data16_in); // transfer 16-bit value with the device
spi_bus_transfer_reg32(device_handle, 0x10203040, &data32_in); // transfer 32-bit value with the device

spi_bus_device_delete(&device_handle);
spi_bus_delete(&bus_handle);

Note

For some special application scenarios, you can operate using spi_bus_transmit_begin() combined with spi_transaction_t directly.

Adapted IDF Versions

ESP-IDF v4.0 and later versions.

API Reference

Header File

components/spi_bus/include/spi_bus.h

Functions

spi_bus_handle_t spi_bus_create(spi_host_device_t host_id, const spi_config_t *bus_conf)

Create and initialize a spi bus and return the spi bus handle.

Parameters

host_id – SPI peripheral that controls this bus, SPI2_HOST or SPI3_HOST
bus_conf – spi bus configurations details in spi_config_t

Returns

spi_bus_handle_t handle for spi bus operation, NULL if failed.

esp_err_t spi_bus_delete(spi_bus_handle_t *p_bus_handle)

Deinitialize and delete the spi bus.

Parameters

p_bus_handle – pointer to spi bus handle, if delete succeed handle will set to NULL.

Returns

esp_err_t

ESP_ERR_INVALID_ARG if parameter is invalid
ESP_FAIL Fail
ESP_OK Success

spi_bus_device_handle_t spi_bus_device_create(spi_bus_handle_t bus_handle, const spi_device_config_t *device_conf)

Create and add a device on the spi bus.

Parameters

bus_handle – handle for spi bus operation.
device_conf – spi device configurations details in spi_device_config_t

Returns

spi_bus_device_handle_t handle for device operation, NULL if failed.

esp_err_t spi_bus_device_delete(spi_bus_device_handle_t *p_dev_handle)

Deinitialize and remove the device from spi bus.

Parameters

p_dev_handle – pointer to device handle, if delete succeed handle will set to NULL.

Returns

esp_err_t

ESP_ERR_INVALID_ARG if parameter is invalid
ESP_FAIL Fail
ESP_OK Success

esp_err_t spi_bus_transfer_byte(spi_bus_device_handle_t dev_handle, uint8_t data_out, uint8_t *data_in)

Transfer one byte with the device.

Parameters

dev_handle – handle for device operation.
data_out – data will send to device.
data_in – pointer to receive buffer, set NULL to skip receive phase.

Returns

esp_err_t

ESP_ERR_INVALID_ARG if parameter is invalid
ESP_ERR_TIMEOUT if bus is busy
ESP_OK on success

esp_err_t spi_bus_transfer_bytes(spi_bus_device_handle_t dev_handle, const uint8_t *data_out, uint8_t *data_in, uint32_t data_len)

Transfer multi-bytes with the device.

Parameters

dev_handle – handle for device operation.
data_out – pointer to sent buffer, set NULL to skip sent phase.
data_in – pointer to receive buffer, set NULL to skip receive phase.
data_len – number of bytes will transfer.

Returns

esp_err_t

ESP_ERR_INVALID_ARG if parameter is invalid
ESP_ERR_TIMEOUT if bus is busy
ESP_OK on success

esp_err_t spi_bus_transmit_begin(spi_bus_device_handle_t dev_handle, spi_transaction_t *p_trans)

Send a polling transaction, wait for it to complete, and return the result.

Note

Only call this function when spi_bus_transfer_xx do not meet the requirements

Parameters

dev_handle – handle for device operation.
p_trans – Description of transaction to execute

Returns

esp_err_t

ESP_ERR_INVALID_ARG if parameter is invalid
ESP_ERR_TIMEOUT if bus is busy
ESP_OK on success

esp_err_t spi_bus_transfer_reg16(spi_bus_device_handle_t dev_handle, uint16_t data_out, uint16_t *data_in)

Transfer one 16-bit value with the device. using msb by default. For example 0x1234, 0x12 will send first then 0x34.

Parameters

dev_handle – handle for device operation.
data_out – data will send to device.
data_in – pointer to receive buffer, set NULL to skip receive phase.

Returns

esp_err_t

ESP_ERR_INVALID_ARG if parameter is invalid
ESP_ERR_TIMEOUT if bus is busy
ESP_OK on success

esp_err_t spi_bus_transfer_reg32(spi_bus_device_handle_t dev_handle, uint32_t data_out, uint32_t *data_in)

Transfer one 32-bit value with the device. using msb by default. For example 0x12345678, 0x12 will send first, 0x78 will send in the end.

Parameters

dev_handle – handle for device operation.
data_out – data will send to device.
data_in – pointer to receive buffer, set NULL to skip receive phase.

Returns

esp_err_t

ESP_ERR_INVALID_ARG if parameter is invalid
ESP_ERR_TIMEOUT if bus is busy
ESP_OK on success

Structures

struct spi_config_t

spi bus initialization parameters.

Public Members

gpio_num_t miso_io_num: GPIO pin for Master In Slave Out (=spi_q) signal, or -1 if not used.

gpio_num_t mosi_io_num: GPIO pin for Master Out Slave In (=spi_d) signal, or -1 if not used.

gpio_num_t sclk_io_num: GPIO pin for Spi CLocK signal, or -1 if not used

int max_transfer_sz: <Maximum length of bytes available to send, if < 4096, 4096 will be set

struct spi_device_config_t

spi device initialization parameters.

Public Members

gpio_num_t cs_io_num: GPIO pin to select this device (CS), or -1 if not used

uint8_t mode: modes (0,1,2,3) that correspond to the four possible clocking configurations

int clock_speed_hz: spi clock speed, divisors of 80MHz, in Hz. See `SPI_MASTER_FREQ_*

Macros

NULL_SPI_CS_PIN: set cs_io_num to NULL_SPI_CS_PIN if spi device has no CP pin

Type Definitions

typedef void *spi_bus_handle_t: spi bus handle

typedef void *spi_bus_device_handle_t: spi device handle

Provide feedback about this document