Azure Sphere – UART

  • Code Sample
Browse code Download ZIP

This sample demonstrates how to communicate over the UART on an MT3620 development board.

This sample does the following:

  • Opens a UART serial port with a baud rate of 115200.
  • Sends characters from the device over the UART when button A is pressed.
  • Displays the data received from the UART in the Output window of Visual Studio or Visual Studio Code.
  • Causes an LED to blink when data is received from the UART.

The sample uses the following Azure Sphere libraries.

Library Purpose
eventloop Invokes handlers for I/O and timer events.
gpio Manages button A on the device.
log Displays messages in the Device Output window during debugging.
uart Manages UART connectivity on the device.

Contents

File/folder Description
app_manifest.json Application manifest file, which describes the resources.
CMakeLists.txt CMake configuration file, which Contains the project information and is required for all builds.
CMakePresets.json CMake presets file, which contains the information to configure the CMake project.
launch.vs.json JSON file that tells Visual Studio how to deploy and debug the application.
LICENSE.txt The license for this sample application.
main.c Main C source code file.
README.md This README file.
.vscode Folder containing the JSON files that configure Visual Studio Code for deploying and debugging the application.
HardwareDefinitions Folder containing the hardware definition files for various Azure Sphere boards.

Prerequisites

  • An Azure Sphere development board that supports the Sample Appliance hardware requirements.

    Note: By default, the sample targets the Reference Development Board design, which is implemented by the Seeed Studios MT3620 Development Board. To build the sample for different Azure Sphere hardware, change the value of the TARGET_HARDWARE variable in the CMakeLists.txt file. For detailed instructions, see the Hardware Definitions README file.

  • Make a loopback connection on header 2 (marked H2) on the lower left side of the board by connecting pins 1 and 3 (ISU0 RXD and ISU0 TXD) of H2 with a jumper. Pins 1 and 3 are the first two pins on the left side of the header, circled in red in the image.

    RDB with header pins circled

  • As an alternative to using the loopback connection, you can connect the UART to an external serial-USB interface board and use a client such as Telnet or Putty to transmit and receive bytes. This solution has been tested using the Adafruit FTDI Friend serial-USB adapter with the following wiring connections.

    Connections for MT3620 and FTDI Friend

    FTDI Friend Azure Sphere MT3620
    GND H2 Pin 2
    TX H2 Pin 1
    RX H2 Pin 3
    RTS H2 Pin 5
    CTS H2 Pin 7

    Putty settings:

    • Local echo = force on
    • Local line editing = force on

Setup

  1. Ensure that your Azure Sphere device is connected to your computer, and your computer is connected to the internet.
  2. Ensure that you have Azure Sphere SDK version 24.03 or above. At the command prompt, run az sphere show-sdk-version to check. Upgrade the Azure Sphere SDK for Windows or Linux as needed.
  3. Ensure that the Azure CLI is installed. At a minimum, the Azure CLI version must be 2.45.0 or later.
  4. Install the Azure Sphere extension.
  5. Enable application development, if you have not already done so, by entering the az sphere device enable-development command in the command prompt.
  6. Clone the Azure Sphere samples repository and find the UART_HighLevelApp sample in the UART folder or download the zip file from the Microsoft samples browser.

Build and run the sample

To build and run this sample, follow the instructions in Build a sample application.

Test the sample

Press button A on the board. This sends 13 bytes over the UART connection and displays the sent and received text in the Device Output window, if you're using Visual Studio or Visual Studio Code:

Sent 13 bytes over UART in 1 calls. UART received 12 bytes: 'Hello world!'. UART received 1 bytes: ' '.

Note: If you are using the serial-USB adapter, you will not see the lines starting UART received, but instead you will be able to see the output on your PC serial client.

The received text might not appear all at the same time and it might not appear immediately.

The message may contain more bytes than the read function can return, depending on the Azure Sphere device (on the MT3620 this is often 12 bytes). The message may need to be assembled asynchronously over a sequence of read calls as a result, as illustrated at this point in the WifiSetupAndDeviceControlViaBle sample.

If it is temporarily not possible to send further bytes, such as when transmitting larger buffers, the write function may fail with errno of EAGAIN. You can handle this by registering an EPOLLOUT event handler, as illustrated at this point in the WifiSetupAndDeviceControlViaBle sample.

Next steps