4.22.2 SPI in MSSP

Serial Peripheral Interface in the Master Synchronous Serial Port

4.22.2.1 Introduction

The Master Synchronous Serial Port (MSSP) peripheral can operate in one of two modes: Serial Peripheral Interface (SPI) and I2C, having the advantage of implementing both communication protocols with the same hardware.

The Serial Peripheral Interface (SPI) module is a synchronous serial data communication bus that operates in Full Duplex mode. In addition, a portable API interface provides a generic SPI interface supporting the MCC Melody Component concept of firmware portability.

4.22.2.2 Supported Device Families

PIC16F152xx PIC16(L)F153xx PIC16(L)F188xx PIC16F171xx
PIC16F181xx PIC16F180xx PIC16(L)F191xx PIC16(L)F184xx
PIC16(L)F183xx PIC16(L)F193x PIC16(L)F194x PIC16(L)F178x
PIC12(L)F182x PIC16(L)F182x PIC12(L)F184x PIC16(L)F184x
PIC12(L)F161x PIC16(L)F161x PIC12(L)F150x PIC16(L)F150x
PIC12LF155x PIC16LF155x PIC16LF156x PIC16LF152x
PIC16(L)F170x PIC16(L)F171x PIC16(L)F176x PIC16(L)F177x
PIC16(L)F151x PIC16(L)F145x
PIC18F-K20 PIC18F-K22 PIC18F-K40 PIC18F-K20
PIC18F-K50 PIC18F-K80 PIC18F-K90 PIC18F-Q10

4.22.2.3 Required header files:


#include "mcc_generated_files/spi/mssp[X].h"
Note: Replace [X] with the selected instance number of the MSSP module.

4.22.2.4 Module Documentation

4.22.2.4.1 SPI2

This header file provides API prototypes for the SPI2 driver.

Module description

This header file provides API prototypes for the SPI2 driver.

Version: SPI2 Driver Version v5.0.0
Data structures
Enumerations
  • enum spi2_configuration_name_t { MSSP2_DEFAULT }

    Enumeration for the different configurations supported by the driver. A configuration is specified as parameter to SPI2_Open() and is used by the function to set SPI parameters as specified by the configuration.

Functions
  • void SPI2_Initialize (void)

    Initializes the SPI2 module.

  • void SPI2_Deinitialize (void)

    Deinitializes the SPI2 module.

  • bool SPI2_Open (uint8_t spiConfigIndex)

    Enables the SPI2 module with the configurations passed as the parameter. See spi2_config_names_t for the available configurations.

  • void SPI2_Close (void)

    Closes the active configuration of the SPI2 module.

  • void SPI2_BufferExchange (void *bufferData, size_t bufferSize)

    Exchanges the buffer using the SPI protocol. This function is blocking in Polling mode.

  • void SPI2_BufferWrite (void *bufferData, size_t bufferSize)

    Writes a buffer using the SPI protocol. This function is blocking in Polling mode.

  • void SPI2_BufferRead (void *bufferData, size_t bufferSize)

    Reads a buffer using the SPI protocol. This function is blocking in Polling mode.

  • uint8_t SPI2_ByteExchange (uint8_t byteData)

    Exchanges one byte using the SPI protocol. This function is blocking.

  • void SPI2_ByteWrite (uint8_t byteData)

    Writes one byte to the SPI buffer.

  • uint8_t SPI2_ByteRead (void)

    Reads one byte of data received in the the SPI buffer.

  • bool SPI2_IsRxReady (void)

    Checks if the SPI2 module is ready to read data.

  • bool SPI2_IsTxReady (void)

    Checks if the SPI2 module is ready to write data.

  • void SPI2_RxCompleteCallbackRegister (void(*CallbackHandler)(void))

    Sets the callback function to be executed at the completion of data transfer in Interrupt mode.

  • void SPI2_ISR (void)

    Interrupt Service Routine (ISR) for the SPI2 module.

Function Documentation

SPI2_BufferExchange()

void SPI2_BufferExchange (void * bufferData, size_t bufferSize)

Exchanges the buffer using the SPI protocol. This function is blocking in Polling mode.

Parameters:
in,out *bufferData

Buffer address of the data to be exchanged

in bufferSize

Size of the data in bytes

Returns:

None.

SPI2_BufferRead()

void SPI2_BufferRead (void * bufferData, size_t bufferSize)

Reads a buffer using the SPI protocol. This function is blocking in Polling mode.

Parameters:
out *bufferData

Buffer address of the data to be read

in bufferSize

Size of the data in bytes

Returns:

None.

SPI2_BufferWrite()

void SPI2_BufferWrite (void * bufferData, size_t bufferSize)

Writes a buffer using the SPI protocol. This function is blocking in Polling mode.

Parameters:
in *bufferData

Buffer address of the data to be written

in bufferSize

Size of the data in bytes

Returns:

None.

SPI2_ByteExchange()

uint8_t SPI2_ByteExchange (uint8_t byteData)

Exchanges one byte using the SPI protocol. This function is blocking.

Parameters:
byteData

The byte to be written

Returns:

Received data byte

SPI2_ByteRead()

uint8_t SPI2_ByteRead (void )

Reads one byte of data received in the the SPI buffer.

Parameters:
None.
Returns:

Received data byte

SPI2_ByteWrite()

void SPI2_ByteWrite (uint8_t byteData)

Writes one byte to the SPI buffer.

Parameters:
byteData

The byte to be written

Returns:

None.

Note:

To prevent undefined operation of other SPI functions, ensure that the byte received in the SPI buffer is read using SPI2_ByteRead(void).

SPI2_Close()

void SPI2_Close (void )

Closes the active configuration of the SPI2 module.

Parameters:
None.
Returns:

None.

SPI2_Deinitialize()

void SPI2_Deinitialize (void )

Deinitializes the SPI2 module.

Parameters:
None.
Returns:

None.

SPI2_Initialize()

void SPI2_Initialize (void )

Initializes the SPI2 module.

Parameters:
None.
Returns:

None.

SPI2_ISR()

void SPI2_ISR (void )

Interrupt Service Routine (ISR) for the SPI2 module.

Parameters:
None.
Returns:

None.

SPI2_IsRxReady()

bool SPI2_IsRxReady (void )

Checks if the SPI2 module is ready to read data.

Parameters:
None.
Return values:
True

SPI2 module has data ready in buffer

False

SPI2 module is not ready to read data

SPI2_IsTxReady()

bool SPI2_IsTxReady (void )

Checks if the SPI2 module is ready to write data.

Parameters:
None.
Return values:
True

SPI2 module is ready to write data

False

SPI2 module is not ready to write data

SPI2_Open()

bool SPI2_Open (uint8_t spiConfigIndex)

Enables the SPI2 module with the configurations passed as the parameter. See spi2_config_names_t for the available configurations.

Parameters:
spiConfigIndex

Configuration

Return values:
True

SPI2 module is enabled successfully with the chosen configuration

False

SPI2 module is already open with another configuration

SPI2_RxCompleteCallbackRegister()

void SPI2_RxCompleteCallbackRegister (void(*)(void) CallbackHandler)

Sets the callback function to be executed at the completion of data transfer in Interrupt mode.

Parameters:
Pointer

to the function to be executed

Returns:

None.

Enumeration Type Documentation

spi2_configuration_name_t

enum enum spi2_configuration_name_t

Enumeration for the different configurations supported by the driver. A configuration is specified as parameter to SPI2_Open() and is used by the function to set SPI parameters as specified by the configuration.

MSSP2_DEFAULT

4.22.2.4.2 SPI1

This header file provides API prototypes for the SPI1 driver.

Module description

This header file provides API prototypes for the SPI1 driver.

Version: SPI1 Driver Version v5.0.0
Data structures
Enumerations
  • enum spi1_configuration_name_t { MSSP1_DEFAULT }

    Enumeration for the different configurations supported by the driver. A configuration is specified as parameter to SPI1_Open() and is used by the function to set SPI parameters as specified by the configuration.

Functions
  • void SPI1_Initialize (void)

    Initializes the SPI1 module.

  • void SPI1_Deinitialize (void)

    Deinitializes the SPI1 module.

  • bool SPI1_Open (uint8_t spiConfigIndex)

    Enables the SPI1 module with the configurations passed as the parameter. See spi1_config_names_t for the available configurations.

  • void SPI1_Close (void)

    Closes the active configuration of the SPI1 module.

  • void SPI1_BufferExchange (void *bufferData, size_t bufferSize)

    Exchanges the buffer using the SPI protocol. This function is blocking in Polling mode.

  • void SPI1_BufferWrite (void *bufferData, size_t bufferSize)

    Writes a buffer using the SPI protocol. This function is blocking in Polling mode.

  • void SPI1_BufferRead (void *bufferData, size_t bufferSize)

    Reads a buffer using the SPI protocol. This function is blocking in Polling mode.

  • uint8_t SPI1_ByteExchange (uint8_t byteData)

    Exchanges one byte using the SPI protocol. This function is blocking.

  • void SPI1_ByteWrite (uint8_t byteData)

    Writes one byte to the SPI buffer.

  • uint8_t SPI1_ByteRead (void)

    Reads one byte of data received in the the SPI buffer.

  • bool SPI1_IsRxReady (void)

    Checks if the SPI1 module is ready to read data.

  • bool SPI1_IsTxReady (void)

    Checks if the SPI1 module is ready to write data.

Function Documentation

SPI1_BufferExchange()

void SPI1_BufferExchange (void * bufferData, size_t bufferSize)

Exchanges the buffer using the SPI protocol. This function is blocking in Polling mode.

Parameters:
in,out *bufferData

Buffer address of the data to be exchanged

in bufferSize

Size of the data in bytes

Returns:

None.

SPI1_BufferRead()

void SPI1_BufferRead (void * bufferData, size_t bufferSize)

Reads a buffer using the SPI protocol. This function is blocking in Polling mode.

Parameters:
out *bufferData

Buffer address of the data to be read

in bufferSize

Size of the data in bytes

Returns:

None.

SPI1_BufferWrite()

void SPI1_BufferWrite (void * bufferData, size_t bufferSize)

Writes a buffer using the SPI protocol. This function is blocking in Polling mode.

Parameters:
in *bufferData

Buffer address of the data to be written

in bufferSize

Size of the data in bytes

Returns:

None.

SPI1_ByteExchange()

uint8_t SPI1_ByteExchange (uint8_t byteData)

Exchanges one byte using the SPI protocol. This function is blocking.

Parameters:
byteData

The byte to be written

Returns:

Received data byte

SPI1_ByteRead()

uint8_t SPI1_ByteRead (void )

Reads one byte of data received in the the SPI buffer.

Parameters:
None.
Returns:

Received data byte

SPI1_ByteWrite()

void SPI1_ByteWrite (uint8_t byteData)

Writes one byte to the SPI buffer.

Parameters:
byteData

The byte to be written

Returns:

None.

Note:

To prevent undefined operation of other SPI functions, ensure that the byte received in the SPI buffer is read using SPI1_ByteRead(void).

SPI1_Close()

void SPI1_Close (void )

Closes the active configuration of the SPI1 module.

Parameters:
None.
Returns:

None.

SPI1_Deinitialize()

void SPI1_Deinitialize (void )

Deinitializes the SPI1 module.

Parameters:
None.
Returns:

None.

SPI1_Initialize()

void SPI1_Initialize (void )

Initializes the SPI1 module.

Parameters:
None.
Returns:

None.

SPI1_IsRxReady()

bool SPI1_IsRxReady (void )

Checks if the SPI1 module is ready to read data.

Parameters:
None.
Return values:
True

SPI1 module has data ready in buffer

False

SPI1 module is not ready to read data

SPI1_IsTxReady()

bool SPI1_IsTxReady (void )

Checks if the SPI1 module is ready to write data.

Parameters:
None.
Return values:
True

SPI1 module is ready to write data

False

SPI1 module is not ready to write data

SPI1_Open()

bool SPI1_Open (uint8_t spiConfigIndex)

Enables the SPI1 module with the configurations passed as the parameter. See spi1_config_names_t for the available configurations.

Parameters:
spiConfigIndex

Configuration

Return values:
True

SPI1 module is enabled successfully with the chosen configuration

False

SPI1 module is already open with another configuration

Enumeration Type Documentation

spi1_configuration_name_t

enum enum spi1_configuration_name_t

Enumeration for the different configurations supported by the driver. A configuration is specified as parameter to SPI1_Open() and is used by the function to set SPI parameters as specified by the configuration.

MSSP1_DEFAULT

4.22.2.4.3 SPI

This header file provides API prototypes for the SPI module in Polling and Interrupt mode.

Module description

This header file provides API prototypes for the SPI module in Polling and Interrupt mode.

This header file provides type definitions for the SPI module operation in Polling mode.

This header file provides type definitions for the SPI module operation in Interrupt mode.

Version: SPI Interface Version v3.0.0 SPI Driver Version v5.0.0
Data structures

Enumeration Type Documentation

spi_status_t

enum enum spi_status_t

Enumeration for the different states of the SPI module.

Note:

The enum values are chosen with a specific bit pattern to make sure no error happens in case a single bit changes.

SPI_RESET

SPI module is in Reset state

SPI_IDLE

SPI module is ready to use

SPI_BUSY

SPI module is in use

spi_transfer_type_t

enum enum spi_transfer_type_t

Enumeration for the different transfer types of the SPI module.

Note:

The enum values are chosen with a specific bit pattern to make sure no error happens in case a single bit changes.

SPI_READ

SPI module is performing a read operation

SPI_WRITE

SPI module is performing a write operation

SPI_EXCHANGE

SPI module is performing an exchange operation

4.22.2.5 Class Documentation

4.22.2.5.1 spi_configuration_t Struct Reference

#include <spi_interrupt_types.h>

Member Data Documentation

The documentation for this struct was generated from the following files:

source/

spi_interrupt_types.h

source/

spi_polling_types.h

baud

uint8_t baud

clock

uint8_t clock

con1

uint8_t con1

con3

uint8_t con3

stat

uint8_t stat

4.22.2.5.2 spi_descriptor_t Struct Reference

#include <spi_interrupt_types.h>

Member Data Documentation

The documentation for this struct was generated from the following file:

source/

spi_interrupt_types.h

buffer

uint8_t* buffer

bufferLength

size_t bufferLength

status

spi_status_t status

transferType

spi_transfer_type_t transferType

4.22.2.5.3 SPI_INTERFACE Struct Reference

SPI driver interface object.

Detailed Description

SPI driver interface object.

SPI Driver prototypes struct.

#include <spi_interface.h>

Public Attributes

Member Data Documentation

The documentation for this struct was generated from the following file:

source/

spi_interface.h

BufferExchange

void(* BufferExchange) (void *bufferData, size_t bufferSize)

BufferRead

void(* BufferRead) (void *bufferData, size_t bufferSize)

BufferWrite

void(* BufferWrite) (void *bufferData, size_t bufferSize)

ByteExchange

uint8_t(* ByteExchange) (uint8_t byteData)

ByteRead

uint8_t(* ByteRead) (void)

ByteWrite

void(* ByteWrite) (uint8_t byteData)

Close

void(* Close) (void)

Deinitialize

void(* Deinitialize) (void)

Initialize

void(* Initialize) (void)

IsRxReady

bool(* IsRxReady) (void)

IsTxReady

bool(* IsTxReady) (void)

Open

bool(* Open) (uint8_t spiConfigIndex)

RxCompleteCallbackRegister

void(* RxCompleteCallbackRegister) (void(*callbackHandler)(void))

TxCompleteCallbackRegister

void(* TxCompleteCallbackRegister) (void(*callbackHandler)(void))

4.22.2.6 File Documentation

4.22.2.6.1 source/mssp_interrupt.c File Reference

#include <xc.h>
#include "../mssp2.h"
#include "../spi_interrupt_types.h"

Functions

  • void SPI2_Initialize (void)

    Initializes the SPI2 module.

  • void SPI2_Deinitialize (void)

    Deinitializes the SPI2 module.

  • bool SPI2_Open (uint8_t spiConfigIndex)

    Enables the SPI2 module with the configurations passed as the parameter. See spi2_config_names_t for the available configurations.

  • void SPI2_Close (void)

    Closes the active configuration of the SPI2 module.

  • void SPI2_BufferExchange (void *bufferData, size_t bufferSize)

    Exchanges the buffer using the SPI protocol. This function is blocking in Polling mode.

  • void SPI2_BufferWrite (void *bufferData, size_t bufferSize)

    Writes a buffer using the SPI protocol. This function is blocking in Polling mode.

  • void SPI2_BufferRead (void *bufferData, size_t bufferSize)

    Reads a buffer using the SPI protocol. This function is blocking in Polling mode.

  • uint8_t SPI2_ByteExchange (uint8_t byteData)

    Exchanges one byte using the SPI protocol. This function is blocking.

  • void SPI2_ByteWrite (uint8_t byteData)

    Writes one byte to the SPI buffer.

  • uint8_t SPI2_ByteRead (void)

    Reads one byte of data received in the the SPI buffer.

  • bool SPI2_IsRxReady (void)

    Checks if the SPI2 module is ready to read data.

  • bool SPI2_IsTxReady (void)

    Checks if the SPI2 module is ready to write data.

  • void SPI2_ISR (void)

    Interrupt Service Routine (ISR) for the SPI2 module.

  • void SPI2_RxCompleteCallbackRegister (void(*CallbackHandler)(void))

    Sets the callback function to be executed at the completion of data transfer in Interrupt mode.

Variable Documentation

SPI2

const struct SPI_INTERFACE SPI2

Initial value:

= {
    .Initialize = SPI2_Initialize,
    .Deinitialize = SPI2_Deinitialize,
    .Open = SPI2_Open,
    .Close = SPI2_Close,
    .BufferExchange = SPI2_BufferExchange,
    .BufferWrite = SPI2_BufferWrite,
    .BufferRead = SPI2_BufferRead,
    .ByteExchange = SPI2_ByteExchange,
    .ByteWrite = SPI2_ByteWrite,
    .ByteRead = SPI2_ByteRead,
    .IsRxReady = SPI2_IsRxReady,
    .IsTxReady = SPI2_IsTxReady,
    .RxCompleteCallbackRegister = SPI2_RxCompleteCallbackRegister,
    .TxCompleteCallbackRegister = NULL
}
spi2_configuration

const spi_configuration_t spi2_configuration[][static]

Initial value:

= {
    { 0x64, 0x4, 0x10, 0x0 }
}
spi2_descriptor

spi_descriptor_t spi2_descriptor[static]

Initial value:

= {
    .buffer         = NULL,
    .bufferLength   = 0,
    .status         = SPI_RESET
}
SPI2_RxCompleteCallback

void(* SPI2_RxCompleteCallback) (void)[static]

4.22.2.6.2 source/mssp_interrupt.h File Reference

#include "spi_interface.h"

Functions

  • void SPI2_Initialize (void)

    Initializes the SPI2 module.

  • void SPI2_Deinitialize (void)

    Deinitializes the SPI2 module.

  • bool SPI2_Open (uint8_t spiConfigIndex)

    Enables the SPI2 module with the configurations passed as the parameter. See spi2_config_names_t for the available configurations.

  • void SPI2_Close (void)

    Closes the active configuration of the SPI2 module.

  • void SPI2_BufferExchange (void *bufferData, size_t bufferSize)

    Exchanges the buffer using the SPI protocol. This function is blocking in Polling mode.

  • void SPI2_BufferWrite (void *bufferData, size_t bufferSize)

    Writes a buffer using the SPI protocol. This function is blocking in Polling mode.

  • void SPI2_BufferRead (void *bufferData, size_t bufferSize)

    Reads a buffer using the SPI protocol. This function is blocking in Polling mode.

  • uint8_t SPI2_ByteExchange (uint8_t byteData)

    Exchanges one byte using the SPI protocol. This function is blocking.

  • void SPI2_ByteWrite (uint8_t byteData)

    Writes one byte to the SPI buffer.

  • uint8_t SPI2_ByteRead (void)

    Reads one byte of data received in the the SPI buffer.

  • bool SPI2_IsRxReady (void)

    Checks if the SPI2 module is ready to read data.

  • bool SPI2_IsTxReady (void)

    Checks if the SPI2 module is ready to write data.

  • void SPI2_RxCompleteCallbackRegister (void(*CallbackHandler)(void))

    Sets the callback function to be executed at the completion of data transfer in Interrupt mode.

  • void SPI2_ISR (void)

    Interrupt Service Routine (ISR) for the SPI2 module.

Enumerations

  • enum spi2_configuration_name_t { MSSP2_DEFAULT }

    Enumeration for the different configurations supported by the driver. A configuration is specified as parameter to SPI2_Open() and is used by the function to set SPI parameters as specified by the configuration.

Variable Documentation

SPI2

const struct SPI_INTERFACE SPI2

4.22.2.6.3 source/mssp_polling.c File Reference

#include <xc.h>
#include "../mssp1.h"
#include "../spi_polling_types.h"

Functions

  • void SPI1_Initialize (void)

    Initializes the SPI1 module.

  • void SPI1_Deinitialize (void)

    Deinitializes the SPI1 module.

  • bool SPI1_Open (uint8_t spiConfigIndex)

    Enables the SPI1 module with the configurations passed as the parameter. See spi1_config_names_t for the available configurations.

  • void SPI1_Close (void)

    Closes the active configuration of the SPI1 module.

  • void SPI1_BufferExchange (void *bufferData, size_t bufferSize)

    Exchanges the buffer using the SPI protocol. This function is blocking in Polling mode.

  • void SPI1_BufferWrite (void *bufferData, size_t bufferSize)

    Writes a buffer using the SPI protocol. This function is blocking in Polling mode.

  • void SPI1_BufferRead (void *bufferData, size_t bufferSize)

    Reads a buffer using the SPI protocol. This function is blocking in Polling mode.

  • uint8_t SPI1_ByteExchange (uint8_t byteData)

    Exchanges one byte using the SPI protocol. This function is blocking.

  • void SPI1_ByteWrite (uint8_t byteData)

    Writes one byte to the SPI buffer.

  • uint8_t SPI1_ByteRead (void)

    Reads one byte of data received in the the SPI buffer.

  • bool SPI1_IsRxReady (void)

    Checks if the SPI1 module is ready to read data.

  • bool SPI1_IsTxReady (void)

    Checks if the SPI1 module is ready to write data.

Variable Documentation

spi1_configuration

const spi_configuration_t spi1_configuration[][static]

Initial value:

= {
    { 0x64, 0x0, 0x10, 0x1 }
}

4.22.2.6.4 source/mssp_polling.h File Reference

#include "spi_interface.h"

Functions

  • void SPI1_Initialize (void)

    Initializes the SPI1 module.

  • void SPI1_Deinitialize (void)

    Deinitializes the SPI1 module.

  • bool SPI1_Open (uint8_t spiConfigIndex)

    Enables the SPI1 module with the configurations passed as the parameter. See spi1_config_names_t for the available configurations.

  • void SPI1_Close (void)

    Closes the active configuration of the SPI1 module.

  • void SPI1_BufferExchange (void *bufferData, size_t bufferSize)

    Exchanges the buffer using the SPI protocol. This function is blocking in Polling mode.

  • void SPI1_BufferWrite (void *bufferData, size_t bufferSize)

    Writes a buffer using the SPI protocol. This function is blocking in Polling mode.

  • void SPI1_BufferRead (void *bufferData, size_t bufferSize)

    Reads a buffer using the SPI protocol. This function is blocking in Polling mode.

  • uint8_t SPI1_ByteExchange (uint8_t byteData)

    Exchanges one byte using the SPI protocol. This function is blocking.

  • void SPI1_ByteWrite (uint8_t byteData)

    Writes one byte to the SPI buffer.

  • uint8_t SPI1_ByteRead (void)

    Reads one byte of data received in the the SPI buffer.

  • bool SPI1_IsRxReady (void)

    Checks if the SPI1 module is ready to read data.

  • bool SPI1_IsTxReady (void)

    Checks if the SPI1 module is ready to write data.

Enumerations

  • enum spi1_configuration_name_t { MSSP1_DEFAULT }

    Enumeration for the different configurations supported by the driver. A configuration is specified as parameter to SPI1_Open() and is used by the function to set SPI parameters as specified by the configuration.

Variable Documentation

SPI1

const struct SPI_INTERFACE SPI1

4.22.2.6.5 source/spi_interface.h File Reference

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>

Data structures

Detailed Description

SPI Driver API Interface File

4.22.2.6.7 source/spi_polling_types.h File Reference

Detailed Description

SPI Type Definitions Header File