getting_started_xilinx.md

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 FreeRTOS download to connect your device to the AWS Cloud. See First steps for instructions. In this tutorial, the path to the FreeRTOS download directory is referred to as 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 a 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 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.

Monitoring MQTT messages on the cloud

Before you run the FreeRTOS demo project, you can set up 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, then choose MQTT test client to open the MQTT client.

3. In Subscription topic, enter your-thing-name/example/topic, and then choose Subscribe to topic.

Build and run the FreeRTOS demo project

Open the FreeRTOS demo in the XSDK IDE

1. Launch the XSDK IDE with the workspace directory set to freertos/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: freertos/projects/xilinx/microzed/xsdk/aws_demos. 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.

7. If you don't see the aws_bsp, fsbl, and MicroZed_hw_platform_0 projects in the projects pane, repeat the previous steps starting from #3 but with the root directory set to freertos/vendors/xilinx, and import aws_bsp, fsbl, and MicroZed_hw_platform_0.

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

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

10. In New String Substitution Variable, for Name, enter AFR_ROOT. For Value, enter the root path of the freertos/projects/xilinx/microzed/xsdk/aws_demos. Choose OK, and then choose OK to save the variable and close Preferences.

Build the 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.

Generate the boot image for the 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 <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.

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 FreeRTOS demo project. For instructions, see Generate the boot image for the FreeRTOS demo project and Run the FreeRTOS demo project.

Run the FreeRTOS demo project

To run the 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 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 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 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 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 FreeRTOS, see Troubleshooting getting started.