Amazon FreeRTOS
User Guide

Getting Started with the Xilinx Avnet MicroZed Industrial IoT Kit

Before you begin, see Prerequisites.

If you do not have the Xilinx Avnet MicroZed Industrial IoT Kit, you can purchase one from Avnet.

Setting 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.

Setting Up Your 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.

Download and Configure Amazon FreeRTOS

After you set up your environment, you can download Amazon FreeRTOS.

Download Amazon FreeRTOS

  1. Browse to the AWS IoT console.

  2. In the navigation pane, choose Software.

  3. Under Amazon FreeRTOS Device Software, choose Configure download.

  4. Under Software Configurations, find Connect to AWS IoT- Xilinx, and then choose Download.

  5. Unzip the downloaded file to the AmazonFreeRTOS folder, and make a note of the folder's path.

Note

The maximum length of a file path on Microsoft Windows is 260 characters. The longest path in the Amazon FreeRTOS download is 122 characters. To accommodate the files in the Amazon FreeRTOS projects, make sure that the path to the AmazonFreeRTOS directory is fewer than 98 characters long. For example, C:\Users\Username\Dev\AmazonFreeRTOS works, but C:\Users\Username\Documents\Development\Projects\AmazonFreeRTOS causes build failures.

In this tutorial, the path to the AmazonFreeRTOS directory is referred to as BASE_FOLDER.

Configure Your Project

To run the demo, you must configure your project to work with AWS IoT.

Note

To configure your project to work with AWS IoT, your board must be registered as an AWS IoT thing. Registering Your MCU Board with AWS IoT is a step in the Prerequisites.

Configure your AWS IoT endpoint

  1. Browse to the AWS IoT console.

  2. In the navigation pane, choose Settings.

  3. Your AWS IoT endpoint appears in the Endpoint text box. It should look like <1234567890123>-ats.iot.<us-east-1>.amazonaws.com. Take note of this endpoint.

  4. In the navigation pane, choose Manage, Things. Your device should have a corresponding AWS IoT thing name. Take note of this name.

  5. With your AWS IoT endpoint and your AWS IoT thing name on hand, open aws_demos\application_code\common_demos\include\aws_clientcredential.h in your IDE, and specify values for the following #define constants:

    • clientcredentialMQTT_BROKER_ENDPOINT Your AWS IoT endpoint

    • clientcredentialIOT_THING_NAME Your board's AWS IoT thing name

Configure your AWS IoT credentials

Note

To configure your AWS IoT credentials, you need the private key and certificate that you downloaded from the AWS IoT Console when you registered your device as an AWS IoT thing. After you have registered your device as an AWS IoT thing, you can retrieve device certificates from the AWS IoT console, but you cannot retrieve private keys.

Amazon FreeRTOS is a C language project, and the certificate and private key must be specially formatted to be added to the project. You need to format the certificate and private key for your device.

  1. In a browser window, open tools\certificate_configuration\CertificateConfigurator.html.

  2. Under Certificate PEM file, choose the <ID>-certificate.pem.crt that you downloaded from the AWS IoT console.

  3. Under Private Key PEM file, choose the <ID>-private.pem.key that you downloaded from the AWS IoT console.

  4. Choose Generate and save aws_clientcredential_keys.h, and then save the file in demos\common\include. This overwrites the existing file in the directory.

    Note

    The certificate and private key should be hard-coded for demonstration purposes only. Production-level applications should store these files in a secure location.

Build and Run Amazon FreeRTOS Samples

Now that you have configured your project, you are ready to build and run the demo project on your board.

Before you run the demo project, use the MQTT client in the AWS IoT console to subscribe to the demo's MQTT topic.

To subscribe to the MQTT topic

  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 freertos/demos/echo, and then choose Subscribe to topic.

Open the Amazon FreeRTOS Sample Code in the XSDK IDE

  1. Launch the XSDK IDE with the workspace directory set to <BASE_FOLDER>\demos\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 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 chooseBuild Project.

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 generated. 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 Project and Run the Amazon FreeRTOS Project.

Generate the Boot Image for the Amazon FreeRTOS 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 <BASE_FOLDER>\demos\xilinx\microzed\xsdk\aws_demos\bootimage\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 <BASE_FOLDER>\lib\third_party\mcu_vendor\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 demos\xilinx\microzed\xsdk\aws_demos\bootimage\BOOT.bin.

Run the Amazon FreeRTOS 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 Setting 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 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

General Troubleshooting Tips

  • 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 Project.

    Note

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