LUFA Library  151115

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 bool Serial_IsSendComplete (void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE
 
static bool Serial_IsSendReady (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. 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.
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 bool Serial_IsSendComplete ( void  )
inlinestatic

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

Returns
Boolean true if no characters are buffered for transmission, false otherwise.
static bool Serial_IsSendReady ( void  )
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.

Returns
Boolean true if a character can be queued for transmission immediately, 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.

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]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.