mbed official / mbed-dev

mbed library sources. Supersedes mbed-src.

Dependents:   Nucleo_Hello_Encoder BLE_iBeaconScan AM1805_DEMO DISCO-F429ZI_ExportTemplate1 ... more

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 >, and NonCopyable< SPI >.

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.
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 transfers in the queue, if any.
void clear_transfer_buffer ()
 Clear the queue of transfers.
void abort_all_transfers ()
 Clear the queue of transfers and abort the on-going transfer.
int set_dma_usage (DMAUsage usage)
 Configure DMA usage suggestion for non-blocking transfers.
 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.
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 transfers in the queue, if any.
void clear_transfer_buffer ()
 Clear the queue of transfers.
void abort_all_transfers ()
 Clear the queue of transfers and abort the 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 interrupt 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)
 Start the transfer or put it on the queue.
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)
 Put a transfer on the transfer queue.
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)
 Configure a callback, SPI peripheral, and initiate a new transfer.
void irq_handler_asynch (void)
 SPI interrupt 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)
 Start the transfer or put it on the queue.
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)
 Put a transfer on the transfer queue.
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)
 Configure 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.
 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 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 82 of file cmsis/BUILD/mbed/drivers/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:
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.

Definition at line 32 of file SPI.cpp.

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

Create a SPI master connected to the specified pins.

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

Member Function Documentation

void abort_all_transfers (  )

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

Definition at line 174 of file SPI.cpp.

void abort_all_transfers (  )

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

void abort_transfer ( void   )

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

Definition at line 157 of file SPI.cpp.

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.

Definition at line 167 of file SPI.cpp.

void clear_transfer_buffer (  )

Clear the queue of transfers.

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
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 55 of file SPI.cpp.

void frequency ( int  hz = 1000000 )

Set the SPI bus clock frequency.

Parameters:
hzClock frequency in Hz (default = 1MHz).

Definition at line 71 of file SPI.cpp.

void frequency ( int  hz = 1000000 )

Set the SPI bus clock frequency.

Parameters:
hzClock frequency in Hz (default = 1MHz).
void irq_handler_asynch ( void   ) [protected]

SPI interrupt handler.

Definition at line 262 of file SPI.cpp.

void irq_handler_asynch ( void   ) [protected]

SPI interrupt handler.

void lock ( void   ) [virtual]

Acquire exclusive access to this SPI bus.

Definition at line 129 of file SPI.cpp.

virtual void lock ( void   ) [virtual]

Acquire exclusive access to this SPI bus.

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]

Put a transfer on the transfer queue.

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.
bit_widthThe buffers element width in bits.
callbackThe event callback function.
eventThe event mask of events to modify.
Returns:
Operation success.
Return values:
0A transfer was added to the queue.
-1Transfer can't be added because queue is full.
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]

Put a transfer on the transfer queue.

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.
bit_widthThe buffers element width in bits.
callbackThe event callback function.
eventThe event mask of events to modify.
Returns:
Operation success.
Return values:
0A transfer was added to the queue.
-1Transfer can't be added because queue is full.

Definition at line 189 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 during a read operation.
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.

Definition at line 139 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:
Result of the operation.
Return values:
0The usage was set.
-1Usage cannot be set as there is an ongoing transaction.
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.

Definition at line 180 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]

Configure a callback, SPI peripheral, and initiate a new transfer.

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.
bit_widthThe buffers element width.
callbackThe event callback function.
eventThe event mask of events to modify.
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]

Configure a callback, SPI peripheral, and initiate a new transfer.

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.
bit_widthThe buffers element width.
callbackThe event callback function.
eventThe event mask of events to modify.

Definition at line 218 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 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 181 of file cmsis/BUILD/mbed/drivers/SPI.h.

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]

Start the transfer or put it on the queue.

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.
bit_widthThe buffers element width in bits.
callbackThe event callback function.
eventThe event mask of events to modify.
Returns:
Operation success.
Return values:
0A transfer was started or added to the queue.
-1Transfer can't be added because queue is full.
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]

Start the transfer or put it on the queue.

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.
bit_widthThe buffers element width in bits.
callbackThe event callback function.
eventThe event mask of events to modify.
Returns:
Operation success.
Return values:
0A transfer was started or added to the queue.
-1Transfer can't be added because queue is full.

Definition at line 148 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 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 181 of file drivers/SPI.h.

virtual void unlock ( void   ) [virtual]

Release exclusive access to this SPI bus.

void unlock ( void   ) [virtual]

Release exclusive access to this SPI bus.

Definition at line 134 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 120 of file SPI.cpp.

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

Definition at line 111 of file SPI.cpp.

Generated on Tue Jul 12 2022 20:41:17 by  doxygen 1.7.2