LUFA Library  130303
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Serial USART Peripheral Driver (AVR8)

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 (void)
 
static void Serial_Init (const uint32_t BaudRate, const bool DoubleSpeed)
 
static bool Serial_IsCharReceived (void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE
 
static int16_t Serial_ReceiveByte (void) ATTR_ALWAYS_INLINE
 
static void Serial_SendByte (const char DataByte) ATTR_ALWAYS_INLINE
 
void Serial_SendData (const void *Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1)
 
void Serial_SendString (const char *StringPtr) ATTR_NON_NULL_PTR_ARG(1)
 
void Serial_SendString_P (const char *FlashStringPtr) ATTR_NON_NULL_PTR_ARG(1)
 

Detailed Description

Module Description

On-chip serial USART driver for the 8-bit 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(9600, false);
// Send a string through the USART
Serial_SendString("Test String\r\n");
// Send a raw byte through the USART
// Receive a byte through the USART (or -1 if no data received)
int16_t DataByte = Serial_ReceiveByte();

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]BaudTarget 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]BaudTarget 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]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.
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]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.
static void Serial_Disable ( void  )
inlinestatic

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

static void Serial_Init ( 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]BaudRateSerial baud rate, in bits per second.
[in]DoubleSpeedEnables double speed mode when set, halving the sample time to double the baud rate.
static bool Serial_IsCharReceived ( void  )
inlinestatic

Indicates whether a character has been received through the USART.

Returns
Boolean true if a character has been received, false otherwise.
static int16_t Serial_ReceiveByte ( void  )
inlinestatic

Receives the next byte from the USART.

Returns
Next byte received from the USART, or a negative value if no byte has been received.
static void Serial_SendByte ( const char  DataByte)
inlinestatic

Transmits a given byte through the USART.

Parameters
[in]DataByteByte to transmit through the USART.
void Serial_SendData ( const void *  Buffer,
uint16_t  Length 
)

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

Parameters
[in]BufferPointer to a buffer containing the data to send.
[in]LengthLength of the data to send, in bytes.
void Serial_SendString ( const char *  StringPtr)

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

Parameters
[in]StringPtrPointer to a string located in SRAM space.
void Serial_SendString_P ( const char *  FlashStringPtr)

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

Parameters
[in]FlashStringPtrPointer to a string located in program space.