SPI Master Driver

SPI Master Driver API Reference. More...

Functions list
void	spi_master_configure_default (spi_master_config_t *config)
	Configure SPI Master configuration structure. More...
err_t	spi_master_open (spi_master_t *obj, spi_master_config_t *config)
	Open the SPI Master driver object on selected pins. More...
void	spi_master_select_device (pin_name_t chip_select)
	Select SPI Slave device. More...
void	spi_master_deselect_device (pin_name_t chip_select)
	Deselect SPI Slave device. More...
void	spi_master_set_chip_select_polarity (spi_master_chip_select_polarity_t polarity)
	Set desired SPI Master chip select polarity. More...
err_t	spi_master_set_default_write_data (spi_master_t *obj, uint8_t default_write_data)
	Set SPI Master driver default ( dummy ) write data. More...
err_t	spi_master_set_speed (spi_master_t *obj, uint32_t speed)
	Set SPI Master driver communication speed. More...
err_t	spi_master_set_mode (spi_master_t *obj, spi_master_mode_t mode)
	Set SPI Master driver communication mode. More...
err_t	spi_master_write (spi_master_t *obj, uint8_t *__generic_ptr write_data_buffer, size_t write_data_length)
	Write byte to SPI bus. More...
err_t	spi_master_read (spi_master_t *obj, uint8_t *read_data_buffer, size_t read_data_length)
	Read byte from SPI bus. More...
err_t	spi_master_write_then_read (spi_master_t *obj, uint8_t *write_data_buffer, size_t length_write_data, uint8_t *read_data_buffer, size_t length_read_data)
	Perform a sequence of SPI Master writes immediately followed by a SPI Master read. More...
err_t	spi_master_close (spi_master_t *obj)
	Close SPI Master Driver context object. More...

Detailed Description

SPI Master Driver API header. Contains all enums, structures and function declarations available for SPI Master module.

Function Documentation

spi_master_configure_default()

void spi_master_configure_default

(

spi_master_config_t *

config

)

Configures spi_master_config_t structure to default initialization values. Take into consideration that this is just structure variable initial values setting. Values need to be redefined by user.

Parameters

[in,out]

config

SPI Master driver configuration settings. See spi_master_config_t structure definition for detailed explanation.

Default values:

Function	Default value
SPI SCK pin	0xFFFFFFFF (invalid pin)
SPI MISO pin	0xFFFFFFFF (invalid pin)
SPI MOSI pin	0xFFFFFFFF (invalid pin)
SPI Speed	100KHz
SPI mode	0
SPI default write data	0

Returns

Nothing.

Example

// SPI Master configuration structure.
spi_master_config_t spi_master_config;
 
// Populate structure to default init values.
spi_master_configure_default( &spi_master_config );

spi_master_open()

err_t spi_master_open	(	spi_master_t *	obj,
		spi_master_config_t *	config
	)

Opens the SPI Master driver object on selected pins. Allocates memory and pin for specified object.

Parameters

[in]	obj	SPI Master driver object. See spi_master_t structure definition for detailed explanation.
[in]	config	SPI Master configuration structure. See spi_master_config_t structure definition for detailed explanation.

Returns

The function can return one of the values defined by spi_master_err_t, which is size dependant on the architecture.

Note

This function needs to be called before other driver functions.

Warning

The following example describes how the function is used. Take into consideration that different hardware might not have the same pins. Make sure to accommodate pin name based on your hardware specifics.

Example

// SPI driver context structure.
spi_master_t spi_master;
 
// SPI Master configuration structure.
spi_master_config_t spi_master_config;
 
// Populate config structure.
spi_master_configure_default( &spi_master_config );
 
// Specify desired SPI Serial Clock pin.
spi_master_config.sck = MIKROBUS_1_SCK;
 
// Specify desired SPI Master-In Slave-Out pin.
spi_master_config.miso = MIKROBUS_1_MISO;
 
// Specify desired SPI Master-Out Slave-In pin.
spi_master_config.mosi = MIKROBUS_1_MOSI;
 
// Specify desired SPI transfer rate.
spi_master_config.speed = 100000;
 
// Specify desired SPI mode.
spi_master_config.mode = SPI_MASTER_MODE_0;
 
// Specify desired default write (dummy) data.
spi_master_config.default_write_data = 0x00;
 
// Allocate resources for SPI module.
if ( SPI_MASTER_SUCCESS == spi_master_open( &spi_master, &spi_master_config ) ) {
 // No error
} else {
 // Handle the error
}

spi_master_select_device()

void spi_master_select_device

(

pin_name_t

chip_select

)

Sets digital output individual slave pin to logic 0.

Parameters

[in]

chip_select

Device-specific chip select pin.

Returns

Nothing.

Warning

The following example describes how the function is used. Take into consideration that different hardware might not have the same pins. Make sure to accommodate pin name based on your hardware specifics.

Example

// Select desired device.
spi_master_select_device( MIKROBUS_1_CS );

spi_master_deselect_device()

void spi_master_deselect_device

(

pin_name_t

chip_select

)

Sets digital output individual slave pin to logic 1.

Parameters

[in]

chip_select

Device-specific chip select pin.

Returns

Nothing.

Warning

The following example describes how the function is used. Take into consideration that different hardware might not have the same pins. Make sure to accommodate pin name based on your hardware specifics.

Example

// Deselect desired device.
spi_master_deselect_device( MIKROBUS_1_CS );

spi_master_set_chip_select_polarity()

void spi_master_set_chip_select_polarity

(

spi_master_chip_select_polarity_t

polarity

)

Sets SPI Master chip select polarity either to active low or active high. Chip select polarity shall be active low by default.

Parameters

[in]

polarity

Desired chip select polarity mode. See spi_master_chip_select_polarity_t for valid values.

Returns

Nothing.

Example

// Specify desired chip-select polarity.
spi_master_set_chip_select_polarity( SPI_MASTER_CHIP_SELECT_POLARITY_ACTIVE_LOW );

spi_master_set_default_write_data()

err_t spi_master_set_default_write_data	(	spi_master_t *	obj,
		uint8_t	default_write_data
	)

Default write data is sent by driver when the data transmit buffer is shorter than data receive buffer.

Parameters

[in]	obj	SPI master driver object. See spi_master_t structure definition for detailed explanation.
[in]	default_write_data	User-defined default write data.

Returns

The function can return one of the values defined by spi_master_err_t, which is size dependant on the architecture.

Precondition

Before calling this function, the user is expected to call spi_master_open function.

Example

// SPI Master driver context structure.
spi_master_t spi_master;
 
// Specify desired default write (dummy) data.
if ( SPI_MASTER_SUCCESS == spi_master_set_default_write_data( &spi_master, 0x00 ) ) {
 // No error
} else {
 // Handle the error
}

spi_master_set_speed()

err_t spi_master_set_speed	(	spi_master_t *	obj,
		uint32_t	speed
	)

Sets SPI Master module speed to passed value if possible. If not possible, returns error. Make sure to check for return value. Initializes SPI module on hardware level.

Parameters

[in]	obj	SPI Master driver object. See spi_master_t structure definition for detailed explanation.
[in]	speed	SPI Master communication speed.

Returns

The function can return one of the values defined by spi_master_err_t, which is size dependant on the architecture.

Precondition

Before calling this function, the user is expected to call spi_master_open function.

Example

// SPI Master driver context structure.
spi_master_t spi_master;
 
// Specify desired SPI transfer rate.
if ( SPI_MASTER_SUCCESS == spi_master_set_speed( &spi_master, 100000 ) ) {
 // No error
} else {
 // Handle the error
}

spi_master_set_mode()

err_t spi_master_set_mode	(	spi_master_t *	obj,
		spi_master_mode_t	mode
	)

Sets SPI Master module mode to passed value if possible. If not possible, returns error. Make sure to check for return value. Initializes SPI module on hardware level.

Parameters

[in]	obj	SPI Master driver object. See spi_master_t structure definition for detailed explanation.
[in]	mode	SPI Master communication mode. See spi_master_mode_t for valid values.

Returns

The function can return one of the values defined by spi_master_err_t, which is size dependant on the architecture.

Precondition

Before calling this function, the user is expected to call spi_master_open function.

Example

// SPI Master driver context structure.
spi_master_t spi_master;
 
// Specify desired SPI mode.
if ( SPI_MASTER_SUCCESS == spi_master_set_mode( &spi_master, SPI_MASTER_MODE_0 ) ) {
 // No error
} else {
 // Handle the error
}

spi_master_write()

err_t spi_master_write	(	spi_master_t *	obj,
		uint8_t *__generic_ptr	write_data_buffer,
		size_t	write_data_length
	)

Writes byte to SPI bus in blocking mode. Received byte is discarded.

Parameters

[in]	obj	SPI master driver object. See spi_master_t structure definition for detailed explanation.
[in]	write_data_buffer	Data transmit buffer.
[in]	write_data_length	Number of bytes to write from data transmit buffer.

Returns

The function can return one of the values defined by spi_master_err_t, which is size dependant on the architecture.

Precondition

Before calling this function, the user is expected to call spi_master_open function.

Warning

The following example describes only how the function is used. This is not a working example.

Example

// Specify length of data to be written.
#define DATA_LENGTH 150
 
// Specify data structure for data to be sent.
uint8_t write_sequence[ DATA_LENGTH ];
 
// Specify i.e. 0th element to be sent.
write_sequence[0] = 0x02;
 
// Specify i.e. 1st element to be sent.
write_sequence[1] = 0x05;
 
// SPI Master driver context structure
spi_master_t spi_master;
 
// Write specified data on SPI bus.
if ( SPI_MASTER_SUCCESS == spi_master_write( &spi_master, &write_sequence, DATA_LENGTH ) ) {
 // No error
} else {
 // Handle the error
}

spi_master_read()

err_t spi_master_read	(	spi_master_t *	obj,
		uint8_t *	read_data_buffer,
		size_t	read_data_length
	)

Reads byte from SPI bus in blocking mode. Transmitted byte is user-defined default (dummy) write data.

Parameters

[in]	obj	SPI master driver object. See spi_master_t structure definition for detailed explanation.
[out]	read_data_buffer	Data receive buffer.
[in]	read_data_length	Number of bytes to be read.

Returns

The function can return one of the values defined by spi_master_err_t, which is size dependant on the architecture.

Precondition

Before calling this function, the user is expected to call spi_master_open function.

Warning

The following example describes only how the function is used. This is not a working example.

Example

// Specify length of data to be read.
#define DATA_LENGTH 150
 
// Specify data structure for data to be read.
uint8_t read_sequence[ DATA_LENGTH ];
 
// SPI Master driver context structure.
spi_master_t spi_master;
 
// Read specified data on SPI bus.
if ( SPI_MASTER_SUCCESS == spi_master_read( &spi_master, &read_sequence, DATA_LENGTH ) ) {
 // No error
} else {
 // Handle the error
}

spi_master_write_then_read()

err_t spi_master_write_then_read	(	spi_master_t *	obj,
		uint8_t *	write_data_buffer,
		size_t	length_write_data,
		uint8_t *	read_data_buffer,
		size_t	length_read_data
	)

Writes a sequence of bytes to SPI bus, followed by a corresponding read.

Parameters

[in]	obj	SPI master driver object. See spi_master_t structure definition for detailed explanation.
[in]	write_data_buffer	Data transmit buffer.
[in]	length_write_data	Number of bytes to write from data transmit buffer.
[out]	read_data_buffer	Data receive buffer.
[in]	length_read_data	Number of bytes to be read.

Returns

The function can return one of the values defined by spi_master_err_t, which is size dependant on the architecture.

Precondition

Before calling this function, the user is expected to call spi_master_open function. Before calling this function.

Note

If the transmitted data sequence is shorter than the received data sequence, the remaining places in the data transmit buffer will be populated with user-defined data. See spi_master_set_default_write_data function for more details.

Warning

The following example describes only how the function is used. This is not a working example.

Example

// Specify length of data to be written and read.
#define DATA_LENGTH 150
 
// Specify data structure for data to be sent.
uint8_t write_sequence[ DATA_LENGTH ];
 
// Specify data structure for data to be read.
uint8_t read_sequence[ DATA_LENGTH ];
 
// Specify i.e. 0th element to be sent.
write_sequence[0] = 0x02;
 
// Specify i.e. 1st element to be sent.
write_sequence[1] = 0x05;
 
// SPI Master driver context structure.
spi_master_t spi_master;
 
// Write then read specified data on SPI bus.
if ( SPI_MASTER_SUCCESS == spi_master_write_then_read( &spi_master, &write_sequence,
 DATA_LENGTH,
 &read_sequence,
 DATA_LENGTH ) )
{
 // No error
} else {
 // Handle the error
}

spi_master_close()

err_t spi_master_close

(

spi_master_t *

obj

)

Closes SPI Master Driver context object, resets pin AF to default values and clears all buffers used by object.

Parameters

[in,out]

obj

Driver context object handle. See spi_master_t structure definition for detailed explanation.

Returns

The function can return one of the values defined by spi_master_err_t, which is size dependant on the architecture.

Example

// SPI Master driver context structure.
spi_master_t spi_master;
 
// Close the SPI module object handler.
if ( SPI_MASTER_SUCCESS == spi_master_close( &spi_master ) ) {
 // No error
} else {
 // Handle the error
}