Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
SAM Serial USART (SERCOM USART) Driver

This driver for Atmel® | SMART ARM®-based microcontrollers provides an interface for the configuration and management of the SERCOM module in its USART mode to transfer or receive USART data frames.

The following driver API modes are covered by this manual:

The following peripheral is used by this module:

The following devices can use this module:

The outline of this documentation is as follows:

Prerequisites

To use the USART you need to have a GCLK generator enabled and running that can be used as the SERCOM clock source. This can either be configured in conf_clocks.h or by using the system clock driver.

Module Overview

This driver will use one (or more) SERCOM interface(s) in the system and configure it to run as a USART interface in either synchronous or asynchronous mode.

Driver Feature Macro Definition

Driver Feature Macro Supported devices
FEATURE_USART_SYNC_SCHEME_V2 SAM D21/R21/D09/D10/D11/L21/L22/DA1/C20/C21/R30/R34/R35
FEATURE_USART_OVER_SAMPLE SAM D21/R21/D09/D10/D11/L21/L22/DA1/C20/C21/R30/R34/R35
FEATURE_USART_HARDWARE_FLOW_CONTROL SAM D21/R21/D09/D10/D11/L21/L22/DA1/C20/C21/R30/R34/R35
FEATURE_USART_IRDA SAM D21/R21/D09/D10/D11/L21/L22/DA1/C20/C21/R30/R34/R35
FEATURE_USART_LIN_SLAVE SAM D21/R21/D09/D10/D11/L21/L22/DA1/C20/C21/R30/R34/R35
FEATURE_USART_COLLISION_DECTION SAM D21/R21/D09/D10/D11/L21/L22/DA1/C20/C21/R30/R34/R35
FEATURE_USART_START_FRAME_DECTION SAM D21/R21/D09/D10/D11/L21/L22/DA1/C20/C21/R30/R34/R35
FEATURE_USART_IMMEDIATE_BUFFER_OVERFLOW_NOTIFICATION SAM D21/R21/D09/D10/D11/L21/L22/DA1/C20/C21/R30/R34/R35
FEATURE_USART_RS485 SAM C20/C21
FEATURE_USART_LIN_MASTER SAM L22/C20/C21
Note
The specific features are only available in the driver when the selected device supports those features.

Frame Format

Communication is based on frames, where the frame format can be customized to accommodate a wide range of standards. A frame consists of a start bit, a number of data bits, an optional parity bit for error detection as well as a configurable length stop bit(s) - see the figure below. The table below shows the available parameters you can change in a frame.

USART Frame Parameters
Parameter Options
Start bit 1
Data bits 5, 6, 7, 8, 9
Parity bit None, Even, Odd
Stop bits 1, 2

usart_frame.svg
USART Frame Overview

Synchronous Mode

In synchronous mode a dedicated clock line is provided; either by the USART itself if in master mode, or by an external master if in slave mode. Maximum transmission speed is the same as the GCLK clocking the USART peripheral when in slave mode, and the GCLK divided by two if in master mode. In synchronous mode the interface needs three lines to communicate:

Data Sampling

In synchronous mode the data is sampled on either the rising or falling edge of the clock signal. This is configured by setting the clock polarity in the configuration struct.

Asynchronous Mode

In asynchronous mode no dedicated clock line is used, and the communication is based on matching the clock speed on the transmitter and receiver. The clock is generated from the internal SERCOM baudrate generator, and the frames are synchronized by using the frame start bits. Maximum transmission speed is limited to the SERCOM GCLK divided by 16. In asynchronous mode the interface only needs two lines to communicate:

Transmitter/receiver Clock Matching

For successful transmit and receive using the asynchronous mode the receiver and transmitter clocks needs to be closely matched. When receiving a frame that does not match the selected baudrate closely enough the receiver will be unable to synchronize the frame(s), and garbage transmissions will result.

Parity

Parity can be enabled to detect if a transmission was in error. This is done by counting the number of "1" bits in the frame. When using even parity the parity bit will be set if the total number of "1"s in the frame are an even number. If using odd parity the parity bit will be set if the total number of "1"s are odd.

When receiving a character the receiver will count the number of "1"s in the frame and give an error if the received frame and parity bit disagree.

GPIO Configuration

The SERCOM module has four internal pads; the RX pin can be placed freely on any one of the four pads, and the TX and XCK pins have two predefined positions that can be selected as a pair. The pads can then be routed to an external GPIO pin using the normal pin multiplexing scheme on the SAM.

Special Considerations

No special considerations.

Extra Information

For extra information, see Extra Information for SERCOM USART Driver. This includes:

Examples

For a list of examples related to this driver, see Examples for SERCOM USART Driver.

API Overview

Data Structures

struct  usart_config
 USART configuration struct. More...
 
struct  usart_module
 SERCOM USART driver software device instance structure. More...
 

Macros

#define PINMUX_DEFAULT   0
 Default pinmux. More...
 
#define PINMUX_UNUSED   0xFFFFFFFF
 Unused pinmux. More...
 
#define USART_TIMEOUT   0xFFFF
 USART timeout value. More...
 

Enumerations

enum  usart_character_size {
  USART_CHARACTER_SIZE_5BIT = SERCOM_USART_CTRLB_CHSIZE(5),
  USART_CHARACTER_SIZE_6BIT = SERCOM_USART_CTRLB_CHSIZE(6),
  USART_CHARACTER_SIZE_7BIT = SERCOM_USART_CTRLB_CHSIZE(7),
  USART_CHARACTER_SIZE_8BIT = SERCOM_USART_CTRLB_CHSIZE(0),
  USART_CHARACTER_SIZE_9BIT = SERCOM_USART_CTRLB_CHSIZE(1)
}
 USART Character Size. More...
 
enum  usart_dataorder {
  USART_DATAORDER_MSB = 0,
  USART_DATAORDER_LSB = SERCOM_USART_CTRLA_DORD
}
 USART Data Order enum. More...
 
enum  usart_parity {
  USART_PARITY_ODD = SERCOM_USART_CTRLB_PMODE,
  USART_PARITY_EVEN = 0,
  USART_PARITY_NONE = 0xFF
}
 USART Parity enum. More...
 
enum  usart_signal_mux_settings {
  USART_RX_0_TX_0_XCK_1 = (SERCOM_USART_CTRLA_RXPO(0)),
  USART_RX_0_TX_2_XCK_3 = (SERCOM_USART_CTRLA_RXPO(0) | SERCOM_USART_CTRLA_TXPO),
  USART_RX_1_TX_0_XCK_1 = (SERCOM_USART_CTRLA_RXPO(1)),
  USART_RX_1_TX_2_XCK_3 = (SERCOM_USART_CTRLA_RXPO(1) | SERCOM_USART_CTRLA_TXPO),
  USART_RX_2_TX_0_XCK_1 = (SERCOM_USART_CTRLA_RXPO(2)),
  USART_RX_2_TX_2_XCK_3 = (SERCOM_USART_CTRLA_RXPO(2) | SERCOM_USART_CTRLA_TXPO),
  USART_RX_3_TX_0_XCK_1 = (SERCOM_USART_CTRLA_RXPO(3)),
  USART_RX_3_TX_2_XCK_3 = (SERCOM_USART_CTRLA_RXPO(3) | SERCOM_USART_CTRLA_TXPO)
}
 USART signal MUX settings. More...
 
enum  usart_stopbits {
  USART_STOPBITS_1 = 0,
  USART_STOPBITS_2 = SERCOM_USART_CTRLB_SBMODE
}
 USART Stop Bits enum. More...
 
enum  usart_transceiver_type {
  USART_TRANSCEIVER_RX,
  USART_TRANSCEIVER_TX
}
 USART Transceiver. More...
 
enum  usart_transfer_mode {
  USART_TRANSFER_SYNCHRONOUSLY = (SERCOM_USART_CTRLA_CMODE),
  USART_TRANSFER_ASYNCHRONOUSLY = (0x0ul << SERCOM_USART_CTRLA_CMODE_Pos)
}
 USART Transfer mode enum. More...
 

Functions

static void usart_disable (const struct usart_module *const module)
 Disable module. More...
 
static void usart_enable (const struct usart_module *const module)
 Enable the module. More...
 
static void usart_get_config_defaults (struct usart_config *const config)
 Initializes the device to predefined defaults. More...
 
enum status_code usart_init (struct usart_module *const module, Sercom *const hw, const struct usart_config *const config)
 Initializes the device. More...
 
static bool usart_is_syncing (const struct usart_module *const module)
 Check if peripheral is busy syncing registers across clock domains. More...
 
static void usart_reset (const struct usart_module *const module)
 Resets the USART module. More...
 

Lock/Unlock

static enum status_code usart_lock (struct usart_module *const module)
 Attempt to get lock on driver instance. More...
 
static void usart_unlock (struct usart_module *const module)
 Unlock driver instance. More...
 

Writing and Reading

enum status_code usart_write_wait (struct usart_module *const module, const uint16_t tx_data)
 Transmit a character via the USART. More...
 
enum status_code usart_read_wait (struct usart_module *const module, uint16_t *const rx_data)
 Receive a character via the USART. More...
 
enum status_code usart_write_buffer_wait (struct usart_module *const module, const uint8_t *tx_data, uint16_t length)
 Transmit a buffer of characters via the USART. More...
 
enum status_code usart_read_buffer_wait (struct usart_module *const module, uint8_t *rx_data, uint16_t length)
 Receive a buffer of length characters via the USART. More...
 

Enabling/Disabling Receiver and Transmitter

static void usart_enable_transceiver (struct usart_module *const module, enum usart_transceiver_type transceiver_type)
 Enable Transceiver. More...
 
static void usart_disable_transceiver (struct usart_module *const module, enum usart_transceiver_type transceiver_type)
 Disable Transceiver. More...
 

#define PINMUX_DEFAULT   0

Default pinmux.

Referenced by usart_get_config_defaults().

#define PINMUX_UNUSED   0xFFFFFFFF

Unused pinmux.

Referenced by usart_init().

#define USART_TIMEOUT   0xFFFF

USART timeout value.

Referenced by usart_read_buffer_wait(), and usart_write_buffer_wait().

USART Character Size.

Number of bits for the character sent in a frame.

Enumerator
USART_CHARACTER_SIZE_5BIT 

The char being sent in a frame is five bits long.

USART_CHARACTER_SIZE_6BIT 

The char being sent in a frame is six bits long.

USART_CHARACTER_SIZE_7BIT 

The char being sent in a frame is seven bits long.

USART_CHARACTER_SIZE_8BIT 

The char being sent in a frame is eight bits long.

USART_CHARACTER_SIZE_9BIT 

The char being sent in a frame is nine bits long.

USART Data Order enum.

The data order decides which MSB or LSB is shifted out first when data is transferred.

Enumerator
USART_DATAORDER_MSB 

The MSB will be shifted out first during transmission, and shifted in first during reception.

USART_DATAORDER_LSB 

The LSB will be shifted out first during transmission, and shifted in first during reception.

USART Parity enum.

Select parity USART parity mode.

Enumerator
USART_PARITY_ODD 

For odd parity checking, the parity bit will be set if number of ones being transferred is even.

USART_PARITY_EVEN 

For even parity checking, the parity bit will be set if number of ones being received is odd.

USART_PARITY_NONE 

No parity checking will be executed, and there will be no parity bit in the received frame.

USART signal MUX settings.

Set the functionality of the SERCOM pins.

See SERCOM USART MUX Settings for a description of the various MUX setting options.

Enumerator
USART_RX_0_TX_0_XCK_1 

MUX setting RX_0_TX_0_XCK_1.

USART_RX_0_TX_2_XCK_3 

MUX setting RX_0_TX_2_XCK_3.

USART_RX_1_TX_0_XCK_1 

MUX setting RX_1_TX_0_XCK_1.

USART_RX_1_TX_2_XCK_3 

MUX setting RX_1_TX_2_XCK_3.

USART_RX_2_TX_0_XCK_1 

MUX setting RX_2_TX_0_XCK_1.

USART_RX_2_TX_2_XCK_3 

MUX setting RX_2_TX_2_XCK_3.

USART_RX_3_TX_0_XCK_1 

MUX setting RX_3_TX_0_XCK_1.

USART_RX_3_TX_2_XCK_3 

MUX setting RX_3_TX_2_XCK_3.

USART Stop Bits enum.

Number of stop bits for a frame.

Enumerator
USART_STOPBITS_1 

Each transferred frame contains one stop bit.

USART_STOPBITS_2 

Each transferred frame contains two stop bits.

USART Transceiver.

Select Receiver or Transmitter.

Enumerator
USART_TRANSCEIVER_RX 

The parameter is for the Receiver.

USART_TRANSCEIVER_TX 

The parameter is for the Transmitter.

USART Transfer mode enum.

Select USART transfer mode.

Enumerator
USART_TRANSFER_SYNCHRONOUSLY 

Transfer of data is done synchronously.

USART_TRANSFER_ASYNCHRONOUSLY 

Transfer of data is done asynchronously.

static void usart_disable ( const struct usart_module *const  module)
inlinestatic

Disable module.

Disables the USART module.

Parameters
[in]modulePointer to USART software instance struct

References _sercom_get_interrupt_vector(), Assert, and system_interrupt_disable().

Referenced by usart_reset().

static void usart_disable_transceiver ( struct usart_module *const  module,
enum usart_transceiver_type  transceiver_type 
)
inlinestatic

Disable Transceiver.

Disable the given transceiver (RX or TX).

Parameters
[in]modulePointer to USART software instance struct
[in]transceiver_typeTransceiver type

References Assert, USART_TRANSCEIVER_RX, and USART_TRANSCEIVER_TX.

static void usart_enable ( const struct usart_module *const  module)
inlinestatic

Enable the module.

Enables the USART module.

Parameters
[in]modulePointer to USART software instance struct

References _sercom_get_interrupt_vector(), Assert, and system_interrupt_enable().

Referenced by configure_usart().

static void usart_enable_transceiver ( struct usart_module *const  module,
enum usart_transceiver_type  transceiver_type 
)
inlinestatic

Enable Transceiver.

Enable the given transceiver. Either RX or TX.

Parameters
[in]modulePointer to USART software instance struct
[in]transceiver_typeTransceiver type

References Assert, USART_TRANSCEIVER_RX, and USART_TRANSCEIVER_TX.

static void usart_get_config_defaults ( struct usart_config *const  config)
inlinestatic

Initializes the device to predefined defaults.

Initialize the USART device to predefined defaults:

  • 8-bit asynchronous USART
  • No parity
  • One stop bit
  • 9600 baud
  • Transmitter enabled
  • Receiver enabled
  • GCLK generator 0 as clock source
  • Default pin configuration

The configuration struct will be updated with the default configuration.

Parameters
[in,out]configPointer to configuration struct

References Assert, usart_config::baudrate, usart_config::character_size, usart_config::clock_polarity_inverted, usart_config::data_order, usart_config::ext_clock_freq, GCLK_GENERATOR_0, usart_config::generator_source, usart_config::mux_setting, usart_config::parity, PINMUX_DEFAULT, usart_config::pinmux_pad0, usart_config::pinmux_pad1, usart_config::pinmux_pad2, usart_config::pinmux_pad3, usart_config::receiver_enable, usart_config::run_in_standby, usart_config::stopbits, usart_config::transfer_mode, usart_config::transmitter_enable, USART_CHARACTER_SIZE_8BIT, USART_DATAORDER_LSB, USART_PARITY_NONE, USART_RX_1_TX_2_XCK_3, USART_STOPBITS_1, USART_TRANSFER_ASYNCHRONOUSLY, and usart_config::use_external_clock.

Referenced by configure_usart().

enum status_code usart_init ( struct usart_module *const  module,
Sercom *const  hw,
const struct usart_config *const  config 
)

Initializes the device.

Initializes the USART device based on the setting specified in the configuration struct.

Parameters
[out]modulePointer to USART device
[in]hwPointer to USART hardware instance
[in]configPointer to configuration struct
Returns
Status of the initialization.
Return values
STATUS_OKThe initialization was successful
STATUS_BUSYThe USART module is busy resetting
STATUS_ERR_DENIEDThe USART has not been disabled in advance of initialization
STATUS_ERR_INVALID_ARGThe configuration struct contains invalid configuration
STATUS_ERR_ALREADY_INITIALIZEDThe SERCOM instance has already been initialized with different clock configuration
STATUS_ERR_BAUD_UNAVAILABLEThe BAUD rate given by the configuration struct cannot be reached with the current clock configuration

References _sercom_get_default_pad(), _sercom_get_sercom_inst_index(), _sercom_instances, _sercom_set_handler(), _usart_set_config(), Assert, usart_config::character_size, system_pinmux_config::direction, usart_config::generator_source, system_pinmux_config::input_pull, system_pinmux_config::mux_position, PINMUX_DEFAULT, usart_config::pinmux_pad0, usart_config::pinmux_pad1, usart_config::pinmux_pad2, usart_config::pinmux_pad3, PINMUX_UNUSED, usart_config::receiver_enable, sercom_set_gclk_generator(), system_gclk_chan_config::source_generator, STATUS_BUSY, STATUS_ERR_DENIED, STATUS_OK, system_apb_clock_set_mask(), SYSTEM_CLOCK_APB_APBC, system_gclk_chan_enable(), system_gclk_chan_get_config_defaults(), system_gclk_chan_set_config(), system_pinmux_get_config_defaults(), SYSTEM_PINMUX_PIN_DIR_INPUT, SYSTEM_PINMUX_PIN_PULL_NONE, system_pinmux_pin_set_config(), and usart_config::transmitter_enable.

Referenced by usart_serial_init().

static bool usart_is_syncing ( const struct usart_module *const  module)
inlinestatic

Check if peripheral is busy syncing registers across clock domains.

Return peripheral synchronization status. If doing a non-blocking implementation this function can be used to check the sync state and hold of any new actions until sync is complete. If this function is not run; the functions will block until the sync has completed.

Parameters
[in]modulePointer to peripheral module
Returns
Peripheral sync status.
Return values
truePeripheral is busy syncing
falsePeripheral is not busy syncing and can be read/written without stalling the bus

References Assert.

static enum status_code usart_lock ( struct usart_module *const  module)
inlinestatic

Attempt to get lock on driver instance.

This function checks the instance's lock, which indicates whether or not it is currently in use, and sets the lock if it was not already set.

The purpose of this is to enable exclusive access to driver instances, so that, e.g., transactions by different services will not interfere with each other.

Parameters
[in,out]modulePointer to the driver instance to lock
Return values
STATUS_OKIf the module was locked
STATUS_BUSYIf the module was already locked

References STATUS_BUSY, STATUS_OK, system_interrupt_enter_critical_section(), and system_interrupt_leave_critical_section().

enum status_code usart_read_buffer_wait ( struct usart_module *const  module,
uint8_t *  rx_data,
uint16_t  length 
)

Receive a buffer of length characters via the USART.

This blocking function will receive a block of length characters via the USART.

Note
Using this function in combination with the interrupt (*_job) functions is not recommended as it has no functionality to check if there is an ongoing interrupt driven operation running or not.
Parameters
[in]modulePointer to USART software instance struct
[out]rx_dataPointer to receive buffer
[in]lengthNumber of characters to receive
Note
If using 9-bit data, the array that rx_data point to should be defined as uint16_t array and should be casted to uint8_t pointer. Because it is an address pointer, the highest byte is not discarded. For example:
#define RX_LEN 3
uint16_t rx_buf[RX_LEN] = {0x0,};
usart_read_buffer_wait(&module, (uint8_t*)rx_buf, RX_LEN);
Returns
Status of the operation.
Return values
STATUS_OKIf operation was completed
STATUS_ERR_INVALID_ARGIf operation was not completed, due to an invalid argument being supplied
STATUS_ERR_TIMEOUTIf operation was not completed, due to USART module timing out
STATUS_ERR_BAD_FORMATIf the operation was not completed, due to a configuration mismatch between USART and the sender
STATUS_ERR_BAD_OVERFLOWIf the operation was not completed, due to the baudrate being too low or the system frequency being too high
STATUS_ERR_BAD_DATAIf the operation was not completed, due to data being corrupted
STATUS_ERR_DENIEDIf the receiver is not enabled

References Assert, STATUS_ERR_DENIED, STATUS_ERR_INVALID_ARG, STATUS_ERR_TIMEOUT, STATUS_OK, USART_CHARACTER_SIZE_9BIT, usart_read_wait(), and USART_TIMEOUT.

Referenced by usart_serial_read_packet().

enum status_code usart_read_wait ( struct usart_module *const  module,
uint16_t *const  rx_data 
)

Receive a character via the USART.

This blocking function will receive a character via the USART.

Parameters
[in]modulePointer to the software instance struct
[out]rx_dataPointer to received data
Returns
Status of the operation.
Return values
STATUS_OKIf the operation was completed
STATUS_BUSYIf the operation was not completed, due to the USART module being busy
STATUS_ERR_BAD_FORMATIf the operation was not completed, due to configuration mismatch between USART and the sender
STATUS_ERR_BAD_OVERFLOWIf the operation was not completed, due to the baudrate being too low or the system frequency being too high
STATUS_ERR_BAD_DATAIf the operation was not completed, due to data being corrupted
STATUS_ERR_DENIEDIf the receiver is not enabled

References Assert, STATUS_BUSY, STATUS_ERR_BAD_DATA, STATUS_ERR_BAD_FORMAT, STATUS_ERR_DENIED, STATUS_ERR_OVERFLOW, STATUS_ERR_PACKET_COLLISION, STATUS_ERR_PROTOCOL, and STATUS_OK.

Referenced by usart_read_buffer_wait(), and usart_serial_getchar().

static void usart_reset ( const struct usart_module *const  module)
inlinestatic

Resets the USART module.

Disables and resets the USART module.

Parameters
[in]modulePointer to the USART software instance struct

References Assert, and usart_disable().

static void usart_unlock ( struct usart_module *const  module)
inlinestatic

Unlock driver instance.

This function clears the instance lock, indicating that it is available for use.

Parameters
[in,out]modulePointer to the driver instance to lock
enum status_code usart_write_buffer_wait ( struct usart_module *const  module,
const uint8_t *  tx_data,
uint16_t  length 
)

Transmit a buffer of characters via the USART.

This blocking function will transmit a block of length characters via the USART.

Note
Using this function in combination with the interrupt (_job) functions is not recommended as it has no functionality to check if there is an ongoing interrupt driven operation running or not.
Parameters
[in]modulePointer to USART software instance struct
[in]tx_dataPointer to data to transmit
[in]lengthNumber of characters to transmit
Note
If using 9-bit data, the array that tx_data point to should be defined as uint16_t array and should be casted to uint8_t pointer. Because it is an address pointer, the highest byte is not discarded. For example:
#define TX_LEN 3
uint16_t tx_buf[TX_LEN] = {0x0111, 0x0022, 0x0133};
usart_write_buffer_wait(&module, (uint8_t*)tx_buf, TX_LEN);
Returns
Status of the operation.
Return values
STATUS_OKIf operation was completed
STATUS_ERR_INVALID_ARGIf operation was not completed, due to invalid arguments
STATUS_ERR_TIMEOUTIf operation was not completed, due to USART module timing out
STATUS_ERR_DENIEDIf the transmitter is not enabled

References Assert, STATUS_ERR_DENIED, STATUS_ERR_INVALID_ARG, STATUS_ERR_TIMEOUT, STATUS_OK, USART_CHARACTER_SIZE_9BIT, USART_TIMEOUT, and usart_write_wait().

Referenced by usart_serial_write_packet().

enum status_code usart_write_wait ( struct usart_module *const  module,
const uint16_t  tx_data 
)

Transmit a character via the USART.

This blocking function will transmit a single character via the USART.

Parameters
[in]modulePointer to the software instance struct
[in]tx_dataData to transfer
Returns
Status of the operation.
Return values
STATUS_OKIf the operation was completed
STATUS_BUSYIf the operation was not completed, due to the USART module being busy
STATUS_ERR_DENIEDIf the transmitter is not enabled

References Assert, STATUS_BUSY, STATUS_ERR_DENIED, and STATUS_OK.

Referenced by usart_serial_putchar(), and usart_write_buffer_wait().