2.124 Universal Synchronous Asynchronous Receiver Transceiver (USART)

Using The Library

Blocking Mode

#define RX_BUFFER_SIZE 10
char message[] = "USART Example in blocking mode";
char receiveBuffer[RX_BUFFER_SIZE] = {0};
USART_ERROR errorStatus;
char rxData = 0;

int main ( void )
{    
    /* Initialize all modules */
    SYS_Initialize ( NULL );

    /* Transmit buffer*/
    USART1_Write(message, sizeof(message));
	
	/* Wait for a character to be received */
	while(USART1_ReceiverIsReady() == false);
		
	if(USART1_ErrorGet() == USART_ERROR_NONE)
	{
		/* Read a byte */
		rxData = USART1_ReadByte();
	}
	
	/* Receive buffer */
    if (USART1_Read(receiveBuffer, RX_BUFFER_SIZE)) == false)
	{
		/* Read failed, get the error */
		errorStatus USART1_ErrorGet();
		
		/* Handle the error */
	}
    else
	{
		/* Transmit the received buffer*/
		USART1_Write(receiveBuffer, RX_BUFFER_SIZE);
	}

	...

    /* Execution should not come here during normal operation */

    return ( EXIT_FAILURE );
}

Non-blocking Mode

#define RX_BUFFER_SIZE 10

char message[] = "**** Non-blocking Transfer with the interrupt  ****\r\n\
**** Type 10 characters. The received characters are echoed back ****\r\n";

char messageError[] = "**** USART error occurred ****\r\n";

char receiveBuffer[RX_BUFFER_SIZE] = {0};
char echoBuffer[RX_BUFFER_SIZE+4] = {0};

bool errorStatus = false;
bool writeStatus = false;
bool readStatus = false;

void APP_WriteCallback(uintptr_t context)
{
    writeStatus = true;
}

void APP_ReadCallback(uintptr_t context)
{
    if(USART1_ErrorGet() != USART_ERROR_NONE)
    {
        /* ErrorGet clears errors, set error flag to notify console */
        errorStatus = true;
    }
    else
    {
        readStatus = true;
    }
}

int main ( void )
{
    /* Initialize all modules */
    SYS_Initialize ( NULL );

    /* Register callback functions and send start message */
    USART1_WriteCallbackRegister(APP_WriteCallback, 0);
    USART1_ReadCallbackRegister(APP_ReadCallback, 0);
    USART1_Write(&message[0], sizeof(message));

    while ( true )
    {
        if(errorStatus == true)
        {
            /* Send error message to console */
            errorStatus = false;
            USART1_Write(&messageError[0], sizeof(messageError));
        }
        else if(readStatus == true)
        {
            /* Echo back received buffer and Toggle LED */
            readStatus = false;

            echoBuffer[0] = '\n';
            echoBuffer[1] = '\r';
            memcpy(&echoBuffer[2], receiveBuffer,sizeof(receiveBuffer));
            echoBuffer[RX_BUFFER_SIZE+2] = '\n';
            echoBuffer[RX_BUFFER_SIZE+3] = '\r';

            USART1_Write(&echoBuffer[0], sizeof(echoBuffer));
        }
        else if(writeStatus == true)
        {
            /* Submit buffer to read user data */
            writeStatus = false;
            USART1_Read(&receiveBuffer[0], sizeof(receiveBuffer));
        }
        else
        {
            /* Repeat the loop */
            ;
        }
    }

    /* Execution should not come here during normal operation */

    return ( EXIT_FAILURE );
}

Ring buffer Mode

uint8_t txBuffer[50];
uint8_t rxBuffer[10];
volatile uint32_t nBytesRead = 0;
volatile bool txThresholdEventReceived = false;
volatile bool rxThresholdEventReceived = false;

void USARTReadEventHandler(USART_EVENT event, uintptr_t context )
{
    uint32_t nBytesAvailable = 0;
    
    if (event == USART_EVENT_READ_THRESHOLD_REACHED)
    {
        /* Receiver should atleast have the thershold number of bytes in the ring buffer */
        nBytesAvailable = USART1_ReadCountGet();
        
        nBytesRead += USART1_Read((uint8_t*)&rxBuffer[nBytesRead], nBytesAvailable);                          
    }
}

void USARTWriteEventHandler(USART_EVENT event, uintptr_t context )
{
    txThresholdEventReceived = true;
}

int main ( void )
{
    uint32_t nBytes = 0;        
    
    /* Initialize all modules */
    SYS_Initialize ( NULL );          
    
    /* Register a callback for write events */
    USART1_WriteCallbackRegister(USARTWriteEventHandler, (uintptr_t) NULL);
    
    /* Register a callback for read events */
    USART1_ReadCallbackRegister(USARTReadEventHandler, (uintptr_t) NULL);              
    
    /* Print the size of the read buffer on the terminal */
    nBytes = sprintf((char*)txBuffer, "RX Buffer Size = %d\r\n", (int)USART1_ReadBufferSizeGet());
    
    USART1_Write((uint8_t*)txBuffer, nBytes);  
    
    /* Print the size of the write buffer on the terminal */
    nBytes = sprintf((char*)txBuffer, "TX Buffer Size = %d\r\n", (int)USART1_WriteBufferSizeGet());
    
    USART1_Write((uint8_t*)txBuffer, nBytes);    
    
    USART1_Write((uint8_t*)"Adding 10 characters to the TX buffer - ", sizeof("Adding 10 characters to the TX buffer - "));    
    
    /* Wait for all bytes to be transmitted out */
    while (USART1_WriteCountGet() != 0);    
    
    USART1_Write((uint8_t*)"0123456789", 10);           
        
    /* Print the amount of free space available in the TX buffer. This should be 10 bytes less than the configured write buffer size. */
    nBytes = sprintf((char*)txBuffer, "\r\nFree Space in Transmit Buffer = %d\r\n", (int)USART1_WriteFreeBufferCountGet());

    USART1_Write((uint8_t*)txBuffer, nBytes);    
    
    /* Let's enable notifications to get notified when the TX buffer is empty */
    USART1_WriteThresholdSet(USART1_WriteBufferSizeGet());   
    
    /* Enable notifications */
    USART1_WriteNotificationEnable(true, false);
   
    /* Wait for the TX buffer to become empty. Flag "txThresholdEventReceived" is set in the callback. */
    while (txThresholdEventReceived == false);
    
    txThresholdEventReceived = false;    
    
    /* Disable TX notifications */
    USART1_WriteNotificationEnable(false, false);
    
    USART1_Write((uint8_t*)"Enter 10 characters. The received characters are echoed back. \r\n>", sizeof("Enter 10 characters. The received characters are echoed back. \r\n>"));               
            
    /* Wait till 10 (or more) characters are received */
    while (USART1_ReadCountGet() < 10);
    
    /* At-least 10 characters are available in the RX buffer. Read out into the application buffer */
    USART1_Read((uint8_t*)rxBuffer, 10);  
    
    /* Echo the received data */
    USART1_Write((uint8_t*)rxBuffer, 10);    
    
    /* Now demonstrating receiver notifications */
    USART1_Write((uint8_t*)"\r\n Now turning on RX notifications \r\n>", sizeof("\r\n Now turning on RX notifications \r\n>"));
    
    /* For demonstration purpose, set a threshold value to receive a callback after every 5 characters are received */
    USART1_ReadThresholdSet(5);
    
    /* Enable RX event notifications */
    USART1_ReadNotificationEnable(true, false);
                   
    while(1)
    {
        /* Wait until at-least 10 characters are entered by the user */
        while (nBytesRead < 10);    
    
        /* Echo the received data */
        USART1_Write((uint8_t*)rxBuffer, nBytesRead);
        
        USART1_Write((uint8_t*)"\r\n>", 3);

        nBytesRead = 0;
    }

    /* Execution should not come here during normal operation */

    return ( EXIT_FAILURE );
}

SPI Mode

The SPI PLIB supports master mode

SPI master mode

In SPI master mode, the PLIB can be configured to run in blocking mode or non-blocking mode. In blocking mode the peripheral interrupt is disabled and the transfer API blocks until the transfer is complete. In non-blocking mode, the peripheral interrupt is enabled. The transfer API initiates the transfer and returns immediately. The transfer is completed from the peripheral interrupt. Application can either use a callback to get notified when the transfer is complete or can use the IsBusy API to check the completion status.

SPI Master in blocking (peripheral interrupt disabled) mode

// Following code demonstrates SPI self loopback with the PLIB configured in blocking mode
uint8_t txData[]  = "SELF LOOPBACK FOR SPI!";
uint8_t rxData[sizeof(txData)];

int main ( void )
{
    /* Initialize all modules */
    SYS_Initialize ( NULL );
               
    /* SPI Write Read */
    USART1_SPI_WriteRead(&txData[0], sizeof(txData), &rxData[0], sizeof(rxData));

    /* Compare received data with the transmitted data */
    if ((memcmp(txData, rxData, sizeof(txData)) == 0))
    {
        /* Pass: Received data is same as transmitted data */        
    }
    else
    {       
        /* Fail: Received data is not same as transmitted data */
    }

    while ( true )
    { 	
    }

    /* Execution should not come here during normal operation */

    return ( EXIT_FAILURE );
}

SPI Master in non-blocking (peripheral interrupt enabled) mode

// Following code demonstrates SPI self loopback with the PLIB configured in non-blocking mode

uint8_t txData[]  = "SELF LOOPBACK FOR SPI!";
uint8_t rxData[sizeof(txData)];
volatile bool transferStatus = false;

/* This function will be called by SPI PLIB when transfer is completed */
void APP_SPI_Callback(uintptr_t context )
{
    transferStatus = true;
}

int main ( void )
{
    /* Initialize all modules */
    SYS_Initialize ( NULL );

    /* Register callback function   */
    USART1_SPI_CallbackRegister(APP_SPI_Callback, 0);
   
    /* SPI Write Read */
    USART1_SPI_WriteRead(&txData[0], sizeof(txData), &rxData[0], sizeof(rxData));
	
	while (1)
	{
		/* Perform other tasks here ...*/
		
		/* Check if transfer has completed */
		if(transferStatus == true)
		{
			/* Compare received data with the transmitted data */
			if(memcmp(txData, rxData, sizeof(txData)) == 0)
			{
				/* Pass: Received data is same as transmitted data */		
			}
			else
			{   
				/* Fail: Received data is not same as transmitted data */		
			}   
		}		        
	}
    
}

Library Interface

USART peripheral library provides the following interfaces:

USART Mode

Functions

Data types and constants

SPI Mode

Functions

Data types and constants