Mistake on this page?
Report an issue in GitHub or email us


SPI class hierarchy

The SPI Interface provides a Serial Peripheral Interface Master.

You can use this interface for communication with SPI slave devices, such as FLASH memory, LCD screens and other modules or integrated circuits.


A pinout map.

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

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

Mode Polarity Phase
0 0 0
1 0 1
2 1 0
3 1 1

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. To communicate with multiple slave devices connected over the same SPI peripheral, you must use multiple SPI objects, one for each slave, but instantiate them with a different Slave select (SSEL) and configuration corresponding to each slave. Note that the SPI object automatically configures the SPI peripheral with the current object's configuration when the application code invokes the interfaces on the SPI object.

Defining multiple SPI objects connected to different buses might require the use of alternative pin names PIN_ALTx defined in PinNames.h for the board in use. The PinMap source which shows the accociated hardware SPI bus can be found in PeripheralPins.c

SPI class reference

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

SPI hello, world

The following example uses the WHOAMI register. The WHOAMI register is an ID register of the slave device. In other words, it's just an example that you can write to a slave's register. In this example, Mbed OS acts as the SPI master, and DigitalOut acts as the slave chip select (cs).

 * Copyright (c) 2006-2020 Arm Limited and affiliates.
 * SPDX-License-Identifier: Apache-2.0
#include "mbed.h"

SPI spi(D11, D12, D13); // mosi, miso, sclk
DigitalOut cs(D0);

int main()
    // Chip must be deselected
    cs = 1;

    // Setup the spi for 8 bit data, high steady state clock,
    // second edge capture, with a 1MHz clock rate
    spi.format(8, 3);

    // Select the device by seting chip select low
    cs = 0;

    // Send 0x8f, the command to read the WHOAMI register

    // Send a dummy byte to receive the contents of the WHOAMI register
    int whoami = spi.write(0x00);
    printf("WHOAMI register = 0x%X\n", whoami);

    // Deselect the device
    cs = 1;

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.