mbed OS 2 and mbed OS 5

This is the handbook for mbed OS 2. If you’re working with mbed OS 5, please see the new handbook and API References. For the latest SPI API, please see SPI.

The SPI Interface provides a "Serial Peripheral Interface" Master.

This interface can be used for communication with SPI slave devices, such as FLASH memory, LCD screens and other modules or integrated circuits.

Hello World!

Import program

00001 #include "mbed.h"
00003 SPI spi(p5, p6, p7); // mosi, miso, sclk
00004 DigitalOut cs(p8);
00006 int main() {
00007     // Chip must be deselected
00008     cs = 1;
00010     // Setup the spi for 8 bit data, high steady state clock,
00011     // second edge capture, with a 1MHz clock rate
00012     spi.format(8,3);
00013     spi.frequency(1000000);
00015     // Select the device by seting chip select low
00016     cs = 0;
00018     // Send 0x8f, the command to read the WHOAMI register
00019     spi.write(0x8F);
00021     // Send a dummy byte to receive the contents of the WHOAMI register
00022     int whoami = spi.write(0x00);
00023     printf("WHOAMI register = 0x%X\n", whoami);
00025     // Deselect the device
00026     cs = 1;
00027 }


Import library

Public Member Functions

  SPI (PinName mosi, PinName miso, PinName sclk, PinName ssel=NC)
  Create a SPI master connected to the specified pins.
void  format (int bits, int mode=0)
  Configure the data transmission format.
void  frequency (int hz=1000000)
  Set the spi bus clock frequency.
virtual int  write (int value)
  Write to the SPI Slave and return the response.
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.
virtual void  lock (void)
  Acquire exclusive access to this SPI bus.
virtual void  unlock (void)
  Release exclusive access to this SPI bus.
void  set_default_write_value (char data)
  Set default write data SPI requires the master to send some data during a read operation.
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.
void  abort_transfer ()
  Abort the on-going SPI transfer, and continue with transfer's in the queue if any.
void  clear_transfer_buffer ()
  Clear the transaction buffer.
void  abort_all_transfers ()
  Clear the transaction buffer and abort on-going transfer.
int  set_dma_usage (DMAUsage usage)
  Configure DMA usage suggestion for non-blocking transfers.

Protected Member Functions

void  irq_handler_asynch (void)
  SPI IRQ handler.
int  transfer (const void *tx_buffer, int tx_length, void *rx_buffer, int rx_length, unsigned char bit_width, const event_callback_t &callback, int event)
  Common transfer method.
int  queue_transfer (const void *tx_buffer, int tx_length, void *rx_buffer, int rx_length, unsigned char bit_width, const event_callback_t &callback, int event)
void  start_transfer (const void *tx_buffer, int tx_length, void *rx_buffer, int rx_length, unsigned char bit_width, const event_callback_t &callback, int event)
  Configures a callback, spi peripheral and initiate a new transfer.
void  start_transaction ( transaction_t *data)
  Start a new transaction.
void  dequeue_transaction ()
  Dequeue a transaction.


See the Pinout page for more details

The default settings of the SPI interface are 1MHz, 8-bit, Mode 0

The SPI Interface can be used to write data words out of the SPI port, returning the data received back from the SPI slave. The SPI clock frequency and format can also be configured. The format is set to data word length 8 to 16 bits, and the mode as per the table below:


The SPI master generates a clock to synchronously drive a serial bit stream slave. The slave returns a bit stream, also synchronous to the clock.