AVR-GCC Libraries
Macros | Functions
UART Library <uart.h>

Detailed Description

Interrupt UART library using the built-in UART with transmit and receive circular buffers.

#include <uart.h>

This library can be used to transmit and receive data through the built in UART.

An interrupt is generated when the UART has finished transmitting or receiving a byte. The interrupt handling routines use circular buffers for buffering received and transmitted data.

The UART_RX_BUFFER_SIZE and UART_TX_BUFFER_SIZE constants define the size of the circular buffers in bytes. Note that these constants must be a power of 2. You may need to adapt these constants to your target and your application by adding CDEFS += -DUART_RX_BUFFER_SIZE=nn -DUART_TX_BUFFER_SIZE=nn to your Makefile.

Note
Based on Atmel Application Note AVR306
Author
Peter Fleury pfleu.nosp@m.ry@g.nosp@m.mx.ch http://tinyurl.com/peterfleury

Macros

#define UART_BAUD_SELECT(baudRate, xtalCpu)   (((xtalCpu) + 8UL * (baudRate)) / (16UL * (baudRate)) -1UL)
 UART Baudrate Expression. More...
 
#define UART_BAUD_SELECT_DOUBLE_SPEED(baudRate, xtalCpu)   ( ((((xtalCpu) + 4UL * (baudRate)) / (8UL * (baudRate)) -1UL)) | 0x8000)
 UART Baudrate Expression for ATmega double speed mode. More...
 
#define UART_RX_BUFFER_SIZE   32
 Size of the circular receive buffer, must be power of 2. More...
 
#define UART_TX_BUFFER_SIZE   32
 Size of the circular transmit buffer, must be power of 2. More...
 
#define UART_FRAME_ERROR   0x1000
 Framing Error by UART.
 
#define UART_OVERRUN_ERROR   0x0800
 Overrun condition by UART.
 
#define UART_PARITY_ERROR   0x0400
 Parity Error by UART.
 
#define UART_BUFFER_OVERFLOW   0x0200
 receive ringbuffer overflow
 
#define UART_NO_DATA   0x0100
 no receive data available
 
#define uart_puts_P(__s)   uart_puts_p(PSTR(__s))
 Macro to automatically put a string constant into program memory.
 
#define uart1_puts_P(__s)   uart1_puts_p(PSTR(__s))
 Macro to automatically put a string constant into program memory.
 

Functions

void uart_init (unsigned int baudrate)
 Initialize UART and set baudrate. More...
 
unsigned int uart_getc (void)
 Get received byte from ringbuffer. More...
 
void uart_putc (unsigned char data)
 Put byte to ringbuffer for transmitting via UART. More...
 
void uart_puts (const char *s)
 Put string to ringbuffer for transmitting via UART. More...
 
void uart_puts_p (const char *s)
 Put string from program memory to ringbuffer for transmitting via UART. More...
 
void uart1_init (unsigned int baudrate)
 Initialize USART1 (only available on selected ATmegas) More...
 
unsigned int uart1_getc (void)
 Get received byte of USART1 from ringbuffer. (only available on selected ATmega) More...
 
void uart1_putc (unsigned char data)
 Put byte to ringbuffer for transmitting via USART1 (only available on selected ATmega) More...
 
void uart1_puts (const char *s)
 Put string to ringbuffer for transmitting via USART1 (only available on selected ATmega) More...
 
void uart1_puts_p (const char *s)
 Put string from program memory to ringbuffer for transmitting via USART1 (only available on selected ATmega) More...
 

Macro Definition Documentation

#define UART_BAUD_SELECT (   baudRate,
  xtalCpu 
)    (((xtalCpu) + 8UL * (baudRate)) / (16UL * (baudRate)) -1UL)

UART Baudrate Expression.

Parameters
xtalCpusystem clock in Mhz, e.g. 4000000UL for 4Mhz
baudRatebaudrate in bps, e.g. 1200, 2400, 9600
#define UART_BAUD_SELECT_DOUBLE_SPEED (   baudRate,
  xtalCpu 
)    ( ((((xtalCpu) + 4UL * (baudRate)) / (8UL * (baudRate)) -1UL)) | 0x8000)

UART Baudrate Expression for ATmega double speed mode.

Parameters
xtalCpusystem clock in Mhz, e.g. 4000000UL for 4Mhz
baudRatebaudrate in bps, e.g. 1200, 2400, 9600
#define UART_RX_BUFFER_SIZE   32

Size of the circular receive buffer, must be power of 2.

You may need to adapt this constant to your target and your application by adding CDEFS += -DUART_RX_BUFFER_SIZE=nn to your Makefile.

#define UART_TX_BUFFER_SIZE   32

Size of the circular transmit buffer, must be power of 2.

You may need to adapt this constant to your target and your application by adding CDEFS += -DUART_TX_BUFFER_SIZE=nn to your Makefile.

Function Documentation

void uart_init ( unsigned int  baudrate)

Initialize UART and set baudrate.

Parameters
baudrateSpecify baudrate using macro UART_BAUD_SELECT()
Returns
none
unsigned int uart_getc ( void  )

Get received byte from ringbuffer.

Returns in the lower byte the received character and in the higher byte the last receive error. UART_NO_DATA is returned when no data is available.

Returns
lower byte: received byte from ringbuffer
higher byte: last receive status
  • 0 successfully received data from UART
  • UART_NO_DATA
    no receive data available
  • UART_BUFFER_OVERFLOW
    Receive ringbuffer overflow. We are not reading the receive buffer fast enough, one or more received character have been dropped
  • UART_OVERRUN_ERROR
    Overrun condition by UART. A character already present in the UART UDR register was not read by the interrupt handler before the next character arrived, one or more received characters have been dropped.
  • UART_FRAME_ERROR
    Framing Error by UART
void uart_putc ( unsigned char  data)

Put byte to ringbuffer for transmitting via UART.

Parameters
databyte to be transmitted
Returns
none
void uart_puts ( const char *  s)

Put string to ringbuffer for transmitting via UART.

The string is buffered by the uart library in a circular buffer and one character at a time is transmitted to the UART using interrupts. Blocks if it can not write the whole string into the circular buffer.

Parameters
sstring to be transmitted
Returns
none
void uart_puts_p ( const char *  s)

Put string from program memory to ringbuffer for transmitting via UART.

The string is buffered by the uart library in a circular buffer and one character at a time is transmitted to the UART using interrupts. Blocks if it can not write the whole string into the circular buffer.

Parameters
sprogram memory string to be transmitted
Returns
none
See also
uart_puts_P
void uart1_init ( unsigned int  baudrate)

Initialize USART1 (only available on selected ATmegas)

See also
uart_init
unsigned int uart1_getc ( void  )

Get received byte of USART1 from ringbuffer. (only available on selected ATmega)

See also
uart_getc
void uart1_putc ( unsigned char  data)

Put byte to ringbuffer for transmitting via USART1 (only available on selected ATmega)

See also
uart_putc
void uart1_puts ( const char *  s)

Put string to ringbuffer for transmitting via USART1 (only available on selected ATmega)

See also
uart_puts
void uart1_puts_p ( const char *  s)

Put string from program memory to ringbuffer for transmitting via USART1 (only available on selected ATmega)

See also
uart_puts_p