SPI

API Reference

Header File

Functions

esp_err_t spi_get_clk_div(spi_host_t host, spi_clk_div_t *clk_div)

Get the SPI clock division factor.

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Parameter error

  • ESP_FAIL spi has not been initialized yet

Parameters

  • host: SPI peripheral number

    • CSPI_HOST SPI0

    • HSPI_HOST SPI1

  • clk_div: Pointer to accept clock division factor

esp_err_t spi_get_intr_enable(spi_host_t host, spi_intr_enable_t *intr_enable)

Get SPI Interrupt Enable.

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Parameter error

  • ESP_FAIL spi has not been initialized yet

Parameters

  • host: SPI peripheral number

    • CSPI_HOST SPI0

    • HSPI_HOST SPI1

  • intr_enable: Pointer to accept interrupt enable

esp_err_t spi_get_mode(spi_host_t host, spi_mode_t *mode)

Get SPI working mode.

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Parameter error

  • ESP_FAIL spi has not been initialized yet

Parameters

  • host: SPI peripheral number

    • CSPI_HOST SPI0

    • HSPI_HOST SPI1

  • mode: Pointer to accept working mode

esp_err_t spi_get_interface(spi_host_t host, spi_interface_t *interface)

Get SPI bus interface configuration.

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Parameter error

  • ESP_FAIL spi has not been initialized yet

Parameters

  • host: SPI peripheral number

    • CSPI_HOST SPI0

    • HSPI_HOST SPI1

  • interface: Pointer to accept bus interface configuration

esp_err_t spi_get_event_callback(spi_host_t host, spi_event_callback_t *event_cb)

Get the SPI event callback function.

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Parameter error

  • ESP_FAIL spi has not been initialized yet

Parameters

  • host: SPI peripheral number

    • CSPI_HOST SPI0

    • HSPI_HOST SPI1

  • event_cb: Pointer to accept event callback function

esp_err_t spi_set_clk_div(spi_host_t host, spi_clk_div_t *clk_div)

Set the SPI clock division factor.

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Parameter error

  • ESP_FAIL spi has not been initialized yet

Parameters

  • host: SPI peripheral number

    • CSPI_HOST SPI0

    • HSPI_HOST SPI1

  • clk_div: Pointer to deliver clock division factor

esp_err_t spi_set_intr_enable(spi_host_t host, spi_intr_enable_t *intr_enable)

Set SPI interrupt enable.

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Parameter error

  • ESP_FAIL spi has not been initialized yet

Parameters

  • host: SPI peripheral number

    • CSPI_HOST SPI0

    • HSPI_HOST SPI1

  • intr_enable: Pointer to deliver interrupt enable

esp_err_t spi_set_mode(spi_host_t host, spi_mode_t *mode)

Set the SPI mode of operation.

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Parameter error

  • ESP_FAIL spi has not been initialized yet

Parameters

  • host: SPI peripheral number

    • CSPI_HOST SPI0

    • HSPI_HOST SPI1

  • mode: Pointer to deliver working mode

esp_err_t spi_get_dummy(spi_host_t host, uint16_t *bitlen)

Get SPI dummy bitlen.

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Parameter error

  • ESP_FAIL spi has not been initialized yet

Parameters

  • host: SPI peripheral number

    • CSPI_HOST SPI0

    • HSPI_HOST SPI1

  • bitlen: Pointer to accept dummy bitlen

esp_err_t spi_set_dummy(spi_host_t host, uint16_t *bitlen)

Set SPI dummy bitlen.

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Parameter error

  • ESP_FAIL spi has not been initialized yet

Parameters

  • host: SPI peripheral number

    • CSPI_HOST SPI0

    • HSPI_HOST SPI1

  • bitlen: Pointer to deliver dummy bitlen

esp_err_t spi_set_interface(spi_host_t host, spi_interface_t *interface)

Set SPI bus interface configuration.

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Parameter error

  • ESP_FAIL spi has not been initialized yet

Parameters

  • host: SPI peripheral number

    • CSPI_HOST SPI0

    • HSPI_HOST SPI1

  • interface: Pointer to deliver bus interface configuration

esp_err_t spi_set_event_callback(spi_host_t host, spi_event_callback_t *event_cb)

Set the SPI event callback function.

Note

This event_cb will be called from an ISR. So there is a stack size limit (configurable as “ISR stack size” in menuconfig). This limit is smaller compared to a global SPI interrupt handler due to the additional level of indirection.

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Parameter error

  • ESP_FAIL spi has not been initialized yet

Parameters

  • host: SPI peripheral number

    • CSPI_HOST SPI0

    • HSPI_HOST SPI1

  • event_cb: Pointer to deliver event callback function

esp_err_t spi_slave_get_status(spi_host_t host, uint32_t *status)

Get SPI slave wr_status register.

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Parameter error

  • ESP_FAIL spi has not been initialized yet

Parameters

  • host: SPI peripheral number

    • CSPI_HOST SPI0

    • HSPI_HOST SPI1

  • status: Pointer to accept wr_status register

esp_err_t spi_slave_set_status(spi_host_t host, uint32_t *status)

Set SPI slave rd_status register.

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Parameter error

  • ESP_FAIL spi has not been initialized yet

Parameters

  • host: SPI peripheral number

    • CSPI_HOST SPI0

    • HSPI_HOST SPI1

  • status: Pointer to deliver rd_status register

esp_err_t spi_trans(spi_host_t host, spi_trans_t *trans)

SPI data transfer function.

Note

If the bit of the corresponding phase in the transmission parameter is 0, its data will not work. For example: trans.bits.cmd = 0, cmd will not be transmitted

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Parameter error

  • ESP_FAIL spi has not been initialized yet

Parameters

  • host: SPI peripheral number

    • CSPI_HOST SPI0

    • HSPI_HOST SPI1

  • trans: Pointer to transmission parameter structure

esp_err_t spi_deinit(spi_host_t host)

Deinit the spi.

Return

  • ESP_OK Success

  • ESP_FAIL spi has not been initialized yet

Parameters

  • host: SPI peripheral number

    • CSPI_HOST SPI0

    • HSPI_HOST SPI1

esp_err_t spi_init(spi_host_t host, spi_config_t *config)

Initialize the spi.

Note

SPI0 has been used by FLASH and cannot be used by the user temporarily.

Return

  • ESP_OK Success

  • ESP_ERR_NO_MEM malloc fail

  • ESP_FAIL spi has been initialized

Parameters

  • host: SPI peripheral number

    • CSPI_HOST SPI0

    • HSPI_HOST SPI1

  • config: Pointer to deliver initialize configuration parameter

Unions

union spi_intr_enable_t
#include <spi.h>

SPI interrupt enable union type definition.

Public Members

uint32_t read_buffer : 1

configurate intterrupt to enable reading

uint32_t write_buffer : 1

configurate intterrupt to enable writing

uint32_t read_status : 1

configurate intterrupt to enable reading status

uint32_t write_status : 1

configurate intterrupt to enable writing status

uint32_t trans_done : 1

configurate intterrupt to enable transmission done

uint32_t reserved5 : 27

reserved

struct spi_intr_enable_t::[anonymous] [anonymous]

not filled

uint32_t val

union fill

union spi_interface_t
#include <spi.h>

SPI bus interface parameter union type definition.

Public Members

uint32_t cpol : 1

Clock Polarity

uint32_t cpha : 1

Clock Phase

uint32_t bit_tx_order : 1

Tx bit order

uint32_t bit_rx_order : 1

Rx bit order

uint32_t byte_tx_order : 1

Tx byte order

uint32_t byte_rx_order : 1

Rx byte order

uint32_t mosi_en : 1

MOSI line enable

uint32_t miso_en : 1

MISO line enable

uint32_t cs_en : 1

CS line enable

uint32_t reserved9 : 23

resserved

struct spi_interface_t::[anonymous] [anonymous]

not filled

uint32_t val

union fill

Structures

struct spi_trans_t

SPI transmission parameter structure type definition.

Public Members

uint16_t *cmd

SPI transmission command

uint32_t *addr

SPI transmission address

uint32_t *mosi

SPI transmission MOSI buffer, in order to improve the transmission efficiency, it is recommended that the external incoming data is (uint32_t *) type data, do not use other type data.

uint32_t *miso

SPI transmission MISO buffer, in order to improve the transmission efficiency, it is recommended that the external incoming data is (uint32_t *) type data, do not use other type data.

uint32_t cmd : 5

SPI transmission command bits

uint32_t addr : 7

SPI transmission address bits

uint32_t mosi : 10

SPI transmission MOSI buffer bits

uint32_t miso : 10

SPI transmission MISO buffer bits

uint32_t val

union fill

union spi_trans_t::[anonymous] bits

SPI transmission packet members’ bits

struct spi_config_t

SPI initialization parameter structure type definition.

Public Members

spi_interface_t interface

SPI bus interface

spi_intr_enable_t intr_enable

check if enable SPI interrupt

spi_event_callback_t event_cb

SPI interrupt event callback

spi_mode_t mode

SPI mode

spi_clk_div_t clk_div

SPI clock divider

Macros

SPI_NUM_MAX
SPI_CPOL_LOW
SPI_CPOL_HIGH
SPI_CPHA_LOW
SPI_CPHA_HIGH
SPI_BIT_ORDER_MSB_FIRST
SPI_BIT_ORDER_LSB_FIRST
SPI_BYTE_ORDER_MSB_FIRST
SPI_BYTE_ORDER_LSB_FIRST
SPI_DEFAULT_INTERFACE
SPI_MASTER_DEFAULT_INTR_ENABLE
SPI_SLAVE_DEFAULT_INTR_ENABLE
SPI_INIT_EVENT
SPI_TRANS_START_EVENT
SPI_TRANS_DONE_EVENT
SPI_DEINIT_EVENT
SPI_MASTER_WRITE_DATA_TO_SLAVE_CMD
SPI_MASTER_READ_DATA_FROM_SLAVE_CMD
SPI_MASTER_WRITE_STATUS_TO_SLAVE_CMD
SPI_MASTER_READ_STATUS_FROM_SLAVE_CMD
SPI_SLV_RD_BUF_DONE
SPI_SLV_WR_BUF_DONE
SPI_SLV_RD_STA_DONE
SPI_SLV_WR_STA_DONE
SPI_TRANS_DONE

Type Definitions

typedef void (*spi_event_callback_t)(int event, void *arg)

Enumerations

enum spi_host_t

SPI peripheral enumeration.

Note

ESP8266 has two hardware SPI, CSPI and HSPI. Currently, HSPI can be used arbitrarily.

Values:

CSPI_HOST = 0
HSPI_HOST
enum spi_clk_div_t

SPI clock division factor enumeration.

Values:

SPI_2MHz_DIV = 40
SPI_4MHz_DIV = 20
SPI_5MHz_DIV = 16
SPI_8MHz_DIV = 10
SPI_10MHz_DIV = 8
SPI_16MHz_DIV = 5
SPI_20MHz_DIV = 4
SPI_40MHz_DIV = 2
SPI_80MHz_DIV = 1
enum spi_mode_t

SPI working mode enumeration.

Values:

SPI_MASTER_MODE
SPI_SLAVE_MODE