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.
Serial_TxString(&USARTD0, "Test String\r\n");
uint8_t DataByte = Serial_RxByte(&USARTD0);
#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.
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 | ) |
|
|
inlinestatic |
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 |
|
) |
| |
|
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] | 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 | ) |
|
|
inlinestatic |
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 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] | USART | Pointer to the base of the USART peripheral within the device. |
- Returns
- Boolean
true
if no characters are buffered for transmission, false
otherwise.
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] | USART | Pointer to the base of the USART peripheral within the device. |
- Returns
- Boolean
true
if a character can be queued for transmission immediately, false
otherwise.
static int16_t Serial_ReceiveByte |
( |
USART_t *const |
USART | ) |
|
|
inlinestatic |
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 |
|
) |
| |
|
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] | 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. |