BA / Mbed OS BaBoRo1

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Embed: (wiki syntax)

« Back to documentation index

SPI Class Reference
Public Member Functions | Protected Member Functions | Private Member Functions

SPI Class Reference
[Drivers]

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

#include <SPI.h>

Inherits NonCopyable< SPI >.

Inherited by SPIHalfDuplex.

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.

Private Member Functions

 MBED_DEPRECATED ("Invalid copy construction of a NonCopyable resource.") NonCopyable(const NonCopyable &)
 NonCopyable copy constructor.
 MBED_DEPRECATED ("Invalid copy assignment of a NonCopyable resource.") NonCopyable &operator
 NonCopyable copy assignment operator.

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: 

 // Send a byte to a SPI slave, and record the response

 #include "mbed.h"

 // hardware ssel (where applicable)
 //SPI device(p5, p6, p7, p8); // mosi, miso, sclk, ssel

 // software ssel
 SPI device(p5, p6, p7); // mosi, miso, sclk
 DigitalOut cs(p8); // ssel

 int main() {
     // hardware ssel (where applicable)
     //int response = device.write(0xFF);

     device.lock();
     // software ssel
     cs = 0;
     int response = device.write(0xFF);
     cs = 1;
     device.unlock();

 }

Definition at line 76 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.

mosi or miso can be specified 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

Definition at line 31 of file SPI.cpp.

Member Function Documentation

void abort_all_transfers (  )

Clear the transaction buffer and abort on-going transfer.

Definition at line 158 of file SPI.cpp.

void abort_transfer ( void   )

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

Definition at line 141 of file SPI.cpp.

void clear_transfer_buffer (  )

Clear the transaction buffer.

Definition at line 151 of file SPI.cpp.

void format ( int  bits,
int  mode = 0 
)

Configure the data transmission format.

Parameters:
bitsNumber of bits per SPI frame (4 - 16)
modeClock polarity and phase mode (0 - 3)
 mode | POL PHA
 -----+--------
   0  |  0   0
   1  |  0   1
   2  |  1   0
   3  |  1   1

Definition at line 48 of file SPI.cpp.

void frequency ( int  hz = 1000000 )

Set the spi bus clock frequency.

Parameters:
hzSCLK frequency in hz (default = 1MHz)

Definition at line 63 of file SPI.cpp.

void irq_handler_asynch ( void   ) [protected]

SPI IRQ handler.

Definition at line 246 of file SPI.cpp.

void lock ( void   ) [virtual]

Acquire exclusive access to this SPI bus.

Definition at line 116 of file SPI.cpp.

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 
) [protected]
Parameters:
tx_bufferThe TX buffer with data to be transfered. 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
bit_widthThe buffers element width
callbackThe event callback function
eventThe logical OR of events to modify
Returns:
Zero if a transfer was added to the queue, or -1 if the queue is full

Definition at line 173 of file SPI.cpp.

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 while read operation

Definition at line 124 of file SPI.cpp.

int set_dma_usage ( DMAUsage  usage )

Configure DMA usage suggestion for non-blocking transfers.

Parameters:
usageThe usage DMA hint for peripheral
Returns:
Zero if the usage was set, -1 if a transaction is on-going

Definition at line 164 of file SPI.cpp.

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 
) [protected]

Configures a callback, spi peripheral and initiate a new transfer.

Parameters:
tx_bufferThe TX buffer with data to be transfered. 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
bit_widthThe buffers element width
callbackThe event callback function
eventThe logical OR of events to modify

Definition at line 202 of file SPI.cpp.

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 
) [protected]

Common transfer method.

Parameters:
tx_bufferThe TX buffer with data to be transfered. 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
bit_widthThe buffers element width
callbackThe event callback function
eventThe logical OR of events to modify
Returns:
Zero if the transfer has started or was added to the queue, or -1 if SPI peripheral is busy/buffer is full

Definition at line 132 of file SPI.cpp.

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 transfered. 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 logical OR of events to modify. Look at spi hal header file for SPI events.
Returns:
Zero if the transfer has started, or -1 if SPI peripheral is busy

Definition at line 172 of file SPI.h.

void unlock ( void   ) [virtual]

Release exclusive access to this SPI bus.

Definition at line 120 of file SPI.cpp.

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

Reimplemented in SPIHalfDuplex.

Definition at line 100 of file SPI.cpp.

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.

Definition at line 108 of file SPI.cpp.

Generated on Tue Jul 12 2022 12:22:54 by  doxygen 1.7.2