UART Example

This page contains information describing the UART example. Code examples can be found within the example folder within the repository.

/********************************************************
 *   File Name: uart_ex.c
 *
 *   Description:
 *              Main file
 *
 *
 *********************************************************/

/*************************************************************************
 System Includes
 ************************************************************************/
#include "sublibinal.h"
#include "sublibinal_config.h"

//forward declarations
void timer_callback(void);

/*************************************************************************
 Main Function
 ************************************************************************/
int main(void) {

    //buffer for uart ISRs
    uint8 uart_tx_buffer[128], uart_rx_buffer[128];

    //structures for configuring peripherals
    UART_Config uart_config = {0};
    Timer_Config timer_config = {0};
    
    //temp buffer
    uint8 blah;

    //setup peripherals
    timer_config.frequency = 1000; //Set the timer to operate at 1KHz
    timer_config.pbclk = PB_CLK;
    timer_config.which_timer = Timer_1; //Use timer 1
    timer_config.callback = &timer_callback; //Hand a callback function for the ISR functionality
    timer_config.enabled = 1; //Enable the timer
    initialize_Timer(timer_config); //Initialize the timer module

    uart_config.which_uart = UART_CH_1; //Specify UART channel 1 for us
    uart_config.pb_clk = PB_CLK; //Tell the module the speed of our clock
    uart_config.speed = 115200; //Specify the buadrate to be 115.2k
    uart_config.rx_buffer_ptr = uart_rx_buffer; //Hand a pointer to some memory for the UART
    uart_config.rx_buffer_size = sizeof(uart_rx_buffer); //Tell the UART the size of this memory
    uart_config.rx_pin = Pin_RPB13; //set RPB13 as the rx pin for UART
	uart_config.rx_en = 1; //Enable receiving
    uart_config.tx_buffer_ptr = uart_tx_buffer; //Hand a data pointer to the transmission buffer
    uart_config.tx_buffer_size = sizeof(uart_tx_buffer); //Tell the UART the size of the transmission buffer
 	uart_config.tx_pin = Pin_RPB15; //specify pin RPB15 for the UART tx pin
 	uart_config.tx_en = 1; //Enable transmission
    initialize_UART(uart_config); //Initialize the UART module
 
    //Global interrupt enable. Do this last!
	enable_Interrupts();

    while (1) {
        //one byte is put in the 'blah' buffer by calling receive_UART
        if (receive_UART(UART_CH_1, &blah, sizeof(blah)) == ERR_NO_ERR) //if we successfully pulled out some data
        {
            //do something with the data
            send_UART(UART_CH_1, &blah, sizeof(blah));
        }
    }

    return 0;
}

void timer_callback(void)
{
    uint8 data[3];

    data[0] = 'a';
    data[1] = 'b';
    data[2] = 'c';

    //send some uart data
    send_UART(UART_CH_1, data, sizeof(data));

}

In this program, we configure the UART for both transmission and receiving. The first important part of the program is the UART_Config declaration

`UART_Config uart_config = {0};'

This portion is extremely important as it ensures that all parameters are initialized to NULL. In the program, we have not explicitly set the UART config callback parameters. If the structure is not initialized to NULL, these values could contain some value causing a break in program execution. It's important that these values either contain pointers to functions or are defined as NULL.

The next portion of code we will discuss is the parameters specified.

uart_config.which_uart = UART_CH_1; //Specify UART channel 1 for us
    uart_config.pb_clk = PB_CLK; //Tell the module the speed of our clock
    uart_config.speed = 115200; //Specify the buadrate to be 115.2k
    uart_config.rx_buffer_ptr = uart_rx_buffer; //Hand a pointer to some memory for the UART
    uart_config.rx_buffer_size = sizeof(uart_rx_buffer); //Tell the UART the size of this memory
    uart_config.rx_en = 1; //Enable receiving
    uart_config.tx_buffer_ptr = uart_tx_buffer; //Hand a data pointer to the transmission buffer
    uart_config.tx_buffer_size = sizeof(uart_tx_buffer); //Tell the UART the size of the transmission buffer
    uart_config.tx_en = 1; //Enable transmission
    initialize_UART(uart_config); //Initialize the UART module

In this section, we specify that we will be configuring UART channel 1 for transmission and receiving. We specify the peripheral bus clock rate so that the proper baud rate may be calculated and then specify what baud rate we would like to transmit and receive at. The initialization function properly configures the microcontroller to talk at the specified baud rate with the specified clock speed. We provide pointers to transmission and receive buffers and specify the size in bytes that these buffers point to. We finally initialize the UART and configure it for our use.

 while (1) {
        //one byte is put in the 'blah' buffer by calling receive_UART
        if (receive_UART(UART_CH_1, &blah, sizeof(blah)) == ERR_NO_ERR) //if we successfully pulled out some data
        {
            //do something with the data
            send_UART(UART_CH_1, &blah, sizeof(blah));
        }
    }

This code section specifies how UART may be received. In the if statement, we specify that we would like to read 1 byte of data into the blah variable. If we succeed in reading a byte of data, we then choose to transmit that piece of data back onto the same channel. Effectively, the microcontroller will echo any data that it receives back tot he sender utilizing this code. It should be noted that a device may be initialized in the middle of a packet sending and there is no guarantee that whole packets will be received in the correct order. To ensure order, please utilize the packetizer peripheral library.

void timer_callback(void)
{
    uint8 data[3];

    data[0] = 'a';
    data[1] = 'b';
    data[2] = 'c';

    //send some uart data
    send_UART(UART_CH_1, data, sizeof(data));

}

In the timer callback function, we construct an array of information to send over the UART. We then call the send_UART function to transmit all pieces of data. It is worth noting that the data array may leave scope and the UART will still successfully transmit the information because the data is copied to an internal buffer in the send_UART function.