ESP Serial Slave Link

Overview

Espressif provides several chips that can work as slaves. These slave devices rely on some common buses, and have their own communication protocols over those buses. The esp_serial_slave_link component is designed for the master to communicate with ESP slave devices through those protocols over the bus drivers.

After an esp_serial_slave_link device is initialized properly, the application can use it to communicate with the ESP slave devices conveniently.

For more details about ESP32 SDIO slave protocol, see document Communication with ESP SDIO Slave.

Terminology

• ESSL: Abbreviation for ESP Serial Slave Link, the component described by this document.

• Master: The device running the esp_serial_slave_link component.

• ESSL device: a virtual device on the master associated with an ESP slave device. The device context has the knowledge of the slave protocol above the bus, relying on some bus drivers to communicate with the slave.

• ESSL device handle: a handle to ESSL device context containing the configuration, status and data required by the ESSL component. The context stores the driver configurations, communication state, data shared by master and slave, etc.

  The context should be initialized before it is used, and get deinitialized if not used any more. The master application operates on the ESSL device through this handle.

• ESP slave: the slave device connected to the bus, which ESSL component is designed to communicate with.

• Bus: The bus over which the master and the slave communicate with each other.

• Slave protocol: The special communication protocol specified by Espressif HW/SW over the bus.

• TX buffer num: a counter, which is on the slave and can be read by the master, indicates the accumulated buffer numbers that the slave has loaded to the hardware to receive data from the master.

• RX data size: a counter, which is on the slave and can be read by the master, indicates the accumulated data size that the slave has loaded to the hardware to send to the master.

Services provided by ESP slave

There are some common services provided by the Espressif slaves:

1. Tohost Interrupts: The slave can inform the master about certain events by the interrupt line.

2. Frhost Interrupts: The master can inform the slave about certain events.

3. Tx FIFO (master to slave): the slave can send data in stream to the master. The SDIO slave can also indicate it has new data to send to master by the interrupt line.

   The slave updates the TX buffer num to inform the master how much data it can receive, and the master then read the TX buffer num, and take off the used buffer number to know how many buffers are remaining.

4. Rx FIFO (slave to master): the slave can receive data from the master in units of receiving buffers.

   The slave updates the RX data size to inform the master how much data it has prepared to send, and then the master read the data size, and take off the data length it has already received to know how many data is remaining.

5. Shared registers: the master can read some part of the registers on the slave, and also write these registers to let the slave read.

Initialization of ESP SDIO Slave Link

The ESP SDIO slave link (ESSL SDIO) devices relies on the sdmmc component. The ESSL device should be initialized as below:

1. Initialize a sdmmc card (see :doc:` Document of SDMMC driver </api-reference/storage/sdmmc>`) structure.

2. Call sdmmc_card_init() to initialize the card.

3. Initialize the ESSL device with essl_sdio_config_t. The card member should be the sdmmc_card_t got in step 2, and the recv_buffer_size member should be filled correctly according to pre-negotiated value.

4. Call essl_init() to do initialization of the SDIO part.

5. Call essl_wait_for_ready() to wait for the slave to be ready.

APIs

After the initialization process above is performed, you can call the APIs below to make use of the services provided by the slave:

Interrupts

1. Call essl_get_intr_ena() to know which events will trigger the interrupts to the master.

2. Call essl_set_intr_ena() to set the events that will trigger interrupts to the master.

3. Call essl_wait_int() to wait until interrupt from the slave, or timeout.

4. When interrupt is triggered, call essl_get_intr() to know which events are active, and call essl_clear_intr() to clear them.

5. Call essl_send_slave_intr() to trigger general purpose interrupt of the slave.

TX FIFO

1. Call essl_get_tx_buffer_num() to know how many buffers the slave has prepared to receive data from the master. This is optional. The master will poll tx_buffer_num when it try to send packets to the slave, until the slave has enough buffer or timeout.

2. Call essl_send_paket() to send data to the slave.

RX FIFO

1. Call essl_get_rx_data_size() to know how many data the slave has prepared to send to the master. This is optional. When the master tries to receive data from the slave, it will update the rx_data_size for once, if the current rx_data_size is shorter than the buffer size the master prepared to receive. And it may poll the rx_data_size if the rx_dat_size keeps 0, until timeout.

2. Call essl_get_packet() to receive data from the slave.

Reset counters (Optional)

Call essl_reset_cnt() to reset the internal counter if you find the slave has reset its counter.

Application Example

The example below shows how ESP32 SDIO host and slave communicate with each other. The host use the ESSL SDIO.

peripherals/sdio.

Please refer to the specific example README.md for details.

API Reference

Header File

• esp_serial_slave_link/include/esp_serial_slave_link/essl.h

Functions

esp_err_t essl_init(essl_handle_t handle, uint32_t wait_ms)

Initialize the slave.

Return

ESP_OK if success, or other value returned from lower layer init.

Parameters

• handle: Handle of a essl device.

• wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.

esp_err_t essl_wait_for_ready(essl_handle_t handle, uint32_t wait_ms)

Wait for interrupt of a ESP32 slave device.

Return

• ESP_OK if success

• One of the error codes from SDMMC host controller

Parameters

• handle: Handle of a essl device.

• wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.

esp_err_t essl_get_tx_buffer_num(essl_handle_t handle, uint32_t *out_tx_num, uint32_t wait_ms)

Get buffer num for the host to send data to the slave. The buffers are size of buffer_size.

Return

• ESP_OK Success

• One of the error codes from SDMMC host controller

Parameters

• handle: Handle of a essl device.

• out_tx_num: Output of buffer num that host can send data to ESP32 slave.

• wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.

esp_err_t essl_get_rx_data_size(essl_handle_t handle, uint32_t *out_rx_size, uint32_t wait_ms)

Get amount of data the ESP32 slave preparing to send to host.

Return

• ESP_OK Success

• One of the error codes from SDMMC host controller

Parameters

• handle: Handle of a essl device.

• out_rx_size: Output of data size to read from slave.

• wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.

esp_err_t essl_reset_cnt(essl_handle_t handle)

Reset the counters of this component. Usually you don’t need to do this unless you know the slave is reset.

Parameters

• handle: Handle of a essl device.

esp_err_t essl_send_packet(essl_handle_t handle, const void *start, size_t length, uint32_t wait_ms)

Send a packet to the ESP32 slave. The slave receive the packet into buffers whose size is buffer_size (configured during initialization).

Return

• ESP_OK Success

• ESP_ERR_TIMEOUT No buffer to use, or error ftrom SDMMC host controller

• One of the error codes from SDMMC host controller

Parameters

• handle: Handle of a essl device.

• start: Start address of the packet to send

• length: Length of data to send, if the packet is over-size, the it will be divided into blocks and hold into different buffers automatically.

• wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.

esp_err_t essl_get_packet(essl_handle_t handle, void *out_data, size_t size, size_t *out_length, uint32_t wait_ms)

Get a packet from ESP32 slave.

Return

• ESP_OK Success, all the data are read from the slave.

• ESP_ERR_NOT_FINISHED Read success, while there’re data remaining.

• One of the error codes from SDMMC host controller

Parameters

• handle: Handle of a essl device.

• [out] out_data: Data output address

• size: The size of the output buffer, if the buffer is smaller than the size of data to receive from slave, the driver returns ESP_ERR_NOT_FINISHED

• [out] out_length: Output of length the data actually received from slave.

• wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.

esp_err_t essl_write_reg(essl_handle_t handle, uint8_t addr, uint8_t value, uint8_t *value_o, uint32_t wait_ms)

Write general purpose R/W registers (8-bit) of ESP32 slave.

Note

sdio 28-31 are reserved, the lower API helps to skip.

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Address not valid.

• One of the error codes from SDMMC host controller

Parameters

• handle: Handle of a essl device.

• addr: Address of register to write. Valid address: 0-59.

• value: Value to write to the register.

• value_o: Output of the returned written value.

• wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.

esp_err_t essl_read_reg(essl_handle_t handle, uint8_t add, uint8_t *value_o, uint32_t wait_ms)

Read general purpose R/W registers (8-bit) of ESP32 slave.

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Address not valid.

• One of the error codes from SDMMC host controller

Parameters

• handle: Handle of a essl device.

• add: Address of register to read. Valid address: 0-27, 32-63 (28-31 reserved, return interrupt bits on read).

• value_o: Output value read from the register.

• wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.

esp_err_t essl_wait_int(essl_handle_t handle, uint32_t wait_ms)

wait for an interrupt of the slave

Return

• ESP_ERR_NOT_SUPPORTED Currently our driver doesnot support SDIO with SPI interface.

• ESP_OK If interrupt triggered.

• ESP_ERR_TIMEOUT No interrupts before timeout.

Parameters

• handle: Handle of a essl device.

• wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.

esp_err_t essl_clear_intr(essl_handle_t handle, uint32_t intr_mask, uint32_t wait_ms)

Clear interrupt bits of ESP32 slave. All the bits set in the mask will be cleared, while other bits will stay the same.

Return

• ESP_OK Success

• One of the error codes from SDMMC host controller

Parameters

• handle: Handle of a essl device.

• intr_mask: Mask of interrupt bits to clear.

• wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.

esp_err_t essl_get_intr(essl_handle_t handle, uint32_t *intr_raw, uint32_t *intr_st, uint32_t wait_ms)

Get interrupt bits of ESP32 slave.

Return

• ESP_OK Success

• ESP_INVALID_ARG if both intr_raw and intr_st are NULL.

• One of the error codes from SDMMC host controller

Parameters

• handle: Handle of a essl device.

• intr_raw: Output of the raw interrupt bits. Set to NULL if only masked bits are read.

• intr_st: Output of the masked interrupt bits. set to NULL if only raw bits are read.

• wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.

esp_err_t essl_set_intr_ena(essl_handle_t handle, uint32_t ena_mask, uint32_t wait_ms)

Set interrupt enable bits of ESP32 slave. The slave only sends interrupt on the line when there is a bit both the raw status and the enable are set.

Return

• ESP_OK Success

• One of the error codes from SDMMC host controller

Parameters

• handle: Handle of a essl device.

• ena_mask: Mask of the interrupt bits to enable.

• wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.

esp_err_t essl_get_intr_ena(essl_handle_t handle, uint32_t *ena_mask_o, uint32_t wait_ms)

Get interrupt enable bits of ESP32 slave.

Return

• ESP_OK Success

• One of the error codes from SDMMC host controller

Parameters

• handle: Handle of a essl device.

• ena_mask_o: Output of interrupt bit enable mask.

• wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.

esp_err_t essl_send_slave_intr(essl_handle_t handle, uint32_t intr_mask, uint32_t wait_ms)

Send interrupts to slave. Each bit of the interrupt will be triggered.

Return

• ESP_OK Success

• One of the error codes from SDMMC host controller

Parameters

• handle: Handle of a essl device.

• intr_mask: Mask of interrupt bits to send to slave.

• wait_ms: Millisecond to wait before timeout, will not wait at all if set to 0-9.

Macros

ESP_ERR_NOT_FINISHED

There is still remaining data.

Type Definitions

typedef struct essl_dev_t *essl_handle_t

Handle of an ESSL device.

Header File

• esp_serial_slave_link/include/esp_serial_slave_link/essl_sdio.h

Functions

esp_err_t essl_sdio_init_dev(essl_handle_t *out_handle, const essl_sdio_config_t *config)

Initialize the ESSL SDIO device and get its handle.

Return

• ESP_OK: on success

• ESP_ERR_NO_MEM: memory exhausted.

Parameters

• out_handle: Output of the handle.

• config: Configuration for the ESSL SDIO device.

esp_err_t essl_sdio_deinit_dev(essl_handle_t handle)

Deinitialize and free the space used by the ESSL SDIO device.

Return

• ESP_OK: on success

• ESP_ERR_INVALID_ARG: wrong handle passed

Parameters

• handle: Handle of the ESSL SDIO device to deinit.

Structures

struct essl_sdio_config_t

Configuration for the essl SDIO device.

Public Members

sdmmc_card_t *card

The initialized sdmmc card pointer of the slave.

int recv_buffer_size

The pre-negotiated recv buffer size used by both the host and the slave.

Provide feedback about this document