LUFA Library

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 (USART_t *USART, FILE *Stream)
 
void Serial_CreateStream (USART_t *USART, 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 bool Serial_IsSendComplete (USART_t *const USART) ATTR_ALWAYS_INLINE ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1)
 
static bool Serial_IsSendReady (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

◆ SERIAL_2X_UBBRVAL

#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]BaudTarget serial UART baud rate.
Returns
Closest UBRR register value for the given UART frequency.

◆ SERIAL_UBBRVAL

#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]BaudTarget serial UART baud rate.
Returns
Closest UBRR register value for the given UART frequency.

Function Documentation

◆ Serial_CreateBlockingStream()

void Serial_CreateBlockingStream ( USART_t *  USART,
FILE *  Stream 
)

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

Parameters
[in,out]USARTPointer to the base of the USART peripheral within the device.
[in,out]StreamPointer 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.

◆ Serial_CreateStream()

void Serial_CreateStream ( USART_t *  USART,
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]USARTPointer to the base of the USART peripheral within the device.
[in,out]StreamPointer 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.

◆ Serial_Disable()

static void Serial_Disable ( USART_t *const  USART)
inlinestatic

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

Parameters
[in,out]USARTPointer to the base of the USART peripheral within the device.

◆ Serial_Init()

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

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]USARTPointer to the base of the USART peripheral within the device.
[in]BaudRateSerial baud rate, in bits per second. This should be the target baud rate regardless of the DoubleSpeed parameter's value.
[in]DoubleSpeedEnables double speed mode when set, halving the sample time to double the baud rate.

◆ Serial_IsCharReceived()

static bool Serial_IsCharReceived ( USART_t *const  USART)
inlinestatic

Indicates whether a character has been received through the USART.

Parameters
[in,out]USARTPointer to the base of the USART peripheral within the device.
Returns
Boolean true if a character has been received, false otherwise.

◆ Serial_IsSendComplete()

static bool Serial_IsSendComplete ( USART_t *const  USART)
inlinestatic

Indicates whether the hardware USART transmit buffer is completely empty, indicating all pending transmissions have completed.

Parameters
[in,out]USARTPointer to the base of the USART peripheral within the device.
Returns
Boolean true if no characters are buffered for transmission, false otherwise.

◆ Serial_IsSendReady()

static bool Serial_IsSendReady ( USART_t *const  USART)
inlinestatic

Indicates whether there is hardware buffer space for a new transmit on the USART. This function can be used to determine if a call to Serial_SendByte() will block in advance.

Parameters
[in,out]USARTPointer to the base of the USART peripheral within the device.
Returns
Boolean true if a character can be queued for transmission immediately, false otherwise.

◆ Serial_ReceiveByte()

static int16_t Serial_ReceiveByte ( USART_t *const  USART)
inlinestatic

Receives the next byte from the USART.

Parameters
[in,out]USARTPointer 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.

◆ Serial_SendByte()

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

Transmits a given byte through the USART.

Note
If no buffer space is available in the hardware USART, this function will block. To check if space is available before calling this function, see Serial_IsSendReady().
Parameters
[in,out]USARTPointer to the base of the USART peripheral within the device.
[in]DataByteByte to transmit through the USART.

◆ Serial_SendData()

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]USARTPointer to the base of the USART peripheral within the device.
[in]BufferPointer to a buffer containing the data to send.
[in]LengthLength of the data to send, in bytes.

◆ Serial_SendString()

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

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

Parameters
[in,out]USARTPointer to the base of the USART peripheral within the device.
[in]StringPtrPointer to a string located in SRAM space.

◆ Serial_SendString_P()

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]USARTPointer to the base of the USART peripheral within the device.
[in]FlashStringPtrPointer to a string located in program space.