Use UARTs in high-level applications

  • Article

Azure Sphere supports universal asynchronous receiver-transmitters (UARTs) for serial communication. A UART is a type of integrated circuit that is used to send and receive data over a serial port on a computer or peripheral device. UARTs are widely used and known for their simplicity. However, unlike SPI and I2C, UARTs do not support multiple subordinate devices.

Note

This topic describes how to use UARTs in a high-level application. See Use peripherals in a real-time capable application for information about UART use in RTApps.

Azure Sphere high-level applications can communicate with UARTs by calling Applibs UART APIs. The UART_HighLevelApp sample demonstrates how to communicate with UARTs on an MT3620 device.

UART requirements

Applications that communicate with UARTs must include the appropriate header files, and add UART settings to the application manifest.

All applications must set their target hardware and include the corresponding hardware definition header file.

Header Files

 #define UART_STRUCTS_VERSION 1
 #include <applibs/uart.h>
 #include "path-to-your-target-hardware.h"

Declare the UART_STRUCTS_VERSION preprocessor definition before including the header file. This specifies the struct version that is used by the application.

Replace "path-to-your-target-hardware.h" with the path to the header file for your hardware.

Application manifest settings

The UART settings in the application manifest list the UARTs that are accessed by the application. Only one application can use a UART at a time. To configure these settings, add the Uart capability to the application manifest, and then add each UART to the capability. Azure Sphere application manifest has more details about the application manifest.

In your code, use the constants that are defined for your hardware to identify the UARTs. The compiler will translate these values to raw values when you build the app.

For example, here's an excerpt from an application manifest that targets an MT3620 reference development board (RDB) and configures two UARTs on an MT3620.

"Uart": [ "$MT3620_RDB_HEADER2_ISU0_UART", "$MT3620_RDB_HEADER4_ISU1_UART" ],

The following excerpt shows how to specify the same UARTs in an application that targets the Avnet MT3620 Starter Kit:

"Uart": [ "$AVNET_MT3620_SK_ISU0_UART", "$AVNET_MT3620_SK_ISU1_UART" ],

Configure and open a UART

Before you perform operations on a UART, you must configure the settings and open the UART. When you open a UART, a file descriptor is returned that you can pass to functions that perform operations on the UART.

To configure the settings, call the UART_InitConfig Function function to initialize the UART_Config Struct struct. After you initialize the UART_Config struct, you can change the UART settings in the struct.

To open the UART and apply the settings, call the UART_Open function and pass the UART_Config struct.

Perform read and write operations on a UART

You can use POSIX functions to perform read and write operations on a UART. To perform a read operation on a UART, call the read() function. To perform a write operation on a UART, call the write() function.

Close a UART

To close the UART, call the POSIX function close().

MT3620 support

This section describes the UART options that only apply when running Azure Sphere on an MT3620.

The UART specifications for the MT3620 are listed in MT3620 Support Status. The MT3620 development board user guide describes the pin layout and functions for wiring.

The HardwareDefinitions folder in the Microsoft Azure Sphere SDK installation directory contains definitions for common Azure Sphere development boards, modules, and chips. It contains header and JSON files that define the master interfaces for the MT3620, MT3620 RDB, along with other MT3620 hardware. The default location for the HardwareDefinitions folder is C:\Program Files (x86)\Microsoft Azure Sphere SDK\Hardware Definitions on Windows and /opt/azurespheresdk/HardwareDefinitions on Linux.

The following UART settings are supported. 8N1 (8 data bits, 1 stop bit, and no parity) is the default setting:

  • When you configure the MT3620 dev board, you can use any ISU port as a UART interface. When you use an ISU port as a UART interface, you can't use the same port as an I2C or SPI interface.
  • baud rate : 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200, 230400, 460800, 500000, 576000, 921600, 1000000, 1152000, 1500000, and 2000000.
  • Data bit: 5, 6, 7, and 8.
  • Stop bit: 1 and 2.
  • Parity: odd, even, and none.
  • Flow control mode: RTS/CTS, XON/XOFF, and no flow control.
  • Hardware receive buffer: 32-byte.

When using a UART in a high-level application, only 4 of the 5 available ISU peripheral block pins are used. The unused pin can be used as a GPIO pin by the same high-level application. See I/O peripherals for a list of the unused ISU pins that can be reused for GPIO.