Mistake on this page?
Report an issue in GitHub or email us
Public Member Functions
SPI Class Reference

A SPI Master, used for communicating with SPI slave devices. More...

#include <SPI.h>

Inheritance diagram for SPI:
NonCopyable< SPI >

Public Member Functions

 SPI (PinName mosi, PinName miso, PinName sclk, PinName ssel=NC)
 Create a SPI master connected to the specified pins. More...
 
 SPI (PinName mosi, PinName miso, PinName sclk, PinName ssel, use_gpio_ssel_t)
 Create a SPI master connected to the specified pins. More...
 
 SPI (const spi_pinmap_t &static_pinmap)
 Create a SPI master connected to the specified pins. More...
 
 SPI (const spi_pinmap_t &static_pinmap, PinName ssel)
 Create a SPI master connected to the specified pins. More...
 
void format (int bits, int mode=0)
 Configure the data transmission format. More...
 
void frequency (int hz=1000000)
 Set the SPI bus clock frequency. More...
 
virtual int write (int value)
 Write to the SPI Slave and return the response. More...
 
virtual int write (const char *tx_buffer, int tx_length, char *rx_buffer, int rx_length)
 Write to the SPI Slave and obtain the response. More...
 
virtual void lock (void)
 Acquire exclusive access to this SPI bus. More...
 
virtual void unlock (void)
 Release exclusive access to this SPI bus. More...
 
void select (void)
 Assert the Slave Select line, acquiring exclusive access to this SPI bus. More...
 
void deselect (void)
 Deassert the Slave Select line, releasing exclusive access to this SPI bus. More...
 
void set_default_write_value (char data)
 Set default write data. More...
 
template<typename Type >
int transfer (const Type *tx_buffer, int tx_length, Type *rx_buffer, int rx_length, const event_callback_t &callback, int event=SPI_EVENT_COMPLETE)
 Start non-blocking SPI transfer using 8bit buffers. More...
 
void abort_transfer ()
 Abort the on-going SPI transfer, and continue with transfers in the queue, if any. More...
 
void clear_transfer_buffer ()
 Clear the queue of transfers. More...
 
void abort_all_transfers ()
 Clear the queue of transfers and abort the on-going transfer. More...
 
int set_dma_usage (DMAUsage usage)
 Configure DMA usage suggestion for non-blocking transfers. More...
 

Detailed Description

A SPI Master, used for communicating with SPI slave devices.

The default format is set to 8-bits, mode 0, and a clock frequency of 1MHz.

Most SPI devices will also require Chip Select and Reset signals. These can be controlled using DigitalOut pins.

Note
Synchronization level: Thread safe

Example of how to send a byte to a SPI slave and record the response:

#include "mbed.h"
SPI device(SPI_MOSI, SPI_MISO, SPI_SCLK)
DigitalOut chip_select(SPI_CS);
int main() {
device.lock();
chip_select = 0;
int response = device.write(0xFF);
chip_select = 1;
device.unlock();
}

Example using hardware Chip Select line:

#include "mbed.h"
SPI device(SPI_MOSI, SPI_MISO, SPI_SCLK, SPI_CS)
int main() {
device.lock();
int response = device.write(0xFF);
device.unlock();
}

Definition at line 98 of file SPI.h.

Constructor & Destructor Documentation

SPI ( PinName  mosi,
PinName  miso,
PinName  sclk,
PinName  ssel = NC 
)

Create a SPI master connected to the specified pins.

Note
This constructor passes the SSEL pin selection to the target HAL. Not all targets support SSEL, so this cannot be relied on in portable code. Portable code should use the alternative constructor that uses GPIO for SSEL.
You can specify mosi or miso as NC if not used.
Parameters
mosiSPI Master Out, Slave In pin.
misoSPI Master In, Slave Out pin.
sclkSPI Clock pin.
sselSPI Chip Select pin.
SPI ( PinName  mosi,
PinName  miso,
PinName  sclk,
PinName  ssel,
use_gpio_ssel_t   
)

Create a SPI master connected to the specified pins.

Note
This constructor manipulates the SSEL pin as a GPIO output using a DigitalOut object. This should work on any target, and permits the use of select() and deselect() methods to keep the pin asserted between transfers.
You can specify mosi or miso as NC if not used.
Parameters
mosiSPI Master Out, Slave In pin.
misoSPI Master In, Slave Out pin.
sclkSPI Clock pin.
sselSPI Chip Select pin.
SPI ( const spi_pinmap_t static_pinmap)

Create a SPI master connected to the specified pins.

Note
This constructor passes the SSEL pin selection to the target HAL. Not all targets support SSEL, so this cannot be relied on in portable code. Portable code should use the alternative constructor that uses GPIO for SSEL.
You can specify mosi or miso as NC if not used.
Parameters
static_pinmapreference to structure which holds static pinmap.
SPI ( const spi_pinmap_t static_pinmap,
PinName  ssel 
)

Create a SPI master connected to the specified pins.

Note
This constructor manipulates the SSEL pin as a GPIO output using a DigitalOut object. This should work on any target, and permits the use of select() and deselect() methods to keep the pin asserted between transfers.
You can specify mosi or miso as NC if not used.
Parameters
static_pinmapreference to structure which holds static pinmap.
sselSPI Chip Select pin.

Member Function Documentation

void abort_all_transfers ( )

Clear the queue of transfers and abort the on-going transfer.

void abort_transfer ( )

Abort the on-going SPI transfer, and continue with transfers in the queue, if any.

void clear_transfer_buffer ( )

Clear the queue of transfers.

void deselect ( void  )

Deassert the Slave Select line, releasing exclusive access to this SPI bus.

void format ( int  bits,
int  mode = 0 
)

Configure the data transmission format.

Parameters
bitsNumber of bits per SPI frame (4 - 32, target dependent).
modeClock polarity and phase mode (0 - 3).
mode | POL PHA
-----+--------
0 | 0 0
1 | 0 1
2 | 1 0
3 | 1 1
void frequency ( int  hz = 1000000)

Set the SPI bus clock frequency.

Parameters
hzClock frequency in Hz (default = 1MHz).
virtual void lock ( void  )
virtual

Acquire exclusive access to this SPI bus.

void select ( void  )

Assert the Slave Select line, acquiring exclusive access to this SPI bus.

If use_gpio_ssel was not passed to the constructor, this only acquires exclusive access; it cannot assert the Slave Select line.

void set_default_write_value ( char  data)

Set default write data.

SPI requires the master to send some data during a read operation. Different devices may require different default byte values. For example: A SD Card requires default bytes to be 0xFF.

Parameters
dataDefault character to be transmitted during a read operation.
int set_dma_usage ( DMAUsage  usage)

Configure DMA usage suggestion for non-blocking transfers.

Parameters
usageThe usage DMA hint for peripheral.
Returns
Result of the operation.
Return values
0The usage was set.
-1Usage cannot be set as there is an ongoing transaction.
int transfer ( const Type *  tx_buffer,
int  tx_length,
Type *  rx_buffer,
int  rx_length,
const event_callback_t callback,
int  event = SPI_EVENT_COMPLETE 
)

Start non-blocking SPI transfer using 8bit buffers.

This function locks the deep sleep until any event has occurred.

Parameters
tx_bufferThe TX buffer with data to be transferred. If NULL is passed, the default SPI value is sent.
tx_lengthThe length of TX buffer in bytes.
rx_bufferThe RX buffer which is used for received data. If NULL is passed, received data are ignored.
rx_lengthThe length of RX buffer in bytes.
callbackThe event callback function.
eventThe event mask of events to modify.
See also
spi_api.h for SPI events.
Returns
Operation result.
Return values
0If the transfer has started.
-1If SPI peripheral is busy.

Definition at line 259 of file SPI.h.

virtual void unlock ( void  )
virtual

Release exclusive access to this SPI bus.

virtual int write ( int  value)
virtual

Write to the SPI Slave and return the response.

Parameters
valueData to be sent to the SPI slave.
Returns
Response from the SPI slave.
virtual int write ( const char *  tx_buffer,
int  tx_length,
char *  rx_buffer,
int  rx_length 
)
virtual

Write to the SPI Slave and obtain the response.

The total number of bytes sent and received will be the maximum of tx_length and rx_length. The bytes written will be padded with the value 0xff.

Parameters
tx_bufferPointer to the byte-array of data to write to the device.
tx_lengthNumber of bytes to write, may be zero.
rx_bufferPointer to the byte-array of data to read from the device.
rx_lengthNumber of bytes to read, may be zero.
Returns
The number of bytes written and read from the device. This is maximum of tx_length and rx_length.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.