| LUFA Library 140302 |

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Macros | Functions
Serial USART Peripheral Driver (XMEGA)
Serial USART Driver - LUFA/Drivers/Peripheral/Serial.h

## Macros
#define | SERIAL_2X_UBBRVAL(Baud) ((((F_CPU / 8) + (Baud / 2)) / (Baud)) - 1)
#define | SERIAL_UBBRVAL(Baud) ((((F_CPU / 16) + (Baud / 2)) / (Baud)) - 1)

## Functions
void | Serial_CreateBlockingStream (FILE *Stream)
void | Serial_CreateStream (FILE *Stream)
static void | Serial_Disable (USART_t *const USART) ATTR_ALWAYS_INLINE ATTR_NON_NULL_PTR_ARG(1)
static void | Serial_Init (USART_t *const USART, const uint32_t BaudRate, const bool DoubleSpeed) ATTR_NON_NULL_PTR_ARG(1)
static bool | Serial_IsCharReceived (USART_t *const USART) ATTR_ALWAYS_INLINE ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1)
static int16_t | Serial_ReceiveByte (USART_t *const USART) ATTR_ALWAYS_INLINE ATTR_NON_NULL_PTR_ARG(1)
static void | Serial_SendByte (USART_t *const USART, const char DataByte) ATTR_ALWAYS_INLINE ATTR_NON_NULL_PTR_ARG(1)
void | Serial_SendData (USART_t *const USART, const void *Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1)
void | Serial_SendString (USART_t *const USART, const char *StringPtr) ATTR_NON_NULL_PTR_ARG(1)
void | Serial_SendString_P (USART_t *const USART, const char *FlashStringPtr) ATTR_NON_NULL_PTR_ARG(1)

## Detailed Description

# Module Description

On-chip serial USART driver for the XMEGA AVR microcontrollers.

Note
  This file should not be included directly. It is automatically included as needed by the USART driver dispatch header located in LUFA/Drivers/Peripheral/Serial.h.

# Example Usage

The following snippet is an example of how this module may be used within a typical application.

// Initialize the serial USART driver before first use, with 9600 baud (and no double-speed mode)
Serial_Init(&USARTD0, 9600, false);
// Send a string through the USART
Serial_TxString(&USARTD0, "Test String\r\n");
// Receive a byte through the USART
uint8_t DataByte = Serial_RxByte(&USARTD0);

## Macro Definition Documentation

#define SERIAL_2X_UBBRVAL | ( |  | Baud | ) | ((((F_CPU / 8) + (Baud / 2)) / (Baud)) - 1)

Macro for calculating the baud value from a given baud rate when the `U2X` (double speed) bit is set.

Parameters

  [in] | Baud | Target serial UART baud rate.

Returns
  Closest UBRR register value for the given UART frequency.

#define SERIAL_UBBRVAL | ( |  | Baud | ) | ((((F_CPU / 16) + (Baud / 2)) / (Baud)) - 1)

Macro for calculating the baud value from a given baud rate when the `U2X` (double speed) bit is not set.

Parameters

  [in] | Baud | Target serial UART baud rate.

Returns
  Closest UBRR register value for the given UART frequency.

## Function Documentation

void Serial_CreateBlockingStream | ( | FILE * | Stream | ) |

Identical to Serial_CreateStream(), except that reads are blocking until the calling stream function terminates the transfer.

Parameters

  [in,out] | Stream | Pointer to a FILE structure where the created stream should be placed, if `NULL`, `stdout` and `stdin` will be configured to use the USART.

Precondition
  The USART must first be configured via a call to Serial_Init() before the stream is used.

void Serial_CreateStream | ( | FILE * | Stream | ) |

Creates a standard character stream from the USART so that it can be used with all the regular functions in the avr-libc `<stdio.h>` library that accept a `FILE` stream as a destination (e.g. `fprintf`). The created stream is bidirectional and can be used for both input and output functions.

Reading data from this stream is non-blocking, i.e. in most instances, complete strings cannot be read in by a single fetch, as the endpoint will not be ready at some point in the transmission, aborting the transfer. However, this may be used when the read data is processed byte-per-bye (via `getc()`) or when the user application will implement its own line buffering.

Parameters

  [in,out] | Stream | Pointer to a FILE structure where the created stream should be placed, if `NULL`, `stdout` and `stdin` will be configured to use the USART.

Precondition
  The USART must first be configured via a call to Serial_Init() before the stream is used.

static void Serial_Disable | ( | USART_t *const | USART | ) |
| inline static

Turns off the USART driver, disabling and returning used hardware to their default configuration.

Parameters

  [in,out] | USART | Pointer to the base of the USART peripheral within the device.

static void Serial_Init | ( | USART_t *const | USART,
|  | const uint32_t | BaudRate,
|  | const bool | DoubleSpeed
| ) |  |
| inline static

Initializes the USART, ready for serial data transmission and reception. This initializes the interface to standard 8-bit, no parity, 1 stop bit settings suitable for most applications.

Parameters

  [in,out] | USART | Pointer to the base of the USART peripheral within the device.
  [in] | BaudRate | Serial baud rate, in bits per second.
  [in] | DoubleSpeed | Enables double speed mode when set, halving the sample time to double the baud rate.

static bool Serial_IsCharReceived | ( | USART_t *const | USART | ) |
| inline static

Indicates whether a character has been received through the USART.

Parameters

  [in,out] | USART | Pointer to the base of the USART peripheral within the device.

Returns
  Boolean `true` if a character has been received, `false` otherwise.

static int16_t Serial_ReceiveByte | ( | USART_t *const | USART | ) |
| inline static

Receives the next byte from the USART.

Parameters

  [in,out] | USART | Pointer to the base of the USART peripheral within the device.

Returns
  Next byte received from the USART, or a negative value if no byte has been received.

static void Serial_SendByte | ( | USART_t *const | USART,
|  | const char | DataByte
| ) |  |
| inline static

Transmits a given byte through the USART.

Parameters

  [in,out] | USART | Pointer to the base of the USART peripheral within the device.
  [in] | DataByte | Byte to transmit through the USART.

void Serial_SendData | ( | USART_t *const | USART,
|  | const void * | Buffer,
|  | uint16_t | Length
| ) |  |

Transmits a given buffer located in SRAM memory through the USART.

Parameters

  [in,out] | USART | Pointer to the base of the USART peripheral within the device.
  [in] | Buffer | Pointer to a buffer containing the data to send.
  [in] | Length | Length of the data to send, in bytes.

void Serial_SendString | ( | USART_t *const | USART,
|  | const char * | StringPtr
| ) |  |

Transmits a given string located in SRAM memory through the USART.

Parameters

  [in,out] | USART | Pointer to the base of the USART peripheral within the device.
  [in] | StringPtr | Pointer to a string located in SRAM space.

void Serial_SendString_P | ( | USART_t *const | USART,
|  | const char * | FlashStringPtr
| ) |  |

Transmits a given string located in program space (FLASH) through the USART.

Parameters

  [in,out] | USART | Pointer to the base of the USART peripheral within the device.
  [in] | FlashStringPtr | Pointer to a string located in program space.