Amazon FreeRTOS
User Guide

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

Getting Started with the Xilinx Avnet MicroZed Industrial IoT Kit

This tutorial provides instructions for getting started with the Xilinx Avnet MicroZed Industrial IoT Kit. If you do not have the Xilinx Avnet MicroZed Industrial IoT Kit, visit the AWS Partner Device Catalog to purchase one from our partner.

Before you begin, you must configure AWS IoT and your Amazon FreeRTOS download to connect your device to the AWS Cloud. See First Steps for instructions. In this tutorial, the path to the Amazon FreeRTOS download directory is referred to as <amazon-freertos>.

Overview

This tutorial contains instructions for the following getting started steps:

  1. Connecting your board to a host machine.

  2. Installing software on the host machine for developing and debugging embedded applications for your microcontroller board.

  3. Cross compiling an Amazon FreeRTOS demo application to a binary image.

  4. Loading the application binary image to your board, and then running the application.

Set Up the MicroZed Hardware

The following diagram might be helpful when you set up the MicroZed hardware:

To set up the MicroZed board

  1. Connect your computer to the USB-UART port on your MicroZed board.

  2. Connect your computer to the JTAG Access port on your MicroZed board.

  3. Connect a router or internet-connected Ethernet port to the Ethernet and USB-Host port on your MicroZed board.

Set Up Your Development Environment

To set up Amazon FreeRTOS configurations for the MicroZed kit, you must use the Xilinx Software Development Kit (XSDK). XSDK is supported on Windows and Linux.

Download and Install XSDK

To install Xilinx software, you need a free Xilinx account.

To download the XSDK

  1. Go to the Software Development Kit Standalone WebInstall Client download page.

  2. Choose the option appropriate for your operating system.

  3. You are directed to a Xilinx sign-in page.

    If you have an account with Xilinx, enter your user name and password and then choose Sign in.

    If you do not have an account, choose Create your account. After you register, you should receive an email with a link to activate your Xilinx account.

  4. On the Name and Address Verification page, enter your information and then choose Next. The download should be ready to start.

  5. Save the Xilinx_SDK_version_os file.

To install the XSDK

  1. Open the Xilinx_SDK_version_os file.

  2. In Select Edition to Install, choose Xilinx Software Development Kit (XSDK) and then choose Next.

  3. On the following page of the installation wizard, under Installation Options, select Install Cable Drivers and then choose Next.

If your computer does not detect the MicroZed's USB-UART connection, install the CP210x USB-to-UART Bridge VCP drivers manually. For instructions, see the Silicon Labs CP210x USB-to-UART Installation Guide.

For more information about XSDK, see the Getting Started with Xilinx SDK on the Xilink website.

Build and Run Amazon FreeRTOS Demo Project

Open the Amazon FreeRTOS Demo in the XSDK IDE

  1. Launch the XSDK IDE with the workspace directory set to projects/xilinx/microzed/xsdk.

  2. Close the welcome page. From the menu, choose Project, and then clear Build Automatically.

  3. From the menu, choose File, and then choose Import.

  4. On the Select page, expand General, choose Existing Projects into Workspace, and then choose Next.

  5. On the Import Projects page, choose Select root directory, and then enter the root directory of your demo project. To browse for the directory, choose Browse.

    After you specify a root directory, the projects in that directory appear on the Import Projects page. All available projects are selected by default.

    Note

    If you see a warning at the top of the Import Projects page ("Some projects cannot be imported because they already exist in the workspace.") you can ignore it.

  6. With all of the projects selected, choose Finish. The XSDK IDE opens all of the projects that are required for the aws_demos project to build and run on the MicroZed board.

  7. From the menu, choose Window, and then choose Preferences.

  8. In the navigation pane, expand Run/Debug, choose String Substitution, and then choose New.

  9. In New String Substitution Variable, for Name, enter AFR_ROOT. For Value, enter the root path of the aws_demos. Choose OK, and then choose OK to save the variable and close Preferences.

Build the Amazon FreeRTOS Demo Project

  1. In the XSDK IDE, from the menu, choose Project, and then choose Clean.

  2. In Clean, leave the options at their default values, and then choose OK. XSDK cleans and builds all of the projects, and then generates .elf files.

    Note

    To build all projects without cleaning them, choose Project, and then choose Build All.

    To build individual projects, select the project you want to build, choose Project, and then choose Build Project.

Monitoring MQTT Messages on the Cloud

You can use the MQTT client in the AWS IoT console to monitor the messages that your device sends to the AWS Cloud.

To subscribe to the MQTT topic with the AWS IoT MQTT client

  1. Sign in to the AWS IoT console.

  2. In the navigation pane, choose Test to open the MQTT client.

  3. In Subscription topic, enter iotdemo/#, and then choose Subscribe to topic.

JTAG Debugging

  1. Set your MicroZed board's boot mode jumpers to the JTAG boot mode.

  2. Insert your MicroSD card into the MicroSD card slot located directly under the USB-UART port.

    Note

    Before you debug, be sure to back up any content that you have on the MicroSD card.

    Your board should look similar to the following:

  3. In the XSDK IDE, right-click aws_demos, choose Debug As, and then choose 1 Launch on System Hardware (System Debugger).

  4. When the debugger stops at the breakpoint in main(), from the menu, choose Run, and then choose Resume.

    Note

    The first time you run the application, a new certificate-key pair is imported into non-volatile memory. For subsequent runs, you can comment out vDevModeKeyProvisioning() in the main.c file before you rebuild the images and the BOOT.bin file. This prevents the copying of the certificates and key to storage on every run.

You can opt to boot your MicroZed board from a MicroSD card or from QSPI flash to run the Amazon FreeRTOS demo project. For instructions, see Generate the Boot Image for the Amazon FreeRTOS Demo Project and Run the Amazon FreeRTOS Demo Project.

Generate the Boot Image for the Amazon FreeRTOS Demo Project

  1. In the XSDK IDE, right-click aws_demos, and then choose Create Boot Image.

  2. In Create Boot Image, choose Create new BIF file.

  3. Next to Output BIF file path, choose Browse, and then choose aws_demos.bif located at <amazon-freertos>/vendors/xilinx/microzed/aws_demos/aws_demos.bif.

  4. Choose Add.

  5. On Add new boot image partition, next to File path, choose Browse, and then choose fsbl.elf, located at vendors/xilinx/fsbl/Debug/fsbl.elf.

  6. For the Partition type, choose bootloader, and then choose OK.

  7. On Create Boot Image, choose Create Image. On Override Files, choose OK to overwrite the existing aws_demos.bif and generate the BOOT.bin file at projects/xilinx/microzed/xsdk/aws_demos/BOOT.bin.

Run the Amazon FreeRTOS Demo Project

To run the Amazon FreeRTOS demo project, you can boot your MicroZed board from a MicroSD card or from QSPI flash.

As you set up your MicroZed board for running the Amazon FreeRTOS demo project, refer to the diagram in Set Up the MicroZed Hardware. Make sure that you have connected your MicroZed board to your computer.

Boot the Amazon FreeRTOS Project from a MicroSD Card

Format the MicroSD card that is provided with the Xilinx MicroZed Industrial IoT Kit.

  1. Copy the BOOT.bin file to the MicroSD card.

  2. Insert the card into the MicroSD card slot directly under the USB-UART port.

  3. Set the MicroZed boot mode jumpers to SD boot mode.

  4. Press the RST button to reset the device and start booting the application. You can also unplug the USB-UART cable from the USB-UART port, and then reinsert the cable.

Boot the Amazon FreeRTOS Demo Project from QSPI flash

  1. Set your MicroZed board's boot mode jumpers to the JTAG boot mode.

  2. Verify that your computer is connected to the USB-UART and JTAG Access ports. The green Power Good LED light should be illuminated.

  3. In the XSDK IDE, from the menu, choose Xilinx, and then choose Program Flash.

  4. In Program Flash Memory, the hardware platform should be filled in automatically. For Connection, choose your MicroZed hardware server to connect your board with your host computer.

    Note

    If you are using the Xilinx Smart Lync JTAG cable, you must create a hardware server in XSDK IDE. Choose New, and then define your server.

  5. In Image File, enter the directory path to your BOOT.bin image file. Choose Browse to browse for the file instead.

  6. In Offset, enter 0x0.

  7. In FSBL File, enter the directory path to your fsbl.elf file. Choose Browse to browse for the file instead.

  8. Choose Program to program your board.

  9. After the QSPI programming is complete, remove the USB-UART cable to power off the board.

  10. Set your MicroZed board's boot mode jumpers to the QSPI boot mode.

  11. Insert your card into the MicroSD card slot located directly under the USB-UART port.

    Note

    Be sure to back up any content that you have on the MicroSD card.

  12. Press the RST button to reset the device and start booting the application. You can also unplug the USB-UART cable from the USB-UART port, and then reinsert the cable.

Troubleshooting

If you encounter build errors that are related to incorrect paths, try to clean and rebuild the project, as described in Build the Amazon FreeRTOS Demo Project.

If you are using Windows, make sure that you use forward slashes when you set the string substitution variables in the Windows XSDK IDE.

For general troubleshooting information about Getting Started with Amazon FreeRTOS, see Troubleshooting Getting Started.