spi_bus

[English]

spi_bus 的使用方法

  1. 创建总线：使用 spi_bus_create() 创建一个总线实例，创建时需要指定 SPI 端口号（可选 SPI2_HOST、SPI3_HOST）以及总线配置项 spi_config_t。配置项包括 MOSI、MISO、SCLK 引脚号，因为这些引脚在系统设计时已经确定，一般不在运行时切换。总线配置项还包括 max_transfer_sz，用于配置一次传输时的最大数据量，设置为 0 将使用默认值 4096。

  2. 创建设备：使用 spi_bus_device_create() 在已创建的总线实例之上创建设备，创建时需要指定总线句柄、设备的 CS 引脚号、设备运行模式、设备运行的时钟频率，SPI 传输时将根据设备的配置项动态切换模式和频率。

  3. 数据传输：使用 spi_bus_transfer_byte()、spi_bus_transfer_bytes()、spi_bus_transfer_reg16() 以及 spi_bus_transfer_reg32() 可直接进行数据的传输操作。由于 SPI 是全双工通信，因此每次传输发送和接收可以同时进行，只需要传入设备句柄、待发送数据、存放读取数据的 buf 和传输长度。

  4. 删除设备和总线：如果所有的 spi_bus 通信已经完成，可以通过删除设备和总线实例释放系统资源。可使用 spi_bus_device_delete() 分别将已创建的设备删除，然后使用 spi_bus_delete() 将总线资源删除。如果在设备未删除时删除总线，操作将不会被执行。

示例：

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);

备注

对于某些特殊应用场景，可以直接使用 spi_bus_transmit_begin() 结合 spi_transaction_t 进行操作。

已适配 IDF 版本

  • ESP-IDF v4.0 及以上版本。

API 参考

Header File

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.

参数

  • host_id – SPI peripheral that controls this bus, SPI2_HOST or SPI3_HOST

  • bus_conf – spi bus configurations details in spi_config_t

返回

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.

参数

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

返回

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.

参数

  • bus_handle – handle for spi bus operation.

  • device_conf – spi device configurations details in spi_device_config_t

返回

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.

参数

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

返回

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.

参数

  • 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.

返回

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.

参数

  • 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.

返回

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.

备注

Only call this function when spi_bus_transfer_xx do not meet the requirements

参数

  • dev_handle – handle for device operation.

  • p_trans – Description of transaction to execute

返回

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.

参数

  • 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.

返回

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.

参数

  • 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.

返回

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

提供有关此文档的反馈