Getting started with the Cypress CYW954907AEVAL1F Development Kit

Important

This reference integration is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you start here when you create a new project. If you already have an existing FreeRTOS project based on the now deprecated Amazon-FreeRTOS repository, see the Amazon-FreeRTOS Github Repository Migration Guide.

This tutorial provides instructions for getting started with the Cypress CYW954907AEVAL1F Development Kit. If you don't have the Cypress CYW954907AEVAL1F Development Kit, visit the AWS Partner Device Catalog to purchase one from our partner.

Note

This tutorial walks you through setting up and running the coreMQTT Mutual Authentication demo. The FreeRTOS port for this board currently doesn't support the TCP server and client demos.

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.

Important

• In this topic, the path to the FreeRTOS download directory is referred to as freertos.

• Space characters in the freertos path can cause build failures. When you clone or copy the repository, make sure the path that you create doesn't contain space characters.

• The maximum length of a file path on Microsoft Windows is 260 characters. Long FreeRTOS download directory paths can cause build failures.

• Because the source code may contain symbolic links, if you're using Windows to extract the archive, you may have to:

  • Enable Developer Mode or,

  • Use a console that is elevated as administrator.

  In this way, Windows can properly create symbolic links when it extracts the archive. Otherwise, symbolic links will be written as normal files that contain the paths of the symbolic links as text or are empty. For more information, see the blog entry Symlinks in Windows 10!.

  If you use Git under Windows, you must enable Developer Mode or you must:

  • Set core.symlinks to true with the following command:

    git config --global core.symlinks true

  • Use a console that is elevated as administrator whenever you use a git command that writes to the system (for example, git pull, git clone, and git submodule update --init --recursive).

• As noted in Downloading FreeRTOS, FreeRTOS ports for Cypress are currently only available on GitHub.

Overview

This tutorial contains instructions for the following getting started steps:

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

2. Cross compiling a FreeRTOS demo application to a binary image.

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

4. Interacting with the application running on your board across a serial connection, for monitoring and debugging purposes.

Setting up your development environment

Download and install the WICED Studio SDK

In this Getting Started guide, you use the Cypress WICED Studio SDK to program your board with the FreeRTOS demo. Visit the WICED Software website to download the WICED Studio SDK from Cypress. You must register for a free Cypress account to download the software. The WICED Studio SDK is compatible with Windows, macOS, and Linux operating systems.

Note

Some operating systems require additional installation steps. Make sure that you read and follow all installation instructions for the operating system and version of WICED Studio that you are installing.

Set environment variables

Before you use WICED Studio to program your board, you must create an environment variable for the WICED Studio SDK installation directory. If WICED Studio is running while you create your variables, you need to restart the application after you set your variables.

Note

The WICED Studio installer creates two separate folders named WICED-Studio-m.n on your machine where m and n are the major and minor version numbers respectively. This document assumes a folder name of WICED-Studio-6.2 but be sure to use the correct name for the version that you install. When you define the WICED_STUDIO_SDK_PATH environment variable, be sure to specify the full installation path of the WICED Studio SDK, and not the installation path of the WICED Studio IDE. In Windows and macOS, the WICED-Studio-m.n folder for the SDK is created in the Documents folder by default.

To create the environment variable on Windows

1. Open Control Panel, choose System, and then choose Advanced System Settings.

2. On the Advanced tab, choose Environment Variables.

3. Under User variables, choose New.

4. For Variable name, enter WICED_STUDIO_SDK_PATH. For Variable value, enter the WICED Studio SDK installation directory.

To create the environment variable on Linux or macOS

1. Open the /etc/profile file on your machine, and add the following to the last line of the file:

   export WICED_STUDIO_SDK_PATH=installation-path/WICED-Studio-6.2

2. Restart your machine.

3. Open a terminal and run the following commands:

   cd freertos/vendors/cypress/WICED_SDK

   perl platform_adjust_make.pl

   chmod +x make

Establishing a serial connection

To establish a serial connection between your host machine and your board

1. Connect the board to your host computer with a USB Standard-A to Micro-B cable.

2. Identify the USB serial port number for the connection to the board on your host computer.

3. Start a serial terminal and open a connection with the following settings:

   • Baud rate: 115200

   • Data: 8 bit

   • Parity: None

   • Stop bits: 1

   • Flow control: None

For more information about installing a terminal and setting up a serial connection, see Installing a terminal emulator.

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

After you set up a serial connection to your board, you can build the FreeRTOS demo project, flash the demo to your board, and then run the demo.

To build and run the FreeRTOS demo project in WICED Studio

1. Launch WICED Studio.

2. From the File menu, choose Import. Expand the General folder, choose Existing Projects into Workspace, and then choose Next.

3. In Select root directory, select Browse..., navigate to the path freertos/projects/cypress/CYW954907AEVAL1F/wicedstudio, and then select OK.

4. Under Projects, check the box for just the aws_demo project. Choose Finish to import the project. The target project aws_demo should appear in the Make Target window.

5. Expand the WICED Platform menu and choose WICED Filters off.

6. In the Make Target window, expand aws_demo, right-click the demo.aws_demo file, and then choose Build Target to build and download the demo to your board. The demo should run automatically after it is built and downloaded to your board.

Troubleshooting

• If you are using Windows, you might receive the following error when you build and run the demo project:

  : recipe for target 'download_dct' failed
  make.exe[1]: *** [download_dct] Error 1

  To troubleshoot this error, do the following:

  1. Browse to WICED-Studio-SDK-PATH\WICED-Studio-6.2\43xxx_Wi-Fi\tools\OpenOCD\Win32 and double-click on openocd-all-brcm-libftdi.exe.

  2. Browse to WICED-Studio-SDK-PATH\WICED-Studio-6.2\43xxx_Wi-Fi\tools\drivers\CYW9WCD1EVAL1 and double-click on InstallDriver.exe.

• If you are using Linux or macOS, you might receive the following error when you build and run the demo project:

  make[1]: *** [download_dct] Error 127

  To troubleshoot this error, use the following command to update the libusb-dev package:

  sudo apt-get install libusb-dev

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