mikroSDK Reference Manual

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]configSPI 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]objSPI Master driver object. See spi_master_t structure definition for detailed explanation.
[in]configSPI 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_selectDevice-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_selectDevice-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]polarityDesired chip select polarity mode. See spi_master_chip_select_polarity_t for valid values.
Returns
Nothing.

Example

◆ 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]objSPI master driver object. See spi_master_t structure definition for detailed explanation.
[in]default_write_dataUser-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]objSPI Master driver object. See spi_master_t structure definition for detailed explanation.
[in]speedSPI 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]objSPI Master driver object. See spi_master_t structure definition for detailed explanation.
[in]modeSPI 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.
// 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]objSPI master driver object. See spi_master_t structure definition for detailed explanation.
[in]write_data_bufferData transmit buffer.
[in]write_data_lengthNumber 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]objSPI master driver object. See spi_master_t structure definition for detailed explanation.
[out]read_data_bufferData receive buffer.
[in]read_data_lengthNumber 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]objSPI master driver object. See spi_master_t structure definition for detailed explanation.
[in]write_data_bufferData transmit buffer.
[in]length_write_dataNumber of bytes to write from data transmit buffer.
[out]read_data_bufferData receive buffer.
[in]length_read_dataNumber 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]objDriver 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
}
spi_master_config_t::default_write_data
uint8_t default_write_data
Definition: drv_spi_master.h:127
spi_master_t
The SPI Master driver context structure.
Definition: drv_spi_master.h:141
spi_master_config_t::mode
spi_master_mode_t mode
Definition: drv_spi_master.h:132
spi_master_set_speed
err_t spi_master_set_speed(spi_master_t *obj, uint32_t speed)
Set SPI Master driver communication speed.
SPI_MASTER_MODE_0
Definition: drv_spi_master.h:71
spi_master_write
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.
spi_master_config_t::miso
pin_name_t miso
Definition: drv_spi_master.h:129
spi_master_config_t
The SPI Master driver configuration structure.
Definition: drv_spi_master.h:125
SPI_MASTER_CHIP_SELECT_POLARITY_ACTIVE_LOW
Definition: drv_spi_master.h:85
spi_master_config_t::speed
uint32_t speed
Definition: drv_spi_master.h:131
spi_master_close
err_t spi_master_close(spi_master_t *obj)
Close SPI Master Driver context object.
spi_master_select_device
void spi_master_select_device(pin_name_t chip_select)
Select SPI Slave device.
spi_master_deselect_device
void spi_master_deselect_device(pin_name_t chip_select)
Deselect SPI Slave device.
SPI_MASTER_SUCCESS
Definition: drv_spi_master.h:61
spi_master_set_mode
err_t spi_master_set_mode(spi_master_t *obj, spi_master_mode_t mode)
Set SPI Master driver communication mode.
spi_master_set_chip_select_polarity
void spi_master_set_chip_select_polarity(spi_master_chip_select_polarity_t polarity)
Set desired SPI Master chip select polarity.
spi_master_open
err_t spi_master_open(spi_master_t *obj, spi_master_config_t *config)
Open the SPI Master driver object on selected pins.
spi_master_read
err_t spi_master_read(spi_master_t *obj, uint8_t *read_data_buffer, size_t read_data_length)
Read byte from SPI bus.
spi_master_configure_default
void spi_master_configure_default(spi_master_config_t *config)
Configure SPI Master configuration structure.
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)
Perform a sequence of SPI Master writes immediately followed by a SPI Master read.
spi_master_config_t::sck
pin_name_t sck
Definition: drv_spi_master.h:128
spi_master_config_t::mosi
pin_name_t mosi
Definition: drv_spi_master.h:130
spi_master_set_default_write_data
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.