Chapter 4

USART

This module provides basic buffered USART support for Atmel AVR microcontrollers. It support microcontrollers with 1 or 2 USART ports.

This module separates the actions of receive and transmit into independent parts. This way, if you will only be receiving or only be transmitting, you only need to link in and initialize the relevant part.

4.1  Usage

To use the USART functions for microcontrollers that only support one USART port, use this:

  #include <uart.h>

and use the function names as shown below.

To use the USART functions for microcontrollers that support two USART ports, use this:

  #include <uart0.h>
  #include <uart1.h>

and append the digit 0 or 1 to the function names shown below to pick the appropriate port. For example, the following initializes the transmit functions of USART port 1 and transmits a single character:

  uart_tx_init1();
  uart_tx_char1('x');

4.2  USART Receive Functions

void uart_rx_init(void)   function

This function initializes the receive part of this module. This entails enabling the USART receive line and enabling the USART receive interrupt. Also, it automatically links in the default receive interrupt service routine from the library.

void uart_rx_init_no_isr(void)   inline

This function is identical to uart_rx_init(), but it does not link in the default receive interrupt service routine. In this case, you must provide your own interrupt service routine.

void uart_rx_clear(void)   function

This function clears the receive buffer.

int uart_rx_char(void)   function

This function takes a character from the receive buffer and returns it. If the receive buffer is empty, this function returns -1.

4.3  USART Transmit Functions

void uart_tx_init(void)   function

This function initializes the transmit part of this module. This entails enabling the USART transmit line. Also, it automatically links in the default transmit interrupt service routine from the library.

void uart_tx_init_no_isr(void)   inline

This function is identical to uart_tx_init(), but it does not link in the default transmit interrupt service routine. In this case, you must provide your own interrupt service routine.

void uart_tx_clear(void)   function

This function clears the transmit buffer.

bool uart_tx_char(char c)   function

If there is room in the transmit buffer, this function places the given character, c, into the transmit buffer. If the transmit interrupt is disabled, it enables the interrupt which starts the transmission process. If the transmit interrupt is already enabled, a transmission is already in progress and the character will eventually be transmitted. The function then returns true.

If the transmit buffer is full when this function is called, it does nothing and returns false.

bool uart_tx_str(const char* str)   function

If there is room in the transmit buffer, this function places the given string, str, into the transmit buffer. If the transmit interrupt is disabled, it enables the interrupt which starts the transmission process. If the transmit interrupt is already enabled, a transmission is already in progress and the character will eventually be transmitted. The function then returns true.

If the transmit buffer is full when this function is called, it does nothing and returns false.

bool uart_tx_str_P(PGM_P str)   function

This function is analogous to uart_tx_str(), except that instead of taking a string in RAM, str points to a string stored in the program space.

const char* uart_tx_str_partial(const char* str)   function

This function places into the transmit buffer as many characters from the given string, str, as will fit.

If any characters were placed into the transmit buffer, and the transmit interrupt is disabled, it enables the interrupt which starts the transmission process. If the transmit interrupt is already enabled, a transmission is already in progress and any characters placed into the transmit buffer will eventually be transmitted.

If all the characters in str were placed into the transmit buffer, then this function returns 0. Otherwise, it returns a pointer to the characters in the string that were not placed into the transmit buffer. This way, you can use the returned string to try again latter.

PGM_P uart_tx_str_partial_P(PGM_P str)   function

This function is analogous to uart_tx_str_partial(), except that instead of taking a string in RAM, str points to a string stored in the program space. Also, it returns a pointer to the remaining characters stored in the program space.

bool uart_tx_data(const char* data, uint8_t count)   function

This function is analogous to uart_tx_str(), except that instead of taking '\0' terminated string, it takes a character pointer to data, data, and the number of characters to transmit, count. If all count characters will not fit in the transmit buffer, this function returns false. Otherwise, it returns true.

uint16_t uart_generate_ubrr(uint32_t fosc, uint32_t baud)   function

This function calculates the closest UBRRvalue for the given oscillator frequency, fosc, and the desired baud rate, baud.