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

#include <SPI.h>

Inherited by UnlockedSPI, and UnlockedSPI.

Public Member Functions
	SPI (PinName mosi, PinName miso, PinName sclk, PinName ssel=NC)
	Create a SPI master connected to the specified pins.
	SPI (PinName mosi, PinName miso, PinName sclk, PinName ssel, use_gpio_ssel_t)
	Create a SPI master connected to the specified pins.
	SPI (const spi_pinmap_t &static_pinmap)
	Create a SPI master connected to the specified pins.
	SPI (const spi_pinmap_t &static_pinmap, PinName ssel)
	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	select (void)
	Assert the Slave Select line, acquiring exclusive access to this SPI bus.
void	deselect (void)
	Deassert the Slave Select line, releasing 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.
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 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:

mosi	SPI Master Out, Slave In pin.
miso	SPI Master In, Slave Out pin.
sclk	SPI Clock pin.
ssel	SPI Chip Select pin.

Definition at line 31 of file SPI.cpp.

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:

mosi	SPI Master Out, Slave In pin.
miso	SPI Master In, Slave Out pin.
sclk	SPI Clock pin.
ssel	SPI Chip Select pin.

Definition at line 53 of file SPI.cpp.

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_pinmap reference to structure which holds static pinmap.

Definition at line 74 of file SPI.cpp.

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_pinmap	reference to structure which holds static pinmap.
ssel	SPI Chip Select pin.

Definition at line 91 of file SPI.cpp.

Member Function Documentation

void abort_all_transfers ( )

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

Definition at line 306 of file SPI.cpp.

void abort_transfer ( void )

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

Definition at line 290 of file SPI.cpp.

void clear_transfer_buffer ( )

Clear the queue of transfers.

Definition at line 299 of file SPI.cpp.

void deselect ( void )

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

Definition at line 263 of file SPI.cpp.

void format	(	int	bits,
		int	mode = `0`
	)

Configure the data transmission format.

Parameters:

bits	Number of bits per SPI frame (4 - 16).
mode	Clock polarity and phase mode (0 - 3).

 mode | POL PHA
 -----+--------
   0  |  0   0
   1  |  0   1
   2  |  1   0
   3  |  1   1

Definition at line 179 of file SPI.cpp.

void frequency ( int hz = 1000000 )

Set the SPI bus clock frequency.

Parameters:

hz	Clock frequency in Hz (default = 1MHz).

Definition at line 195 of file SPI.cpp.

void irq_handler_asynch ( void ) [protected]

SPI interrupt handler.

Definition at line 395 of file SPI.cpp.

void lock ( void ) [virtual]

Acquire exclusive access to this SPI bus.

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

Put a transfer on the transfer queue.

Parameters:

tx_buffer	The TX buffer with data to be transferred. If NULL is passed, the default SPI value is sent.
tx_length	The length of TX buffer in bytes.
rx_buffer	The RX buffer which is used for received data. If NULL is passed, received data are ignored.
rx_length	The length of RX buffer in bytes.
bit_width	The buffers element width in bits.
callback	The event callback function.
event	The event mask of events to modify.

Returns:: Operation success.

Return values:

0	A transfer was added to the queue.
-1	Transfer can't be added because queue is full.

Definition at line 321 of file SPI.cpp.

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.

Definition at line 249 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:

data	Default character to be transmitted during a read operation.

Definition at line 271 of file SPI.cpp.

int set_dma_usage ( DMAUsage usage )

Configure DMA usage suggestion for non-blocking transfers.

Parameters:

usage The usage DMA hint for peripheral.

Returns:: Result of the operation.

Return values:

0	The usage was set.
-1	Usage cannot be set as there is an ongoing transaction.

Definition at line 312 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_buffer	The TX buffer with data to be transferred. If NULL is passed, the default SPI value is sent.
tx_length	The length of TX buffer in bytes.
rx_buffer	The RX buffer which is used for received data. If NULL is passed, received data are ignored.
rx_length	The length of RX buffer in bytes.
bit_width	The buffers element width.
callback	The event callback function.
event	The event mask of events to modify.

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

Start the transfer or put it on the queue.

Parameters:

tx_buffer	The TX buffer with data to be transferred. If NULL is passed, the default SPI value is sent
tx_length	The length of TX buffer in bytes.
rx_buffer	The RX buffer which is used for received data. If NULL is passed, received data are ignored.
rx_length	The length of RX buffer in bytes.
bit_width	The buffers element width in bits.
callback	The event callback function.
event	The event mask of events to modify.

Returns:: Operation success.

Return values:

0	A transfer was started or added to the queue.
-1	Transfer can't be added because queue is full.

Definition at line 281 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_buffer	The TX buffer with data to be transferred. If NULL is passed, the default SPI value is sent.
tx_length	The length of TX buffer in bytes.
rx_buffer	The RX buffer which is used for received data. If NULL is passed, received data are ignored.
rx_length	The length of RX buffer in bytes.
callback	The event callback function.
event	The event mask of events to modify.

See also:: spi_api.h for SPI events.

Returns:: Operation result.

Return values:

0	If the transfer has started.
-1	If SPI peripheral is busy.

Definition at line 259 of file SPI.h.

void unlock ( void ) [virtual]

Release exclusive access to this SPI bus.

Definition at line 258 of file SPI.cpp.

int write ( int value ) [virtual]

Write to the SPI Slave and return the response.

Parameters:

value Data to be sent to the SPI slave.

Returns:: Response from the SPI slave.

Definition at line 221 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_buffer	Pointer to the byte-array of data to write to the device.
tx_length	Number of bytes to write, may be zero.
rx_buffer	Pointer to the byte-array of data to read from the device.
rx_length	Number 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 229 of file SPI.cpp.

Type:	Library
Created:	17 Dec 2019
Imports:	79
Forks:	0
Commits:	2
Dependents:	2
Dependencies:	0
Followers:	1

Important changes to repositories hosted on mbed.com

SPI Class Reference
[SPI class]

Public Member Functions

Protected Member Functions

Private Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Important changes to repositories hosted on mbed.com

SPI Class Reference [SPI class]

Public Member Functions

Protected Member Functions

Private Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning

SPI Class Reference
[SPI class]