# Get Started with FreeRTOS
<a name="freertos-getting-started"></a>

**Important**  <a name="deprecation-message-general"></a>
This page refers to the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).

This Getting Started with FreeRTOS tutorial shows you how to download and configure FreeRTOS on a host machine, and then compile and run a simple demo application on a [ qualified microcontroller board](https://devices.amazonaws.com/search?page=1&sv=freertos).

Throughout this tutorial, we assume that you are familiar with AWS IoT and the AWS IoT console. If not, we recommend that you complete the [AWS IoT Getting Started](https://docs.aws.amazon.com/iot/latest/developerguide/iot-gs.html) tutorial before you continue.

**Topics**
+ [FreeRTOS demo application](freertos-getting-started-demo.md)
+ [First steps](freertos-prereqs.md)
+ [Troubleshooting getting started](gsg-troubleshooting.md)
+ [Using CMake with FreeRTOS](getting-started-cmake.md)
+ [Developer-mode key provisioning](dev-mode-key-provisioning.md)
+ [Board-specific getting started guides](getting-started-guides.md)
+ [Next steps with FreeRTOS](getting-started-next-steps.md)

# FreeRTOS demo application
<a name="freertos-getting-started-demo"></a>

**Important**  <a name="deprecation-message-general"></a>
This page refers to the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).

The demo application in this tutorial is the coreMQTT Agent demo defined in the `freertos/demos/coreMQTT_Agent/mqtt_agent_task.c` file. It uses the [coreMQTT library](coremqtt.md) to connect to the AWS Cloud and then periodically publish messages to an MQTT topic hosted by the [AWS IoT MQTT broker](https://docs.aws.amazon.com/iot/latest/developerguide/mqtt.html).

Only a single FreeRTOS demo application can run at a time. When you build a FreeRTOS demo project, the first demo enabled in the `freertos/vendors/vendor/boards/board/aws_demos/config_files/aws_demo_config.h` header file is the application that runs. For this tutorial, you do not need to enable or disable any demos. The coreMQTT Agent demo is enabled by default.

For more information about the demo applications included with FreeRTOS, see [FreeRTOS demos](freertos-next-steps.md).

# First steps
<a name="freertos-prereqs"></a>

**Important**  <a name="deprecation-message-general"></a>
This page refers to the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).

To get started using FreeRTOS with AWS IoT, you must have an AWS account, a user with permissions to access AWS IoT and FreeRTOS cloud services. You also must download FreeRTOS and configure your board's FreeRTOS demo project to work with AWS IoT. The following sections walk you through these requirements.

**Note**  
If you're using the Espressif ESP32-DevKitC, ESP-WROVER-KIT, or the ESP32-WROOM-32SE, skip these steps and go to [Getting started with the Espressif ESP32-DevKitC and the ESP-WROVER-KIT](getting_started_espressif.md).
If you're using the Nordic nRF52840-DK, skip these steps and go to [Getting started with the Nordic nRF52840-DK](getting_started_nordic.md).

1. [Setting up your AWS account and permissions](#freertos-account-and-permissions) 

1. [Registering your MCU board with AWS IoT](#get-started-freertos-thing)

1. [Downloading FreeRTOS](#freertos-download)

1. [Configuring the FreeRTOS demos](#freertos-configure)

## Setting up your AWS account and permissions
<a name="freertos-account-and-permissions"></a>

### Sign up for an AWS account
<a name="sign-up-for-aws"></a>

If you do not have an AWS account, complete the following steps to create one.

**To sign up for an AWS account**

1. Open [https://portal.aws.amazon.com/billing/signup](https://portal.aws.amazon.com/billing/signup).

1. Follow the online instructions.

   Part of the sign-up procedure involves receiving a phone call or text message and entering a verification code on the phone keypad.

   When you sign up for an AWS account, an *AWS account root user* is created. The root user has access to all AWS services and resources in the account. As a security best practice, assign administrative access to a user, and use only the root user to perform [tasks that require root user access](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks).

AWS sends you a confirmation email after the sign-up process is complete. At any time, you can view your current account activity and manage your account by going to [https://aws.amazon.com/](https://aws.amazon.com/) and choosing **My Account**.

### Create a user with administrative access
<a name="create-an-admin"></a>

After you sign up for an AWS account, secure your AWS account root user, enable AWS IAM Identity Center, and create an administrative user so that you don't use the root user for everyday tasks.

**Secure your AWS account root user**

1.  Sign in to the [AWS Management Console](https://console.aws.amazon.com/) as the account owner by choosing **Root user** and entering your AWS account email address. On the next page, enter your password.

   For help signing in by using root user, see [Signing in as the root user](https://docs.aws.amazon.com/signin/latest/userguide/console-sign-in-tutorials.html#introduction-to-root-user-sign-in-tutorial) in the *AWS Sign-In User Guide*.

1. Turn on multi-factor authentication (MFA) for your root user.

   For instructions, see [Enable a virtual MFA device for your AWS account root user (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/enable-virt-mfa-for-root.html) in the *IAM User Guide*.

**Create a user with administrative access**

1. Enable IAM Identity Center.

   For instructions, see [Enabling AWS IAM Identity Center](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-set-up-for-idc.html) in the *AWS IAM Identity Center User Guide*.

1. In IAM Identity Center, grant administrative access to a user.

   For a tutorial about using the IAM Identity Center directory as your identity source, see [ Configure user access with the default IAM Identity Center directory](https://docs.aws.amazon.com//singlesignon/latest/userguide/quick-start-default-idc.html) in the *AWS IAM Identity Center User Guide*.

**Sign in as the user with administrative access**
+ To sign in with your IAM Identity Center user, use the sign-in URL that was sent to your email address when you created the IAM Identity Center user.

  For help signing in using an IAM Identity Center user, see [Signing in to the AWS access portal](https://docs.aws.amazon.com/signin/latest/userguide/iam-id-center-sign-in-tutorial.html) in the *AWS Sign-In User Guide*.

**Assign access to additional users**

1. In IAM Identity Center, create a permission set that follows the best practice of applying least-privilege permissions.

   For instructions, see [ Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-started-create-a-permission-set.html) in the *AWS IAM Identity Center User Guide*.

1. Assign users to a group, and then assign single sign-on access to the group.

   For instructions, see [ Add groups](https://docs.aws.amazon.com//singlesignon/latest/userguide/addgroups.html) in the *AWS IAM Identity Center User Guide*.

To provide access, add permissions to your users, groups, or roles:
+ Users and groups in AWS IAM Identity Center:

  Create a permission set. Follow the instructions in [Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html) in the *AWS IAM Identity Center User Guide*.
+ Users managed in IAM through an identity provider:

  Create a role for identity federation. Follow the instructions in [Create a role for a third-party identity provider (federation)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html) in the *IAM User Guide*.
+ IAM users:
  + Create a role that your user can assume. Follow the instructions in [Create a role for an IAM user](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html) in the *IAM User Guide*.
  + (Not recommended) Attach a policy directly to a user or add a user to a user group. Follow the instructions in [Adding permissions to a user (console)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) in the *IAM User Guide*.

## Registering your MCU board with AWS IoT
<a name="get-started-freertos-thing"></a>

Your board must be registered with AWS IoT to communicate with the AWS Cloud. To register your board with AWS IoT, you must have:

**An AWS IoT policy**  
The AWS IoT policy grants your device permissions to access AWS IoT resources. It is stored on the AWS Cloud.

**An AWS IoT thing**  
An AWS IoT thing allows you to manage your devices in AWS IoT. It is stored on the AWS Cloud.

**A private key and X.509 certificate**  
The private key and certificate allow your device to authenticate with AWS IoT. 

To register your board, follow the procedures below.

**To create an AWS IoT policy**

1. To create an IAM policy, you must know your AWS Region and AWS account number. 

   To find your AWS account number, open the [AWS Management Console](https://console.aws.amazon.com/), locate and expand the menu beneath your account name in the upper-right corner, and choose **My Account**. Your account ID is displayed under **Account Settings**.

   To find the AWS region for your AWS account, use the AWS Command Line Interface. To install the AWS CLI, follow the instructions in the [AWS Command Line Interface User Guide](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html). After you install the AWS CLI, open a command prompt window and enter the following command:

   ```
   aws iot describe-endpoint --endpoint-type=iot:Data-ATS
   ```

   The output should look like this:

   ```
   {
       "endpointAddress": "xxxxxxxxxxxxxx-ats.iot.us-west-2.amazonaws.com"
   }
   ```

   In this example, the region is `us-west-2`.
**Note**  
We recommend using ATS endpoints as seen in the example.

1. Browse to the [AWS IoT console](https://console.aws.amazon.com/iotv2/).

1. In the navigation pane, choose **Secure**, choose **Policies**, and then choose **Create**.

1. Enter a name to identify your policy.

1. In the **Add statements** section, choose **Advanced mode**. Copy and paste the following JSON into the policy editor window. Replace `aws-region` and `aws-account` with your AWS Region and account ID.

------
#### [ JSON ]

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": [
           {
               "Effect": "Allow",
               "Action": "iot:Connect",
               "Resource": "arn:aws:iot:us-east-1:123456789012:*"
           },
           {
               "Effect": "Allow",
               "Action": "iot:Publish",
               "Resource": "arn:aws:iot:us-east-1:123456789012:*"
           },
           {
               "Effect": "Allow",
               "Action": "iot:Subscribe",
               "Resource": "arn:aws:iot:us-east-1:123456789012:*"
           },
           {
               "Effect": "Allow",
               "Action": "iot:Receive",
               "Resource": "arn:aws:iot:us-east-1:123456789012:*"
           }
       ]
   }
   ```

------

   This policy grants the following permissions:  
**`iot:Connect`**  
Grants your device the permission to connect to the AWS IoT message broker with any client ID.  
**`iot:Publish`**  
Grants your device the permission to publish an MQTT message on any MQTT topic.  
**`iot:Subscribe`**  
Grants your device the permission to subscribe to any MQTT topic filter.  
**`iot:Receive`**  
Grants your device the permission to receive messages from the AWS IoT message broker on any MQTT topic.

1. Choose **Create**.

**To create an IoT thing, private key, and certificate for your device**

1. Browse to the [AWS IoT console](https://console.aws.amazon.com/iotv2/).

1. In the navigation pane, choose **Manage**, and then choose **Things**.

1. If you do not have any IoT things registered in your account, the **You don't have any things yet** page is displayed. If you see this page, choose **Register a thing**. Otherwise, choose **Create**.

1. On the **Creating AWS IoT things** page, choose **Create a single thing**.

1. On the **Add your device to the thing registry** page, enter a name for your thing, and then choose **Next**.

1. On the **Add a certificate for your thing** page, under **One-click certificate creation**, choose **Create certificate**.

1. Download your private key and certificate by choosing the **Download** links for each.

1. Choose **Activate** to activate your certificate. Certificates must be activated prior to use.

1. Choose **Attach a policy** to attach a policy to your certificate that grants your device access to AWS IoT operations.

1. Choose the policy you just created and choose **Register thing**.

After your board is registered with AWS IoT, you can continue to [Downloading FreeRTOS](#freertos-download).

## Downloading FreeRTOS
<a name="freertos-download"></a>

You can download FreeRTOS from the [FreeRTOS GitHub repository](https://github.com/freertos/freertos).

After you download FreeRTOS, you can continue to [Configuring the FreeRTOS demos](#freertos-configure).

## Configuring the FreeRTOS demos
<a name="freertos-configure"></a>

You must edit some configuration files in your FreeRTOS directory before you can compile and run any demos on your board.

**To configure your AWS IoT endpoint**

You must provide FreeRTOS with your AWS IoT endpoint so the application running on your board can send requests to the correct endpoint.

1. Browse to the [AWS IoT console](https://console.aws.amazon.com/iotv2/).

1. In the left navigation pane, choose **Settings**.

   Your AWS IoT endpoint is displayed in **Device data endpoint**. It should look like `1234567890123-ats.iot.us-east-1.amazonaws.com`. Make a note of this endpoint.

1. In the navigation pane, choose **Manage**, and then choose **Things**.

   Your device should have an AWS IoT thing name. Make a note of this name.

1. Open `demos/include/aws_clientcredential.h`.

1. Specify values for the following constants:
   + `#define clientcredentialMQTT_BROKER_ENDPOINT "Your AWS IoT endpoint";`
   + `#define clientcredentialIOT_THING_NAME "The AWS IoT thing name of your board"`

**To configure your Wi-Fi**

If your board is connecting to the internet across a Wi-Fi connection, you must provide FreeRTOS with Wi-Fi credentials to connect to the network. If your board does not support Wi-Fi, you can skip these steps.

1. `demos/include/aws_clientcredential.h`.

1. Specify values for the following `#define` constants:
   + `#define clientcredentialWIFI_SSID "The SSID for your Wi-Fi network"`
   + `#define clientcredentialWIFI_PASSWORD "The password for your Wi-Fi network"`
   + `#define clientcredentialWIFI_SECURITY` *The security type of your Wi-Fi network*

     Valid security types are:
     + `eWiFiSecurityOpen` (Open, no security)
     + `eWiFiSecurityWEP` (WEP security)
     + `eWiFiSecurityWPA` (WPA security)
     + `eWiFiSecurityWPA2` (WPA2 security)

**To format your AWS IoT credentials**

FreeRTOS must have the AWS IoT certificate and private keys associated with your registered thing and its permissions policies to successfully communicate with AWS IoT on behalf of your device.
**Note**  
To configure your AWS IoT credentials, you must have the private key and certificate that you downloaded from the AWS IoT console when you registered your device. 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.

FreeRTOS is a C language project, and the certificate and private key must be specially formatted to be added to the project.

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

1. Under **Certificate PEM file**, choose the `ID-certificate.pem.crt` that you downloaded from the AWS IoT console.

1. Under **Private Key PEM file**, choose the `ID-private.pem.key` that you downloaded from the AWS IoT console.

1. Choose **Generate and save aws\$1clientcredential\$1keys.h**, and then save the file in `demos/include`. This overwrites the existing file in the directory.
**Note**  
The certificate and private key are hard-coded for demonstration purposes only. Production-level applications should store these files in a secure location.

After you configure FreeRTOS, you can continue to the Getting Started guide for your board to set up your platform's hardware and its software development environment, and then compile and run the demo on your board. For board-specific instructions, see the [Board-specific getting started guides](getting-started-guides.md). The demo application that is used in the Getting Started tutorial is the coreMQTT Mutual Authentication demo, which is located at `demos/coreMQTT/mqtt_demo_mutual_auth.c`.

# Troubleshooting getting started
<a name="gsg-troubleshooting"></a>

**Important**  <a name="deprecation-message-general"></a>
This page refers to the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).

The following topics can help you troubleshoot issues that you encounter while getting started with FreeRTOS:

**Topics**
+ [General getting started troubleshooting tips](#gsg-troubleshooting-general)
+ [Installing a terminal emulator](#uart-term)

For board-specific troubleshooting, see the [Get Started with FreeRTOS](freertos-getting-started.md) guide for your board.

## General getting started troubleshooting tips
<a name="gsg-troubleshooting-general"></a>

**No messages appear in the AWS IoT console after I run the Hello World demo project. What do I do?**  
Try the following:  

1. Open a terminal window to view the logging output of the sample. This can help you determine what is going wrong.

1. Check that your network credentials are valid.

**The logs shown in my terminal when running a demo are truncated. How can I increase their length?**  
Increase the value of `configLOGGING_MAX_MESSAGE_LENGTH` to 255 in the `FreeRTOSconfig.h` file for the demo you are running:  

```
#define configLOGGING_MAX_MESSAGE_LENGTH    255
```

## Installing a terminal emulator
<a name="uart-term"></a>

A terminal emulator can help you diagnose problems or verify that your device code is running properly. There are a variety of terminal emulators available for Windows, macOS, and Linux.

You must connect your board to your computer before you attempt to establish a serial connection to your board with a terminal emulator.

Use the following settings to configure your terminal emulator:


| Terminal Setting | Value | 
| --- | --- | 
|  BAUD rate  |  115200  | 
|  Data  |  8 bit  | 
|  Parity  |  none  | 
|  Stop  |  1 bit  | 
|  Flow control  |  none  | 

### Finding your board's serial port
<a name="serial-port-ts"></a>

If you do not know your board's serial port, you can issue one of the following commands from the command line or terminal to return the serial ports for all devices connected to your host computer:

**Windows**  

```
chgport
```

**Linux**  

```
ls /dev/tty*
```

**macOS**  

```
ls /dev/cu.*
```

# Using CMake with FreeRTOS
<a name="getting-started-cmake"></a>

**Important**  <a name="deprecation-message-general"></a>
This page refers to the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).

You can use CMake to generate project build files from FreeRTOS application source code, and to build and run the source code.

You can also use an IDE to edit, debug, compile, flash, and run code on FreeRTOS-qualified devices. Each board-specific Getting Started guide includes instructions for setting up the IDE for a particular platform. If you prefer working without an IDE, you can use other third-party code editing and debugging tools for developing and debugging your code, and then use CMake to build and run the applications.

The following boards support CMake:
+ Espressif ESP32-DevKitC
+ Espressif ESP-WROVER-KIT
+ Infineon XMC4800 IoT Connectivity Kit
+ Marvell MW320 AWS IoT Starter Kit
+ Marvell MW322 AWS IoT Starter Kit
+ Microchip Curiosity PIC32MZEF Bundle
+ Nordic nRF52840 DK Development kit
+ STMicroelectronicsSTM32L4 Discovery Kit IoT Node
+ Texas Instruments CC3220SF-LAUNCHXL
+ Microsoft Windows Simulator

See the topics below for more information about using CMake with FreeRTOS.

**Topics**
+ [Prerequisites](#building-cmake-prereqs)
+ [Developing FreeRTOS applications with third-party code editors and debugging tools](#developing-third-party)
+ [Building FreeRTOS with CMake](#building-cmake)

## Prerequisites
<a name="building-cmake-prereqs"></a>

Make sure that your host machine meets the following prerequisites before continuing:
+ Your device's compilation toolchain must support the machine's operating system. CMake supports all versions of Windows, macOS, and Linux

  Windows subsystem for Linux (WSL) is not supported. Use native CMake on Windows machines.
+ You must have CMake version 3.13 or higher installed.

  You can download the binary distribution of CMake from [CMake.org](https://cmake.org/download/).
**Note**  
If you download the binary distribution of CMake, make sure that you add the CMake executable to the PATH environment variable before you using CMake from command line.

  You can also download and install CMake using a package manager, like [homebrew](https://brew.sh/) on macOS, and [scoop](https://scoop.sh/) or [chocolatey](https://chocolatey.org/) on Windows.
**Note**  
The CMake package versions provided in the package managers for many Linux distributions are out-of-date. If your distribution's package manager does not provide the latest version of CMake, you can try alternative package managers, like `linuxbrew` or `nix`.
+ You must have a compatible native build system.

  CMake can target many native build systems, including [GNU Make](https://www.gnu.org/software/make/) or [Ninja](https://github.com/ninja-build/ninja/releases). Both Make and Ninja can be installed with package managers on Linux, macOS and Windows. If you are using Make on Windows, you can install a standalone version from [Equation](http://www.equation.com/servlet/equation.cmd?fa=make), or you can install [MinGW](https://sourceforge.net/projects/mingw-w64/files/), which bundles make.
**Note**  
The Make executable in MinGW is called `mingw32-make.exe`, instead of `make.exe`.

  We recommend that you use Ninja, as it is faster than Make and also provides native support to all desktop operating systems.

## Developing FreeRTOS applications with third-party code editors and debugging tools
<a name="developing-third-party"></a>

You can use a code editor and a debugging extension or a third-party debugging tool to develop applications for FreeRTOS.

If, for example, you use [Visual Studio Code](https://code.visualstudio.com/) as your code editor, you can install the [Cortex-Debug](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug) VS Code extension as a debugger. When you finish developing your application, you can invoke the CMake command-line tool to build your project from within VS Code. For more information about using CMake to build FreeRTOS applications, see [Building FreeRTOS with CMake](#building-cmake).

For debugging, you can provide a VS Code with debug configuration similar to the following:

```
"configurations": [
    {
        "name": "Cortex Debug",
        "cwd": "${workspaceRoot}",
        "executable": "./build/st/stm32l475_discovery/aws_demos.elf",
        "request": "launch",
        "type": "cortex-debug",
        "servertype": "stutil"
    }
]
```

## Building FreeRTOS with CMake
<a name="building-cmake"></a>

CMake targets your host operating system as the target system by default. To use it for cross compiling, CMake requires a toolchain file, which specifies the compiler that you want to use. In FreeRTOS, we provide default toolchain files in `freertos/tools/cmake/toolchains`. The way to provide this file to CMake depends on whether you’re using the CMake command line interface or GUI. For more details, follow the [Generating build files (CMake command-line tool)](#cmake-gen-cli) instructions below. For more information about cross-compiling in CMake, see [CrossCompiling](https://gitlab.kitware.com/cmake/community/wikis/doc/cmake/CrossCompiling) in the official CMake wiki.

**To build a CMake-based project**

1. Run CMake to generate the build files for a native build system, like Make or Ninja.

   You can use either the [CMake command-line tool](https://cmake.org/cmake/help/latest/manual/cmake.1.html) or the [CMake GUI](https://cmake.org/cmake/help/latest/manual/cmake-gui.1.html) to generate the build files for your native build system.

   For information about generating FreeRTOS build files, see [Generating build files (CMake command-line tool)](#cmake-gen-cli) and [Generating build files (CMake GUI)](#cmake-gen-gui).

1. Invoke the native build system to make the project into an executable.

   For information about making FreeRTOS build files, see [Building FreeRTOS from generated build files](#cmake-build).

### Generating build files (CMake command-line tool)
<a name="cmake-gen-cli"></a>

You can use the CMake command-line tool (cmake) to generate build files for FreeRTOS. To generate the build files, you need to specify a target board, a compiler, and the location of the source code and build directory. 

You can use the following options for cmake:
+ `-DVENDOR` – Specifies the target board.
+ `-DCOMPILER` – Specifies the compiler.
+ `-S` – Specifies the location of the source code.
+ `-B` – Specifies the location of generated build files.

 

**Note**  
The compiler must be in the system's `PATH` variable, or you must specify the location of the compiler.

For example, if the vendor is Texas Instruments, and the board is the CC3220 Launchpad, and the compiler is GCC for ARM, you can issue the following command to build the source files from the current directory to a directory named `build-directory`:

```
cmake -DVENDOR=ti -DBOARD=cc3220_launchpad -DCOMPILER=arm-ti -S . -B build-directory
```

**Note**  
If you are using Windows, you must specify the native build system because CMake uses Visual Studio by default. For example:  

```
cmake -DVENDOR=ti -DBOARD=cc3220_launchpad -DCOMPILER=arm-ti -S . -B build-directory -G Ninja
```
Or:  

```
cmake -DVENDOR=ti -DBOARD=cc3220_launchpad -DCOMPILER=arm-ti -S . -B build-directory -G "MinGW Makefiles"
```

The regular expressions `${VENDOR}.*` and `${BOARD}.*` are used to search for a matching board, so you don't have to use the full names of the vendor and board for the `VENDOR` and `BOARD` options. Partial names work, provided there is a single match. For example, the following commands generate the same build files from the same source:

```
cmake -DVENDOR=ti -DCOMPILER=arm-ti -S . -B build-directory
```

```
cmake -DBOARD=cc3220 -DCOMPILER=arm-ti -S . -B build-directory
```

```
cmake -DVENDOR=t -DBOARD=cc -DCOMPILER=arm-ti -S . -B build-directory
```

You can use the `CMAKE_TOOLCHAIN_FILE` option if you want to use a toolchain file that is not located in the default directory `cmake/toolchains`. For example:

```
cmake -DBOARD=cc3220 -DCMAKE_TOOLCHAIN_FILE='/path/to/toolchain_file.cmake' -S . -B build-directory
```

If the toolchain file does not use absolute paths for your compiler, and you didn't add your compiler to the `PATH` environment variable, CMake might not be able to find it. To make sure that CMake finds your toolchain file, you can use the `AFR_TOOLCHAIN_PATH` option. This option searches the specified toolchain directory path and the toolchain's subfolder under `bin`. For example:

```
cmake -DBOARD=cc3220 -DCMAKE_TOOLCHAIN_FILE='/path/to/toolchain_file.cmake' -DAFR_TOOLCHAIN_PATH='/path/to/toolchain/' -S . -B build-directory
```

To enable debugging, set the `CMAKE_BUILD_TYPE` to `debug`. With this option enabled, CMake adds debug flags to the compile options, and builds FreeRTOS with debug symbols.

```
# Build with debug symbols
cmake -DBOARD=cc3220 -DCOMPILER=arm-ti -DCMAKE_BUILD_TYPE=debug -S . -B build-directory
```

You can also set the `CMAKE_BUILD_TYPE` to `release` to add optimization flags to the compile options.

### Generating build files (CMake GUI)
<a name="cmake-gen-gui"></a>

You can use the CMake GUI to generate FreeRTOS build files.

**To generate build files with the CMake GUI**

1. From the command line, issue `cmake-gui` to start the GUI.

1. Choose **Browse Source** and specify the source input, and then choose **Browse Build** and specify the build output.  
![\[CMake window with input fields for source code location and build binaries location, along with options to browse sources, browse build directory, search, add or remove entry, and view grouped or advanced options.\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/cmake-gui1.png)

1. Choose **Configure**, and under **Specify the build generator for this project**, find and choose the build system that you want to use to build the generated build files. if you do not see the pop up window, you might be reusing an existing build directory. In this case, delete the CMake cache by choosing **Delete Cache** from the **File** menu.  
![\[CMakeSetup dialog with options to specify the generator for the project as Unix Makefiles, and specify toolchain file for cross-compiling.\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/cmake-gui2.png)

1. Choose **Specify toolchain file for cross-compiling**, and then choose **Next**.

1. Choose the toolchain file (for example, `freertos/tools/cmake/toolchains/arm-ti.cmake`), and then choose **Finish**.

   The default configuration for FreeRTOS is the template board, which does not provide any portable layer targets. As a result, a window appears with the message Error in configuration process.
**Note**  
If you are seeing the following error:  

   ```
   CMake Error at tools/cmake/toolchains/find_compiler.cmake:23 (message):
   Compiler not found, you can specify search path with AFR_TOOLCHAIN_PATH.
   ```

   It means the compiler is not in your `PATH` environment variable. You can set the `AFR_TOOLCHAIN_PATH` variable in the GUI to tell CMake where you installed your compiler. If you do not see the `AFR_TOOLCHAIN_PATH` variable, choose **Add Entry**. In the pop up window, under **Name**, type **AFR\$1TOOLCHAIN\$1PATH**. Under **Compiler Path** type the path to your compiler. for example, `C:/toolchains/arm-none-eabi-gcc`.

1. The GUI should now look like this:  
![\[CMake configuration window for building FreeRTOS with vendor board selected, modules enabled, and build paths specified.\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/cmake-gui3.png)

   Choose **AFR\$1BOARD**, choose your board, and then choose **Configure** again.

1. Choose **Generate**. CMake generates the build system files (for example, makefiles or ninja files), and these files appear in the build directory you specified in the first step. Follow the instructions in the next section to generate the binary image.

### Building FreeRTOS from generated build files
<a name="cmake-build"></a>

#### Building with native build system
<a name="gsg-cmake-native"></a>

You can build FreeRTOS with a native build system by calling the build system command from the output binaries directory.

For example, if your build file output directory is `<build_dir>`, and you are using Make as your native build system, run the following commands:

```
cd <build_dir>
make -j4
```

#### Building with CMake
<a name="gsg-cmake-build"></a>

You can also use the CMake command-line tool to build FreeRTOS. CMake provides an abstraction layer for calling native build systems. For example:

```
cmake --build build_dir
```

Here are some other common uses of the CMake command-line tool's build mode:

```
# Take advantage of CPU cores.
cmake --build build_dir --parallel 8
```

```
# Build specific targets.
cmake --build build_dir --target afr_kernel
```

```
# Clean first, then build.
cmake --build build_dir --clean-first
```

For more information about the CMake build mode, see the [CMake documentation](https://cmake.org/cmake/help/latest/manual/cmake.1.html#build-tool-mode).

# Developer-mode key provisioning
<a name="dev-mode-key-provisioning"></a>

**Important**  <a name="deprecation-message-general"></a>
This page refers to the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).

## Introduction
<a name="dev-mode-key-provisioning-intro"></a>

This section discusses two options to get a trusted X.509 client certificate onto an IoT device for lab testing. Depending on the capabilities of the device, various provisioning-related operations may or may not be supported, including onboard ECDSA key generation, private key import, and X.509 certificate enrollment. In addition, different use cases call for different levels of key protection, ranging from onboard flash storage to the use of dedicated crypto hardware. This section provides logic for working within the cryptographic capabilities of your device.

## Option \$11: private key import from AWS IoT
<a name="dev-mode-key-provisioning-option1"></a>

For lab testing purposes, if your device allows the import of private keys, follow the instructions in [Configuring the FreeRTOS demos](freertos-prereqs.md#freertos-configure).

## Option \$12: onboard private key generation
<a name="dev-mode-key-provisioning-option2"></a>

If your device has a secure element, or if you prefer to generate your own device key pair and certificate, follow the instructions here.

**Initial Configuration**  
First, perform the steps in [Configuring the FreeRTOS demos](freertos-prereqs.md#freertos-configure), but skip the last step (that is, don't do *To format your AWS IoT credentials*). The net result should be that the `demos/include/aws_clientcredential.h` file has been updated with your settings, but the `demos/include/aws_clientcredential_keys.h` file has not.

**Demo Project Configuration**  
Open the coreMQTT Mutual Authentication demo as described in the guide for your board in [Board-specific getting started guides](getting-started-guides.md) . In the project, open the file `aws_dev_mode_key_provisioning.c` and change the definition of `keyprovisioningFORCE_GENERATE_NEW_KEY_PAIR`, which is set to zero by default, to one:  

```
#define keyprovisioningFORCE_GENERATE_NEW_KEY_PAIR 1
```
Then build and run the demo project and continue to the next step.

**Public Key Extraction**  
Because the device hasn't been provisioned with a private key and client certificate, the demo will fail to authenticate to AWS IoT. However, the coreMQTT Mutual Authentication demo starts by running developer-mode key provisioning, resulting in the creation of a private key if one was not already present. You should see something like the following near the beginning of the serial console output.  

```
7 910 [IP-task] Device public key, 91 bytes:
3059 3013 0607 2a86 48ce 3d02 0106 082a
8648 ce3d 0301 0703 4200 04cd 6569 ceb8
1bb9 1e72 339f e8cf 60ef 0f9f b473 33ac
6f19 1813 6999 3fa0 c293 5fae 08f1 1ad0
41b7 345c e746 1046 228e 5a5f d787 d571
dcb2 4e8d 75b3 2586 e2cc 0c
```
Copy the six lines of key bytes into a file called `DevicePublicKeyAsciiHex.txt`. Then use the command-line tool "xxd" to parse the hex bytes into binary:  

```
xxd -r -ps DevicePublicKeyAsciiHex.txt DevicePublicKeyDer.bin
```
Use "openssl" to format the binary encoded (DER) device public key as PEM:  

```
openssl ec -inform der -in DevicePublicKeyDer.bin -pubin -pubout -outform pem -out DevicePublicKey.pem
```
Don't forget to disable the temporary key generation setting you enabled above. Otherwise, the device will create yet another key pair, and you will have to repeat the previous steps:  

```
#define keyprovisioningFORCE_GENERATE_NEW_KEY_PAIR 0
```

**Public Key Infrastructure Setup**  
Follow the instructions in [ Registering Your CA Certificate](https://docs.aws.amazon.com/iot/latest/developerguide/device-certs-your-own.html#register-CA-cert) to create a certificate hierarchy for your device lab certificate. Stop before executing the sequence described in the section *Creating a Device Certificate Using Your CA Certificate*.  
In this case, the device will not be signing the certificate request (that is, the Certificate Service Request or CSR) because the X.509 encoding logic required for creating and signing a CSR has been excluded from the FreeRTOS demo projects to reduce ROM size. Instead, for lab testing purposes, create a private key on your workstation and use it to sign the CSR.  

```
openssl genrsa -out tempCsrSigner.key 2048
openssl req -new -key tempCsrSigner.key -out deviceCert.csr
```
Once your Certificate Authority has been created and registered with AWS IoT, use the following command to issue a client certificate based on the device CSR that was signed in the previous step:  

```
openssl x509 -req -in deviceCert.csr -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -out deviceCert.pem -days 500 -sha256 -force_pubkey DevicePublicKey.pem 
```
Even though the CSR was signed with a temporary private key, the issued certificate can only be used with the actual device private key. The same mechanism can be used in production if you store the CSR signer key in separate hardware, and configure your certificate authority so that it only issues certificates for requests that have been signed by that specific key. That key should also remain under the control of a designated administrator.

**Certificate Import**  
With the certificate issued, the next step is to import it into your device. You will also need to import your Certificate Authority (CA) certificate, since it is required in order for first-time authentication to AWS IoT to succeed when using JITP. In the `aws_clientcredential_keys.h` file in your project, set the `keyCLIENT_CERTIFICATE_PEM` macro to be the contents of deviceCert.pem and set the `keyJITR_DEVICE_CERTIFICATE_AUTHORITY_PEM` macro to be the contents of `rootCA.pem`.

**Device Authorization**  
Import `deviceCert.pem` into the AWS IoT registry as described in [ Use Your Own Certificate](https://docs.aws.amazon.com/iot/latest/developerguide/device-certs-your-own.html#manual-cert-registration). You must create a new AWS IoT thing, attach the PENDING certificate and a policy to your thing, then mark the certificate as ACTIVE. All of these steps can be performed manually in the AWS IoT console.  
Once the new client certificate is ACTIVE and associated with a thing and a policy, run the coreMQTT Mutual Authentication demo again. This time, the connection to the AWS IoT MQTT broker will succeed.

# Board-specific getting started guides
<a name="getting-started-guides"></a>

**Important**  <a name="deprecation-message-general"></a>
This page refers to the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).

After you complete the [First steps](freertos-prereqs.md), see your board's guide for board-specific instructions on getting started with FreeRTOS:
+ [Getting started with the Cypress CYW943907AEVAL1F Development Kit](getting_started_cypress_43.md)
+ [Getting started with the Cypress CYW954907AEVAL1F Development Kit](getting_started_cypress_54.md)
+ [Getting started with the Cypress CY8CKIT-064S0S2-4343W kit](getting_started_cypress_psoc64.md)
+ [Getting started with the Infineon XMC4800 IoT Connectivity Kit](getting_started_infineon.md)
+ [Getting started with the MW32x AWS IoT Starter Kit](getting_started_mw32x.md)
+ [Getting started with the MediaTek MT7697Hx development kit](getting_started_mediatek.md)
+ [Getting started with the Microchip Curiosity PIC32MZ EF](getting_started_mch.md)
+ [Getting started with the Nuvoton NuMaker-IoT-M487](getting-started-nuvoton-m487.md)
+ [Getting started with the NXP LPC54018 IoT Module](getting_started_nxp.md)
+ [Getting started with the Renesas Starter Kit\$1 for RX65N-2MB](getting_started_renesas.md)
+ [Getting started with the STMicroelectronics STM32L4 Discovery Kit IoT Node](getting_started_st.md)
+ [Getting started with the Texas Instruments CC3220SF-LAUNCHXL](getting_started_ti.md)
+ [Getting started with the Windows Device Simulator](getting_started_windows.md)
+ [Getting started with the Xilinx Avnet MicroZed Industrial IoT Kit](getting_started_xilinx.md)

**Note**  
You do not need to complete the [First steps](freertos-prereqs.md) for the following self-contained Getting Started with FreeRTOS guides:  
[Getting started with the Microchip ATECC608A Secure Element with Windows simulator](getting_started_atecc608a.md)
[Getting started with the Espressif ESP32-DevKitC and the ESP-WROVER-KIT](getting_started_espressif.md)
[Getting started with the Espressif ESP32-WROOM-32SE](getting_started_esp32wroom-32se.md)
[Getting started with the Espressif ESP32-S2](getting_started_esp32-s2.md)
[Getting started with the Infineon OPTIGA Trust X and XMC4800 IoT Connectivity Kit](getting_started_infineon_trust_x.md)
[Getting started with the Nordic nRF52840-DK](getting_started_nordic.md)

# Getting started with the Cypress CYW943907AEVAL1F Development Kit
<a name="getting_started_cypress_43"></a>

**Important**  <a name="deprecation-message"></a>
This reference integration is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).

This tutorial provides instructions for getting started with the Cypress CYW943907AEVAL1F Development Kit. If you do not have the Cypress CYW943907AEVAL1F Development Kit, visit the AWS Partner Device Catalog to purchase one from our [partner](https://devices.amazonaws.com/detail/a3G0L00000AAPg0UAH/CYW943907AEVAL1F).

**Note**  
This tutorial walks you through setting up and running the coreMQTT Mutual Authentication demo. The FreeRTOS port for this board currently does not 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](freertos-prereqs.md) for instructions.

**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](https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development) 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\$1](https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-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-prereqs.md#freertos-download), FreeRTOS ports for Cypress are currently only available on [ GitHub](https://github.com/aws/amazon-freertos).

## Overview
<a name="overview-for-cypress-tutorial"></a>

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.

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

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

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

## Setting up your development environment
<a name="cypress43-setup-env"></a>

### Download and install the WICED Studio SDK
<a name="cypress43-install-wiced-studio"></a>

In this Getting Started guide, you use the Cypress WICED Studio SDK to program your board with the FreeRTOS demo. Visit the [WICED Software](https://www.cypress.com/products/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
<a name="cypress43-environment"></a>

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

1. On the **Advanced** tab, choose **Environment Variables**.

1. Under **User variables**, choose **New**.

1. For **Variable name**, enter **WICED\$1STUDIO\$1SDK\$1PATH**. 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
   ```

1. Restart your machine.

1. 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
<a name="cypress43-serial-connection"></a>

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

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

1. 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](gsg-troubleshooting.md#uart-term).

## Monitoring MQTT messages on the cloud
<a name="cypress43-monitor-mqtt"></a>

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](https://console.aws.amazon.com/iotv2/).

1. In the navigation pane, choose **Test**, then choose **MQTT test client** to open the MQTT client.

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

## Build and run the FreeRTOS demo project
<a name="gsg-cypress43-build-and-run-example"></a>

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.

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

1. In **Select root directory**, select **Browse...**, navigate to the path `freertos/projects/cypress/CYW943907AEVAL1F/wicedstudio`, and then select **OK**.

1. Under **Projects**, check the box for just the **aws\$1demo** project. Choose **Finish** to import the project. The target project **aws\$1demo** should appear in the **Make Target** window.

1. Expand the **WICED Platform** menu and choose **WICED Filters off**.

1. In the **Make Target** window, expand **aws\$1demo**, 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
<a name="cypress43-troubleshooting"></a>
+ 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`.

  1. 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](gsg-troubleshooting.md).

# Getting started with the Cypress CYW954907AEVAL1F Development Kit
<a name="getting_started_cypress_54"></a>

**Important**  <a name="deprecation-message"></a>
This reference integration is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).

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](https://devices.amazonaws.com/detail/a3G0L00000AAPg5UAH/CYW954907AEVAL1F).

**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](freertos-prereqs.md) 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](https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development) 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\$1](https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-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-prereqs.md#freertos-download), FreeRTOS ports for Cypress are currently only available on [ GitHub](https://github.com/aws/amazon-freertos).

## Overview
<a name="overview-for-cypress-CYW954907AEVAL1F-tutorial"></a>

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.

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

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

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

## Setting up your development environment
<a name="cypress54-setup-env"></a>

### Download and install the WICED Studio SDK
<a name="cypress54-install-wiced-studio"></a>

In this Getting Started guide, you use the Cypress WICED Studio SDK to program your board with the FreeRTOS demo. Visit the [WICED Software](https://www.cypress.com/products/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
<a name="cypress54-environment"></a>

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

1. On the **Advanced** tab, choose **Environment Variables**.

1. Under **User variables**, choose **New**.

1. For **Variable name**, enter **WICED\$1STUDIO\$1SDK\$1PATH**. 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
   ```

1. Restart your machine.

1. 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
<a name="cypress54-serial-connection"></a>

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

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

1. 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](gsg-troubleshooting.md#uart-term).

## Monitoring MQTT messages on the cloud
<a name="cypress54-monitor-mqtt"></a>

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](https://console.aws.amazon.com/iotv2/).

1. In the navigation pane, choose **Test**, then choose **MQTT test client** to open the MQTT client.

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

## Build and run the FreeRTOS demo project
<a name="cypress54-build-and-run-example"></a>

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.

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

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

1. Under **Projects**, check the box for just the **aws\$1demo** project. Choose **Finish** to import the project. The target project **aws\$1demo** should appear in the **Make Target** window.

1. Expand the **WICED Platform** menu and choose **WICED Filters off**.

1. In the **Make Target** window, expand **aws\$1demo**, 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
<a name="cypress54-troubleshooting"></a>
+ 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`.

  1. 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](gsg-troubleshooting.md).

# Getting started with the Cypress CY8CKIT-064S0S2-4343W kit
<a name="getting_started_cypress_psoc64"></a>

**Important**  <a name="deprecation-message"></a>
This reference integration is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).

This tutorial provides instructions for getting started with the [CY8CKIT-064S0S2-4343W](https://www.cypress.com/CY8CKIT-064S0S2-4343W) kit. If you don't already have one, you can use that link to purchase a kit. You can also use that link to access the kit user guide. 

## Getting started
<a name="getting_started_cypress_psoc64_first"></a>

Before you begin, you must configure AWS IoT and FreeRTOS to connect your device to the AWS Cloud. For instructions, see [First steps](freertos-prereqs.md). After you complete the prerequisites, you will have a FreeRTOS package with AWS IoT Core credentials.

**Note**  
In this tutorial, the path to the FreeRTOS download directory created in the "First steps" section is referred to as `freertos`.

## Setting up the development environment
<a name="getting_started_cypress_psoc64_setup"></a>

FreeRTOS works with either a CMake or Make build flow. You can use ModusToolbox for your Make build flow. You can use the Eclipse IDE delivered with ModusToolbox or a partner IDE such as IAR EW-Arm, Arm MDK, or Microsoft Visual Studio Code. The Eclipse IDE is compatible with the Windows, macOS, and Linux operating systems. 

Before you begin, download and install the latest [ModusToolbox software](https://www.cypress.com/products/modustoolbox-software-environment). For more information, see the [ModusToolbox Installation Guide](https://www.cypress.com/ModusToolboxInstallGuide).

### Updating tools for ModusToolbox 2.1 or older
<a name="getting_started_cypress_psoc64_modus_toolbox_updates"></a>

If you're using the ModusToolbox 2.1 Eclipse IDE to program this kit, you'll need to update the OpenOCD and Firmware-loader tools. 

In the following steps, by default the `ModusToolbox` path for:
+ Windows is `C:\Users\user_name\ModusToolbox`.
+ Linux is `user_home/ModusToolbox` or where you choose to extract the archive file.
+ MacOS is under the Applications folder in the volume you select in the wizard.

#### Updating OpenOCD
<a name="getting_started_cypress_psoc64_openocd_update"></a>

This kit requires Cypress OpenOCD 4.0.0 or later to successfully erase and program the chip.

**To update Cypress OpenOCD**

1. Go to the [Cypress OpenOCD release page](https://github.com/Infineon/openocd/releases).

1. Download the archive file for your OS (Windows/Mac/Linux).

1. Delete the existing files in `ModusToolbox/tools_2.x/openocd`.

1. Replace the files in `ModusToolbox/tools_2.x/openocd` with the extracted contents of the archive that you downloaded in a previous step.

#### Updating Firmware-loader
<a name="getting_started_cypress_psoc64_firmware_loader_update"></a>

This kit requires Cypress Firmware-loader 3.0.0 or later.

**To update Cypress Firmware-loader**

1. Go to the [Cypress Firmware-loader release page](https://github.com/cypresssemiconductorco/Firmware-loader/releases).

1. Download the archive file for your OS (Windows/Mac/Linux).

1. Delete the existing files in `ModusToolbox/tools_2.x/fw-loader`.

1. Replace the files in `ModusToolbox/tools_2.x/fw-loader` with the extracted contents of the archive that you downloaded in a previous step.

Alternatively, you can use CMake to generate project build files from FreeRTOS application source code, build the project using your preferred build tool, and then program the kit using OpenOCD. If you prefer to use a GUI tool for programming with the CMake flow, download and install Cypress Programmer from the [Cypress Programming Solutions](https://www.cypress.com/products/psoc-programming-solutions) webpage. For more information, see [Using CMake with FreeRTOS](getting-started-cmake.md).

## Setting up your hardware
<a name="getting_started_cypress_psoc64_hardware"></a>

Follow these steps to set up the kit's hardware.

1. 

**Provision your kit**  
Follow the [Provisioning Guide for CY8CKIT-064S0S2-4343W Kit](https://community.cypress.com/docs/DOC-20043) instructions to securely provision your kit for AWS IoT.

   This kit requires CySecureTools 3.1.0 or later.

1. **Set up a serial connection**

   1. Connect the kit to your host computer.

   1. The USB Serial port for the kit is automatically enumerated on the host computer. Identify the port number. In Windows, you can identify it using the **Device Manager** under **Ports** (COM & LPT).

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

## Build and run the FreeRTOS Demo project
<a name="getting_started_cypress_psoc64_build_run"></a>

In this section you build and run the demo.

1. Make sure to follow the steps in [Provisioning Guide for CY8CKIT-064S0S2-4343W Kit](https://community.cypress.com/docs/DOC-20043).

1. **Build the FreeRTOS Demo.**

   1. Open the Eclipse IDE for ModusToolbox and choose, or create, a workspace.

   1. From the **File** menu, choose **Import**.

      Expand **General**, choose **Existing Project Into Workspace**, and then choose **Next**.

   1. In **Root Directory**, enter `freertos/projects/cypress/CY8CKIT-064S0S2-4343W/mtb/aws_demos` and then select the project name `aws_demos`. It should be selected by default.

   1. Choose **Finish** to import the project into your workspace.

   1. Build the application by doing one of the following:
      + From the **Quick Panel**, select **Build aws\$1demos Application**.
      + Choose **Project** and choose **Build All**.

      Make sure the project compiles without errors.

1. 

**Monitoring MQTT Messages on the Cloud**  
Before you run the demo, 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, follow these steps.

   1. Sign in to the [AWS IoT console](https://console.aws.amazon.com//iotv2/).

   1. In the navigation pane, choose **Test**, then choose **MQTT test client** to open the MQTT client.

   1. For **Subscription topic**, enter ***your-thing-name*/example/topic**, and then choose **Subscribe to topic**.

1. **Run the FreeRTOS demo project**

   1. Select the project `aws_demos` in the workspace.

   1. From the **Quick Panel**, select **aws\$1demos Program (KitProg3)**. This programs the board and the demo application starts running after the programming is finished.

   1. You can view the status of the running application in the serial terminal. The following figure shows a part of the terminal output.  
![\[Screenshot of the terminal output after you build the aws_demo project.\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/gsg-psoc64-terminal-output.png)

      The MQTT demo publishes messages on four different topics (`iotdemo/topic/n`, where n=1 to 4) and subscribes to all those topics to receive the same messages back. When a message is received, the demo publishes an acknowledgement message on the topic `iotdemo/acknowledgements`. The following list describes the debug messages that appear in the terminal output, with references to the serial numbers of the messages. In the output, the WICED Host Driver (WHD) driver details are printed first without serial numbering. 

      1. 1 to 4 – Device connects to the configured Access Point (AP) and is provisioned by connecting to the AWS server using the configured endpoint and certificates.

      1. 5 to 13 – coreMQTT library is initialized and device establishes MQTT connection.

      1. 14 to 17 – Device subscribes to all the topics to receive the published messages back.

      1. 18 to 30 – Device publishes two messages and waits to receive them back. When each message is received, the device sends an acknowledgement message.

      The same cycle of publish, receive, and acknowledge continues until all the messages are published. Two messages are published per cycle until the number of cycles configured are completed.

1. 

**Using CMake with FreeRTOS**  
You can also use CMake to build and run the demo application. To set up CMake and a native build system, see [Prerequisites](getting-started-cmake.md#building-cmake-prereqs).

   1. Use the following command to generate build files. Specify the target board with the `-DBOARD` option. 

      ```
      cmake -DVENDOR=cypress -DBOARD=CY8CKIT_064S0S2_4343W -DCOMPILER=arm-gcc -S freertos -B build_dir
      ```

      If you're using Windows, you must specify the native build system using the `-G` option because CMake uses Visual Studio by default.   
**Example**  

      ```
      cmake -DVENDOR=cypress -DBOARD=CY8CKIT_064S0S2_4343W -DCOMPILER=arm-gcc -S freertos -B build_dir -G Ninja
      ```

      If `arm-none-eabi-gcc` is not in your shell path, you also need to set the `AFR_TOOLCHAIN_PATH` CMake variable.   
**Example**  

      ```
       -DAFR_TOOLCHAIN_PATH=/home/user/opt/gcc-arm-none-eabi/bin
      ```

   1. Use the following command to build the project using CMake.

      ```
      cmake --build build_dir
      ```

   1. Finally, program the `cm0.hex` and `cm4.hex` files generated under `build_dir` by using Cypress Programmer.

### Running other demos
<a name="getting_started_cypress_psoc64_demos"></a>

The following demo applications have been tested and verified to work with the current release. You can find these demos under the `freertos/demos` directory. For information on how to run these demos, see [FreeRTOS demos](freertos-next-steps.md).
+ Bluetooth Low Energy demo
+ Over-the-Air Updates demo
+ Secure Sockets Echo Client demo
+ AWS IoT Device Shadow demo

## Debugging
<a name="getting_started_cypress_psoc64_debugging"></a>

The KitProg3 on the kit supports debugging over the SWD protocol.
+ To debug the FreeRTOS application, select the **aws\$1demos project** in the workspace and then select **aws\$1demos Debug (KitProg3)** from the **Quick Panel**.

## OTA updates
<a name="getting_started_cypress_psoc64_ota_updates"></a>

PSoC 64 MCUs have passed all of the required FreeRTOS qualification tests. However, the optional over-the-air (OTA) feature implemented in the PSoC 64 Standard Secure AWS firmware library is still pending evaluation. The OTA feature as-implemented currently passes all of the OTA qualification tests except [ aws\$1ota\$1test\$1case\$1rollback\$1if\$1unable\$1to\$1connect\$1after\$1update.py](https://github.com/aws/amazon-freertos/blob/202012.00/tools/ota_e2e_tests/aws_ota_test/aws_ota_test_case_rollback_if_unable_to_connect_after_update.py). 

When a successfully validated OTA image is applied to a device using the PSoC64 Standard Secure – AWS MCU and the device can't communicate with AWS IoT Core, the device can't automatically rollback to the original known good image. This might result in the device being unreachable from AWS IoT Core for further updates. This functionality is still under development by the Cypress team.

For more information, see [OTA Updates with AWS and the CY8CKIT-064S0S2-4343W Kit](https://community.cypress.com/docs/DOC-20063). If you have further questions or need technical support, contact the [Cypress Developer Community](https://community.cypress.com).

# Getting started with the Microchip ATECC608A Secure Element with Windows simulator
<a name="getting_started_atecc608a"></a>

**Important**  <a name="deprecation-message"></a>
This reference integration is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).

This tutorial provides instructions for getting started with the Microchip ATECC608A Secure Element with Windows Simulator.

You need the following hardware:
+ [Microchip ATECC608A secure element clickboard](https://www.mikroe.com/secure-4-click)
+ [ SAMD21 XPlained Pro](https://www.microchipdirect.com/product/ATSAMD21-XPRO?dfw_tracker=64197-ATSAMD21-XPRO&gclid=EAIaIQobChMIn5jIuM3C5QIVk_5kCh1m1Ag4EAQYASABEgLKtfD_BwE)
+ [ mikroBUS Xplained Pro adapter](https://www.microchip.com/Developmenttools/ProductDetails/ATMBUSADAPTER-XPRO)

Before you begin, you must configure AWS IoT and your FreeRTOS download to connect your device to the AWS Cloud. See [First steps](freertos-prereqs.md) for instructions. In this tutorial, the path to the FreeRTOS download directory is referred to as *freertos*.

## Overview
<a name="gsg-atcc608a-overview"></a>

This tutorial contains the following steps:

1. Connect your board to a host machine.

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

1. Cross-compile an FreeRTOS demo application to a binary image.

1. Load the application binary image to your board, and then run the application.

## Set up the Microchip ATECC608A hardware
<a name="gsg-atcc608a-setup"></a>

Before you can interact with your Microchip ATECC608A device, you must first program the SAMD21.

**To set up the SAMD21 XPlained Pro board**

1. Follow the [CryptoAuthSSH-XSTK (DM320109) - Latest Firmware](http://ww1.microchip.com/downloads/en/DeviceDoc/ATCRYPTOAUTHSSH-XSTK_v1.0.1.zip) link to download a .zip file containing instructions (PDF) and a binary which can be programmed onto the D21.

1. Download and install the [Atmel Studio 7](https://microchipdeveloper.com/atstudio:studio7intro) IDP. Make sure that you select the **SMART ARM MCU** driver architecture during installation.

1. Use a USB 2.0 Micro B cable to attach the "Debug USB" connector to your computer, and follow the instructions in the PDF. (The "Debug USB" connector is the USB port closest to the POWER led and pins.)

**To connect the hardware**

1. Unplug the micro USB cable from Debug USB.

1. Plug the mikroBUS XPlained Pro adapter into the SAMD21 board in the EXT1 location.

1. Plug the ATECC608A Secure 4 Click board into the mikroBUSX XPlained Pro adapter. Make sure that the notched corner of the click board matches with the notched icon on the adapter board.

1. Plug the micro USB cable into Target USB.

Your setup should look like the following.

![\[Breadboard with USB cable labeled "Target USB", connected to an external device labeled "Connected to EXT 1", notches that match default jumper positions.\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/samd21.png)


## Set up your development environment
<a name="gsg-atecc608a-setup-dev-env"></a>

### Sign up for an AWS account
<a name="sign-up-for-aws"></a>

If you do not have an AWS account, complete the following steps to create one.

**To sign up for an AWS account**

1. Open [https://portal.aws.amazon.com/billing/signup](https://portal.aws.amazon.com/billing/signup).

1. Follow the online instructions.

   Part of the sign-up procedure involves receiving a phone call or text message and entering a verification code on the phone keypad.

   When you sign up for an AWS account, an *AWS account root user* is created. The root user has access to all AWS services and resources in the account. As a security best practice, assign administrative access to a user, and use only the root user to perform [tasks that require root user access](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks).

AWS sends you a confirmation email after the sign-up process is complete. At any time, you can view your current account activity and manage your account by going to [https://aws.amazon.com/](https://aws.amazon.com/) and choosing **My Account**.

### Create a user with administrative access
<a name="create-an-admin"></a>

After you sign up for an AWS account, secure your AWS account root user, enable AWS IAM Identity Center, and create an administrative user so that you don't use the root user for everyday tasks.

**Secure your AWS account root user**

1.  Sign in to the [AWS Management Console](https://console.aws.amazon.com/) as the account owner by choosing **Root user** and entering your AWS account email address. On the next page, enter your password.

   For help signing in by using root user, see [Signing in as the root user](https://docs.aws.amazon.com/signin/latest/userguide/console-sign-in-tutorials.html#introduction-to-root-user-sign-in-tutorial) in the *AWS Sign-In User Guide*.

1. Turn on multi-factor authentication (MFA) for your root user.

   For instructions, see [Enable a virtual MFA device for your AWS account root user (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/enable-virt-mfa-for-root.html) in the *IAM User Guide*.

**Create a user with administrative access**

1. Enable IAM Identity Center.

   For instructions, see [Enabling AWS IAM Identity Center](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-set-up-for-idc.html) in the *AWS IAM Identity Center User Guide*.

1. In IAM Identity Center, grant administrative access to a user.

   For a tutorial about using the IAM Identity Center directory as your identity source, see [ Configure user access with the default IAM Identity Center directory](https://docs.aws.amazon.com//singlesignon/latest/userguide/quick-start-default-idc.html) in the *AWS IAM Identity Center User Guide*.

**Sign in as the user with administrative access**
+ To sign in with your IAM Identity Center user, use the sign-in URL that was sent to your email address when you created the IAM Identity Center user.

  For help signing in using an IAM Identity Center user, see [Signing in to the AWS access portal](https://docs.aws.amazon.com/signin/latest/userguide/iam-id-center-sign-in-tutorial.html) in the *AWS Sign-In User Guide*.

**Assign access to additional users**

1. In IAM Identity Center, create a permission set that follows the best practice of applying least-privilege permissions.

   For instructions, see [ Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-started-create-a-permission-set.html) in the *AWS IAM Identity Center User Guide*.

1. Assign users to a group, and then assign single sign-on access to the group.

   For instructions, see [ Add groups](https://docs.aws.amazon.com//singlesignon/latest/userguide/addgroups.html) in the *AWS IAM Identity Center User Guide*.

To provide access, add permissions to your users, groups, or roles:
+ Users and groups in AWS IAM Identity Center:

  Create a permission set. Follow the instructions in [Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html) in the *AWS IAM Identity Center User Guide*.
+ Users managed in IAM through an identity provider:

  Create a role for identity federation. Follow the instructions in [Create a role for a third-party identity provider (federation)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html) in the *IAM User Guide*.
+ IAM users:
  + Create a role that your user can assume. Follow the instructions in [Create a role for an IAM user](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html) in the *IAM User Guide*.
  + (Not recommended) Attach a policy directly to a user or add a user to a user group. Follow the instructions in [Adding permissions to a user (console)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) in the *IAM User Guide*.

**Setting up**

1. Download the FreeRTOS repo from the [FreeRTOS GitHub repository](https://github.com/aws/amazon-freertos).

   To download FreeRTOS from GitHub:

   1. Browse to the [FreeRTOS GitHub repository](https://github.com/aws/amazon-freertos).

   1. Choose **Clone or download**.

   1. From the command line on your computer, clone the repository to a directory on your host machine.

      ```
      git clone https://github.com/aws/amazon-freertos.git -\-recurse-submodules
      ```
**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](https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development) 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\$1](https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-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 -\$1-init -\$1-recursive**).

   1. From the `freertos` directory, check out the branch to use.

1. Set up your development environment.

   1. Install the latest version of [WinPCap](https://www.winpcap.org).

   1. Install Microsoft Visual Studio.

      Visual Studio versions 2017 and 2019 are known to work. All editions of these Visual Studio versions are supported (Community, Professional, or Enterprise).

      In addition to the IDE, install the Desktop development with C\$1\$1 component. Then, under **Optional**, install the latest Windows 10 SDK.

   1. Make sure that you have an active hard-wired Ethernet connection.

## Build and run the FreeRTOS demo project
<a name="gsg-atecc608a-build-and-run"></a>

**Important**  
The Microchip ATECC608A device has a one time initialization that is locked onto the device the first time a project is run (during the call to `C_InitToken`). However, the FreeRTOS demo project and test project have different configurations. If the device is locked during the demo project configurations, it will not be possible for all tests in the test project to succeed.

**To build and run the FreeRTOS demo project with the Visual Studio IDE**

1. Load the project into Visual Studio.

   From the **File** menu, choose **Open**. Choose **File/Solution**, navigate to the `freertos\projects\microchip\ecc608a_plus_winsim\visual_studio\aws_demos\aws_demos.sln` file, and then choose **Open**.

1. Retarget the demo project.

   The demo project depends on the Windows SDK, but it does not have a Windows SDK version specified. By default, the IDE might attempt to build the demo with an SDK version not present on your machine. To set the Windows SDK version, right-click **aws\$1demos**, and then choose **Retarget Projects**. This opens the **Review Solution Actions** window. Choose a Windows SDK version that is present on your machine (use the initial value in the drop-down list), and then choose **OK**.

1. Build and run the project.

   From the **Build** menu, choose **Build Solution**, and make sure the solution builds without errors. Choose **Debug, Start Debugging** to run the project. On the first run, you need to configure your device interface and recompile. For more information, see [Configure your network interface](getting_started_windows.md#win-network-interface).

1. Provision the Microchip ATECC608A.

   Microchip has provided several scripting tools to help with the setup of the ATECC608A parts. Navigate to `freertos\vendors\microchip\secure_elements\app\example_trust_chain_tool`, and open the README.md file.

   Follow the instructions in the `README.md` file to provision your device. The steps include the following:

   1. Create and register a certificate authority with AWS.

   1. Generate your keys on the Microchip ATECC608A and export the public key and device serial number.

   1. Generate a certificate for the device and registering that certificate with AWS.

   1. Load the CA certificate and device certificate onto the device.

1. Build and run FreeRTOS samples.

   Re-run the demo project again. This time you should connect\$1

## Troubleshooting
<a name="ecc680a-troubleshooting"></a>

For general troubleshooting information, see [Troubleshooting getting started](gsg-troubleshooting.md).

# Getting started with the Espressif ESP32-DevKitC and the ESP-WROVER-KIT
<a name="getting_started_espressif"></a>

**Important**  <a name="deprecation-message"></a>
This reference integration is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).

**Note**  
To explore how to integrate FreeRTOS modular libraries and demos within your own Espressif IDF project, see our [ featured reference integration for ESP32-C3 platform](https://www.freertos.org/featured-freertos-iot-integration-targeting-an-espressif-esp32-c3-risc-v-mcu/). 

Follow this tutorial to get started with the Espressif ESP32-DevKitC equipped with ESP32-WROOM-32, ESP32-SOLO-1, or ESP-WROVER modules and the ESP-WROVER-KIT-VB. To purchase one from our partner on the AWS Partner Device catalog, use the following links:
+ [ESP32-WROOM-32 DevKitC](https://devices.amazonaws.com/detail/a3G0L00000AANtjUAH/ESP32-DevKitC)
+ [ESP32-SOLO-1](https://devices.amazonaws.com/detail/a3G0h0000076lSMEAY)
+ [ ESP32-WROVER-KIT](https://devices.amazonaws.com/detail/a3G0L00000AANtlUAH/ESP-WROVER-KIT)

These versions of development boards are supported on FreeRTOS.

For more information about the latest versions of these boards, see [ ESP32-DevKitC V4](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/hw-reference/modules-and-boards.html#esp32-devkitc-v4) or [ ESP-WROVER-KIT v4.1](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/hw-reference/modules-and-boards.html#esp-wrover-kit-v4-1) on the Espressif website.

**Note**  
Currently, the FreeRTOS port for ESP32-WROVER-KIT and ESP DevKitC doesn't support the Symmetric multiprocessing (SMP) feature.

## Overview
<a name="getting_started_espressif-overview"></a>

This tutorial guides you through the following steps:

1. Connecting your board to a host machine.

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

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

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

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

## Prerequisites
<a name="setup-espressif-prereqs"></a>

Before you get started with FreeRTOS on your Espressif board, you must set up your AWS account and permissions.

### Sign up for an AWS account
<a name="sign-up-for-aws"></a>

If you do not have an AWS account, complete the following steps to create one.

**To sign up for an AWS account**

1. Open [https://portal.aws.amazon.com/billing/signup](https://portal.aws.amazon.com/billing/signup).

1. Follow the online instructions.

   Part of the sign-up procedure involves receiving a phone call or text message and entering a verification code on the phone keypad.

   When you sign up for an AWS account, an *AWS account root user* is created. The root user has access to all AWS services and resources in the account. As a security best practice, assign administrative access to a user, and use only the root user to perform [tasks that require root user access](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks).

AWS sends you a confirmation email after the sign-up process is complete. At any time, you can view your current account activity and manage your account by going to [https://aws.amazon.com/](https://aws.amazon.com/) and choosing **My Account**.

### Create a user with administrative access
<a name="create-an-admin"></a>

After you sign up for an AWS account, secure your AWS account root user, enable AWS IAM Identity Center, and create an administrative user so that you don't use the root user for everyday tasks.

**Secure your AWS account root user**

1.  Sign in to the [AWS Management Console](https://console.aws.amazon.com/) as the account owner by choosing **Root user** and entering your AWS account email address. On the next page, enter your password.

   For help signing in by using root user, see [Signing in as the root user](https://docs.aws.amazon.com/signin/latest/userguide/console-sign-in-tutorials.html#introduction-to-root-user-sign-in-tutorial) in the *AWS Sign-In User Guide*.

1. Turn on multi-factor authentication (MFA) for your root user.

   For instructions, see [Enable a virtual MFA device for your AWS account root user (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/enable-virt-mfa-for-root.html) in the *IAM User Guide*.

**Create a user with administrative access**

1. Enable IAM Identity Center.

   For instructions, see [Enabling AWS IAM Identity Center](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-set-up-for-idc.html) in the *AWS IAM Identity Center User Guide*.

1. In IAM Identity Center, grant administrative access to a user.

   For a tutorial about using the IAM Identity Center directory as your identity source, see [ Configure user access with the default IAM Identity Center directory](https://docs.aws.amazon.com//singlesignon/latest/userguide/quick-start-default-idc.html) in the *AWS IAM Identity Center User Guide*.

**Sign in as the user with administrative access**
+ To sign in with your IAM Identity Center user, use the sign-in URL that was sent to your email address when you created the IAM Identity Center user.

  For help signing in using an IAM Identity Center user, see [Signing in to the AWS access portal](https://docs.aws.amazon.com/signin/latest/userguide/iam-id-center-sign-in-tutorial.html) in the *AWS Sign-In User Guide*.

**Assign access to additional users**

1. In IAM Identity Center, create a permission set that follows the best practice of applying least-privilege permissions.

   For instructions, see [ Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-started-create-a-permission-set.html) in the *AWS IAM Identity Center User Guide*.

1. Assign users to a group, and then assign single sign-on access to the group.

   For instructions, see [ Add groups](https://docs.aws.amazon.com//singlesignon/latest/userguide/addgroups.html) in the *AWS IAM Identity Center User Guide*.

To provide access, add permissions to your users, groups, or roles:
+ Users and groups in AWS IAM Identity Center:

  Create a permission set. Follow the instructions in [Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html) in the *AWS IAM Identity Center User Guide*.
+ Users managed in IAM through an identity provider:

  Create a role for identity federation. Follow the instructions in [Create a role for a third-party identity provider (federation)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html) in the *IAM User Guide*.
+ IAM users:
  + Create a role that your user can assume. Follow the instructions in [Create a role for an IAM user](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html) in the *IAM User Guide*.
  + (Not recommended) Attach a policy directly to a user or add a user to a user group. Follow the instructions in [Adding permissions to a user (console)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) in the *IAM User Guide*.

## Get started
<a name="setup-espressif-idf42"></a>

**Note**  
The Linux commands in this tutorial require that you use the Bash shell.

1. **Set up the Espressif hardware.**
   + For information about setting up the ESP32-DevKitC development board hardware, see the [ ESP32-DevKitC V4 Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/hw-reference/esp32/get-started-devkitc.html).
   + For information about setting up the ESP-WROVER-KIT development board hardware, see the [ ESP-WROVER-KIT V4.1 Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/hw-reference/esp32/get-started-wrover-kit.html).
**Important**  
When you reach the **Get Started** section of the Espressif guides, stop, and then return to the instructions on this page.

1. Download Amazon FreeRTOS from [GitHub](https://github.com/aws/amazon-freertos). (For instructions, see the [README.md](https://github.com/aws/amazon-freertos/blob/main/README.md) file.)

1. **Set up your development environment**.

   To communicate with your board, you must install a toolchain. Espressif provides the ESP-IDF to develop software for their boards. Since the ESP-IDF has its own version of the FreeRTOS Kernel integrated as a component, Amazon FreeRTOS includes a custom version of the ESP-IDF v4.2 that has the FreeRTOS Kernel removed. This fixes problems with duplicate files when you compile. To use the custom version of the ESP-IDF v4.2 included with Amazon FreeRTOS, follow the instructions below for your host machine's operating system.

   **Windows**

   1. Download ESP-IDF's [ Universal Online Installer](https://dl.espressif.com/dl/esp-idf/?idf=4.2) for Windows.

   1. Run the **Universal Online Installer**.

   1. When you get to the step **Download or use ESP-IDF**, select **Use an existing ESP-IDF directory** and set **Choose existing ESP-IDF directory** to `freertos/vendors/espressif/esp-idf`.

   1. Complete the installation.

   **macOS**

   1. Follow the instructions in the [ Standard Setup of Toolchain prerequisites (ESP-IDF v4.2) for macOS](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/get-started/macos-setup.html).
**Important**  
When you reach the "Get ESP-IDF" instructions under **Next Steps**, stop, and then return to the instructions on this page.

   1. Open a command line window.

   1. Navigate to the FreeRTOS download directory, and then run the following script to download and install the espressif toolchain for your platform.

      ```
      vendors/espressif/esp-idf/install.sh
      ```

   1. Add the ESP-IDF toolchain tools to your terminal's path with the following command.

      ```
      source vendors/espressif/esp-idf/export.sh
      ```

   **Linux**

   1. Follow the instructions in the [ Standard Setup of Toolchain prerequisites (ESP-IDF v4.2) for Linux](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/get-started/linux-setup.html).
**Important**  
When you reach the "Get ESP-IDF" instructions under **Next Steps**, stop, and then return to the instructions on this page.

   1. Open a command line window.

   1. Navigate to the FreeRTOS download directory, and then run the following script to download and install the Espressif toolchain for your platform.

      ```
      vendors/espressif/esp-idf/install.sh
      ```

   1. Add the ESP-IDF toolchain tools to your terminal's path with the following command.

      ```
      source vendors/espressif/esp-idf/export.sh
      ```

1. **Establish a serial connection.**

   1. To establish a serial connection between your host machine and the ESP32-DevKitC, you must install the CP210x USB to UART Bridge VCP drivers. You can download these drivers from [ Silicon Labs](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers).

      To establish a serial connection between your host machine and the ESP32-WROVER-KIT, you must install the FTDI virtual COM port driver. You can download this driver from [FTDI](https://www.ftdichip.com/Drivers/VCP.htm).

   1. Follow the steps to [ Establish Serial Connection with ESP32](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/get-started/establish-serial-connection.html).

   1. After you establish a serial connection, make a note of the serial port for your board's connection. You need it to flash the demo.

### Configure the FreeRTOS demo applications
<a name="configure-demos-espressif-idf42"></a>

For this tutorial, the FreeRTOS configuration file is located at `freertos/vendors/espressif/boards/board-name/aws_demos/config_files/FreeRTOSConfig.h`. (For example, if `AFR_BOARD espressif.esp32_devkitc` is chosen, the configuration file is located at `freertos/vendors/espressif/boards/esp32/aws_demos/config_files/FreeRTOSConfig.h`.) 

1. If you're running macOS or Linux, open a terminal prompt. If you're running Windows, open the "ESP-IDF 4.x CMD" app (if you included this option when you installed the ESP-IDF toolchain), or the "Command Prompt" app otherwise. 

1. To verify that you have Python3 installed, run 

   ```
   python --version
   ```

   The version installed is displayed. If you don't have Python 3.0.1 or later installed, you can install it from the [Python](https://www.python.org/downloads/) website.

1. You need the AWS Command Line Interface (CLI) to run AWS IoT commands. If you're running Windows, use the `easy_install awscli` command to install the AWS CLI in the "Command" or "ESP-IDF 4.x CMD" app. 

   If you're running macOS or Linux, see [Installing the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/installing.html). 

1. Run

   ```
   aws configure
   ```

   and configure the AWS CLI with your AWS access key ID, secret access key, and default AWS Region. For more information, see [Configuring the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html).

1. Use the following command to install the AWS SDK for Python (boto3):
   + On Windows, in the "Command" or "ESP-IDF 4.x CMD" app, run

     ```
     pip install boto3 --user
     ```
**Note**  
See [Boto3 documentation](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html) for details.
   + On macOS or Linux, run

     ```
     pip install tornado nose --user
     ```

     and then run

     ```
     pip install boto3 --user
     ```

   FreeRTOS includes the `SetupAWS.py` script to make it easier to set up your Espressif board to connect to AWS IoT. To configure the script, open `freertos/tools/aws_config_quick_start/configure.json` and set the following attributes:  
**`afr_source_dir`**  
The complete path to the `freertos` directory on your computer. Make sure that you use forward slashes to specify this path.  
**`thing_name`**  
The name that you want to assign to the AWS IoT thing that represents your board.  
**`wifi_ssid`**  
The SSID of your Wi-Fi network.  
**`wifi_password`**  
The password for your Wi-Fi network.  
**`wifi_security`**  
The security type for your Wi-Fi network.  
The following are valid security types:  
   + `eWiFiSecurityOpen` (Open, no security)
   + `eWiFiSecurityWEP` (WEP security)
   + `eWiFiSecurityWPA` (WPA security)
   + `eWiFiSecurityWPA2` (WPA2 security)

1. Run the configuration script.

   1. If you're running macOS or Linux, open a terminal prompt. If you're running Windows, open the "ESP-IDF 4.x CMD" or "Command" app. 

   1. Navigate to the `freertos/tools/aws_config_quick_start` directory and run 

      ```
      python SetupAWS.py setup
      ```

      The script does the following:
      + Creates an IoT thing, certificate, and policy.
      + Attaches the IoT policy to the certificate and the certificate to the AWS IoT thing.
      + Populates the `aws_clientcredential.h` file with your AWS IoT endpoint, Wi-Fi SSID, and credentials.
      + Formats your certificate and private key and writes them to the `aws_clientcredential_keys.h` header file.
**Note**  
The certificate is hardcoded for demonstration purposes only. Production-level applications should store these files in a secure location.

      For more information about `SetupAWS.py`, see the `README.md` in the `freertos/tools/aws_config_quick_start` directory.

### Monitoring MQTT messages on the cloud
<a name="gsg-espressif-monitor-mqtt"></a>

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. Navigate to the [AWS IoT console](https://console.aws.amazon.com/iotv2/).

1. In the navigation pane, choose **Test**, then choose **MQTT Test Client**.

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

When the demo project successfully runs on your device you see "Hello World\$1" sent multiple times to the topic that you subscribed to.

### Build, flash, and run the FreeRTOS demo project using the idf.py script
<a name="build-and-run-example-espressif-idf42"></a>

You can use Espressif's IDF utility (`idf.py`) to build the project and flash the binaries onto your device.

**Note**  
Some setups might require that you use the port option `"-p port-name"` with `idf.py` to specify the correct port, as in the following example.  

```
idf.py -p /dev/cu.usbserial-00101301B flash
```

**Build and flash FreeRTOS on Windows, Linux, and macOS (ESP-IDF v4.2)**

1. Navigate to the root of your FreeRTOS download directory.

1. In a command line window, enter the following command to add the ESP-IDF tools to your terminal's PATH.  
**Windows ("Command" app)**  

   ```
   vendors\espressif\esp-idf\export.bat
   ```  
**Windows ("ESP-IDF 4.x CMD" app)**  
(This has already been done when you opened the app.)  
**Linux / macOS**  

   ```
   source vendors/espressif/esp-idf/export.sh
   ```

1. Configure cmake in the `build` directory and build the firmware image with the following command.

   ```
   idf.py -DVENDOR=espressif -DBOARD=esp32_wrover_kit -DCOMPILER=xtensa-esp32 build
   ```

   You should see output like the following.

   ```
      Running cmake in directory /path/to/hello_world/build
      Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"...
      Warn about uninitialized values.
      -- Found Git: /usr/bin/git (found version "2.17.0")
      -- Building empty aws_iot component due to configuration
      -- Component names: ...
      -- Component paths: ...
   
      ... (more lines of build system output)
   
      [527/527] Generating hello-world.bin
      esptool.py v2.3.1
   
      Project build complete. To flash, run this command:
      ../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin  build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin
      or run 'idf.py -p PORT flash'
   ```

   If there are no errors, the build will generate the firmware binary .bin files.

1. Erase your development board's flash memory with the following command.

   ```
   idf.py erase_flash
   ```

1. Use the `idf.py` script to flash the application binary to your board.

   ```
   idf.py flash
   ```

1. Monitor the output from your board's serial port with the following command.

   ```
   idf.py monitor
   ```
**Note**  
You can combine these commands such as in the following example.  

   ```
   idf.py erase_flash flash monitor
   ```

   For certain host machine setups, you must specify the port when you flash the board such as in the following example.

   ```
   idf.py erase_flash flash monitor -p /dev/ttyUSB1
   ```

### Build and Flash FreeRTOS with CMake
<a name="flash-espressif-cmake-idf42"></a>

In addition to the `idf.py` script provided by the IDF SDK to build and run your code, you can also build the project with CMake. Currently, it supports either Unix Makefiles or the Ninja build system.

**To build and flash the project**

1. In a command line window, navigate to the root of your FreeRTOS download directory.

1. Run the following script to add the ESP-IDF tools to your shell's PATH.  
**Windows**  

   ```
   vendors\espressif\esp-idf\export.bat
   ```  
**Linux / macOS**  

   ```
   source vendors/espressif/esp-idf/export.sh
   ```

1. Enter the following command to generate the build files.  
**With Unix Makefiles**  

   ```
   cmake -DVENDOR=espressif -DBOARD=esp32_wrover_kit -DCOMPILER=xtensa-esp32 -S . -B ./YOUR_BUILD_DIRECTORY -DAFR_ENABLE_ALL_MODULES=1 -DAFR_ENABLE_TESTS=0
   ```  
**With Ninja**  

   ```
   cmake -DVENDOR=espressif -DBOARD=esp32_wrover_kit -DCOMPILER=xtensa-esp32 -S . -B ./YOUR_BUILD_DIRECTORY -DAFR_ENABLE_ALL_MODULES=1 -DAFR_ENABLE_TESTS=0 -GNinja
   ```

1. Build the project.  
**With Unix Makefiles**  

   ```
   make -C ./YOUR_BUILD_DIRECTORY -j8 
   ```  
**With Ninja**  

   ```
   ninja -C ./YOUR_BUILD_DIRECTORY -j8
   ```

1. Erase the flash and then flash the board.  
**With Unix Makefiles**  

   ```
   make -C ./YOUR_BUILD_DIRECTORY erase_flash
   ```

   ```
   make -C ./YOUR_BUILD_DIRECTORY flash
   ```  
**With Ninja**  

   ```
   ninja -C ./YOUR_BUILD_DIRECTORY erase_flash
   ```

   ```
   ninja -C ./YOUR_BUILD_DIRECTORY flash
   ```

## Run the Bluetooth Low Energy demos
<a name="espressif-run-ble"></a>

FreeRTOS supports [Bluetooth Low Energy library](freertos-ble-library.md) connectivity.

To run the FreeRTOS demo project across Bluetooth Low Energy, you must run the FreeRTOS Bluetooth Low Energy Mobile SDK Demo Application on an iOS or Android mobile device.

**To set up the FreeRTOS Bluetooth Low Energy mobile SDK demo application**

1. Follow the instructions in [Mobile SDKs for FreeRTOS Bluetooth devices](freertos-ble-mobile.md) to download and install the SDK for your mobile platform on your host computer.

1. Follow the instructions in [FreeRTOS Bluetooth Low Energy Mobile SDK demo application](ble-demo.md#ble-sdk-app) to set up the demo mobile application on your mobile device.

For instructions about how to run the MQTT over Bluetooth Low Energy demo on your board, see [MQTT over Bluetooth Low Energy](ble-demo.md#ble-demo-mqtt).

For instructions about how to run the Wi-Fi provisioning demo on your board, see [Wi-Fi provisioning](ble-demo.md#ble-demo-wifi).

## Using FreeRTOS in your own CMake project for ESP32
<a name="getting_started_espressif_cmake_project"></a>

If you want to consume FreeRTOS in your own CMake project, you can set it up as a subdirectory and build it together with your application. First, get a copy of FreeRTOS from [GitHub](https://github.com/aws/amazon-freertos). You can also set it up as a Git submodule with the following command so it's easier to update in the future.

```
git submodule add -b release https://github.com/aws/amazon-freertos.git freertos
```

If a later version is released, you can update your local copy with these commands.

```
# Pull the latest changes from the remote tracking branch.
git submodule update --remote -- freertos
```

```
# Commit the submodule change because it is pointing to a different revision now.
git add freertos
```

```
git commit -m "Update FreeRTOS to a new release"
```

If your project has the following directory structure: 

```
- freertos (the copy that you obtained from GitHub or the AWS IoT console)
- src
  - main.c (your application code)
- CMakeLists.txt
```

Then the following is an example of the top-level `CMakeLists.txt` file that can be used to build your application together with FreeRTOS.

```
cmake_minimum_required(VERSION 3.13)

project(freertos_examples)

# Tell IDF build to link against this target.
set(IDF_EXECUTABLE_SRCS "<complete_path>/src/main.c")
set(IDF_PROJECT_EXECUTABLE my_app)

# Add FreeRTOS as a subdirectory. AFR_BOARD tells which board to target.
set(AFR_BOARD espressif.esp32_devkitc CACHE INTERNAL "")
add_subdirectory(freertos)

# Link against the mqtt library so that we can use it. Dependencies are transitively
# linked.
target_link_libraries(my_app PRIVATE AFR::core_mqtt)
```

To build the project, run the following CMake commands. Make sure the ESP32 compiler is in the PATH environment variable.

```
cmake -S . -B build-directory -DCMAKE_TOOLCHAIN_FILE=freertos/tools/cmake/toolchains/xtensa-esp32.cmake -GNinja 
```

```
cmake --build build-directory 
```

To flash the application to your board, run the following command.

```
cmake --build build-directory --target flash 
```

### Using components from FreeRTOS
<a name="getting_started_espressif_cmake_project_components"></a>

After running CMake, you can find all available components in the summary output. It should look something like the following example.

```
====================Configuration for FreeRTOS====================
  Version:                 202107.00
  Git version:             202107.00-g79ad6defb

Target microcontroller:
  vendor:                  Espressif
  board:                   ESP32-DevKitC
  description:             Development board produced by Espressif that comes in two
                           variants either with ESP-WROOM-32 or ESP32-WROVER module
  family:                  ESP32
  data ram size:           520KB
  program memory size:     4MB

Host platform:
  OS:                      Linux-4.15.0-66-generic
  Toolchain:               xtensa-esp32
  Toolchain path:          /opt/xtensa-esp32-elf
  CMake generator:         Ninja

FreeRTOS modules:
  Modules to build:        backoff_algorithm, common, common_io, core_http,
                           core_http_demo_dependencies, core_json, core_mqtt,
                           core_mqtt_agent, core_mqtt_agent_demo_dependencies,
                           core_mqtt_demo_dependencies, crypto, defender, dev_mode_key_
                           provisioning, device_defender, device_defender_demo_
                           dependencies, device_shadow, device_shadow_demo_dependencies,
                           freertos_cli_plus_uart, freertos_plus_cli, greengrass,
                           http_demo_helpers, https, jobs, jobs_demo_dependencies,
                           kernel, logging, mqtt, mqtt_agent_interface, mqtt_demo_
                           helpers, mqtt_subscription_manager, ota, ota_demo_
                           dependencies, ota_demo_version, pkcs11, pkcs11_helpers,
                           pkcs11_implementation, pkcs11_utils, platform, secure_sockets,
                           serializer, shadow, tls, transport_interface_secure_sockets,
                           wifi
  Enabled by user:         common_io, core_http_demo_dependencies, core_json,
                           core_mqtt_agent_demo_dependencies, core_mqtt_demo_
                           dependencies, defender, device_defender, device_defender_demo_
                           dependencies, device_shadow, device_shadow_demo_dependencies,
                           freertos_cli_plus_uart, freertos_plus_cli, greengrass, https,
                           jobs, jobs_demo_dependencies, logging, ota_demo_dependencies,
                           pkcs11, pkcs11_helpers, pkcs11_implementation, pkcs11_utils,
                           platform, secure_sockets, shadow, wifi
  Enabled by dependency:   backoff_algorithm, common, core_http, core_mqtt,
                           core_mqtt_agent, crypto, demo_base, dev_mode_key_provisioning,
                           freertos, http_demo_helpers, kernel, mqtt, mqtt_agent_
                           interface, mqtt_demo_helpers, mqtt_subscription_manager, ota,
                           ota_demo_version, pkcs11_mbedtls, serializer, tls,
                           transport_interface_secure_sockets, utils
  3rdparty dependencies:   jsmn, mbedtls, pkcs11, tinycbor
  Available demos:         demo_cli_uart, demo_core_http, demo_core_mqtt, demo_core_mqtt_
                           agent, demo_device_defender, demo_device_shadow,
                           demo_greengrass_connectivity, demo_jobs, demo_ota_core_http,
                           demo_ota_core_mqtt, demo_tcp
  Available tests:
=========================================================================
```

You can reference any components from the `Modules to build` list. To link them into your application, put the `AFR::` namespace in front of the name, for example, `AFR::core_mqtt`, `AFR::ota`, and so on.

### Add custom components using ESP-IDF
<a name="getting_started_espressif_cmake_project_espidf"></a>

You can add more components while using ESP-IDF. For example, assuming you want to add a component called `example_component`, and your project looks like this:

```
- freertos
- components
  - example_component
    - include
      - example_component.h
    - src
      - example_component.c
    - CMakeLists.txt
- src
  - main.c
- CMakeLists.txt
```

The following is an example of the `CMakeLists.txt` file for your component. 

```
add_library(example_component src/example_component.c)
target_include_directories(example_component PUBLIC include)
```

Then, in the top level `CMakeLists.txt` file, add the component by inserting the following line just after `add_subdirectory(freertos)`.

```
add_subdirectory(component/example_component) 
```

Then, modify `target_link_libraries` to include your component.

```
target_link_libraries(my_app PRIVATE AFR::core_mqtt PRIVATE example_component) 
```

This component is now automatically linked to your application code by default. You can now include its header files and call the functions it defines.

### Override the configurations for FreeRTOS
<a name="getting_started_espressif_cmake_project_override"></a>

There's currently no well-defined approach to redefining the configs outside of the FreeRTOS source tree. By default, CMake will look for the `freertos/vendors/espressif/boards/esp32/aws_demos/config_files/` and `freertos/demos/include/` directories. However, you can use a workaround to tell the compiler to search other directories first. For example, you can add another folder for FreeRTOS configurations.

```
- freertos
- freertos-configs
  - aws_clientcredential.h
  - aws_clientcredential_keys.h
  - iot_mqtt_agent_config.h
  - iot_config.h
- components
- src
- CMakeLists.txt
```

The files under `freertos-configs` are copied from the `freertos/vendors/espressif/boards/esp32/aws_demos/config_files/` and `freertos/demos/include/` directories. Then, in your top level `CMakeLists.txt` file, add this line before `add_subdirectory(freertos)` so that the compiler will search this directory first.

```
include_directories(BEFORE freertos-configs)
```

### Providing your own sdkconfig for ESP-IDF
<a name="getting_started_espressif_providing_sdkconfig"></a>

In case you want to provide your own `sdkconfig.default`, you can set the CMake variable `IDF_SDKCONFIG_DEFAULTS`, from the command line:

```
cmake -S . -B build-directory -DIDF_SDKCONFIG_DEFAULTS=path_to_your_sdkconfig_defaults -DCMAKE_TOOLCHAIN_FILE=freertos/tools/cmake/toolchains/xtensa-esp32.cmake -GNinja 
```

If you don't specify a location for your own `sdkconfig.default` file, FreeRTOS uses the default file located at `freertos/vendors/espressif/boards/esp32/aws_demos/sdkconfig.defaults`.

For more information, see [Project Configuration](https://docs.espressif.com/projects/esp-idf/en/v4.2-beta1/esp32s2/api-reference/kconfig.html) in the Espressif *API Reference* and, if you encounter issues after you have successfully compiled, see the section on [ Deprecated options and their replacements](https://docs.espressif.com/projects/esp-idf/en/v4.2-beta1/esp32s2/api-reference/kconfig.html#deprecated-options-and-their-replacements) on that page.

### Summary
<a name="getting_started_espressif_cmake_project_summary"></a>

If you have a project with a component called `example_component`, and you want to override some configurations, here's a complete example of the top level `CMakeLists.txt` file.

```
cmake_minimum_required(VERSION 3.13)

project(freertos_examples)

set(IDF_PROJECT_EXECUTABLE my_app)
set(IDF_EXECUTABLE_SRCS "src/main.c")

# Tell IDF build to link against this target.
set(IDF_PROJECT_EXECUTABLE my_app)

# Add some extra components. IDF_EXTRA_COMPONENT_DIRS is a variable used by ESP-IDF
# to collect extra components.
get_filename_component(
    EXTRA_COMPONENT_DIRS
    "components/example_component" ABSOLUTE
)
list(APPEND IDF_EXTRA_COMPONENT_DIRS ${EXTRA_COMPONENT_DIRS})

# Override the configurations for FreeRTOS.
include_directories(BEFORE freertos-configs)

# Add FreeRTOS as a subdirectory. AFR_BOARD tells which board to target.
set(AFR_BOARD espressif.esp32_devkitc CACHE INTERNAL "")
add_subdirectory(freertos)

# Link against the mqtt library so that we can use it. Dependencies are transitively
# linked.
target_link_libraries(my_app PRIVATE AFR::core_mqtt)
```

## Troubleshooting
<a name="getting_started_espressif_troubleshooting"></a>
+ If you're running macOS and the operating system doesn't recognize your ESP-WROVER-KIT, make sure you don't have the D2XX drivers installed. To uninstall them, follow the instructions in the [ FTDI Drivers Installation Guide for macOS X](http://www.ftdichip.com/Support/Documents/AppNotes/AN_134_FTDI_Drivers_Installation_Guide_for_MAC_OSX.pdf).
+ The monitor utility provided by ESP-IDF (and invoked using make monitor) helps you decode addresses. For this reason, it can help you get some meaningful backtraces in the event the application stops working. For more information, see [ Automatic Address Decoding](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/api-guides/tools/idf-monitor.html#automatic-address-decoding) on the Espressif website.
+ It's also possible to enable GDBstub for communication with gdb without requiring any special JTAG hardware. For more information, see [ Launching GDB with GDBStub](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/api-guides/tools/idf-monitor.html#launching-gdb-with-gdbstub) on the Espressif website.
+ For information about setting up an OpenOCD-based environment if JTAG hardware-based debugging is required, see [ JTAG Debugging](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/index.html) on the Espressif website.
+ If `pyserial` can't be installed using `pip` on macOS, download it from the [pyserial website](https://pypi.org/simple/pyserial).
+ If the board resets continuously, try erasing the flash by entering the following command on the terminal.

  ```
  make erase_flash
  ```
+ If you see errors when you run `idf_monitor.py`, use Python 2.7.
+ Required libraries from ESP-IDF are included in FreeRTOS, so there is no need to download them externally. If the `IDF_PATH` environment variable is set, we recommend that you clear it before you build FreeRTOS.
+ On Windows, it can take 3-4 minutes for the project to build. To reduce the build time, you can use the `-j4` switch on the make command.

  ```
  make flash monitor -j4
  ```
+ If your device has trouble connecting to AWS IoT, open the `aws_clientcredential.h` file, and verify that the configuration variables are properly defined in the file. `clientcredentialMQTT_BROKER_ENDPOINT[]` should look like `1234567890123-ats.iot.us-east-1.amazonaws.com`.
+ If you're following the steps in [Using FreeRTOS in your own CMake project for ESP32](#getting_started_espressif_cmake_project) and you see undefined reference errors from the linker, it's usually because of missing dependent libraries or demos. To add them, update the `CMakeLists.txt` file (under the root directory) using the standard CMake function `target_link_libraries`.
+ ESP-IDF v4.2 supports the use of the *xtensa\$1-esp32\$1-elf\$1-gcc 8\$1.2\$1.0\$1.* toolchain. If you're using an earlier version of the Xtensa toolchain, download the required version.
+ If you see an error log like the following about python dependencies that are not being met for ESP-IDF v4.2:

  ```
  The following Python requirements are not satisfied:
    click>=5.0
    pyserial>=3.0
    future>=0.15.2
    pyparsing>=2.0.3,<2.4.0
    pyelftools>=0.22
    gdbgui==0.13.2.0
    pygdbmi<=0.9.0.2
    reedsolo>=1.5.3,<=1.5.4
    bitstring>=3.1.6
    ecdsa>=0.16.0
    Please follow the instructions found in the "Set up the tools" section of ESP-IDF Getting Started Guide
  ```

  Install the python dependencies on your platform using the following Python command:

  ```
  root/vendors/espressif/esp-idf/requirements.txt
  ```

For more troubleshooting information, see [Troubleshooting getting started](gsg-troubleshooting.md).

## Debugging
<a name="getting_started_espressif_debugging"></a>

### Debugging code on Espressif ESP32-DevKitC and ESP-WROVER-KIT (ESP-IDF v4.2)
<a name="debugging-espressif-idf42"></a>

This section shows you how to debug Espressif hardware using ESP-IDF v4.2. You need a JTAG to USB cable. We use a USB to MPSSE cable (for example, the [ FTDI C232HM-DDHSL-0](http://www.ftdichip.com/Products/Cables/USBMPSSE.htm)).

**ESP-DevKitC JTAG setup**  
For the FTDI C232HM-DDHSL-0 cable, these are the connections to the ESP32 DevkitC.  

```
| C232HM-DDHSL-0 Wire Color | ESP32 GPIO Pin | JTAG Signal Name |
| ------------------------- | -------------- | ---------------- |
|  Brown (pin 5)            |  IO14          |  TMS             |
|  Yellow (pin 3)           |  IO12          |  TDI             |
|  Black (pin 10)           |  GND           |  GND             |
|  Orange (pin 2)           |  IO13          |  TCK             |
|  Green (pin 4)            |  IO15          |  TDO             |
```

**ESP-WROVER-KIT JTAG setup**  
For the FTDI C232HM-DDHSL-0 cable, these are the connections to the ESP32-WROVER-KIT.  

```
| C232HM-DDHSL-0 Wire Color | ESP32 GPIO Pin | JTAG Signal Name |
| ------------------------- | -------------- | ---------------- |
|  Brown (pin 5)            |  IO14          |  TMS             |
|  Yellow (pin 3)           |  IO12          |  TDI             |
|  Orange (pin 2)           |  IO13          |  TCK             |
|  Green (pin 4)            |  IO15          |  TDO             |
```
These tables were developed from the [ FTDI C232HM-DDHSL-0 datasheet](https://www.ftdichip.com/Support/Documents/DataSheets/Cables/DS_C232HM_MPSSE_CABLE.pdf). For more information, see the section "C232HM MPSSE Cable Connection and Mechanical Details in the data sheet.  
To enable JTAG on the ESP-WROVER-KIT, place jumpers on the TMS, TDO, TDI, TCK, and S\$1TDI pins as shown here.  

![\[Jumper placement\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/JP8-jumpers.png)


**Debugging on Windows (ESP-IDF v4.2)**  

**To set up for debugging on Windows**

1. Connect the USB side of the FTDI C232HM-DDHSL-0 to your computer and the other side as described in [Debugging code on Espressif ESP32-DevKitC and ESP-WROVER-KIT (ESP-IDF v4.2)](#debugging-espressif-idf42). The FTDI C232HM-DDHSL-0 device should appear in **Device Manager** under **Universal Serial Bus Controllers**.

1. Under the list of universal serial bus devices, right-click the **C232HM-DDHSL-0** device, and then choose **Properties**.
**Note**  
The device might be listed as **USB Serial Port**.

   To see the properties of the device, in the properties window, choose the **Details** tab. If the device isn't listed, install the [Windows driver for FTDI C232HM-DDHSL-0](http://www.ftdichip.com/Drivers/D2XX.htm).

1. On the **Details** tab, choose **Property**, and then choose **Hardware IDs**. You should see something like this in the **Value** field.

   ```
   FTDIBUS\COMPORT&VID_0403&PID_6014
   ```

   In this example, the vendor ID is 0403 and the product ID is 6014.

   Verify these IDs match the IDs in `projects/espressif/esp32/make/aws_demos/esp32_devkitj_v1.cfg`. The IDs are specified in a line that begins with `ftdi_vid_pid` followed by a vendor ID and a product ID.

   ```
   ftdi_vid_pid 0x0403 0x6014
   ```

1. Download [OpenOCD for Windows](https://github.com/espressif/openocd-esp32/releases).

1. Unzip the file to `C:\` and add `C:\openocd-esp32\bin` to your system path.

1. OpenOCD requires libusb, which is not installed by default on Windows. To install libusb:

   1. Download [zadig.exe](https://zadig.akeo.ie).

   1. Run `zadig.exe`. From the **Options** menu, choose **List All Devices**.

   1. From the dropdown menu, choose **C232HM-DDHSL-0**.

   1. In the target driver field, to the right of the green arrow, choose **WinUSB**.

   1. For the list under the target driver field, choose the arrow, and then choose **Install Driver**. Choose **Replace Driver**.

1. Open a command prompt, navigate to the root of your FreeRTOS download directory, and run the following command.

   ```
   idf.py openocd
   ```

   Leave this command prompt open.

1. Open a new command prompt, navigate to the root of your FreeRTOS download directory, and run

   ```
   idf.py flash monitor
   ```

1. Open another command prompt, navigate to the root of your FreeRTOS download directory, and wait until the demo starts running on your board. When it does, run

   ```
   idf.py gdb
   ```

   The program should stop in the `main` function.
**Note**  
The ESP32 supports a maximum of two break points.

**Debugging on macOS (ESP-IDF v4.2)**  

1. Download the [FTDI driver for macOS](http://www.ftdichip.com/Drivers/VCP.htm).

1. Download [OpenOCD](https://github.com/espressif/openocd-esp32/releases). 

1. Extract the downloaded .tar file and set the path in `.bash_profile` to `OCD_INSTALL_DIR/openocd-esp32/bin`.

1. Use the following command to install `libusb` on macOS.

   ```
   brew install libusb
   ```

1. Use the following command to unload the serial port driver.

   ```
   sudo kextunload -b com.FTDI.driver.FTDIUSBSerialDriver
   ```

1. Use the following command to unload the serial port driver.

   ```
   sudo kextunload -b com.FTDI.driver.FTDIUSBSerialDriver
   ```

1. If you're running a macOS version later than 10.9, use the following command to unload the Apple FTDI driver.

   ```
   sudo kextunload -b com.apple.driver.AppleUSBFTDI
   ```

1. Use the following command to get the product ID and vendor ID of the FTDI cable. It lists the attached USB devices.

   ```
   system_profiler SPUSBDataType
   ```

   The output from `system_profiler` should look like the following.

   ```
      DEVICE:
   
      Product ID: product-ID
      Vendor ID: vendor-ID (Future Technology Devices International Limited)
   ```

1. Open the `projects/espressif/esp32/make/aws_demos/esp32_devkitj_v1.cfg` file. The vendor ID and product ID for your device are specified in a line that begins with `ftdi_vid_pid`. Change the IDs to match the IDs from the `system_profiler` output in the previous step.

1. Open a terminal window, navigate to the root of your FreeRTOS download directory, and use the following command to run OpenOCD.

   ```
   idf.py openocd
   ```

   Leave this terminal window open.

1. Open a new terminal, and use the following command to load the FTDI serial port driver.

   ```
   sudo kextload -b com.FTDI.driver.FTDIUSBSerialDriver
   ```

1. Navigate to the root of your FreeRTOS download directory, and run 

   ```
   idf.py flash monitor
   ```

1. Open another new terminal, navigate to the root of your FreeRTOS download directory, and run

   ```
   idf.py gdb
   ```

   The program should stop at `main`.

**Debugging on Linux (ESP-IDF v4.2)**  

1. Download [OpenOCD](https://github.com/espressif/openocd-esp32/releases). Extract the tarball and follow the installation instructions in the readme file.

1. Use the following command to install libusb on Linux.

   ```
   sudo apt-get install libusb-1.0
   ```

1. Open a terminal and enter **ls -l /dev/ttyUSB\$1** to list all USB devices connected to your computer. This helps you check if the board's USB ports are recognized by the operating system. You should see output like the following.

   ```
      $ls -l /dev/ttyUSB*
      crw-rw----    1    root    dialout    188,    0    Jul    10    19:04    /dev/ttyUSB0
      crw-rw----    1    root    dialout    188,    1    Jul    10    19:04    /dev/ttyUSB1
   ```

1. Sign off and then sign in and cycle the power to the board to make the changes take effect. In a terminal prompt, list the USB devices. Make sure the group owner has changed from `dialout` to `plugdev`.

   ```
      $ls -l /dev/ttyUSB*
      crw-rw----    1    root    plugdev    188,    0    Jul    10    19:04    /dev/ttyUSB0
      crw-rw----    1    root    plugdev    188,    1    Jul    10    19:04    /dev/ttyUSB1
   ```

   The `/dev/ttyUSBn` interface with the lower number is used for JTAG communication. The other interface is routed to the ESP32's serial port (UART) and is used for uploading code to the ESP32's flash memory.

1. In a terminal window, navigate to the root of your FreeRTOS download directory, and use the following command to run OpenOCD.

   ```
   idf.py openocd 
   ```

1. Open another terminal, navigate to the root of your FreeRTOS download directory, and run the following command.

   ```
   idf.py flash monitor 
   ```

1. Open another terminal, navigate the root of your FreeRTOS download directory, and run the following command:

   ```
   idf.py gdb
   ```

   The program should stop in `main()`.

# Getting started with the Espressif ESP32-WROOM-32SE
<a name="getting_started_esp32wroom-32se"></a>

**Important**  <a name="deprecation-message"></a>
This reference integration is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).

**Note**  
To explore how to integrate FreeRTOS modular libraries and demos within your own Espressif IDF project, see our [ featured reference integration for ESP32-C3 platform](https://www.freertos.org/featured-freertos-iot-integration-targeting-an-espressif-esp32-c3-risc-v-mcu/). 
Currently, the FreeRTOS port for ESP32-WROOM-32SE doesn't support the symmetric multiprocessing (SMP) feature.

This tutorial shows you how to get started with the Espressif ESP32-WROOM-32SE. To purchase one from our partner on the AWS Partner Device catalog, see [ESP32-WROOM-32SE](https://devices.amazonaws.com/detail/a3G0h0000077nRtEAI/ESP32-WROOM-32SE).

## Overview
<a name="getting_started_esp32wroom-32se-overview"></a>

This tutorial guides you through the following steps:

1. Connect your board to a host machine.

1. Install software on your host machine to develop and debug embedded applications for your microcontroller board.

1. Cross compile a FreeRTOS demo application to a binary image.

1. Load the application binary image to your board, and then run the application.

1. Monitor and debug the running application by using a serial connection.

## Prerequisites
<a name="setup-esp32wroom-32se-prereqs"></a>

Before you get started with FreeRTOS on your Espressif board, you must set up your AWS account and permissions.

### Sign up for an AWS account
<a name="sign-up-for-aws"></a>

If you do not have an AWS account, complete the following steps to create one.

**To sign up for an AWS account**

1. Open [https://portal.aws.amazon.com/billing/signup](https://portal.aws.amazon.com/billing/signup).

1. Follow the online instructions.

   Part of the sign-up procedure involves receiving a phone call or text message and entering a verification code on the phone keypad.

   When you sign up for an AWS account, an *AWS account root user* is created. The root user has access to all AWS services and resources in the account. As a security best practice, assign administrative access to a user, and use only the root user to perform [tasks that require root user access](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks).

AWS sends you a confirmation email after the sign-up process is complete. At any time, you can view your current account activity and manage your account by going to [https://aws.amazon.com/](https://aws.amazon.com/) and choosing **My Account**.

### Create a user with administrative access
<a name="create-an-admin"></a>

After you sign up for an AWS account, secure your AWS account root user, enable AWS IAM Identity Center, and create an administrative user so that you don't use the root user for everyday tasks.

**Secure your AWS account root user**

1.  Sign in to the [AWS Management Console](https://console.aws.amazon.com/) as the account owner by choosing **Root user** and entering your AWS account email address. On the next page, enter your password.

   For help signing in by using root user, see [Signing in as the root user](https://docs.aws.amazon.com/signin/latest/userguide/console-sign-in-tutorials.html#introduction-to-root-user-sign-in-tutorial) in the *AWS Sign-In User Guide*.

1. Turn on multi-factor authentication (MFA) for your root user.

   For instructions, see [Enable a virtual MFA device for your AWS account root user (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/enable-virt-mfa-for-root.html) in the *IAM User Guide*.

**Create a user with administrative access**

1. Enable IAM Identity Center.

   For instructions, see [Enabling AWS IAM Identity Center](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-set-up-for-idc.html) in the *AWS IAM Identity Center User Guide*.

1. In IAM Identity Center, grant administrative access to a user.

   For a tutorial about using the IAM Identity Center directory as your identity source, see [ Configure user access with the default IAM Identity Center directory](https://docs.aws.amazon.com//singlesignon/latest/userguide/quick-start-default-idc.html) in the *AWS IAM Identity Center User Guide*.

**Sign in as the user with administrative access**
+ To sign in with your IAM Identity Center user, use the sign-in URL that was sent to your email address when you created the IAM Identity Center user.

  For help signing in using an IAM Identity Center user, see [Signing in to the AWS access portal](https://docs.aws.amazon.com/signin/latest/userguide/iam-id-center-sign-in-tutorial.html) in the *AWS Sign-In User Guide*.

**Assign access to additional users**

1. In IAM Identity Center, create a permission set that follows the best practice of applying least-privilege permissions.

   For instructions, see [ Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-started-create-a-permission-set.html) in the *AWS IAM Identity Center User Guide*.

1. Assign users to a group, and then assign single sign-on access to the group.

   For instructions, see [ Add groups](https://docs.aws.amazon.com//singlesignon/latest/userguide/addgroups.html) in the *AWS IAM Identity Center User Guide*.

To provide access, add permissions to your users, groups, or roles:
+ Users and groups in AWS IAM Identity Center:

  Create a permission set. Follow the instructions in [Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html) in the *AWS IAM Identity Center User Guide*.
+ Users managed in IAM through an identity provider:

  Create a role for identity federation. Follow the instructions in [Create a role for a third-party identity provider (federation)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html) in the *IAM User Guide*.
+ IAM users:
  + Create a role that your user can assume. Follow the instructions in [Create a role for an IAM user](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html) in the *IAM User Guide*.
  + (Not recommended) Attach a policy directly to a user or add a user to a user group. Follow the instructions in [Adding permissions to a user (console)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) in the *IAM User Guide*.

## Get started
<a name="setup-esp32wroom-32s-idf42"></a>

**Note**  
The Linux commands in this tutorial require that you use the Bash shell.

1. **Set up the Espressif hardware.**

   For information about setting up the ESP32-WROOM-32SE development board hardware, see the [ ESP32-DevKitC V4 Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/get-started/index.html#installation-step-by-step).
**Important**  
When you reach the **Installation Step by Step** section of the guide, follow till you complete Step 4 (Set up the environment variables). Stop after you complete Step 4 and follow the remaining steps here.

1. Download Amazon FreeRTOS from [GitHub](https://github.com/aws/amazon-freertos). (For instructions, see the [README.md](https://github.com/aws/amazon-freertos/blob/main/README.md) file.)

1. **Set up your development environment**.

   To communicate with your board, you must install a toolchain. Espressif provides the ESP-IDF to develop software for their boards. Since the ESP-IDF has its own version of the FreeRTOS Kernel integrated as a component, Amazon FreeRTOS includes a custom version of the ESP-IDF v4.2 that has the FreeRTOS Kernel removed. This fixes problems with duplicate files when you compile. To use the custom version of the ESP-IDF v4.2 included with Amazon FreeRTOS, follow the instructions below for your host machine's operating system.

   **Windows**

   1. Download ESP-IDF's [ Universal Online Installer](https://dl.espressif.com/dl/esp-idf/?idf=4.2) for Windows.

   1. Run the **Universal Online Installer**.

   1. When you get to the step **Download or use ESP-IDF**, select **Use an existing ESP-IDF directory** and set **Choose existing ESP-IDF directory** to `freertos/vendors/espressif/esp-idf`.

   1. Complete the installation.

   **macOS**

   1. Follow the instructions in the [ Standard Setup of Toolchain prerequisites (ESP-IDF v4.2) for macOS](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/get-started/macos-setup.html).
**Important**  
When you reach the "Get ESP-IDF" instructions under **Next Steps**, stop, and then return to the instructions on this page.

   1. Open a command line window.

   1. Navigate to the FreeRTOS download directory, and then run the following script to download and install the espressif toolchain for your platform.

      ```
      vendors/espressif/esp-idf/install.sh
      ```

   1. Add the ESP-IDF toolchain tools to your terminal's path with the following command.

      ```
      source vendors/espressif/esp-idf/export.sh
      ```

   **Linux**

   1. Follow the instructions in the [ Standard Setup of Toolchain prerequisites (ESP-IDF v4.2) for Linux](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/get-started/linux-setup.html).
**Important**  
When you reach the "Get ESP-IDF" instructions under **Next Steps**, stop, and then return to the instructions on this page.

   1. Open a command line window.

   1. Navigate to the FreeRTOS download directory, and then run the following script to download and install the Espressif toolchain for your platform.

      ```
      vendors/espressif/esp-idf/install.sh
      ```

   1. Add the ESP-IDF toolchain tools to your terminal's path with the following command.

      ```
      source vendors/espressif/esp-idf/export.sh
      ```

1. **Establish a serial connection.**

   1. To establish a serial connection between your host machine and the ESP32-WROOM-32SE, install the CP210x USB to UART Bridge VCP drivers. You can download these drivers from [ Silicon Labs](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers).

   1. Follow the steps to [ Establish a Serial Connection with ESP32](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/get-started/establish-serial-connection.html).

   1. After you establish a serial connection, make a note of the serial port for your board's connection. You need it to flash the demo.

### Configure the FreeRTOS demo applications
<a name="configure-demos-esp32wroom-32s-idf42"></a>

For this tutorial, the FreeRTOS configuration file is located at `freertos/vendors/espressif/boards/board-name/aws_demos/config_files/FreeRTOSConfig.h`. (For example, if `AFR_BOARD espressif.esp32_devkitc` is chosen, the configuration file is located at `freertos/vendors/espressif/boards/esp32/aws_demos/config_files/FreeRTOSConfig.h`.) 

**Important**  
The ATECC608A device has a one-time initialization that is locked onto the device the first time a project is run (during the call to `C_InitToken`). However, the FreeRTOS demo project and test project have different configurations. If the device is locked during the demo project configurations, not all tests in the test project will succeed.

1. Configure the FreeRTOS Demo Project by following the steps in [Configuring the FreeRTOS demos](freertos-prereqs.md#freertos-configure). When you get to the last step **To format your AWS IoT credentials**, stop, and perform the following steps.

1. Microchip has provided several scripting tools to help with the setup of the ATECC608A parts. Navigate to the `freertos/vendors/microchip/example_trust_chain_tool` directory, and open the `README.md` file.

1. To provision your device, follow the instructions in the `README.md` file. The steps include the following:

   1. Create and register a certificate authority with AWS.

   1. Generate your keys on the ATECC608A and export the public key and device serial number.

   1. Generate a certificate for the device and register that certificate with AWS.

1. Load the CA certificate and device certificate onto the device by following the instructions for [Developer-mode key provisioning](dev-mode-key-provisioning.md).

### Monitoring MQTT messages on the AWS Cloud
<a name="gsg-esp32wroom-32se-monitor-mqtt"></a>

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](https://console.aws.amazon.com/iotv2/).

1. In the navigation pane, choose **Test**, then choose **MQTT Test Client**.

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

### Build, flash, and run the FreeRTOS demo project using the idf.py script
<a name="build-and-run-example-esp32wroom-32se-idf42"></a>

You can use Espressif's IDF utility (`idf.py`) to generate the build files, build the application binary, and flash the binaries onto your device.

**Note**  
Some setups might require that you use the port option "`-p port-name`" with `idf.py` to specify the correct port, as in the following example.  

```
idf.py -p /dev/cu.usbserial-00101301B flash
```

**Build and flash FreeRTOS on Windows, Linux, and macOS (ESP-IDF v4.2)**

1. Navigate to the root of your FreeRTOS download directory.

1. In a command line window, enter the following command to add the ESP-IDF tools to your terminal's PATH:  
**Windows ("Command" app)**  

   ```
   vendors\espressif\esp-idf\export.bat
   ```  
**Windows ("ESP-IDF 4.x CMD" app)**  
(This has already been done when you opened the app.)  
**Linux / macOS**  

   ```
   source vendors/espressif/esp-idf/export.sh
   ```

1. Configure cmake in the `build` directory and build the firmware image with the following command.

   ```
   idf.py -DVENDOR=espressif -DBOARD=esp32_ecc608a_devkitc -DCOMPILER=xtensa-esp32 build
   ```

   You should see output like this following example.

   ```
      Running cmake in directory /path/to/hello_world/build
      Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"...
      Warn about uninitialized values.
      -- Found Git: /usr/bin/git (found version "2.17.0")
      -- Building empty aws_iot component due to configuration
      -- Component names: ...
      -- Component paths: ...
   
      ... (more lines of build system output)
   
      [527/527] Generating hello-world.bin
      esptool.py v2.3.1
   
      Project build complete. To flash, run this command:
      ../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin  build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin
      or run 'idf.py -p PORT flash'
   ```

   If there are no errors, the build will generate the firmware binary .bin files.

1. Erase your development board's flash memory with the following command.

   ```
   idf.py erase_flash
   ```

1. Use the `idf.py` script to flash the application binary to your board.

   ```
   idf.py flash
   ```

1. Monitor the output from your board's serial port with the following command.

   ```
   idf.py monitor
   ```
**Note**  
You can combine these commands as in the following example.  

     ```
     idf.py erase_flash flash monitor
     ```
For certain host machine setups, you must specify the port when you flash the board as in the following example.  

     ```
     idf.py erase_flash flash monitor -p /dev/ttyUSB1
     ```

### Build and Flash FreeRTOS with CMake
<a name="flash-esp32wroom-32se-cmake-idf42"></a>

Besides using the `idf.py` script provided by the IDF SDK to build and run your code, you can also build the project with CMake. Currently it supports Unix Makefile and the Ninja build system.

**To build and flash the project**

1. In a command line window, navigate to the root of your FreeRTOS download directory.

1. Run the following script to add the ESP-IDF tools to your shell's PATH.  
**Windows**  

   ```
   vendors\espressif\esp-idf\export.bat
   ```  
**Linux / macOS**  

   ```
   source vendors/espressif/esp-idf/export.sh
   ```

1. Enter the following command to generate the build files.  
**With Unix Makefiles**  

   ```
   cmake -DVENDOR=espressif -DBOARD=esp32_plus_ecc608a_devkitc -DCOMPILER=xtensa-esp32 -S . -B ./YOUR_BUILD_DIRECTORY -DAFR_ENABLE_ALL_MODULES=1 -DAFR_ENABLE_TESTS=0
   ```  
**With Ninja**  

   ```
   cmake -DVENDOR=espressif -DBOARD=esp32_plus_ecc608a_devkitc -DCOMPILER=xtensa-esp32 -S . -B ./YOUR_BUILD_DIRECTORY -DAFR_ENABLE_ALL_MODULES=1 -DAFR_ENABLE_TESTS=0 -GNinja
   ```

1. Erase the flash and then flash the board.  
**With Unix Makefiles**  

   ```
   make -C ./YOUR_BUILD_DIRECTORY erase_flash
   ```

   ```
   make -C ./YOUR_BUILD_DIRECTORY flash
   ```  
**With Ninja**  

   ```
   ninja -C ./YOUR_BUILD_DIRECTORY erase_flash
   ```

   ```
   ninja -C ./YOUR_BUILD_DIRECTORY flash
   ```

## Additional information
<a name="getting_started_esp32wroom-32se-additional"></a>

For more information about using and troubleshooting Espressif ESP32 boards, see the following topics:
+ [Using FreeRTOS in your own CMake project for ESP32](getting_started_espressif.md#getting_started_espressif_cmake_project)
+ [Troubleshooting](getting_started_espressif.md#getting_started_espressif_troubleshooting)
+ [Debugging](getting_started_espressif.md#getting_started_espressif_debugging)

# Getting started with the Espressif ESP32-S2
<a name="getting_started_esp32-s2"></a>

**Important**  <a name="deprecation-message"></a>
This reference integration is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).

**Note**  
To explore how to integrate FreeRTOS modular libraries and demos within your own Espressif IDF project, see our [ featured reference integration for ESP32-C3 platform](https://www.freertos.org/featured-freertos-iot-integration-targeting-an-espressif-esp32-c3-risc-v-mcu/). 

This tutorial shows you how to get started with the Espressif ESP32-S2 SoC and [ESP32-S2-Saola-1](https://devices.amazonaws.com/detail/a3G0h00000AkFngEAF/ESP32-S2-Saola-1) development boards.

## Overview
<a name="getting_started_esp32-s2-overview"></a>

This tutorial guides you through the following steps:

1. Connect your board to a host machine.

1. Install software on your host machine to develop and debug embedded applications for your microcontroller board.

1. Cross-compile a FreeRTOS demo application to a binary image.

1. Load the application binary image to your board, and then run the application.

1. Monitor and debug the running application using a serial connection.

## Prerequisites
<a name="setup-esp32-s2-prereqs"></a>

Before you get started with FreeRTOS on your Espressif board, you must set up your AWS account and permissions.

### Sign up for an AWS account
<a name="sign-up-for-aws"></a>

If you do not have an AWS account, complete the following steps to create one.

**To sign up for an AWS account**

1. Open [https://portal.aws.amazon.com/billing/signup](https://portal.aws.amazon.com/billing/signup).

1. Follow the online instructions.

   Part of the sign-up procedure involves receiving a phone call or text message and entering a verification code on the phone keypad.

   When you sign up for an AWS account, an *AWS account root user* is created. The root user has access to all AWS services and resources in the account. As a security best practice, assign administrative access to a user, and use only the root user to perform [tasks that require root user access](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks).

AWS sends you a confirmation email after the sign-up process is complete. At any time, you can view your current account activity and manage your account by going to [https://aws.amazon.com/](https://aws.amazon.com/) and choosing **My Account**.

### Create a user with administrative access
<a name="create-an-admin"></a>

After you sign up for an AWS account, secure your AWS account root user, enable AWS IAM Identity Center, and create an administrative user so that you don't use the root user for everyday tasks.

**Secure your AWS account root user**

1.  Sign in to the [AWS Management Console](https://console.aws.amazon.com/) as the account owner by choosing **Root user** and entering your AWS account email address. On the next page, enter your password.

   For help signing in by using root user, see [Signing in as the root user](https://docs.aws.amazon.com/signin/latest/userguide/console-sign-in-tutorials.html#introduction-to-root-user-sign-in-tutorial) in the *AWS Sign-In User Guide*.

1. Turn on multi-factor authentication (MFA) for your root user.

   For instructions, see [Enable a virtual MFA device for your AWS account root user (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/enable-virt-mfa-for-root.html) in the *IAM User Guide*.

**Create a user with administrative access**

1. Enable IAM Identity Center.

   For instructions, see [Enabling AWS IAM Identity Center](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-set-up-for-idc.html) in the *AWS IAM Identity Center User Guide*.

1. In IAM Identity Center, grant administrative access to a user.

   For a tutorial about using the IAM Identity Center directory as your identity source, see [ Configure user access with the default IAM Identity Center directory](https://docs.aws.amazon.com//singlesignon/latest/userguide/quick-start-default-idc.html) in the *AWS IAM Identity Center User Guide*.

**Sign in as the user with administrative access**
+ To sign in with your IAM Identity Center user, use the sign-in URL that was sent to your email address when you created the IAM Identity Center user.

  For help signing in using an IAM Identity Center user, see [Signing in to the AWS access portal](https://docs.aws.amazon.com/signin/latest/userguide/iam-id-center-sign-in-tutorial.html) in the *AWS Sign-In User Guide*.

**Assign access to additional users**

1. In IAM Identity Center, create a permission set that follows the best practice of applying least-privilege permissions.

   For instructions, see [ Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-started-create-a-permission-set.html) in the *AWS IAM Identity Center User Guide*.

1. Assign users to a group, and then assign single sign-on access to the group.

   For instructions, see [ Add groups](https://docs.aws.amazon.com//singlesignon/latest/userguide/addgroups.html) in the *AWS IAM Identity Center User Guide*.

To provide access, add permissions to your users, groups, or roles:
+ Users and groups in AWS IAM Identity Center:

  Create a permission set. Follow the instructions in [Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html) in the *AWS IAM Identity Center User Guide*.
+ Users managed in IAM through an identity provider:

  Create a role for identity federation. Follow the instructions in [Create a role for a third-party identity provider (federation)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html) in the *IAM User Guide*.
+ IAM users:
  + Create a role that your user can assume. Follow the instructions in [Create a role for an IAM user](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html) in the *IAM User Guide*.
  + (Not recommended) Attach a policy directly to a user or add a user to a user group. Follow the instructions in [Adding permissions to a user (console)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) in the *IAM User Guide*.

## Get started
<a name="setup-esp32-s2-idf42"></a>

**Note**  
The Linux commands in this tutorial require that you use the Bash shell.

1. **Set up the Espressif hardware.**

   For information about setting up the ESP32-S2 development board hardware, see the [ ESP32-S2-Saola-1 Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32s2/hw-reference/esp32s2/user-guide-saola-1-v1.2.html).
**Important**  
When you reach the **Get Started** section of the Espressif guides, stop, and then return to the instructions on this page.

1. Download Amazon FreeRTOS from [GitHub](https://github.com/aws/amazon-freertos). (For instructions, see the [README.md](https://github.com/aws/amazon-freertos/blob/main/README.md) file.)

1. **Set up your development environment**.

   To communicate with your board, you must install a toolchain. Espressif provides the ESP-IDF to develop software for their boards. Since the ESP-IDF has its own version of the FreeRTOS Kernel integrated as a component, Amazon FreeRTOS includes a custom version of the ESP-IDF v4.2 that has the FreeRTOS Kernel removed. This fixes problems with duplicate files when you compile. To use the custom version of the ESP-IDF v4.2 included with Amazon FreeRTOS, follow the instructions below for your host machine's operating system.

   **Windows**

   1. Download ESP-IDF's [ Universal Online Installer](https://dl.espressif.com/dl/esp-idf/?idf=4.2) for Windows.

   1. Run the **Universal Online Installer**.

   1. When you get to the step **Download or use ESP-IDF**, select **Use an existing ESP-IDF directory** and set **Choose existing ESP-IDF directory** to `freertos/vendors/espressif/esp-idf`.

   1. Complete the installation.

   **macOS**

   1. Follow the instructions in the [ Standard Setup of Toolchain prerequisites (ESP-IDF v4.2) for macOS](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32s2/get-started/macos-setup.html).
**Important**  
When you reach the "Get ESP-IDF" instructions under **Next Steps**, stop, and then return to the instructions on this page.

   1. Open a command line window.

   1. Navigate to the FreeRTOS download directory, and then run the following script to download and install the espressif toolchain for your platform.

      ```
      vendors/espressif/esp-idf/install.sh
      ```

   1. Add the ESP-IDF toolchain tools to your terminal's path with the following command.

      ```
      source vendors/espressif/esp-idf/export.sh
      ```

   **Linux**

   1. Follow the instructions in the [ Standard Setup of Toolchain prerequisites (ESP-IDF v4.2) for Linux](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32s2/get-started/linux-setup.html).
**Important**  
When you reach the "Get ESP-IDF" instructions under **Next Steps**, stop, and then return to the instructions on this page.

   1. Open a command line window.

   1. Navigate to the FreeRTOS download directory, and then run the following script to download and install the Espressif toolchain for your platform.

      ```
      vendors/espressif/esp-idf/install.sh
      ```

   1. Add the ESP-IDF toolchain tools to your terminal's path with the following command.

      ```
      source vendors/espressif/esp-idf/export.sh
      ```

1. **Establish a serial connection.**

   1. To establish a serial connection between your host machine and the ESP32-DevKitC, install the CP210x USB to UART Bridge VCP drivers. You can download these drivers from [ Silicon Labs](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers).

   1. Follow the steps to [ Establish a Serial Connection with ESP32](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/get-started/establish-serial-connection.html). 

   1. After you establish a serial connection, make a note of the serial port for your board's connection. You need it to flash the demo.

### Configure the FreeRTOS demo applications
<a name="configure-demos-esp32-s2-idf42"></a>

For this tutorial, the FreeRTOS configuration file is located at `freertos/vendors/espressif/boards/board-name/aws_demos/config_files/FreeRTOSConfig.h`. (For example, if `AFR_BOARD espressif.esp32_devkitc` is chosen, the configuration file is located at `freertos/vendors/espressif/boards/esp32/aws_demos/config_files/FreeRTOSConfig.h`.) 

1. If you're running macOS or Linux, open a terminal prompt. If you're running Windows, open the "ESP-IDF 4.x CMD" app (if you included this option when you installed the ESP-IDF toolchain), or the "Command Prompt" app otherwise. 

1. To verify that you have Python3 installed, run the following:

   ```
   python --version
   ```

   The version installed is displayed. If you don't have Python 3.0.1 or later installed, you can install it from the [Python](https://www.python.org/downloads/) website.

1. You need the AWS Command Line Interface (CLI) to run AWS IoT commands. If you're running Windows, use the `easy_install awscli` command to install the AWS CLI in the "Command" or "ESP-IDF 4.x CMD" app. 

   If you're running macOS or Linux, see [Installing the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/installing.html).

1. Run

   ```
   aws configure
   ```

   and configure the AWS CLI with your AWS access key ID, secret access key, and default AWS Region. For more information, see [Configuring the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html).

1. Use the following command to install the AWS SDK for Python (boto3):
   + On Windows, in the "Command" or "ESP-IDF 4.x CMD" app, run

     ```
     easy_install boto3
     ```
   + On macOS or Linux, run

     ```
     pip install tornado nose --user
     ```

     and then run

     ```
     pip install boto3 --user
     ```

FreeRTOS includes the `SetupAWS.py` script to make it easier to set up your Espressif board to connect to AWS IoT.

**To run the configuration script**

1. To configure the script, open `freertos/tools/aws_config_quick_start/configure.json` and set the following attributes:   
**`afr_source_dir`**  
The complete path to the `freertos` directory on your computer. Make sure that you use forward slashes to specify this path.  
**`thing_name`**  
The name that you want to assign to the AWS IoT thing that represents your board.  
**`wifi_ssid`**  
The SSID of your Wi-Fi network.  
**`wifi_password`**  
The password for your Wi-Fi network.  
**`wifi_security`**  
The security type for your Wi-Fi network. The following are valid security types:  
   + `eWiFiSecurityOpen` (Open, no security)
   + `eWiFiSecurityWEP` (WEP security)
   + `eWiFiSecurityWPA` (WPA security)
   + `eWiFiSecurityWPA2` (WPA2 security)

1. If you're running macOS or Linux, open a terminal prompt. If you're running Windows, open the "ESP-IDF 4.x CMD" or "Command" app. 

1. Navigate to the `freertos/tools/aws_config_quick_start` directory and run

   ```
   python SetupAWS.py setup
   ```

   The script does the following:
   + Creates an AWS IoT thing, certificate, and policy.
   + Attaches the AWS IoT policy to the certificate and the certificate to the AWS IoT thing.
   + Populates the `aws_clientcredential.h` file with your AWS IoT endpoint, Wi-Fi SSID, and credentials.
   + Formats your certificate and private key and writes them to the `aws_clientcredential_keys.h` header file.
**Note**  
The certificate is hardcoded for demonstration purposes only. Production-level applications should store these files in a secure location.

   For more information about `SetupAWS.py`, see the `README.md` in the `freertos/tools/aws_config_quick_start` directory.

### Monitoring MQTT messages on the AWS Cloud
<a name="gsg-esp32-s2-monitor-mqtt"></a>

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](https://console.aws.amazon.com/iotv2/).

1. In the navigation pane, choose **Test**, then choose **MQTT Test Client**.

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

When the demo project successfully runs on your device you see "Hello World\$1" sent multiple times to the topic that you subscribed to.

### Build, flash, and run the FreeRTOS demo project using the idf.py script
<a name="build-and-run-example-esp32-s2-idf42"></a>

You can use Espressif's IDF utility to generate the build files, build the application binary, and flash your board.

#### Build and flash FreeRTOS on Windows, Linux, and macOS (ESP-IDF v4.2)
<a name="build-esp32-s2-idf42"></a>

Use the `idf.py` script to build the project and flash the binaries onto your device.

**Note**  
Some setups might require that you use the port option `-p port-name` with `idf.py` to specify the correct port, as in the following example.  

```
idf.py -p /dev/cu.usbserial-00101301B flash
```

**To build and flash the project**

1. Navigate to the root of your FreeRTOS download directory.

1. In a command line window, enter the following command to add the ESP-IDF tools to your terminal's PATH:   
**Windows ("Command" app)**  

   ```
   vendors\espressif\esp-idf\export.bat
   ```  
**Windows ("ESP-IDF 4.x CMD" app)**  
(This has already been done when you opened the app.)  
**Linux / macOS**  

   ```
   source vendors/espressif/esp-idf/export.sh
   ```

1. Configure cmake in the `build` directory and build the firmware image with the following command.

   ```
   idf.py -DVENDOR=espressif -DBOARD=esp32s2_saola_1 -DCOMPILER=xtensa-esp32s2 build
   ```

   You should see output like this following example.

   ```
   Executing action: all (aliases: build)
      Running cmake in directory /path/to/hello_world/build
      Executing "cmake -G Ninja -DPYTHON_DEPS_CHECKED=1 -DESP_PLATFORM=1 -DVENDOR=espressif -DBOARD=esp32s2_saola_1 -DCOMPILER=xtensa-esp32s2 -DCCACHE_ENABLE=0 /path/to/hello_world"...
      -- The C compiler identification is GNU 8.4.0
      -- The CXX compiler identification is GNU 8.4.0
      -- The ASM compiler identification is GNU
   
      ... (more lines of build system output)
   
      [1628/1628] Generating binary image from built executable
      esptool.py v3.0
      Generated /path/to/hello_world/build/aws_demos.bin
   
      Project build complete. To flash, run this command:
      esptool.py -p (PORT) -b 460800 --before default_reset --after hard_reset --chip esp32s2  write_flash --flash_mode dio --flash_size detect --flash_freq 80m 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin 0x16000 build/ota_data_initial.bin 0x20000 build/aws_demos.bin
      or run 'idf.py -p (PORT) flash'
   ```

   If there are no errors, the build generates the firmware binary .bin files.

1. Erase your development board's flash memory with the following command.

   ```
   idf.py erase_flash
   ```

1. Use the `idf.py` script to flash the application binary to your board.

   ```
   idf.py flash
   ```

1. Monitor the output from your board's serial port with the following command.

   ```
   idf.py monitor
   ```
**Note**  
You can combine these commands as in the following example.  

     ```
     idf.py erase_flash flash monitor
     ```
For certain host machine setups, you must specify the port when you flash the board as in the following example.  

     ```
     idf.py erase_flash flash monitor -p /dev/ttyUSB1
     ```

### Build and Flash FreeRTOS with CMake
<a name="flash-esp32-s2-cmake-idf42"></a>

Besides using the `idf.py` script provided by the IDF SDK to build and run your code, you can also build the project with CMake. Currently it supports Unix Makefile and the Ninja build system.

**To build and flash the project**

1. In a command line window, navigate to the root of your FreeRTOS download directory.

1. Run the following script to add the ESP-IDF tools to your shell's PATH.
   + Windows

     ```
     vendors\espressif\esp-idf\export.bat
     ```
   + Linux / macOS 

     ```
     source vendors/espressif/esp-idf/export.sh
     ```

1. Enter the following command to generate the build files.
   + With Unix Makefiles

     ```
     cmake -DVENDOR=espressif -DBOARD=esp32s2_saola_1 -DCOMPILER=xtensa-esp32s2 -S . -B ./YOUR_BUILD_DIRECTORY -DAFR_ENABLE_ALL_MODULES=1 -DAFR_ENABLE_TESTS=0
     ```
   + With Ninja

     ```
     cmake -DVENDOR=espressif -DBOARD=esp32s2_saola_1 -DCOMPILER=xtensa-esp32s2 -S . -B ./YOUR_BUILD_DIRECTORY -DAFR_ENABLE_ALL_MODULES=1 -DAFR_ENABLE_TESTS=0 -GNinja
     ```

1. Build the project.
   + With Unix Makefiles

     ```
     make -C ./YOUR_BUILD_DIRECTORY -j8
     ```
   + With Ninja

     ```
     ninja -C ./YOUR_BUILD_DIRECTORY -j8
     ```

1. Erase the flash and then flash the board.
   + With Unix Makefiles

     ```
     make -C ./YOUR_BUILD_DIRECTORY erase_flash
     ```

     ```
     make -C ./YOUR_BUILD_DIRECTORY flash
     ```
   + With Ninja

     ```
     ninja -C ./YOUR_BUILD_DIRECTORY erase_flash
     ```

     ```
     ninja -C ./YOUR_BUILD_DIRECTORY flash
     ```

## Additional information
<a name="getting_started_esp32-s2-additional"></a>

For more information about using and troubleshooting Espressif ESP32 boards, see the following topics:
+ [Using FreeRTOS in your own CMake project for ESP32](getting_started_espressif.md#getting_started_espressif_cmake_project)
+ [Troubleshooting](getting_started_espressif.md#getting_started_espressif_troubleshooting)
+ [Debugging](getting_started_espressif.md#getting_started_espressif_debugging)

# Getting started with the Infineon XMC4800 IoT Connectivity Kit
<a name="getting_started_infineon"></a>

**Important**  <a name="deprecation-message"></a>
This reference integration is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).

This tutorial provides instructions for getting started with the Infineon XMC4800 IoT Connectivity Kit. If you do not have the Infineon XMC4800 IoT Connectivity Kit, visit the AWS Partner Device Catalog to purchase one from our [ partner](https://devices.amazonaws.com/detail/a3G0L00000AANsbUAH/XMC4800-IoT-Amazon-FreeRTOS-Connectivity-Kit-WiFi).

If you want to open a serial connection with the board to view logging and debugging information, you need a 3.3V USB/Serial converter, in addition to the XMC4800 IoT Connectivity Kit. The CP2104 is a common USB/Serial converter that is widely available in boards such as Adafruit's [CP2104 Friend](https://www.adafruit.com/product/3309).

Before you begin, you must configure AWS IoT and your FreeRTOS download to connect your device to the AWS Cloud. See [First steps](freertos-prereqs.md) for instructions. In this tutorial, the path to the FreeRTOS download directory is referred to as `freertos`.

## Overview
<a name="w2aac31b9b7c25c27c13"></a>

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.

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

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

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

## Set up your development environment
<a name="infineon-setup-env"></a>

FreeRTOS uses Infineon's DAVE development environment to program the XMC4800. Before you begin, you need to download and install DAVE and some J-Link drivers to communicate with the on-board debugger.

### Install DAVE
<a name="install-dave"></a>

1. Go to Infineon's [DAVE software download](https://infineoncommunity.com/dave-download_ID645) page.

1. Choose the DAVE package for your operating system and submit your registration information. After registering with Infineon, you should receive a confirmation email with a link to download a .zip file.

1. Download the DAVE package .zip file (`DAVE_version_os_date.zip`), and unzip it to the location where you want to install DAVE (for example, `C:\DAVE4`). 
**Note**  
Some Windows users have reported problems using Windows Explorer to unzip the file. We recommend that you use a third-party program such as 7-Zip.

1. To launch DAVE, run the executable file found in the unzipped `DAVE_version_os_date.zip` folder.

For more information, see the [DAVE Quick Start Guide](https://www.infineon.com/dgdl/Infineon-DAVE_Quick_Start-GS-v02_00-EN.pdf?fileId=5546d4624cb7f111014d059f7b8c712d).

### Install Segger J-Link drivers
<a name="install-jlink"></a>

To communicate with the XMC4800 Relax EtherCAT board's on-board debugging probe, you need the drivers included in the J-Link Software and Documentation pack. You can download the J-Link Software and Documentation pack from Segger's [J-Link software download](https://www.segger.com/downloads/jlink/#J-LinkSoftwareAndDocumentationPack) page.

## Establish a serial connection
<a name="install-serial-connection"></a>

Setting up a serial connection is optional, but recommended. A serial connection allows your board to send logging and debugging information in a form that you can view on your development machine.

The XMC4800 demo application uses a UART serial connection on pins P0.0 and P0.1, which are labeled on the XMC4800 Relax EtherCAT board's silkscreen. To set up a serial connection:

1. Connect the pin labeled “RX<P0.0” to your USB/Serial converter's “TX” pin.

1. Connect the pin labeled “TX>P0.1” to your USB/Serial converter's “RX” pin.

1. Connect your serial converter's Ground pin to one of the pins labeled “GND” on your board. The devices must share a common ground.

Power is supplied from the USB debugging port, so do not connect your serial adapter's positive voltage pin to the board.

**Note**  
Some serial cables use a 5V signaling level. The XMC4800 board and the Wi-Fi Click module require a 3.3V. Do not use the board's IOREF jumper to change the board's signals to 5V.

 With the cable connected, you can open a serial connection on a terminal emulator such as [GNU Screen](https://www.gnu.org/software/screen/). The baud rate is set to 115200 by default with 8 data bits, no parity, and 1 stop bit. 

## Monitoring MQTT messages on the cloud
<a name="infineon-monitor-mqtt"></a>

Before you run the FreeRTOS demo, 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](https://console.aws.amazon.com/iotv2/).

1. In the navigation pane, choose **Test**, then choose **MQTT test client** to open the MQTT client.

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

When the demo project successfully runs on your device you see "Hello World\$1" sent multiple times to the topic that you subscribed to.

## Build and run the FreeRTOS demo project
<a name="infineon-build-and-run-example"></a>

### Import the FreeRTOS demo into DAVE
<a name="infineon-freertos-import-project"></a><a name="infineon-load-project"></a>

1. Start DAVE.

1. In DAVE, choose **File**, **Import**. In the **Import** window, expand the **Infineon** folder, choose **DAVE Project**, and then choose **Next**.

1. In the **Import DAVE Projects** window, choose **Select Root Directory**, choose **Browse**, and then choose the XMC4800 demo project.

   In the directory where you unzipped your FreeRTOS download, the demo project is located in `projects/infineon/xmc4800_iotkit/dave4/aws_demos`. 

   Make sure that **Copy Projects Into Workspace** is unchecked.

1. Choose **Finish**.

   The `aws_demos` project should be imported into your workspace and activated.

1. From the **Project** menu, choose **Build Active Project**.

   Make sure that the project builds without errors.

### Run the FreeRTOS demo project
<a name="infineon-run-examples"></a>

1. Use a USB cable to connect your XMC4800 IoT Connectivity Kit to your computer. The board has two microUSB connectors. Use the one labeled “X101”, where Debug appears next to it on the board's silkscreen.

1. From the **Project** menu, choose **Rebuild Active Project** to rebuild `aws_demos` and ensure that your configuration changes are picked up.

1. From **Project Explorer**, right-click `aws_demos`, choose **Debug As**, and then choose **DAVE C/C\$1\$1 Application**.

1. Double-click **GDB SEGGER J-Link Debugging** to create a debug confirmation. Choose **Debug**.

1. When the debugger stops at the breakpoint in `main()`, from the **Run** menu, choose **Resume**.

In the AWS IoT console, the MQTT client from steps 4-5 should display the MQTT messages sent by your device. If you use the serial connection, you see something like this on the UART output:

```
0 0 [Tmr Svc] Starting key provisioning...
1 1 [Tmr Svc] Write root certificate...
2 4 [Tmr Svc] Write device private key...
3 82 [Tmr Svc] Write device certificate...
4 86 [Tmr Svc] Key provisioning done...
5 291 [Tmr Svc] Wi-Fi module initialized. Connecting to AP...
.6 8046 [Tmr Svc] Wi-Fi Connected to AP. Creating tasks which use network...
7 8058 [Tmr Svc] IP Address acquired [IP Address]
8 8058 [Tmr Svc] Creating MQTT Echo Task...
9 8059 [MQTTEcho] MQTT echo attempting to connect to [MQTT Broker].
...10 23010 [MQTTEcho] MQTT echo connected.
11 23010 [MQTTEcho] MQTT echo test echoing task created.
.12 26011 [MQTTEcho] MQTT Echo demo subscribed to iotdemo/#
13 29012 [MQTTEcho] Echo successfully published 'Hello World 0'
.14 32096 [Echoing] Message returned with ACK: 'Hello World 0 ACK'
.15 37013 [MQTTEcho] Echo successfully published 'Hello World 1'
16 40080 [Echoing] Message returned with ACK: 'Hello World 1 ACK'
.17 45014 [MQTTEcho] Echo successfully published 'Hello World 2'
.18 48091 [Echoing] Message returned with ACK: 'Hello World 2 ACK'
.19 53015 [MQTTEcho] Echo successfully published 'Hello World 3'
.20 56087 [Echoing] Message returned with ACK: 'Hello World 3 ACK'
.21 61016 [MQTTEcho] Echo successfully published 'Hello World 4'
22 64083 [Echoing] Message returned with ACK: 'Hello World 4 ACK'
.23 69017 [MQTTEcho] Echo successfully published 'Hello World 5'
.24 72091 [Echoing] Message returned with ACK: 'Hello World 5 ACK'
.25 77018 [MQTTEcho] Echo successfully published 'Hello World 6'
26 80085 [Echoing] Message returned with ACK: 'Hello World 6 ACK'
.27 85019 [MQTTEcho] Echo successfully published 'Hello World 7'
.28 88086 [Echoing] Message returned with ACK: 'Hello World 7 ACK'
.29 93020 [MQTTEcho] Echo successfully published 'Hello World 8'
.30 96088 [Echoing] Message returned with ACK: 'Hello World 8 ACK'
.31 101021 [MQTTEcho] Echo successfully published 'Hello World 9'
32 104102 [Echoing] Message returned with ACK: 'Hello World 9 ACK'
.33 109022 [MQTTEcho] Echo successfully published 'Hello World 10'
.34 112047 [Echoing] Message returned with ACK: 'Hello World 10 ACK'
.35 117023 [MQTTEcho] Echo successfully published 'Hello World 11'
36 120089 [Echoing] Message returned with ACK: 'Hello World 11 ACK'
.37 122068 [MQTTEcho] MQTT echo demo finished.
38 122068 [MQTTEcho] ----Demo finished----
```

### Build the FreeRTOS demo with CMake
<a name="infineon-cmake"></a>

If you prefer not to use an IDE for FreeRTOS development, you can alternatively use CMake to build and run the demo applications or applications that you have developed using third-party code editors and debugging tools.

**Note**  
This section covers using CMake on Windows with MingW as the native build system. For more information about using CMake with other operating systems and options, see [Using CMake with FreeRTOS](getting-started-cmake.md). ([MinGW ](https://sourceforge.net/projects/mingw-w64/files/) is a minimalist development environment for native Microsoft Windows applications.)

**To build the FreeRTOS demo with CMake**

1. Set up the GNU Arm Embedded Toolchain.

   1. Download a Windows version of the toolchain from the [Arm Embedded Toolchain download page](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads).
**Note**  
We recommend that you download a version other than "8-2018-q4-major", due to [a bug reported](https://bugs.launchpad.net/gcc-arm-embedded/+bug/1810274) with the “objcopy” utility in that version.

   1. Open the downloaded toolchain installer, and follow the installation wizard's instructions to install the toolchain.
**Important**  
On the final page of the installation wizard, select **Add path to environment variable** to add the toolchain path to the system path environment variable.

1. Install CMake and MingW.

   For instructions, see [CMake Prerequisites](getting-started-cmake.md#building-cmake-prereqs).

1. Create a folder to contain the generated build files (*build-folder*).

1. Change directories to your FreeRTOS download directory (`freertos`), and use the following command to generate the build files:

   ```
   cmake -DVENDOR=infineon -DBOARD=xmc4800_iotkit -DCOMPILER=arm-gcc -S . -B build-folder -G "MinGW Makefiles" -DAFR_ENABLE_TESTS=0
   ```

1. Change directories to the build directory (*build-folder*), and use the following command to build the binary:

   ```
   cmake --build . --parallel 8
   ```

   This command builds the output binary `aws_demos.hex` to the build directory.

1. Flash and run the image with [JLINK](#install-jlink).

   1. From the build directory (*build-folder*), use the following commands to create a flash script:

      ```
      echo loadfile aws_demos.hex > flash.jlink
      ```

      ```
      echo r >> flash.jlink
      ```

      ```
      echo g >> flash.jlink
      ```

      ```
      echo q >> flash.jlink
      ```

   1. Flash the image using the JLNIK executable.

      ```
      JLINK_PATH\JLink.exe  -device XMC4800-2048 -if SWD -speed auto -CommanderScript flash.jlink
      ```

      The application logs should be visible through [the serial connection](#install-serial-connection) that you established with the board.

## Troubleshooting
<a name="infineon-troubleshooting"></a>

If you haven't already, be sure to configure AWS IoT and your FreeRTOS download to connect your device to the AWS Cloud. See [First steps](freertos-prereqs.md) for instructions.

For general troubleshooting information about Getting Started with FreeRTOS, see [Troubleshooting getting started](gsg-troubleshooting.md).

# Getting started with the Infineon OPTIGA Trust X and XMC4800 IoT Connectivity Kit
<a name="getting_started_infineon_trust_x"></a>

**Important**  <a name="deprecation-message"></a>
This reference integration is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).

This tutorial provides instructions for getting started with the Infineon OPTIGA Trust X Secure Element and XMC4800 IoT Connectivity Kit. In comparison to the [Getting started with the Infineon XMC4800 IoT Connectivity Kit](getting_started_infineon.md) tutorial, this guide shows you how to provide secure credentials using an Infineon OPTIGA Trust X Secure Element.

You need the following hardware:

1. Host MCU - Infineon XMC4800 IoT Connectivity Kit, visit the AWS Partner Device Catalog to purchase one from our [ partner](https://devices.amazonaws.com/detail/a3G0L00000AANsbUAH/XMC4800-IoT-Amazon-FreeRTOS-Connectivity-Kit-WiFi).

1. Security Extension Pack: 
   + Secure Element - Infineon OPTIGA Trust X.

     Visit the AWS Partner Device Catalog to purchase them from our [ partner](https://devices.amazonaws.com/detail/a3G0h000000TePnEAK/OPTIGA%E2%84%A2-Trust-X-Security-Solution).
   + Personalization Board - Infineon OPTIGA Personalisation Board.
   + Adapter Board - Infineon MyIoT Adapter.

To follow the steps here, you must open a serial connection with the board to view logging and debugging information. (One of the steps requires you to copy a public key from the serial debugging output from the board and paste it to a file.) To do this, you need a 3.3V USB/Serial converter in addition to the XMC4800 IoT Connectivity Kit. The [ JBtek EL-PN-47310126](https://www.amazon.com/gp/product/B00QT7LQ88) USB/Serial converter is known to work for this demo. You also need three male-to-male [jumper wires](https://www.amazon.com/gp/product/B077N6HFCX/) (for receive (RX), transmit (TX), and ground (GND)) to connect the serial cable to the Infineon MyIoT Adapter board. 

Before you begin, you must configure AWS IoT and your FreeRTOS download to connect your device to the AWS Cloud. For instructions, see [Option \$12: onboard private key generation](dev-mode-key-provisioning.md#dev-mode-key-provisioning-option2). In this tutorial, the path to the FreeRTOS download directory is referred to as `freertos`.

## Overview
<a name="getting_started_infineon_trust_x_overview"></a>

This tutorial contains the following steps:

1. Install software on the host machine to develop and debug embedded applications for your microcontroller board.

1. Cross-compile a FreeRTOS demo application to a binary image.

1. Load the application binary image to your board, and then run the application.

1. For monitoring and debugging purposes, interact with the application running on your board across a serial connection.

## Set up your development environment
<a name="infineon_trust_x_setup_env"></a>

FreeRTOS uses Infineon's DAVE development environment to program the XMC4800. Before you begin, download and install DAVE and some J-Link drivers to communicate with the on-board debugger.

### Install DAVE
<a name="infineon_trust_x_install_dave"></a>

1. Go to Infineon's [DAVE software download](https://infineoncommunity.com/dave-download_ID645) page.

1. Choose the DAVE package for your operating system and submit your registration information. After you register, you should receive a confirmation email with a link to download a .zip file.

1. Download the DAVE package .zip file (`DAVE_version_os_date.zip`), and unzip it to the location where you want to install DAVE (for example, `C:\DAVE4`).
**Note**  
Some Windows users have reported problems using Windows Explorer to unzip the file. We recommend that you use a third-party program such as 7-Zip.

1. To launch DAVE, run the executable file found in the unzipped `DAVE_version_os_date.zip` folder.

For more information, see the [DAVE Quick Start Guide](https://www.infineon.com/dgdl/Infineon-DAVE_Quick_Start-GS-v02_00-EN.pdf?fileId=5546d4624cb7f111014d059f7b8c712d). 

### Install Segger J-Link drivers
<a name="infineon_trust_x_install_jlink"></a>

To communicate with the XMC4800 IoT Connectivity kit's on-board debugging probe, you need the drivers included in the J-Link Software and Documentation pack. You can download the J-Link Software and Documentation pack from Segger's [J-Link software download](https://www.segger.com/downloads/jlink/#J-LinkSoftwareAndDocumentationPack) page.

## Establish a serial connection
<a name="infineon_trust_x_install_serial_connection"></a>

Connect the USB/Serial converter cable to the Infineon Shield2Go Adapter. This allows your board to send logging and debugging information in a form that you can view on your development machine. To set up a serial connection:

1. Connect the RX pin to your USB/Serial converter's TX pin.

1. Connect the TX pin to your USB/Serial converter's RX pin.

1. Connect your serial converter's ground pin to one of the GND pins on your board. The devices must share a common ground.

Power is supplied from the USB debugging port, so do not connect your serial adapter's positive voltage pin to the board.

**Note**  
Some serial cables use a 5V signaling level. The XMC4800 board and the Wi-Fi Click module require a 3.3V. Do not use the board's IOREF jumper to change the board's signals to 5V.

 With the cable connected, you can open a serial connection on a terminal emulator such as [GNU Screen](https://www.gnu.org/software/screen/). The baud rate is set to 115200 by default with 8 data bits, no parity, and 1 stop bit. 

## Monitoring MQTT messages on the cloud
<a name="infineon_trust_x_monitoring"></a>

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](https://console.aws.amazon.com/iotv2/).

1. In the navigation pane, choose **Test**, then choose **MQTT test client** to open the MQTT client.

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

When the demo project successfully runs on your device you see "Hello World\$1" sent multiple times to the topic that you subscribed to.

## Build and run the FreeRTOS demo project
<a name="infineon_trust_x_build_and_run_example"></a>

### Import the FreeRTOS demo into DAVE
<a name="infineon_trust_x_freertos_import-project"></a><a name="infineon_trust_x_load_project"></a>

1. Start DAVE.

1. In DAVE, choose **File**, and then choose **Import**. Expand the **Infineon** folder, choose **DAVE Project**, and then choose **Next**.

1. In the **Import DAVE Projects** window, choose **Select Root Directory**, choose **Browse**, and then choose the XMC4800 demo project.

   In the directory where you unzipped your FreeRTOS download, the demo project is located in `projects/infineon/xmc4800_plus_optiga_trust_x/dave4/aws_demos/dave4`.

   Make sure that **Copy Projects Into Workspace** is cleared.

1. Choose **Finish**.

   The `aws_demos` project should be imported into your workspace and activated.

1. From the **Project** menu, choose **Build Active Project**.

   Make sure that the project builds without errors.

### Run the FreeRTOS demo project
<a name="infineon_trust_x_run_examples"></a>

1. From the **Project** menu, choose **Rebuild Active Project** to rebuild `aws_demos` and confirm that your configuration changes are picked up.

1. From **Project Explorer**, right-click `aws_demos`, choose **Debug As**, and then choose **DAVE C/C\$1\$1 Application**.

1. Double-click **GDB SEGGER J-Link Debugging** to create a debug confirmation. Choose **Debug**.

1. When the debugger stops at the breakpoint in `main()`, from the **Run** menu, choose **Resume**.

At this point, continue with the public key extraction step in [Option \$12: onboard private key generation](dev-mode-key-provisioning.md#dev-mode-key-provisioning-option2). After all steps are complete, go to the AWS IoT console. The MQTT client you set up previously should display the MQTT messages sent by your device. Through the device's serial connection, you should see something like this on the UART output:

```
0 0 [Tmr Svc] Starting key provisioning...
1 1 [Tmr Svc] Write root certificate...
2 4 [Tmr Svc] Write device private key...
3 82 [Tmr Svc] Write device certificate...
4 86 [Tmr Svc] Key provisioning done...
5 291 [Tmr Svc] Wi-Fi module initialized. Connecting to AP...
.6 8046 [Tmr Svc] Wi-Fi Connected to AP. Creating tasks which use network...
7 8058 [Tmr Svc] IP Address acquired [IP Address]
8 8058 [Tmr Svc] Creating MQTT Echo Task...
9 8059 [MQTTEcho] MQTT echo attempting to connect to [MQTT Broker].
...10 23010 [MQTTEcho] MQTT echo connected.
11 23010 [MQTTEcho] MQTT echo test echoing task created.
.12 26011 [MQTTEcho] MQTT Echo demo subscribed to iotdemo/#
13 29012 [MQTTEcho] Echo successfully published 'Hello World 0'
.14 32096 [Echoing] Message returned with ACK: 'Hello World 0 ACK'
.15 37013 [MQTTEcho] Echo successfully published 'Hello World 1'
16 40080 [Echoing] Message returned with ACK: 'Hello World 1 ACK'
.17 45014 [MQTTEcho] Echo successfully published 'Hello World 2'
.18 48091 [Echoing] Message returned with ACK: 'Hello World 2 ACK'
.19 53015 [MQTTEcho] Echo successfully published 'Hello World 3'
.20 56087 [Echoing] Message returned with ACK: 'Hello World 3 ACK'
.21 61016 [MQTTEcho] Echo successfully published 'Hello World 4'
22 64083 [Echoing] Message returned with ACK: 'Hello World 4 ACK'
.23 69017 [MQTTEcho] Echo successfully published 'Hello World 5'
.24 72091 [Echoing] Message returned with ACK: 'Hello World 5 ACK'
.25 77018 [MQTTEcho] Echo successfully published 'Hello World 6'
26 80085 [Echoing] Message returned with ACK: 'Hello World 6 ACK'
.27 85019 [MQTTEcho] Echo successfully published 'Hello World 7'
.28 88086 [Echoing] Message returned with ACK: 'Hello World 7 ACK'
.29 93020 [MQTTEcho] Echo successfully published 'Hello World 8'
.30 96088 [Echoing] Message returned with ACK: 'Hello World 8 ACK'
.31 101021 [MQTTEcho] Echo successfully published 'Hello World 9'
32 104102 [Echoing] Message returned with ACK: 'Hello World 9 ACK'
.33 109022 [MQTTEcho] Echo successfully published 'Hello World 10'
.34 112047 [Echoing] Message returned with ACK: 'Hello World 10 ACK'
.35 117023 [MQTTEcho] Echo successfully published 'Hello World 11'
36 120089 [Echoing] Message returned with ACK: 'Hello World 11 ACK'
.37 122068 [MQTTEcho] MQTT echo demo finished.
38 122068 [MQTTEcho] ----Demo finished----
```

#### Build the FreeRTOS demo with CMake
<a name="infineon_trust_x_cmake"></a>

This section covers using CMake on Windows with MingW as the native build system. For more information about using CMake with other operating systems and options, see [Using CMake with FreeRTOS](getting-started-cmake.md). ([MinGW ](https://sourceforge.net/projects/mingw-w64/files/) is a minimalist development environment for native Microsoft Windows applications.)

If you prefer not to use an IDE for FreeRTOS development, you can use CMake to build and run the demo applications or applications that you have developed using third-party code editors and debugging tools.

**To build the FreeRTOS demo with CMake**

1. Set up the GNU Arm Embedded Toolchain.

   1. Download a Windows version of the toolchain from the [ Arm Embedded Toolchain download page](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads). 
**Note**  
Due to [a bug reported](https://bugs.launchpad.net/gcc-arm-embedded/+bug/1810274) in the objcopy utility, we recommend that you download a version other than "8-2018-q4-major."

   1. Open the downloaded toolchain installer, and follow the instructions in the wizard.

   1. On the final page of the installation wizard, select **Add path to environment variable** to add the toolchain path to the system path environment variable.

1. Install CMake and MingW.

   For instructions, see [CMake Prerequisites](getting-started-cmake.md#building-cmake-prereqs).

1. Create a folder to contain the generated build files (*build-folder*). 

1. Change directories to your FreeRTOS download directory (`freertos`), and use the following command to generate the build files:

   ```
   cmake -DVENDOR=infineon -DBOARD=xmc4800_plus_optiga_trust_x -DCOMPILER=arm-gcc -S . -B build-folder -G "MinGW Makefiles" -DAFR_ENABLE_TESTS=0
   ```

1. Change directories to the build directory (*build-folder*), and use the following command to build the binary:

   ```
   cmake --build . --parallel 8
   ```

   This command builds the output binary `aws_demos.hex` to the build directory.

1. Flash and run the image with [JLINK](getting_started_infineon.md#install-jlink).

   1. From the build directory (*build-folder*), use the following commands to create a flash script:

      ```
      echo loadfile aws_demos.hex > flash.jlink
      echo r >> flash.jlink
      echo g >> flash.jlink
      echo q >> flash.jlink
      ```

   1. Flash the image using the JLNIK executable.

      ```
      JLINK_PATH\JLink.exe  -device XMC4800-2048 -if SWD -speed auto -CommanderScript flash.jlink
      ```

      The application logs should be visible through [the serial connection](getting_started_infineon.md#install-serial-connection) that you established with the board. Continue to the public key extraction step in [Option \$12: onboard private key generation](dev-mode-key-provisioning.md#dev-mode-key-provisioning-option2). After all the steps are complete, go to the AWS IoT console. The MQTT client you set up previously should display the MQTT messages sent by your device. 

### Troubleshooting
<a name="infineon_trust_x_troubleshooting"></a>

For general troubleshooting information, see [Troubleshooting getting started](gsg-troubleshooting.md).

# Getting started with the MW32x AWS IoT Starter Kit
<a name="getting_started_mw32x"></a>

**Important**  <a name="deprecation-message"></a>
This reference integration is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).

The AWS IoT Starter Kit is a development kit based on the 88MW320/88MW322, the latest integrated Cortex M4 Microcontroller from NXP, that integrates 802.11b/g/n Wi-Fi on a single microcontroller chip. The development kit is FCC certified. For more information, see the [AWS Partner Device Catalog](https://devices.amazonaws.com/detail/a3G0h000000OaRnEAK/MW320-AWS-IoT-Starter-Kit) to purchase one from our partner. The 88MW320/88MW322 modules are also FCC certified and available for customization and volume sale.

This getting started guide shows you how to cross compile your application together with the SDK on a host computer, then load the generated binary file onto the board using the tools provided with the SDK. When the application starts running on the board, you can debug or interact with it from the Serial console on your host computer.

Ubuntu 16.04 is the host platform supported for development and debugging. You might be able to use other platforms, but these are not officially supported. You must have permissions to install software on the host platform. The following external tools required to build the SDK:
+ Ubuntu 16.04 host platform
+ ARM toolchain version 4\$19\$12015q3
+ Eclipse 4.9.0 IDE

The ARM toolchain is required to cross compile your application and the SDK. The SDK takes advantage of the latest versions of the toolchain to optimize the image footprint and fit more functionality into less space. This guide assumes that you're using version 4\$19\$12015q3 of the toolchain. Using older versions of the toolchain isn't recommended. The development kit is pre-flashed with Wireless Microcontroller Demo project firmware.

**Topics**
+ [Setting up your hardware](#gsg-mw32x-hardware)
+ [Setting up the development environment](#gsg-mw32x-dev-env)
+ [Build and run the FreeRTOS demo project](#gsg-mw32x-build-and-run)
+ [Debugging](#gsg-mw32x-debugging)
+ [Troubleshooting](#gsg-mw32x-troubleshooting)

## Setting up your hardware
<a name="gsg-mw32x-hardware"></a>

Connect the MW32x board to your laptop by using a mini-USB to USB cable. Connect the mini-USB cable to the only mini-USB connector present on the board. You don't need a jumper change. 

If the board is connected to a laptop or desktop computer, you don't need an external power supply.

This USB connection provides the following:
+ Console access to the board. A virtual tty/com port is registered with the development host that can be used to access the console.
+ JTAG access to the board. This can be used to load or unload firmware images into the RAM or flash of the board, or for debugging purposes.

## Setting up the development environment
<a name="gsg-mw32x-dev-env"></a>

For development purposes, the minimum requirement is the ARM toolchain and the tools bundled with the SDK. The following sections provide details on the ARM toolchain setup. 

### GNU Toolchain
<a name="gsg-mw32x-dev-env-gnu"></a>

The SDK officially supports the GCC Compiler toolchain. The cross-compiler toolchain for GNU ARM is available at [GNU Arm Embedded Toolchain 4.9-2015-q3-update](https://launchpad.net/gcc-arm-embedded/4.9/4.9-2015-q3-update).

The build system is configured to use the GNU toolchain by default. The Makefiles assume that the GNU compiler toolchain binaries are available on the user's PATH and can be invoked from the Makefiles. The Makefiles also assume that the file names of the GNU toolchain binaries are prefixed with `arm-none-eabi-`.

The GCC toolchain can be used with GDB to debug with OpenOCD (bundled with the SDK). This provides the software that interfaces with JTAG.

We recommend version 4\$19\$12015q3 of the gcc-arm-embedded toolchain.

### Linux Toolchain Setup Procedure
<a name="gsg-mw32x-dev-env-linux"></a>

Follow these steps to set up the GCC toolchain in Linux.

1. Download the toolchain tarball available at [GNU Arm Embedded Toolchain 4.9-2015-q3-update](https://launchpad.net/gcc-arm-embedded/4.9/4.9-2015-q3-update). The file is `gcc-arm-none-eabi-4_9-2015q3-20150921-linux.tar.bz2`.

1. Copy the file to a directory of your choice. Make sure there are no spaces in the directory name.

1. Use the following command to untar the file.

   ```
   tar –vxf filename
   ```

1. Add the path of the installed toolchain to the system PATH. For example, append the following line at the end of the `.profile` file located in `/home/user-name` directory.

   ```
   PATH=$PATH:path to gcc-arm-none-eabit-4_9_2015_q3/bin
   ```

**Note**  
Newer distributions of Ubuntu might come with a Debian version of the GCC Cross Compiler. If so, you must remove the native Cross Compiler and follow the above setup procedure.

### Working with a Linux development host
<a name="gsg-mw32x-dev-env-linux-host"></a>

Any modern Linux desktop distribution such as Ubuntu or Fedora can be used. However, we recommend that you upgrade to the most recent release. The following steps have been verified to work on Ubuntu 16.04 and assume that you're using that version.

#### Installing Packages
<a name="gsg-mw32x-dev-env-linux-host-pkgs"></a>

The SDK includes a script to enable quick setup of your development environment on a newly setup Linux machine. The script attempts to auto detect the machine type and install the appropriate software, including C libraries, USB library, FTDI library, ncurses, python, and latex. In this section, the generic directory name `amzsdk_bundle-x.y.z` indicates the AWS SDK root directory. The actual directory name might be different. You must have root privileges.
+ Navigate to the `amzsdk_bundle-x.y.z/` directory and run this command.

  ```
  ./lib/third_party/mcu_vendor/marvell/WMSDK/mw320/sdk/tools/bin/installpkgs.sh
  ```

#### Avoiding sudo
<a name="gsg-mw32x-dev-env-linux-host-sudo"></a>

In this guide, the `flashprog` operation uses the `flashprog.py` script to flash the NAND of the board, as explained below. Similarly, the `ramload` operation uses the `ramload.py` script to copy the firmware image from the host directly to the RAM of the microcontroller, without flashing the NAND.

You can configure your Linux development host to perform the `flashprog` and `ramload` operations without requiring the `sudo` command each time. To do this, run the following command.

```
./lib/third_party/mcu_vendor/marvell/WMSDK/mw320/sdk/tools/bin/perm_fix.sh
```

**Note**  
You must configure your Linux development host permissions in this way to ensure a smooth Eclipse IDE experience.

#### Setting up the Serial Console
<a name="gsg-mw32x-dev-env-linux-host-serial"></a>

Insert the USB cable into the Linux host USB slot. This triggers the detection of the device. You should see messages like the following in the `/var/log/messages` file, or after executing the `dmesg` command.

```
Jan 6 20:00:51 localhost kernel: usb 4-2: new full speed USB device using uhci_hcd and address 127
Jan 6 20:00:51 localhost kernel: usb 4-2: configuration #1 chosen from 1 choice
Jan 6 20:00:51 localhost kernel: ftdi_sio 4-2:1.0: FTDI USB Serial Device converter detected
Jan 6 20:00:51 localhost kernel: ftdi_sio: Detected FT2232C
Jan 6 20:00:51 localhost kernel: usb 4-2: FTDI USB Serial Device converter now attached to ttyUSB0
Jan 6 20:00:51 localhost kernel: ftdi_sio 4-2:1.1: FTDI USB Serial Device converter detected
Jan 6 20:00:51 localhost kernel: ftdi_sio: Detected FT2232C
Jan 6 20:00:51 localhost kernel: usb 4-2: FTDI USB Serial Device converter now attached to ttyUSB1
```

Verify that two ttyUSB devices have been created. The second ttyUSB is the serial console. In the example above, this is named "ttyUSB1". 

In this guide, we use minicom to see the serial console output. You might also use other serial programs such as `putty`. Run the following command to execute minicom in setup mode.

```
minicom –s
```

In minicom, navigate to **Serial Port Setup** and capture the following settings.

```
| A - Serial Device : /dev/ttyUSB1
| B – Lockfile Location : /var/lock
| C - Callin Program :
| D - Callout Program :
| E - Bps/Par/Bits : 115200 8N1
| F – Hardware Flow Control : No
| G – Software Flow Control : No
```

You can save these settings in minicom for future use. The minicom window now shows messages from the serial console.

Choose the serial console window and press the **Enter** key. This displays a hash (\$1) on the screen. 

**Note**  
The development boards include an FTDI silicon device. The FTDI device exposes two USB interfaces for the host. The first interface is associated with the JTAG functionality of the MCU and the second interface is associated with the physical UARTx port of the MCU.

#### Installing OpenOCD
<a name="gsg-mw32x-dev-env-linux-host-openocd"></a>

OpenOCD is software that provides debugging, in-system programming, and boundary-scan testing for embedded target devices.

OpenOCD version 0.9 is required. It's also required for Eclipse functionality. If an earlier version, such as version 0.7, was installed on your Linux host, remove that repository with the appropriate command for the Linux distribution that you're currently using.

Run the standard Linux command to install OpenOCD,

```
apt-get install openocd
```

If the above command doesn't install version 0.9 or later, use the following procedure to download and compile the openocd source code.

**To install OpenOCD**

1. Run the following command to install libusb-1.0.

   ```
   sudo apt-get install libusb-1.0 
   ```

1. Download the openocd 0.9.0 source code from [http://openocd.org/](http://openocd.org/).

1. Extract openocd and navigate to the directory where you extracted it.

1. Configure openocd with the following command.

   ```
   ./configure --enable-ftdi --enable-jlink
   ```

1. Run the make utility to compile opencd.

   ```
   make install
   ```

### Setting up Eclipse
<a name="gsg-mw32x-eclipse"></a>

**Note**  
This section assumes that you have completed the steps in [Avoiding sudo](#gsg-mw32x-dev-env-linux-host-sudo)

Eclipse is the preferred IDE for application development and debugging. It provides a rich, user-friendly IDE with integrated debugging support, including thread aware debugging. This section describes the common Eclipse setup for all the development hosts that are supported.

**To set up Eclipse**

1. Download and install the Java Run Time Environment (JRE).

   Eclipse requires that you install the JRE. We recommend that you install this first, although it can be installed after you install Eclipse. The JRE version (32/64 bit) must match the version of Eclipse (32/64 bit). You can download the JRE from [Java SE Runtime Environment 8 Downloads](http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html) on the Oracle website.

1. Download and install the "Eclipse IDE for C/C\$1\$1 Developers" from [http://www.eclipse.org](http://www.eclipse.org). Eclipse version 4.9.0 or later is supported. The installation only requires you to extract the downloaded archive. You run the platform-specific Eclipse executable to start the application. 

## Build and run the FreeRTOS demo project
<a name="gsg-mw32x-build-and-run"></a>

There are two ways to run the FreeRTOS demo project:
+ Use the command line.
+ Use the Eclipse IDE.

This topic covers both options.

**Provisioning**
+ Depending on whether you use the test or demo application, set the provisioning data in one of the following files:
  + `./tests/common/include/aws_clientcredential.h` 
  + `./demos/common/include/aws_clientcredential.h` 

  For example:

  ```
  #define clientcredentialWIFI_SSID "Wi-Fi SSID"
  #define clientcredentialWIFI_PASSWORD "Wi-Fi password"
  #define clientcredentialWIFI_SECURITY "Wi-Fi security"
  ```
**Note**  
You can enter the following Wi-Fi security values:   
`eWiFiSecurityOpen`
`eWiFiSecurityWEP`
`eWiFiSecurityWPA`
`eWiFiSecurityWPA2`
The SSID and password should be enclosed in double quotes.

**Build and run the FreeRTOS demo using the command line**

1. Use the following command to start building the demo application.

   ```
   cmake -DVENDOR=marvell -DBOARD=mw320 -DCOMPILER=arm-gcc -S .  -Bbuild -DAFR_ENABLE_TESTS=0
   ```

   Make sure you get the same output as shown in the following example.  
![\[Command terminal output showing FreeRTOS build configuration details for a Marvell mw300_rd wireless microcontroller board.\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/mw32x-build-demo-app1.png)

1. Navigate to the build directory.

   ```
   cd build
   ```

1. Run the make utility to build the application.

   ```
   make all -j4
   ```

   Make sure you get the same output as shown in the following figure:   
![\[Terminal output showing the build process of C object files and linking into a static library and executable for AWS demos.\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/mw32x-build-demo-app2.png)

1. Use the following commands to build a test application.

   ```
   cmake -DVENDOR=marvell -DBOARD=mw320 -DCOMPILER=arm-gcc -S .  -Bbuild -DAFR_ENABLE_TESTS=1
   cd build
   make all -j4
   ```

   Run the `cmake` command every time you switch between the `aws_demos project` and the `aws_tests project`.

1. Write the firmware image to the flash of the development board. The firmware will execute after the development board is reset. You must build the SDK before you flash the image to the microcontroller.

   1. Before you flash the firmware image, prepare the development board's flash with the common components Layout and Boot2. Use the following commands.

      ```
      cd amzsdk_bundle-x.y.z
      ./vendors/marvell/WMSDK/mw320/sdk/tools/OpenOCD/flashprog.py -l ./vendors/marvell/WMSDK/mw320/sdk/tools/OpenOCD/mw300/layout.txt --boot2 ./vendors/marvell/WMSDK/mw320/boot2/bin/boot2.bin
      ```

      The `flashprog` command initiates the following:
      + Layout – The flashprog utility is first instructed to write a layout to the flash. The layout is similar to partition information for the flash. The default layout is located at `/lib/third_party/mcu_vendor/marvell/WMSDK/mw320/sdk/tools/OpenOCD/mw300/layout.txt`. 
      + Boot2 – This is the boot-loader used by the WMSDK. The `flashprog` command also writes a bootloader to the flash. It's the bootloader's job to load the microcontroller's firmware image after it's flashed. Make sure you get the same output as shown in the figure below.   
![\[Output of the command to flash Layout and boot2 elements.\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/mw32x-output-flash-layout.png)

   1. The firmware uses the Wi-Fi chipset for its functionality, and the Wi-Fi chipset has its own firmware that must also be present in the flash. You use the `flashprog.py` utility to flash the Wi-Fi firmware in the same way that you did to flash the Boot2 boot-loader and the MCU firmware. Use the following commands to flash the Wi-Fi firmware.

      ```
      cd amzsdk_bundle-x.y.z
      ./vendors/marvell/WMSDK/mw320/sdk/tools/OpenOCD/flashprog.py --wififw ./vendors/marvell/WMSDK/mw320/wifi-firmware/mw30x/mw30x_uapsta_W14.88.36.p135.bin
      ```

      Make sure the output of the command is similar to the figure below.  
![\[Flashing the Wi-Fi firmware\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/mw32x-flash-wifi-firmware.png)

   1.  Use the following commands to flash the MCU firmware.

      ```
      cd amzsdk_bundle-x.y.z 
      ./vendors/marvell/WMSDK/mw320/sdk/tools/OpenOCD/flashprog.py --mcufw build/cmake/vendors/marvell/mw300_rd/aws_demos.bin -r
      ```

   1. Reset the board. You should see the logs for the demo app.

   1. To run the test app, flash the `aws_tests.bin` binary located at the same directory.

      ```
      cd amzsdk_bundle-x.y.z
      ./vendors/marvell/WMSDK/mw320/sdk/tools/OpenOCD/flashprog.py --mcufw build/cmake/vendors/marvell/mw300_rd/aws_tests.bin -r
      ```

      Your command output should be similar to the one shown in the figure below.  
![\[Flashing the MCU Firmware\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/mw32x-flash-mcu-firmware.png)

1. After you flash the firmware and reset the board, the demo app should start as shown in the figure below.  
![\[Demo App Start\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/mw32x-demo-app-start.png)

1. (Optional) As an alternative method to test your image, use the flashprog utility to copy the microcontroller image from the host directly into the microcontroller RAM. The image isn't copied in the flash, so it will be lost after you reboot the microcontroller.

   Loading the firmware image into the SRAM is a faster operation because it launches the execution file immediately. This method is used primarily for iterative development.

   Use the following commands to load the firmware into the SRAM.

   ```
   cd amzsdk_bundle-x.y.z
   ./lib/third_party/mcu_vendor/marvell/WMSDK/mw320/sdk/tools/OpenOCD/ramload.py build/cmake/vendors/marvell/mw300_rd/aws_demos.axf
   ```

   The command output is shown in the figure below.  
![\[Loading the firmware image into the SRAM\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/mw32x-load-firmware-sram.png)

   When the command execution is complete, you should see the logs of the demo app.

**Build and run the FreeRTOS demo using the Eclipse IDE**

1. Before you set up an Eclipse workspace, you must run the `cmake` command.

   Run the following command to work with the `aws_demos` Eclipse project.

   ```
   cmake -DVENDOR=marvell -DBOARD=mw320 -DCOMPILER=arm-gcc -S .  -Bbuild -DAFR_ENABLE_TESTS=0
   ```

   Run the following command to work with the `aws_tests` Eclipse project.

   ```
   cmake -DVENDOR=marvell -DBOARD=mw320 -DCOMPILER=arm-gcc -S .  -Bbuild -DAFR_ENABLE_TESTS=1
   ```
**Tip**  
Run the `cmake` command every time you switch between the `aws_demos` project and the `aws_tests` project.

1. Open Eclipse and, when prompted, choose your Eclipse workspace as shown in the figure below.  
![\[Selecting the Eclipse workspace\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/mw32x-select-eclipse-workspace.png)

1. Choose the option to create a **Makefile Project: with Existing Code** as shown in the figure below.  
![\[Creating a Makefile project with existing code\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/mw32x-create-makefile-project.png)

1. Choose **Browse**, specify the directory of the existing code, and then choose **Finish**.  
![\[Browsing to locate the existing code\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/mw32x-locate-existing-code.png)

1. In the navigation pane, choose **aws\$1demos** in the project explorer. Right-click **aws\$1demos** to open the menu, then choose **Build**.  
![\[Building the aws_demos project\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/mw32x-building-aws_demos.png)

   If the build succeeds, it generates the `build/cmake/vendors/marvell/mw300_rd/aws_demos.bin` file.

1. Use the command line tools to flash the Layout file (`layout.txt`), the Boot2 binary (`boot2.bin`), the MCU firmware binary (`aws_demos.bin`), and the Wi-Fi firmware.

   1. Before you flash the firmware image, prepare the development board's flash with the common components, Layout and Boot2. Use the following commands.

      ```
      cd amzsdk_bundle-x.y.z
      ./vendors/marvell/WMSDK/mw320/sdk/tools/OpenOCD/flashprog.py -l ./vendors/marvell/WMSDK/mw320/sdk/tools/OpenOCD/mw300/layout.txt --boot2 ./vendors/marvell/WMSDK/mw320/boot2/bin/boot2.bin
      ```

      The `flashprog` command initiates the following:
      + Layout – The flashprog utility is first instructed to write a layout to the flash. The layout is similar to partition information for the flash. The default layout is located at `/lib/third_party/mcu_vendor/marvell/WMSDK/mw320/sdk/tools/OpenOCD/mw300/layout.txt`. 
      + Boot2 – This is the boot-loader used by the WMSDK. The flashprog command also writes a bootloader to the flash. It is the bootloader's job to load the microcontroller's firmware image after it is flashed. Make sure you get the same output as shown in the figure below.   
![\[Output of the command to flash Layout and boot2 elements\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/mw32x-output-flash-layout.png)

   1. The firmware uses the Wi-Fi chipset for its functionality, and the Wi-Fi chipset has its own firmware that must also be present in the flash. You use the `flashprog.py` utility to flash the Wi-Fi firmware in the same way that you did to flash the boot2 boot-loader and the MCU firmware. Use the following commands to flash the Wi-Fi firmware.

      ```
      cd amzsdk_bundle-x.y.z
      ./vendors/marvell/WMSDK/mw320/sdk/tools/OpenOCD/flashprog.py --wififw ./vendors/marvell/WMSDK/mw320/wifi-firmware/mw30x/mw30x_uapsta_W14.88.36.p135.bin
      ```

      Make sure the output of the command is similar to the figure below.  
![\[Flashing the Wi-Fi firmware\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/mw32x-flash-wifi-firmware.png)

   1.  Use the following commands to flash the MCU firmware.

      ```
      cd amzsdk_bundle-x.y.z
      ./vendors/marvell/WMSDK/mw320/sdk/tools/OpenOCD/flashprog.py --mcufw build/cmake/vendors/marvell/mw300_rd/aws_demos.bin -r
      ```

   1. Reset the board. You should see the logs for the demo app.

   1. To run the test app, flash the `aws_tests.bin` binary located at the same directory.

      ```
      cd amzsdk_bundle-x.y.z
      ./vendors/marvell/WMSDK/mw320/sdk/tools/OpenOCD/flashprog.py --mcufw build/cmake/vendors/marvell/mw300_rd/aws_tests.bin -r
      ```

      Your command output should be similar to the one shown in the figure below.  
![\[Flashing the MCU Firmware\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/mw32x-flash-mcu-firmware.png)

## Debugging
<a name="gsg-mw32x-debugging"></a>
+ Start Eclipse and choose **Help** and then choose **Install new software**. In the **Work with** menu, choose **All Available Sites**. Enter the filter text `GDB Hardware`. Select the **C/C\$1\$1 GDB Hardware Debugging** option and install the plugin.  
![\[Screenshot of Install window in software interface, showing GDB Hardware Debugging item selected for installation under gdb hardware category.\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/mw32x-debugging.png)

## Troubleshooting
<a name="gsg-mw32x-troubleshooting"></a>

**Network issues**  
Check your network credentials. See "Provisioning" in [Build and run the FreeRTOS demo project](#gsg-mw32x-build-and-run).

**Enabling additional logs**  
+ Enable board specific logs.

  Enable calls to `wmstdio_init(UART0_ID, 0)` in the function `prvMiscInitialization` in the `main.c` file for tests or demos.
+ Enabling Wi-Fi logs

  Enable the macro `CONFIG_WLCMGR_DEBUG` in the `freertos/vendors/marvell/WMSDK/mw320/sdk/src/incl/autoconf.h` file. 

**Using GDB**  
We recommend that you use the `arm-none-eabi-gdb` and `gdb` command files packaged along with the SDK. Navigate to the directory.  

```
cd freertos/lib/third_party/mcu_vendor/marvell/WMSDK/mw320
```
Run the following command (on a single line) to connect to GDB.  

```
arm-none-eabi-gdb -x ./sdk/tools/OpenOCD/gdbinit ../../../../../../build/cmake/vendors/marvell/mw300 _rd/aws_demos.axf
```

# Getting started with the MediaTek MT7697Hx development kit
<a name="getting_started_mediatek"></a>

**Important**  <a name="deprecation-message"></a>
This reference integration is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).

This tutorial provides instructions for getting started with the MediaTek MT7697Hx Development Kit. If you do not have the MediaTek MT7697Hx Development Kit, visit the AWS Partner Device Catalog to purchase one from our [ partner](https://devices.amazonaws.com/detail/a3G0L00000AAOmPUAX/MT7697Hx-Development-Kit).

Before you begin, you must configure AWS IoT and your FreeRTOS download to connect your device to the AWS Cloud. See [First steps](freertos-prereqs.md) for instructions. In this tutorial, the path to the FreeRTOS download directory is referred to as `freertos`.

## Overview
<a name="w2aac31b9b7c25c33c11"></a>

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.

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

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

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

## Set up your development environment
<a name="mediatek-setup-env"></a>

Before you set up your environment, connect your computer to the USB port on the MediaTek MT7697Hx Development Kit.

### Download and install Keil MDK
<a name="install-keil-mdk"></a>

You can use the GUI-based Keil Microcontroller Development Kit (MDK) to configure, build, and run FreeRTOS projects on your board. Keil MDK includes the μVision IDE and the μVision Debugger.

**Note**  
Keil MDK is supported on Windows 7, Windows 8, and Windows 10 64-bit machines only.

**To download and install Keil MDK**

1. Go to the [Keil MDK Getting Started](http://www2.keil.com/mdk5/install/) page, and choose **Download MDK-Core**.

1. Enter and submit your information to register with Keil.

1. Right-click the MDK executable and save the Keil MDK installer to your computer.

1. Open the Keil MDK installer and follow the steps to completion. Make sure that you install the MediaTek device pack (MT76x7 Series).

## Establish a serial connection
<a name="mediatek-serial-connection"></a>

Connect the board to your host computer with a USB cable. A COM port appears in the Windows Device Manager. For debugging, you can open a session to the port with a terminal utility tool such as HyperTerminal or TeraTerm.

## Monitoring MQTT messages on the cloud
<a name="gsg-mediatek-monitor-mqtt"></a>

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](https://console.aws.amazon.com/iotv2/).

1. In the navigation pane, choose **Test**, then choose **MQTT test client** to open the MQTT client.

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

When the demo project successfully runs on your device you see "Hello World\$1" sent multiple times to the topic that you subscribed to.

## Build and run the FreeRTOS demo project with Keil MDK
<a name="mediatek-build-and-run-keil"></a>

**To build the FreeRTOS demo project in Keil μVision**

1. From the **Start** menu, open Keil μVision 5.

1. Open the `projects/mediatek/mt7697hx-dev-kit/uvision/aws_demos/aws_demos.uvprojx` project file.

1. From the menu, choose **Project**, and then choose **Build target**.

   After the code is built, you see the demo executable file at `projects/mediatek/mt7697hx-dev-kit/uvision/aws_demos/out/Objects/aws_demo.axf`.

**To run the FreeRTOS demo project**

1. Set the MediaTek MT7697Hx Development Kit to PROGRAM mode.

   To set the kit to PROGRAM mode, press and hold the **PROG** button. With the **PROG** button still pressed, press and release the **RESET** button, and then release the **PROG** button.

1. From the menu, choose **Flash**, and then choose **Configure Flash Tools**.

1. In **Options for Target '`aws_demo`'**, choose the **Debug** tab. Select **Use**, set the debugger to **CMSIS-DAP Debugger**, and then choose **OK**.

1. From the menu, choose **Flash**, and then choose **Download**.

   μVision notifies you when the download is complete.

1. Use a terminal utility to open the serial console window. Set the serial port to 115200 bps, none-parity, 8-bits, and 1 stop-bit.

1. Choose the **RESET** button on your MediaTek MT7697Hx Development Kit.

## Troubleshooting
<a name="mediatek-troubleshooting"></a>

### Debugging FreeRTOS projects in Keil μVision
<a name="mediatek-debugging"></a>

Currently, you must edit the MediaTek package that is included with Keil μVision before you can debug the FreeRTOS demo project for MediaTek with Keil μVision.

**To edit the MediaTek package for debugging FreeRTOS projects**

1. Find and open the `Keil_v5\ARM\PACK\.Web\MediaTek.MTx.pdsc` file in your Keil MDK installation folder.

1. Replace all instances of `flag = Read32(0x20000000);` with `flag = Read32(0x0010FBFC);`.

1. Replace all instances of `Write32(0x20000000, 0x76877697);` with `Write32(0x0010FBFC, 0x76877697);`.

**To start debugging the project**

1. From the menu, choose **Flash**, and then choose **Configure Flash Tools**.

1. Choose the **Target** tab, and then choose **Read/Write Memory Areas**. Confirm that IRAM1 and IRAM2 are both selected.

1. Choose the **Debug** tab, and then choose **CMSIS-DAP Debugger**.

1. Open `vendors/mediatek/boards/mt7697hx-dev-kit/aws_demos/application_code/main.c`, and set the macro `MTK_DEBUGGER` to `1`. 

1. Rebuild the demo project in μVision. 

1. Set the MediaTek MT7697Hx Development Kit to PROGRAM mode.

   To set the kit to PROGRAM mode, press and hold the **PROG** button. With the **PROG** button still pressed, press and release the **RESET** button, and then release the **PROG** button.

1. From the menu, choose **Flash**, and then choose **Download**. 

   μVision notifies you when the download is complete.

1. Press the **RESET** button on your MediaTek MT7697Hx Development Kit.

1. From the μVision menu, choose **Debug**, and then choose **Start/Stop Debug Session**. The **Call Stack \$1 Locals** window opens when you start the debug session. 

1. From the menu, choose **Debug**, and then choose **Stop** to pause the code execution. The program counter stops at the following line: 

   ```
   { volatile int wait_ice = 1 ; while ( wait_ice ) ; }
   ```

1. In the **Call Stack \$1 Locals** window, change the value for `wait_ice` to `0`. 

1. Set breakpoints in your project's source code, and run the code. 

### Troubleshooting the IDE debugger settings
<a name="gsg-mediatek-ts-ide"></a>

If you are having trouble debugging an application, your debugger settings might be incorrect.

**To verify that your debugger settings are correct**

1. Open Keil μVision.

1. Right-click the `aws_demos` project, choose **Options**, and under the **Utilities** tab, choose **Settings**, next to **“-- Use Debug Driver --”**.

1. Verify that the settings under the **Debug** tab appear as follows:  
![\[CMSIS-DAP Cortex-M Target Driver Setup dialog with serial number, firmware version, adapter type, SW device options, and config settings.\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/mediatek-debug-2.png)

1. Verify that the settings under the **Flash Download** tab appear as follows:  
![\[Cortex-M Target Driver Setup window with options for Download Function, RAM for Algorithm, Programming Algorithm description and device details.\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/mediatek-debug-3.png)

For general troubleshooting information about Getting Started with FreeRTOS, see [Troubleshooting getting started](gsg-troubleshooting.md).

# Getting started with the Microchip Curiosity PIC32MZ EF
<a name="getting_started_mch"></a>

**Important**  <a name="deprecation-message"></a>
This reference integration is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).

**Note**  
In agreement with Microchip, we are removing the Curiosity PIC32MZEF (DM320104) from the FreeRTOS Reference Integration repository main branch and will no longer carry it in new releases. Microchip has issued an [official notice](https://www.microchip.com/DevelopmentTools/ProductDetails/PartNO/DM320104) that the PIC32MZEF (DM320104) is no longer recommended for new designs. The PIC32MZEF projects and source code can still be accessed through the previous release tags. Microchip recommends that customers use the Curiosity [ PIC32MZ-EF-2.0 Development board (DM320209)](https://devices.amazonaws.com/detail/a3G0h0000077I69EAE/Curiosity-PIC32MZ-EF-2-0-Development-Board) for new designs. The PIC32MZv1 platform can still be found in [v202012.00](https://github.com/aws/amazon-freertos/tree/202012.00) of the FreeRTOS Reference Integration repository. However, the platform is no longer supported by [v202107.00](https://github.com/aws/amazon-freertos/tree/202107.00) of the FreeRTOS Reference.

This tutorial provides instructions for getting started with the Microchip Curiosity PIC32MZ EF. If you do not have the Microchip Curiosity PIC32MZ EF bundle, visit the AWS Partner Device Catalog to purchase one from our [ partner](https://devices.amazonaws.com/detail/a3G0L00000AANscUAH/Curiosity-PIC32MZ-EF-Amazon-FreeRTOS-Bundle).

The bundle includes the following items:
+ [Curiosity PIC32MZ EF Development Board](https://www.microchip.com/Developmenttools/ProductDetails/DM320104)
+ [MikroElectronika USB UART click Board](https://www.mikroe.com/usb-uart-click)
+ [MikroElectronika WiFi 7 click Board](https://www.mikroe.com/wifi-7-click) 
+ [PIC32 LAN8720 PHY daughter board](http://www.microchip.com/DevelopmentTools/ProductDetails.aspx?PartNO=ac320004-3)

You also need the following items for debugging:
+ [MPLAB Snap In-Circuit Debugger](https://www.microchip.com/Developmenttools/ProductDetails/PG164100)
+ (Optional) [PICkit 3 Programming Cable Kit](https://www.microchip.com/TPROG001)

Before you begin, you must configure AWS IoT and your FreeRTOS download to connect your device to the AWS Cloud. See [First steps](freertos-prereqs.md) for instructions.

**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](https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development) 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\$1](https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-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**).

## Overview
<a name="getting_started_mch_overview"></a>

This tutorial contains instructions for the following getting started steps:

1. Connecting your board to a host machine.

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

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

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

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

## Set up the Microchip Curiosity PIC32MZ EF hardware
<a name="setup-hw-mch"></a>

1. Connect the MikroElectronika USB UART click Board to the microBUS 1 connector on the Microchip Curiosity PIC32MZ EF.

1. Connect the PIC32 LAN8720 PHY daughter board to the J18 header on the Microchip Curiosity PIC32MZ EF.

1. Connect the MikroElectronika USB UART click Board to your computer using a USB A to USB mini-B cable.

1. To connect your board to the internet, use one of the following options:
   + To use **Wi-Fi**, connect the MikroElectronika Wi-Fi 7 click Board to the microBUS 2 connector on the Microchip Curiosity PIC32MZ EF. See [Configuring the FreeRTOS demos](freertos-prereqs.md#freertos-configure).
   + To use **Ethernet** to connect the Microchip Curiosity PIC32MZ EF Board to the internet, connect the PIC32 LAN8720 PHY daughter board to the J18 header on the Microchip Curiosity PIC32MZ EF. Connect one end of an Ethernet cable to the LAN8720 PHY daughter board. Connect the other end to your router or other internet port. You must also define the preprocessor macro `PIC32_USE_ETHERNET`.

1. If not done already, solder the angle connector to the ICSP header on the Microchip Curiosity PIC32MZ EF.

1. Connect one end of the ICSP cable from the PICkit 3 Programming Cable Kit to the Microchip Curiosity PIC32MZ EF.

   If you don't have the PICkit 3 Programming Cable Kit, you can use M-F Dupont wire jumpers to wire the connection instead. Note that the white circle signifies the position of Pin 1.

1. Connect the other end of the ICSP cable (or jumpers) to the MPLAB Snap Debugger. Pin 1 of the 8-pin SIL Programming Connector is marked by the black triangle on the bottom right of the board.

   Make sure that any cabling to Pin 1 on the Microchip Curiosity PIC32MZ EF, signified by the white circle, aligns with Pin 1 on the MPLAB Snap Debugger.

   For more information about the MPLAB Snap Debugger, see the [ MPLAB Snap In-Circuit Debugger Information Sheet](http://ww1.microchip.com/downloads/en/DeviceDoc/MPLAB%20Snap%20In-Circuit%20Debugger%20IS%20DS50002787A.pdf).

## Set up the Microchip Curiosity PIC32MZ EF hardware using PICkit On Board (PKOB)
<a name="setup-env_mch-pkob"></a>

We recommend that you follow the setup procedure in the previous section. However, you can evaluate and run FreeRTOS demos with basic debugging using the integrated PICkit On Board (PKOB) programmer/debugger by following these steps.

1. Connect the MikroElectronika USB UART click Board to the microBUS 1 connector on the Microchip Curiosity PIC32MZ EF.

1. To connect your board to the internet, do one of the following:
   + To use **Wi-Fi**, connect the MikroElectronika Wi-Fi 7 click Board to the microBUS 2 connector on the Microchip Curiosity PIC32MZ EF. (Follow the steps "To configure your Wi-Fi" in [Configuring the FreeRTOS demos](freertos-prereqs.md#freertos-configure).
   + To use **Ethernet** to connect the Microchip Curiosity PIC32MZ EF Board to the internet, connect the PIC32 LAN8720 PHY daughter board to the J18 header on the Microchip Curiosity PIC32MZ EF. Connect one end of an Ethernet cable to the LAN8720 PHY daughter board. Connect the other end to your router or other internet port. You must also define the preprocessor macro `PIC32_USE_ETHERNET`.

1. Connect the USB micro-B port named "USB DEBUG" on the Microchip Curiosity PIC32MZ EF Board to your computer using a USB type A to USB micro-B cable.

1. Connect the MikroElectronika USB UART click Board to your computer using a USB A to USB mini-B cable.

## Set up your development environment
<a name="setup-env_mch"></a>

**Note**  
The FreeRTOS project for this device is based on MPLAB Harmony v2. To build the project, you need to use versions of the MPLAB tools that are compatible with Harmony v2, like v2.10 of the MPLAB XC32 Compiler and versions 2.X.X of the MPLAB Harmony Configurator (MHC).

1. Install [Python version 3.x](https://www.python.org/downloads/) or later.

1. Install the MPLAB X IDE:
**Note**  
FreeRTOS AWS Reference Integrations v202007.00 is currently supported on MPLabv5.35 only. Prior versions of FreeRTOS AWS Reference Integrations are supported on MPLabv5.40.

**MPLabv5.35 downloads**
   + [ MPLAB X Integrated Development Environment for Windows](http://ww1.microchip.com/downloads/en/DeviceDoc/MPLABX-v5.35-windows-installer.exe)
   + [ MPLAB X Integrated Development Environment for macOS](http://ww1.microchip.com/downloads/en/DeviceDoc/MPLABX-v5.35-osx-installer.dmg)
   + [ MPLAB X Integrated Development Environment for Linux](http://ww1.microchip.com/downloads/en/DeviceDoc/MPLABX-v5.35-linux-installer.tar)

**Latest MPLab downloads (MPLabv5.40)**
   + [MPLAB X Integrated Development Environment for Windows](http://www.microchip.com/mplabx-ide-windows-installer)
   + [MPLAB X Integrated Development Environment for macOS](http://www.microchip.com/mplabx-ide-osx-installer)
   + [MPLAB X Integrated Development Environment for Linux](http://www.microchip.com/mplabx-ide-linux-installer)

1. Install the MPLAB XC32 Compiler:
   + [MPLAB XC32/32\$1\$1 Compiler for Windows](http://www.microchip.com/mplabxc32windows)
   + [MPLAB XC32/32\$1\$1 Compiler for macOS](http://www.microchip.com/mplabxc32osx)
   + [MPLAB XC32/32\$1\$1 Compiler for Linux](http://www.microchip.com/mplabxc32linux)

1. Start up a UART terminal emulator and open a connection with the following settings:
   + Baud rate: 115200
   + Data: 8 bit
   + Parity: None
   + Stop bits: 1
   + Flow control: None

## Monitoring MQTT messages in the cloud
<a name="getting_started_mch_monitor_mqtt"></a>

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](https://console.aws.amazon.com/iotv2/).

1. In the navigation pane, choose **Test**, then choose **MQTT test client** to open the MQTT client.

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

When the demo project successfully runs on your device you see "Hello World\$1" sent multiple times to the topic that you subscribed to.

## Build and run the FreeRTOS demo project
<a name="mch-build-and-run-example"></a>

### Open the FreeRTOS demo in the MPLAB IDE
<a name="mch-freertos-import-project"></a><a name="mch-load-project"></a>

1. Open MPLAB IDE. If you have more than one version of the compiler installed, you need to select the compiler that you want to use from within the IDE. 

1. From the **File** menu, choose **Open Project**.

1. Browse to and open `projects/microchip/curiosity_pic32mzef/mplab/aws_demos`.

1. Choose **Open project**.

**Note**  
When you open the project for the first time, you might get an error message about the compiler. In the IDE, navigate to **Tools**, **Options**, **Embedded**, and then select the compiler that you are using for your project.

To use Ethernet to connect, you must define the preprocessor macro `PIC32_USE_ETHERNET`. 

**To use Ethernet to connect using the MPLAB IDE**

1. In the MPLAB IDE, right-click the project and choose **Properties**.

1. In the **Project Properties** dialog box, choose ***compiler-name* (Global Options)** to expand it, and then select ***compiler-name*-gcc**.

1. For **Options categories**, choose **Preprocessing and messages**, and then add the `PIC32_USE_ETHERNET` string to **Preprocessor macros**.

### Run the FreeRTOS demo project
<a name="mch-run-example"></a>

1. Rebuild your project.

1. On the **Projects** tab, right-click the `aws_demos` top-level folder, and then choose **Debug**.

1. When the debugger stops at the breakpoint in `main()`, from the **Run** menu, choose **Resume**.

### Build the FreeRTOS demo with CMake
<a name="microchip-cmake"></a>

If you prefer not to use an IDE for FreeRTOS development, you can alternatively use CMake to build and run the demo applications or applications that you have developed using third-party code editors and debugging tools.

**To build the FreeRTOS demo with CMake**

1. Create a directory to contain the generated build files, such as *build-directory*.

1. Use the following command to generate build files from source code.

   ```
   cmake -DVENDOR=microchip -DBOARD=curiosity_pic32mzef -DCOMPILER=xc32 -DMCHP_HEXMATE_PATH=path/microchip/mplabx/version/mplab_platform/bin  -DAFR_TOOLCHAIN_PATH=path/microchip/xc32/version/bin -S freertos -B build-folder
   ```
**Note**  
You must specify the correct paths to the Hexmate and toolchain binaries, such as the `C:\Program Files (x86)\Microchip\MPLABX\v5.35\mplab_platform\bin` and `C:\Program Files\Microchip\xc32\v2.40\bin` paths.

1. Change directories to the build directory (*build-directory*), and then run `make` from that directory.

For more information, see [Using CMake with FreeRTOS](getting-started-cmake.md).

To use Ethernet to connect, you must define the preprocessor macro `PIC32_USE_ETHERNET`. 

## Troubleshooting
<a name="getting_started_mch_troubleshooting"></a>

For troubleshooting information, see [Troubleshooting getting started](gsg-troubleshooting.md).

# Getting started with the Nordic nRF52840-DK
<a name="getting_started_nordic"></a>

**Important**  <a name="deprecation-message"></a>
This reference integration is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).

This tutorial provides instructions for getting started with the Nordic nRF52840-DK. If you do not have the Nordic nRF52840-DK, visit the AWS Partner Device Catalog to purchase one from our [partner](https://devices.amazonaws.com/detail/a3G0L00000AANtrUAH/nRF52840-Development-Kit).

Before you begin, you need to [Set up AWS IoT and Amazon Cognito for FreeRTOS Bluetooth Low Energy](ble-demo.md#set-up-ble-demo-aws).

To run the FreeRTOS Bluetooth Low Energy demo, you also need an iOS or Android mobile device with Bluetooth and Wi-Fi capabilities.

**Note**  
If you are using an iOS device, you need Xcode to build the demo mobile application. If you are using an Android device, you can use Android Studio to build the demo mobile application.

## Overview
<a name="getting_started_nordic-overview"></a>

This tutorial contains instructions for the following getting started steps:

1. Connecting your board to a host machine.

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

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

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

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

## Set up the Nordic hardware
<a name="nordic-setup-hardware"></a>

Connect your host computer to the USB port labeled J2, located directly above the coin cell battery holder on your Nordic nRF52840 board.

For more information about setting up the Nordic nRF52840-DK, see the [nRF52840 Development Kit User Guide](http://infocenter.nordicsemi.com/pdf/nRF52840_DK_User_Guide_v1.2.pdf).

## Set up your development environment
<a name="nordic-setup-env"></a>

### Download and install Segger Embedded Studio
<a name="install-embedded-studio"></a>

FreeRTOS supports Segger Embedded Studio as a development environment for the Nordic nRF52840-DK.

To set up your environment, you need to download and install Segger Embedded Studio on your host computer.

**To download and install Segger Embedded Studio**

1. Go to the [Segger Embedded Studio Downloads](https://www.segger.com/downloads/embedded-studio/) page, and choose the Embedded Studio for ARM option for your operating system.

1. Run the installer and follow the prompts to completion.

### Set up the FreeRTOS Bluetooth Low Energy Mobile SDK demo application
<a name="install-mobile-sdks"></a>

To run the FreeRTOS demo project across Bluetooth Low Energy, you need to run the FreeRTOS Bluetooth Low Energy Mobile SDK demo application on your mobile device.

**To set up the FreeRTOS Bluetooth Low Energy Mobile SDK Demo application**

1. Follow the instructions in [Mobile SDKs for FreeRTOS Bluetooth devices](freertos-ble-mobile.md) to download and install the SDK for your mobile platform on your host computer.

1. Follow the instructions in [FreeRTOS Bluetooth Low Energy Mobile SDK demo application](ble-demo.md#ble-sdk-app) to set up the demo mobile application on your mobile device.

## Establish a serial connection
<a name="nordic-serial-connection"></a>

Segger Embedded Studio includes a terminal emulator that you can use to receive log messages across a serial connection to your board.

**To establish a serial connection with Segger Embedded Studio**

1. Open Segger Embedded Studio.

1. From the top menu, choose **Target**, **Connect J-Link**.

1. From the top menu, choose **Tools**, **Terminal Emulator**, **Properties**, and set the properties as instructed in [Installing a terminal emulator](gsg-troubleshooting.md#uart-term).

1. From the top menu, choose **Tools**, **Terminal Emulator**, **Connect *port* (115200,N,8,1)**.

**Note**  
The Segger embedded studio terminal emulator does not support an input capability. For this, use a terminal emulator like PuTTy, Tera Term, or GNU Screen. Configure the terminal to connect to your board by a serial connection as instructed in [Installing a terminal emulator](gsg-troubleshooting.md#uart-term).

## Download and configure FreeRTOS
<a name="nordic-download-and-configure"></a>

After you set up your hardware and environment, you can download FreeRTOS.

### Download FreeRTOS
<a name="nordic-download"></a>

To download FreeRTOS for the Nordic nRF52840-DK, go to the [FreeRTOS GitHub page](https://github.com/aws/amazon-freertos) and clone the repository. See the [ README.md](https://github.com/aws/amazon-freertos/blob/main/README.md) file for instructions. 

**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 cloning or copying the repository, make sure the path you create does not 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](https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development) 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\$1](https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-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**).

### Configure your project
<a name="nordic-freertos-config-project"></a>

To enable the demo, you need to configure your project to work with AWS IoT. To configure your project to work with AWS IoT, your device must be registered as an AWS IoT thing. You should have registered your device when you [Set up AWS IoT and Amazon Cognito for FreeRTOS Bluetooth Low Energy](ble-demo.md#set-up-ble-demo-aws).

**To configure your AWS IoT endpoint**

1. Sign in to the [AWS IoT console](https://console.aws.amazon.com/iotv2/).

1. In the navigation pane, choose **Settings**.

   Your AWS IoT endpoint appears in the **Device data endpoint** text box. It should look like `1234567890123-ats.iot.us-east-1.amazonaws.com`. Make a note of this endpoint.

1. In the navigation pane, choose **Manage**, and then choose **Things**. Make a note of the AWS IoT thing name for your device. 

1. With your AWS IoT endpoint and your AWS IoT thing name on hand, open `freertos/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*

**To enable the demo**

1. Check that the Bluetooth Low Energy GATT Demo is enabled. Go to `vendors/nordic/boards/nrf52840-dk/aws_demos/config_files/iot_ble_config.h`, and add `#define IOT_BLE_ADD_CUSTOM_SERVICES ( 1 )` to the list of define statements.

1. Open `vendors/nordic/boards/nrf52840-dk/aws_demos/config_files/aws_demo_config.h`, and define either `CONFIG_OTA_MQTT_BLE_TRANSPORT_DEMO_ENABLED` or `CONFIG_OTA_HTTP_BLE_TRANSPORT_DEMO_ENABLED` as in this example.

   ```
   /* To run a particular demo you need to define one of these.
    * Only one demo can be configured at a time
    *
    *          CONFIG_BLE_GATT_SERVER_DEMO_ENABLED
    *          CONFIG_MQTT_BLE_TRANSPORT_DEMO_ENABLED
    *          CONFIG_SHADOW_BLE_TRANSPORT_DEMO_ENABLED
    *          CONFIG_OTA_MQTT_BLE_TRANSPORT_DEMO_ENABLED
    *          CONFIG_OTA_HTTP_BLE_TRANSPORT_DEMO_ENABLED
    *          CONFIG_POSIX_DEMO_ENABLED
    *
    *  These defines are used in iot_demo_runner.h for demo selection */
   
   #define CONFIG_OTA_MQTT_BLE_TRANSPORT_DEMO_ENABLED
   ```

1. Since the Nordic chip comes with very little RAM (250KB), the BLE configuration might need to be changed to allow for larger GATT table entries compared to the size of each attribute. In this way you can adjust the amount of memory the application gets. To do this, override the definitions of the following attributes in the file `freertos/vendors/nordic/boards/nrf52840-dk/aws_demos/config_files/sdk_config.h`: 
   + NRF\$1SDH\$1BLE\$1VS\$1UUID\$1COUNT

     The number of vendor-specific UUIDs. Increase this count by 1 when you add a new vendor-specific UUID.
   + NRF\$1SDH\$1BLE\$1GATTS\$1ATTR\$1TAB\$1SIZE

     Attribute Table size in bytes. The size must be a multiple of 4. This value indicates the set amount of memory dedicated for the attribute table (including the characteristic size), so this will vary from project to project. If you exceed the size of the attribute table you will get a NRF\$1ERROR\$1NO\$1MEM error. If you modify the NRF\$1SDH\$1BLE\$1GATTS\$1ATTR\$1TAB\$1SIZE usually you must also reconfigure the RAM settings.

   (For tests, the location of the file is `freertos/vendors/nordic/boards/nrf52840-dk/aws_tests/config_files/sdk_config.h`.) 

## Build and run the FreeRTOS demo project
<a name="nordic-build-and-run-example"></a>

After you download FreeRTOS and configure your demo project, you are ready to build and run the demo project on your board.

**Important**  
If this is the first time that you are running the demo on this board, you need to flash a bootloader to the board before the demo can run.  
To build and flash the bootloader, follow the steps below, but instead of using the `projects/nordic/nrf52840-dk/ses/aws_demos/aws_demos.emProject` project file, use `projects/nordic/nrf52840-dk/ses/aws_demos/bootloader/bootloader.emProject`.

**To build and run the FreeRTOS Bluetooth Low Energy demo from Segger Embedded Studio**

1. Open Segger Embedded Studio. From the top menu, choose **File**, choose **Open Solution**, and then navigate to the project file `projects/nordic/nrf52840-dk/ses/aws_demos/aws_demos.emProject`

1. If you are using the Segger Embedded Studio terminal emulator, choose **Tools** from the top menu, and then choose **Terminal Emulator**, **Terminal Emulator** to display information from your serial connection.

   If you are using another terminal tool, you can monitor that tool for output from your serial connection.

1. Right-click the `aws_demos` demo project in the **Project Explorer**, and choose **Build**.
**Note**  
If this is your first time using Segger Embedded Studio, you might see you a warning "No license for commercial use". Segger Embedded Studio can be used free of charge for Nordic Semiconductor devices. [Request a free license](http://license.segger.com/Nordic.cgi) then, during setup choose **Activate Your Free License**, and follow the instructions.

1. Choose **Debug**, and then choose **Go**.

   After the demo starts, it waits to pair with a mobile device across Bluetooth Low Energy.

1. Follow the instructions for the [MQTT over Bluetooth Low Energy Demo Application](https://docs.aws.amazon.com/freertos/latest/userguide/ble-demo.html#ble-demo-mqtt) to complete the demo with the FreeRTOS Bluetooth Low Energy Mobile SDK demo application as the mobile MQTT proxy.

## Troubleshooting
<a name="nordic-troubleshooting"></a>

For general troubleshooting information about Getting Started with FreeRTOS, see [Troubleshooting getting started](gsg-troubleshooting.md).

# Getting started with the Nuvoton NuMaker-IoT-M487
<a name="getting-started-nuvoton-m487"></a>

**Important**  <a name="deprecation-message"></a>
This reference integration is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).

This tutorial provides instructions for getting started with the Nuvoton NuMaker-IoT-M487 development board. The series microcontroller, and includes built-in RJ45 Ethernet and Wi-Fi modules. If you don't have the Nuvoton NuMaker-IoT-M487, visit the [AWS Partner Device Catalog](https://devices.amazonaws.com/detail/a3G0h000000Tg9cEAC/NuMaker-IoT-M487) to purchase one from our partner. 

Before you begin, you must configure AWS IoT and your FreeRTOS software to connect your development board to the AWS Cloud. For instructions, see [First steps](freertos-prereqs.md). In this tutorial, the path to the FreeRTOS download directory is referred to as `freertos`.

## Overview
<a name="getting-started-nuvoton-m487-overview"></a>

This tutorial guides you through the following steps:

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

1. Cross-compile a FreeRTOS demo application to a binary image.

1. Load the application binary image to your board, and then run the application.

## Set up your development environment
<a name="gsg-nuvoton-m487-setup-env"></a>

The Keil MDK Nuvoton edition is designed for developing and debugging applications for Nuvoton M487 boards. The Keil MDK v5 Essential, Plus, or Pro version should also work for the Nuvoton M487 (Cortex-M4 core) MCU. You can download the Keil MDK Nuvoton edition with a price discount for the Nuvoton Cortex-M4 series MCUs. The Keil MDK is only supported on Windows.

**To install the development tool for the NuMaker-IoT-M487**

1. Download the [ Keil MDK Nuvoton Edition](https://store.developer.arm.com/store/embedded-iot-software-tools/keil-mdk-nuvoton-edition?edition=1164) from the Keil MDK website. 

1. Install the Keil MDK on your host machine using your license. The Keil MDK includes the Keil µVision IDE, a C/C\$1\$1 compilation toolchain, and the µVision debugger.

   If you experience issues during installation, contact [Nuvoton](https://www.nuvoton.com/contact-us) for assistance.

1. Install the **Nu-Link\$1Keil\$1Driver\$1V3.06.7215r** (or latest version), which is on the [ Nuvoton Development Tool](https://www.nuvoton.com/tool-and-software/ide-and-compiler/) page.

## Build and run the FreeRTOS demo project
<a name="gsg-nuvoton-m487-build-run"></a>

**To build the FreeRTOS demo project**

1. Open the Keil µVision IDE.

1. On the **File** menu, choose **Open**. In the **Open file** dialog box, make sure the file type selector is set to **Project Files**.

1. Choose either the Wi-Fi or Ethernet demo project to build.
   + To open the Wi-Fi demo project, choose the target project `aws_demos.uvproj` in the `freertos\projects\nuvoton\numaker_iot_m487_wifi\uvision\aws_demos` directory. 
   + To open the Ethernet demo project, choose the target project `aws_demos_eth.uvproj` in the `freertos\projects\nuvoton\numaker_iot_m487_wifi\uvision\aws_demos_eth` directory. 

1. To make sure your settings are correct to flash the board, right-click the `aws_demo` project in the IDE, and then choose **Options**. (See [Troubleshooting](#gsg-nuvoton-m487-troubleshoot) for more details.)

1. On the **Utilities** tab, verify that **Use Target Driver for Flash Programming** is selected, and that **Nuvoton Nu-Link Debugger** is set as the target driver. 

1. On the **Debug** tab, next to **Nuvoton Nu-Link Debugger**, choose **Settings**.

1. Verify that the **Chip Type** is set to **M480**. 

1. In the Keil µVision IDE **Project** navigation pane, choose the `aws_demos` project. On the **Project** menu, choose **Build Target**. 

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](https://console.aws.amazon.com/iotv2).

1. In the navigation pane, choose **Test**, then choose **MQTT test client** to open the MQTT client. 

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

**To run the FreeRTOS demo project**

1. Connect your Numaker-IoT-M487 board to your host machine (computer). 

1. Rebuild the project. 

1. In the Keil µVision IDE, on the **Flash** menu, choose **Download**. 

1. On the **Debug** menu, choose **Start/Stop Debug Session**.

1. When the debugger stops at the breakpoint in `main()`, open the **Run** menu, and then choose **Run (F5)**.

   You should see MQTT messages sent by your device in the MQTT client in the AWS IoT console. 

## Using CMake with FreeRTOS
<a name="gsg-nuvoton-m487-cmake"></a>

You can also use CMake to build and run the FreeRTOS demo applications or applications you have developed using third-party code editors and debugging tools. 

Make sure you have installed the CMake build system. Follow the instructions in [Using CMake with FreeRTOS](getting-started-cmake.md), and then follow the steps in this section.

**Note**  
Be sure the path to the location of the compiler (Keil) is in your Path system variable, for example, `C:\Keil_v5\ARM\ARMCC\bin`. 

You can also 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](https://console.aws.amazon.com/iotv2).

1. In the navigation pane, choose **Test**, then choose **MQTT test client** to open the MQTT client. 

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

**To generate build files from source files and run the demo project**

1. On your host machine, open the command prompt and navigate to the *freertos* folder. 

1. Create a folder to contain the generated build file. We will refer to this folder as the *BUILD\$1FOLDER*. 

1. Generate the build files for either the Wi-Fi or Ethernet demo.
   + For Wi-Fi:

     Navigate to the directory that contains the source files for the FreeRTOS demo project. Then, generate the build files by running the following command. 

     ```
     cmake -DVENDOR=nuvoton -DBOARD=numaker_iot_m487_wifi -DCOMPILER=arm-keil -S . -B BUILD_FOLDER -G Ninja 
     ```
   + For Ethernet:

     Navigate to the directory that contains the source files for the FreeRTOS demo project. Then, generate the build files by running the following command. 

     ```
     cmake -DVENDOR=nuvoton -DBOARD=numaker_iot_m487_wifi -DCOMPILER=arm-keil -DAFR_ENABLE_ETH=1 -S . -B BUILD_FOLDER -G Ninja 
     ```

1. Generate the binary to flash onto the M487 by running the following command.

   ```
   cmake --build BUILD_FOLDER 
   ```

   At this point, the binary file `aws_demos.bin` should be in the `BUILD_FOLDER/vendors/Nuvoton/boards/numaker_iot_m487_wifi` folder. 

1. To configure the board for flashing mode, make sure the MSG switch (No.4 of ISW1 on ICE) is switched ON. When you plug in the board, a window (and drive) will be assigned. (See [Troubleshooting](#gsg-nuvoton-m487-troubleshoot).)

1. Open a terminal emulator to view the messages over UART. Follow the instructions at [Installing a terminal emulator](gsg-troubleshooting.md#uart-term).

1. Run the demo project by copying the generated binary onto the device. 

   If you subscribed to the MQTT topic with the AWS IoT MQTT client, you should see MQTT messages sent by your device in the AWS IoT console. 

## Troubleshooting
<a name="gsg-nuvoton-m487-troubleshoot"></a>
+ If your windows can’t recognize the device `VCOM`, install the NuMaker windows serial port driver from the link [Nu-Link USB Driver v1.6](https://www.nuvoton.com/export/resource-files/Nu-Link_USB_Driver_V1.6.zip).
+ If you connect your device to the Keil MDK (IDE) through Nu-Link, make sure the MSG switch (No.4 of ISW1 on ICE) is OFF, as shown.  
![\[Circuit board with SD card slot, microcontroller, pins, power and reset connectors labeled.\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/nuvoton-m487-gsg.png)

If you experience issues setting up your development environment or connecting to your board, contact [Nuvoton](http://www.nuvoton.com/contact-us/).

### Debugging FreeRTOS projects in Keil μVision
<a name="gsg-nuvoton-m487-troubleshoot-debug-projects"></a>

**To start a debug session in Keil μVision**

1. Open Keil μVision. 

1. Follow the steps to build the FreeRTOS demo project in [Build and run the FreeRTOS demo project](#gsg-nuvoton-m487-build-run).

1. On the **Debug** menu, choose **Start/Stop Debug Session**. 

   The **Call Stack \$1 Locals** window appears when you start a debug session. μVision flashes the demo to the board, runs the demo, and stops at the beginning of the `main()` function. 

1. Set breakpoints in your project's source code, and then run the code. The project should look something like the following.  
![\[Main source code file with hardware initialization, task scheduling, key provisioning for a device microcontroller project.\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/numaker-iot-m487-debug.png)

### Troubleshooting μVision debug settings
<a name="gsg-nuvoton-m487-troubleshoot-debug"></a>

If you encounter problems while debugging an application, check that your debug settings are set correctly in Keil μVision.

**To verify that the μVision debug settings are correct**

1. Open Keil μVision. 

1. Right-click the `aws_demo` project in the IDE, and then choose **Options**. 

1. On the **Utilities** tab, verify that **Use Target Driver for Flash Programming** is selected, and that **Nuvoton Nu-Link Debugger** is set as the target driver.   
![\[Options window showing configuration settings for flash programming, debugging, and output file processing.\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/nulink-debugger-target.png)

1. On the **Debug** tab, next to **Nuvoton Nu-Link Debugger**, choose **Settings**.  
![\[Nu-Link Debugger settings dialog with options for driver version, ICE version, device family, device ID, port, max clock, chip type, connection mode, reset option, and power control voltages.\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/nulink-driver-setup.png)

1. Verify that the **Chip Type** is set to **M480**. 

# Getting started with the NXP LPC54018 IoT Module
<a name="getting_started_nxp"></a>

**Important**  <a name="deprecation-message"></a>
This reference integration is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).

This tutorial provides instructions for getting started with the NXP LPC54018 IoT Module. If you do not have an NXP LPC54018 IoT Module, visit the AWS Partner Device Catalog to purchase one from our [partner](https://devices.amazonaws.com/detail/a3G0L00000AANtAUAX/LPC54018-IoT-Solution). Use a USB cable to connect your NXP LPC54018 IoT Module to your computer.

Before you begin, you must configure AWS IoT and your FreeRTOS download to connect your device to the AWS Cloud. See [First steps](freertos-prereqs.md) for instructions. In this tutorial, the path to the FreeRTOS download directory is referred to as `freertos`.

## Overview
<a name="w2aac31b9b7c25c42c11"></a>

This tutorial contains instructions for the following getting started steps:

1. Connecting your board to a host machine.

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

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

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

## Set up the NXP hardware
<a name="nxp-setup-hardware"></a>

**To set up the NXP LPC54018**
+ Connect your computer to the USB port on the NXP LPC54018.

**To set up the JTAG debugger**

You need a JTAG debugger to launch and debug your code running on the NXP LPC54018 board. FreeRTOS was tested using an OM40006 IoT Module. For more information about supported debuggers, see the *User Manual for NXP LPC54018 IoT Module* that is available from the [ OM40007 LPC54018 IoT Module](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/lpc54018-iot-module-for-the-lpc540xx-family-of-mcus:OM40007) product page. 

1. If you're using an OM40006 IoT Module debugger, use a converter cable to connect the 20-pin connector from the debugger to the 10-pin connector on the NXP IoT module. 

1. Connect the NXP LPC54018 and the OM40006 IoT Module Debugger to the USB ports on your computer using mini-USB to USB cables.

## Set up your development environment
<a name="setup-env_nxp"></a>

FreeRTOS supports two IDEs for the NXP LPC54018 IoT Module: IAR Embedded Workbench and MCUXpresso.

Before you begin, install one of these IDEs.

**To install IAR Embedded Workbench for ARM**

1. Browse to [ IAR Embedded Workbench for ARM](https://www.iar.com/iar-embedded-workbench/#!?architecture=Arm) and download the software.
**Note**  
IAR Embedded Workbench for ARM requires Microsoft Windows.

1. Run the installer and follow the prompts.

1. In the **License Wizard**, choose **Register with IAR Systems to get an evaluation license**.

1. Put the bootloader on the device before attempting to run any demos.

**To install MCUXpresso from NXP**

1. Download and run the MCUXpresso installer from [NXP](https://www.nxp.com/support/developer-resources/software-development-tools/mcuxpresso-software-and-tools/mcuxpresso-integrated-development-environment-ide:MCUXpresso-IDE).
**Note**  
Versions 10.3.x and later are supported.

1. Browse to [MCUXpresso SDK](https://www.nxp.com/support/developer-resources/software-development-tools/mcuxpresso-software-and-tools/mcuxpresso-software-development-kit-sdk:MCUXpresso-SDK) and choose **Build your SDK.**
**Note**  
Versions 2.5 and later are supported.

1. Choose **Select Development Board**.

1. Under **Select Development Board**, in **Search by Name**, enter **LPC54018-IoT-Module**.

1. Under **Boards**, choose **LPC54018-IoT-Module**.

1. Verify the hardware details, and then choose **Build MCUXepresso SDK**.

1. The SDK for Windows using the MCUXpresso IDE is already built. Choose **Download SDK**. If you are using another operating system, under **Host OS**, choose your operating system, and then choose **Download SDK**. 

1. Start the MCUXpresso IDE, and choose the **Installed SDKs** tab.

1. Drag and drop the downloaded SDK archive file into the **Installed SDKs** window.

If you experience issues during installation, see [NXP Support](https://www.nxp.com/support/support:SUPPORTHOME?tid=sbmenu) or [NXP Developer Resources](https://www.nxp.com/support/developer-resources:DEVELOPER_HOME).

## Monitoring MQTT messages on the cloud
<a name="getting_started_nxp_mqtt_monitoring"></a>

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](https://console.aws.amazon.com/iotv2/).

1. In the navigation pane, choose **Test**, then choose **MQTT test client** to open the MQTT client.

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

When the demo project successfully runs on your device you see "Hello World\$1" sent multiple times to the topic that you subscribed to.

## Build and run the FreeRTOS Demo project
<a name="nxp-build-and-run"></a>

### Import the FreeRTOS demo into your IDE
<a name="nxp-freertos-import-project"></a><a name="nxp-load-project"></a>

**To import the FreeRTOS sample code into the IAR Embedded Workbench IDE**

1. Open IAR Embedded Workbench, and from the **File** menu, choose **Open Workspace**.

1. In the **search-directory** text box, enter `projects/nxp/lpc54018iotmodule/iar/aws_demos`, and choose **aws\$1demos.eww**.

1. From the **Project** menu, choose **Rebuild All**.

**To import the FreeRTOS sample code into the MCUXpresso IDE**

1. Open MCUXpresso, and from the **File** menu, choose **Open Projects From File System**.

1. In the **Directory** text box, enter `projects/nxp/lpc54018iotmodule/mcuxpresso/aws_demos`, and choose **Finish**

1. From the **Project** menu, choose **Build All**.

### Run the FreeRTOS demo project
<a name="nxp-run-example"></a>

**To run the FreeRTOS demo project with the IAR Embedded Workbench IDE**

1. In your IDE, from the **Project** menu, choose **Make**.

1. From the **Project** menu, choose **Download and Debug**.

1. From the **Debug** menu, choose **Start Debugging**.

1. When the debugger stops at the breakpoint in `main`, from the **Debug** menu, choose **Go.**
**Note**  
If a **J-Link Device Selection** dialog box opens, choose **OK** to continue. In the **Target Device Settings** dialog box, choose **Unspecified**, choose **Cortex-M4**, and then choose **OK**. You only need to be do this once.

**To run the FreeRTOS demo project with the MCUxpresso IDE**

1. In your IDE, from the **Project** menu, choose **Build**.

1. If this is your first time debugging, choose the `aws_demos` project and from the **Debug** toolbar, choose the blue debug button.

1. Any detected debug probes are displayed. Choose the probe you want to use, and then choose **OK** to start debugging.
**Note**  
When the debugger stops at the breakpoint in `main()`, press the debug restart button ![\[Colorful logo with overlapping circles representing cloud services integration.\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/reset.png) once to reset the debugging session. (This is required due to a bug with MCUXpresso debugger for NXP54018-IoT-Module).

1. When the debugger stops at the breakpoint in `main()`, from the **Debug** menu, choose **Go**.

## Troubleshooting
<a name="getting_started_nxp_troubleshooting"></a>

For general troubleshooting information about Getting Started with FreeRTOS, see [Troubleshooting getting started](gsg-troubleshooting.md).

# Getting started with the Renesas Starter Kit\$1 for RX65N-2MB
<a name="getting_started_renesas"></a>

**Important**  <a name="deprecation-message"></a>
This reference integration is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).

This tutorial provides instructions for getting started with the Renesas Starter Kit\$1 for RX65N-2MB. If you do not have the Renesas RSK\$1 for RX65N-2MB, visit the AWS Partner Device Catalog, and purchase one from our [ partners](https://devices.amazonaws.com/detail/a3G0L00000AAOkeUAH/Renesas-Starter-Kit+-for-RX65N-2MB).

Before you begin, you must configure AWS IoT and your FreeRTOS download to connect your device to the AWS Cloud. See [First steps](freertos-prereqs.md) for instructions. In this tutorial, the path to the FreeRTOS download directory is referred to as `freertos`.

## Overview
<a name="gsg-renesas-overview"></a>

This tutorial contains instructions for the following getting started steps:

1. Connecting your board to a host machine.

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

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

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

## Set up the Renesas hardware
<a name="renesas-setup-hardware"></a>

**To set up the RSK\$1 for RX65N-2MB**

1. Connect the positive \$15V power adapter to the PWR connector on the RSK\$1 for RX65N-2MB.

1. Connect your computer to the USB2.0 FS port on the RSK\$1 for RX65N-2MB.

1. Connect your computer to the USB-to-serial port on the RSK\$1 for RX65N-2MB.

1. Connect a router or internet-connected Ethernet port to the Ethernet port on the RSK\$1 for RX65N-2MB.

**To set up the E2 Lite Debugger module**

1. Use the 14-pin ribbon cable to connect the E2 Lite Debugger module to the ‘E1/E2 Lite’ port on the RSK\$1 for RX65N-2MB.

1. Use a USB cable to connect the E2 Lite debugger module to your host machine. When the E2 Lite debugger is connected to both the board and your computer, a green ‘ACT’ LED on the debugger flashes.

1. After the debugger is connected to your host machine and RSK\$1 for RX65N-2MB, the E2 Lite debugger drivers begin installing.

   Note that administrator privileges are required to install the drivers.

![\[Embedded system board with various interfaces and connected peripherals.\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/renesas-board3.png)


## Set up your development environment
<a name="renesas-setup-env"></a>

To set up FreeRTOS configurations for the RSK\$1 for RX65N-2MB, use the Renesas e2studio IDE and CC-RX compiler.

**Note**  
The Renesas e2studio IDE and CC-RX compiler are only supported on Windows 7, 8, and 10 operating systems.

**To download and install e2studio**

1. Go to the [ Renesas e2studio installer](https://www.renesas.com/us/en/document/uid/e-studio-2020-10-installer-offline-installer) download page, and download the offline installer.

1. You are directed to a Renesas Login page.

   If you have an account with Renesas, enter your sign-in credentials and then choose **Login**.

   If you do not have an account, choose **Register now**, and follow the first registration steps. You should receive an email with a link to activate your Renesas account. Follow this link to complete your registration with Renesas, and then log in to Renesas.

1. After you log in, download the e2studio installer to your computer.

1. Open the installer and follow the steps to completion.

For more information, see the [ e2studio](https://www.renesas.com/us/en/products/software-tools/tools/ide/e2studio.html#productInfo) on the Renesas website.

**To download and install the RX Family C/C\$1\$1 Compiler Package**

1. Go to the [ RX Family C/C\$1\$1 Compiler Package](https://www.renesas.com/us/en/document/esw/rx-family-cc-compiler-package-v3-without-ide-v30000) download page, and download the V3.00.00 package.

1. Open the executable and install the compiler.

For more information, see the [C/C\$1\$1 Compiler Package for RX Family](https://www.renesas.com/us/en/products/software-tools/tools/compiler-assembler/compiler-package-for-rx-family.html#productInfo) on the Renesas website.

**Note**  
The compiler is available free for evaluation version only and valid for 60 days. On the 61st day, you need to get a License Key. For more information, see [Evaluation Software Tools](https://www.renesas.com/us/en/products/software-tools/evaluation-software-tools.html).

## Build and run FreeRTOS samples
<a name="renesas-build-and-run-example"></a>

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

### Build the FreeRTOS Demo in e2studio
<a name="renesas-freertos-import-project"></a>

**To import and build the demo in e2studio**

1. Launch e2studio from the Start menu. 

1. On the **Select a directory as a workspace** window, browse to the folder that you want to work in, and choose **Launch**.

1. The first time you open e2studio, the **Toolchain Registry** window opens. Choose **Renesas Toolchains**, and confirm that **CC-RX v3.00.00** is selected. Choose **Register**, and then choose **OK**.

1. If you are opening e2studio for the first time, the **Code Generator Registration** window appears. Choose **OK**.

1. The **Code Generator COM component register** window appears. Under **Please restart e2studio to use Code Generator**, choose **OK**.

1. The **Restart e2studio** window appears. Choose **OK**.

1. e2studio restarts. On the **Select a directory as a workspace** window, choose **Launch**.

1. On the e2studio welcome screen, choose the **Go to the e2studio workbench** arrow icon.

1. Right-click the **Project Explorer** window, and choose **Import**.

1. In the import wizard, choose **General**, **Existing Projects into Workspace**, and then choose **Next**.

1. Choose **Browse**, locate the directory `projects/renesas/rx65n-rsk/e2studio/aws_demos`, and then choose **Finish**. 

1. From **Project** menu, choose **Project**, **Build All**.

   The build console issues a warning message that the License Manager is not installed. You can ignore this message unless you have a license key for the CC-RX compiler. To install the License Manager, see the [License Manager](https://www.renesas.com/us/en/document/swr/license-manager-v20301) download page.

### Monitoring MQTT messages on the cloud
<a name="gsg-renesas-monitor-mqtt"></a>

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](https://console.aws.amazon.com/iotv2/).

1. In the navigation pane, choose **Test**, then choose **MQTT test client** to open the MQTT client.

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

When the demo project successfully runs on your device you see "Hello World\$1" sent multiple times to the topic that you subscribed to.

### Run the FreeRTOS project
<a name="renesas-run"></a>

**To run the project in e2studio**

1. Confirm that you have connected the E2 Lite Debugger module to your RSK\$1 for RX65N-2MB

1. From the top menu, choose **Run**, **Debug Configuration**.

1. Expand **Renesas GDB Hardware Debugging**, and choose **aws\$1demos HardwareDebug**.

1. Choose the **Debugger** tab, and then choose the **Connection Settings** tab. Confirm that your connection settings are correct.

1. Choose **Debug** to download the code to your board and begin debugging.

   You might be prompted by a firewall warning for `e2-server-gdb.exe`. Check **Private networks, such as my home or work network**, and then choose **Allow access**.

1. e2studio might ask to change to **Renesas Debug Perspective**. Choose **Yes**.

   The green 'ACT' LED on the E2 Lite Debugger illuminates.

1. After the code is downloaded to the board, choose **Resume** to run the code up to the first line of the main function. Choose **Resume** again to run the rest of the code.

For the latest projects released by Renesas, see the `renesas-rx` fork of the `amazon-freertos` repository on [GitHub](https://github.com/renesas-rx/amazon-freertos).

## Troubleshooting
<a name="renesas-troubleshooting"></a>

For general troubleshooting information about Getting Started with FreeRTOS, see [Troubleshooting getting started](gsg-troubleshooting.md).

# Getting started with the STMicroelectronics STM32L4 Discovery Kit IoT Node
<a name="getting_started_st"></a>

**Important**  <a name="deprecation-message"></a>
This reference integration is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).

This tutorial provides instructions for getting started with the STMicroelectronics STM32L4 Discovery Kit IoT Node. If you do not already have the STMicroelectronics STM32L4 Discovery Kit IoT Node, visit the AWS Partner Device Catalog to purchase one from our [partner](https://devices.amazonaws.com/detail/a3G0L00000AANsWUAX/STM32L4-Discovery-Kit-IoT-Node).

Make sure you have installed the latest Wi-Fi firmware. To download the latest Wi-Fi firmware, see [STM32L4 Discovery kit IoT node, low-power wireless, Bluetooth Low Energy, NFC, SubGHz, Wi-Fi](https://www.st.com/resource/en/utilities/inventek_fw_updater.zip). Under **Binary Resources**, choose **Inventek ISM 43362 Wi-Fi module firmware update (read the readme file for instructions) **.

Before you begin, you must configure AWS IoT, your FreeRTOS download, and Wi-Fi to connect your device to the AWS Cloud. See [First steps](freertos-prereqs.md) for instructions . In this tutorial, the path to the FreeRTOS download directory is referred to as `freertos`.

## Overview
<a name="w2aac31b9b7c25c46c13"></a>

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.

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

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

## Set up your development environment
<a name="st-setup-env"></a>

### Install System Workbench for STM32
<a name="install-system-workbench"></a>

1. Browse to [OpenSTM32.org](http://www.openstm32.org/HomePage).

1. Register on the OpenSTM32 webpage. You need to sign in to download System Workbench.

1. Browse to the [System Workbench for STM32 installer](http://www.openstm32.org/System%2BWorkbench%2Bfor%2BSTM32) to download and install System Workbench.

If you experience issues during installation, see the FAQs on the [System Workbench website](http://www.openstm32.org/HomePage).

## Build and run the FreeRTOS demo project
<a name="st-build-and-run-example"></a>

### Import the FreeRTOS demo into the STM32 System Workbench
<a name="st-freertos-import-project"></a><a name="st-import-project"></a>

1. Open the STM32 System Workbench and enter a name for a new workspace.

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

1. In **Select Root Directory**, enter `projects/st/stm32l475_discovery/ac6/aws_demos`.

1. The project `aws_demos` should be selected by default.

1. Choose **Finish** to import the project into STM32 System Workbench.

1. From the **Project** menu, choose **Build All**. Confirm the project compiles without any errors.

### Monitoring MQTT messages on the cloud
<a name="w2aac31b9b7c25c46c17b5"></a>

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](https://console.aws.amazon.com/iotv2/).

1. In the navigation pane, choose **Test**, then choose **MQTT test client** to open the MQTT client.

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

When the demo project successfully runs on your device you see "Hello World\$1" sent multiple times to the topic that you subscribed to.

### Run the FreeRTOS demo project
<a name="st-run-example"></a>

1. Use a USB cable to connect your STMicroelectronics STM32L4 Discovery Kit IoT Node to your computer. (Check the manufacturer's documentation that came with your board for the correct USB port to use.)

1. From **Project Explorer**, right-click `aws_demos`, choose **Debug As**, and then choose **Ac6 STM32 C/C\$1\$1 Application**.

   If a debug error occurs the first time a debug session is launched, follow these steps:

   1. In STM32 System Workbench, from the **Run** menu, choose **Debug Configurations**.

   1. Choose **aws\$1demos Debug**. (You might need to expand **Ac6 STM32 Debugging**.)

   1. Choose the **Debugger** tab.

   1. In **Configuration Script**, choose **Show Generator Options**.

   1. In **Mode Setup**, set **Reset Mode** to **Software System Reset**. Choose **Apply**, and then choose **Debug**. 

1. When the debugger stops at the breakpoint in `main()`, from the **Run** menu, choose **Resume**.

### Using CMake with FreeRTOS
<a name="w2aac31b9b7c25c46c17b9"></a>

If you prefer not to use an IDE for FreeRTOS development, you can alternatively use CMake to build and run the demo applications or applications that you have developed using third-party code editors and debugging tools.

First create a folder to contain the generated build files (*build-folder*).

Use the following command to generate build files:

```
cmake -DVENDOR=st -DBOARD=stm32l475_discovery -DCOMPILER=arm-gcc -S freertos -B build-folder
```

If `arm-none-eabi-gcc` is not in your shell path, you also need to set the `AFR_TOOLCHAIN_PATH` CMake variable. For example:

```
-D AFR_TOOLCHAIN_PATH=/home/user/opt/gcc-arm-none-eabi/bin
```

For more information about using CMake with FreeRTOS, see [Using CMake with FreeRTOS](getting-started-cmake.md).

## Troubleshooting
<a name="st-troubleshooting"></a>

If you see the following in the UART output from the demo application, you need to update the Wi-Fi module’s firmware:

```
[Tmr Svc] WiFi firmware version is: xxxxxxxxxxxxx
[Tmr Svc] [WARN] WiFi firmware needs to be updated.
```

To download the latest Wi-Fi firmware, see [STM32L4 Discovery kit IoT node, low-power wireless, Bluetooth Low Energy, NFC, SubGHz, Wi-Fi](https://www.st.com/resource/en/utilities/inventek_fw_updater.zip). In **Binary Resources**, choose the download link for **Inventek ISM 43362 Wi-Fi module firmware update**.

For general troubleshooting information about Getting Started with FreeRTOS, see [Troubleshooting getting started](gsg-troubleshooting.md).

# Getting started with the Texas Instruments CC3220SF-LAUNCHXL
<a name="getting_started_ti"></a>

**Important**  <a name="deprecation-message"></a>
This reference integration is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).

This tutorial provides instructions for getting started with the Texas Instruments CC3220SF-LAUNCHXL. If you do not have the Texas Instruments (TI) CC3220SF-LAUNCHXL Development Kit, visit the AWS Partner Device Catalog to purchase one from our [ partner](https://devices.amazonaws.com/detail/a3G0L00000AANtaUAH/SimpleLink-Wi-Fi®-CC3220SF-Wireless-Microcontroller-LaunchPad-Development-Kit).

Before you begin, you must configure AWS IoT and your FreeRTOS download to connect your device to the AWS Cloud. See [First steps](freertos-prereqs.md) for instructions. In this tutorial, the path to the FreeRTOS download directory is referred to as `freertos`.

## Overview
<a name="w2aac31b9b7c25c48c11"></a>

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.

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

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

## Set up your development environment
<a name="ti-setup-env"></a>

Follow the steps below to set up your development environment to get started with FreeRTOS.

Note that FreeRTOS supports two IDEs for the TI CC3220SF-LAUNCHXL Development Kit: Code Composer Studio and IAR Embedded Workbench version 8.32. You can use either IDE to get started.

### Install Code Composer Studio
<a name="install-ccs"></a>

1. Browse to [TI Code Composer Studio](http://processors.wiki.ti.com/index.php/Download_CCS).

1. Download the offline installer for the platform of your host machine (Windows, macOS, or Linux 64-bit).

1. Unzip and run the offline installer. Follow the prompts.

1. For **Product Families to Install**, choose **SimpleLink Wi-Fi CC32xx Wireless MCUs**.

1. On the next page, accept the default settings for debugging probes, and then choose **Finish**.

If you experience issues when you are installing Code Composer Studio, see [TI Development Tools Support](http://software-dl.ti.com/ccs/esd/documents/ccs_support.html), [Code Composer Studio FAQs](http://processors.wiki.ti.com/index.php/FAQ_-_CCS), and [Troubleshooting CCS](http://processors.wiki.ti.com/index.php/Troubleshooting_CCSv7).

### Install IAR Embedded Workbench
<a name="install-iar"></a>

1. Download and run the [ Windows installer for version 8.32](http://netstorage.iar.com/SuppDB/Protected/PRODUPD/013570/EWARM-CD-8322-19423.exe) of the IAR Embedded Workbench for ARM. In **Debug probe drivers**, make sure that **TI XDS** is selected.

1. Complete the installation and launch the program. On the **License Wizard** page, choose **Register with IAR Systems to get an evaluation license**, or use your own IAR license.

### Install the SimpleLink CC3220 SDK
<a name="install-ti-sdk"></a>

Install the [SimpleLink CC3220 SDK](http://www.ti.com/tool/SIMPLELINK-CC3220-SDK). The SimpleLink Wi-Fi CC3220 SDK contains drivers for the CC3220SF programmable MCU, more than 40 sample applications, and documentation required to use the samples.

### Install Uniflash
<a name="install-uniflash"></a>

Install [Uniflash](http://www.ti.com/tool/UNIFLASH). CCS Uniflash is a standalone tool used to program on-chip flash memory on TI MCUs. Uniflash has a GUI, command line, and scripting interface.

### Install the latest service pack
<a name="ti-servicepack"></a>

1. On your TI CC3220SF-LAUNCHXL, place the SOP jumper on the middle set of pins (position = 1) and reset the board.

1. Start Uniflash. If your CC3220SF LaunchPad board appears under **Detected Devices**, choose **Start**. If your board is not detected, choose **CC3220SF-LAUNCHXL** from the list of boards under **New Configuration**, and then choose **Start Image Creator**.

1. Choose **New Project**.

1. On the **Start new project** page, enter a name for your project. For **Device Type**, choose **CC3220SF**. For **Device Mode**, choose **Develop**, and then choose **Create Project**.

1. On the right side of the Uniflash application window, choose **Connect**.

1. From the left column, choose **Advanced**, **Files**, and then **Service Pack**.

1. Choose **Browse**, and then navigate to where you installed the CC3220SF SimpleLink SDK. The service pack is located at `ti/simplelink_cc32xx_sdk_VERSION/tools/cc32xx_tools/servicepack-cc3x20/sp_VERSION.bin`.

1. Choose the **Burn** (![\[Feather icon representing a lightweight or simplified feature or concept.\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/flame.png)) button, and then choose **Program Image (Create & Program)** to install the service pack. Remember to switch the SOP jumper back to position 0 and reset the board.

### Configure Wi-Fi provisioning
<a name="wifi-provision"></a>

To configure the Wi-Fi settings for your board, do one of the following:
+ Configure the FreeRTOS demo application described in [Configuring the FreeRTOS demos](freertos-prereqs.md#freertos-configure).
+ Use [SmartConfig](http://dev.ti.com/tirex/#/?link=Software%2FSimpleLink%20CC32xx%20SDK%2FSimpleLink%20Academy%2FWi-Fi%2FWi-Fi%20Provisioning) from Texas Instruments.

## Build and run the FreeRTOS demo project
<a name="ti-build-and-run-examples"></a>

### Build and run the FreeRTOS demo project in TI Code Composer
<a name="ti-build-and-run-ccs"></a><a name="ti-load-project"></a>

**To import the FreeRTOS demo into TI Code Composer**

1. Open TI Code Composer, and choose **OK** to accept the default workspace name.

1. On the **Getting Started** page, choose **Import Project**.

1. In **Select search-directory**, enter `projects/ti/cc3220_launchpad/ccs/aws_demos`. The project `aws_demos` should be selected by default. To import the project into TI Code Composer, choose **Finish**.

1. In **Project Explorer**, double-click **aws\$1demos** to make the project active.

1. From **Project**, choose **Build Project** to make sure the project compiles without errors or warnings.<a name="ti-run-project-css"></a>

**To run the FreeRTOS demo in TI Code Composer**

1. Make sure the Sense On Power (SOP) jumper on your Texas Instruments CC3220SF-LAUNCHXL is in position 0. For more information, see [SimpleLink Wi-Fi CC3x20, CC3x3x Network Processor User's Guide](http://www.ti.com/lit/swru455).

1. Use a USB cable to connect your Texas Instruments CC3220SF-LAUNCHXL to your computer.

1. In the project explorer, make sure the `CC3220SF.ccxml` is selected as the active target configuration. To make it active, right-click the file and choose **Set as active target configuration**.

1. In TI Code Composer, from **Run**, choose **Debug**.

1. When the debugger stops at the breakpoint in `main()`, go to the **Run** menu, and choose **Resume**.

### Monitoring MQTT messages on the cloud
<a name="w2aac31b9b7c25c48c15b5"></a>

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](https://console.aws.amazon.com/iotv2/).

1. In the navigation pane, choose **Test**, then choose **MQTT test client** to open the MQTT client.

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

When the demo project successfully runs on your device you see "Hello World\$1" sent multiple times to the topic that you subscribed to.

### Build and run FreeRTOS demo project in IAR Embedded Workbench
<a name="ti-build-and-run-iar"></a><a name="ti-load-project-iar"></a>

**To import the FreeRTOS demo into IAR Embedded Workbench**

1. Open IAR Embedded Workbench, choose **File**, and then choose **Open Workspace**.

1. Navigate to `projects/ti/cc3220_launchpad/iar/aws_demos`, choose **aws\$1demos.eww**, and then choose **OK**.

1. Right-click the project name (`aws_demos`), and then choose **Make**.

**To run the FreeRTOS demo in IAR Embedded Workbench**

1. Make sure the Sense On Power (SOP) jumper on your Texas Instruments CC3220SF-LAUNCHXL is in position 0. For more information, see [SimpleLink Wi-Fi CC3x20, CC3x3x Network Processor User's Guide](http://www.ti.com/lit/swru455).

1. Use a USB cable to connect your Texas Instruments CC3220SF-LAUNCHXL to your computer.

1. Rebuild your project.

   To rebuild the project, from the **Project** menu, choose **Make**.

1. From the **Project** menu, choose **Download and Debug**. You can ignore "Warning: Failed to initialize EnergyTrace," if it's displayed. For more information about EnergyTrace, see [MSP EnergyTrace Technology](http://www.ti.com/tool/energytrace?jktype=recommendedresults).

1. When the debugger stops at the breakpoint in `main()`, go to the **Debug** menu, and choose **Go**.

### Using CMake with FreeRTOS
<a name="w2aac31b9b7c25c48c15b9"></a>

If you prefer not to use an IDE for FreeRTOS development, you can alternatively use CMake to build and run the demo applications or applications that you have developed using third-party code editors and debugging tools.

**To build the FreeRTOS demo with CMake**

1. Create a folder to contain the generated build files (*build-folder*).

1. Make sure your search path (**\$1PATH** environment variable) contains the folder where the TI CGT compiler binary is located (for example `C:\ti\ccs910\ccs\tools\compiler\ti-cgt-arm_18.12.2.LTS\bin`).

   If you are using the TI ARM compiler with your TI board, use the following command to generate build files from source code:

   ```
   cmake -DVENDOR=ti -DBOARD=cc3220_launchpad -DCOMPILER=arm-ti -S freertos -B build-folder
   ```

For more information, see [Using CMake with FreeRTOS](getting-started-cmake.md).

## Troubleshooting
<a name="getting_started_ti_troubleshooting"></a>

If you don’t see messages in the MQTT client of the AWS IoT console, you might need to configure debug settings for the board.

**To configure debug settings for TI boards**

1. In Code Composer, on **Project Explorer**, choose **aws\$1demos**.

1. From the **Run** menu, choose **Debug Configurations**.

1. In the navigation pane, choose **aws\$1demos**.

1. On the **Target** tab, under **Connection Options**, choose **Reset the target on a connect**.

1. Choose **Apply**, and then choose **Close**.

If these steps don’t work, look at the program's output in the serial terminal. You should see some text that indicates the source of the problem.

For general troubleshooting information about Getting Started with FreeRTOS, see [Troubleshooting getting started](gsg-troubleshooting.md).

# Getting started with the Windows Device Simulator
<a name="getting_started_windows"></a>

This tutorial provides instructions for getting started with the FreeRTOS Windows Device Simulator.

Before you begin, you must configure AWS IoT and your FreeRTOS download to connect your device to the AWS Cloud. See [First steps](freertos-prereqs.md) for instructions. In this tutorial, the path to the FreeRTOS download directory is referred to as `freertos`.

FreeRTOS is released as a zip file that contains the FreeRTOS libraries and sample applications for the platform you specify. To run the samples on a Windows machine, download the libraries and samples ported to run on Windows. This set of files is referred to as the FreeRTOS simulator for Windows.

**Note**  
This tutorial cannot be successfully run on Amazon EC2 Windows instances.

## Set up your development environment
<a name="win-setup-env"></a>

1. Install the latest version of [Npcap](https://npcap.com/). Select the "WinPcap API-compatible mode" during installation.

1. Install [Microsoft Visual Studio](https://www.visualstudio.com/downloads).

   Visual Studio versions 2017 and 2019 are known to work. All editions of these Visual Studio versions are supported (Community, Professional, or Enterprise).

   In addition to the IDE, install the **Desktop development with C\$1\$1** component.

   Install the latest Windows 10 SDK. You can choose this under the **Optional** section of the **Desktop development with C\$1\$1** component.

1. Make sure that you have an active hard-wired Ethernet connection.

1. (Optional) If you would like to use the CMake-based build system to build your FreeRTOS projects, install the latest version of [CMake](https://cmake.org/download/). FreeRTOS requires CMake version 3.13 or later.

## Monitoring MQTT messages on the cloud
<a name="getting_started_windows_monitor_mqtt"></a>

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](https://console.aws.amazon.com/iotv2/).

1. In the navigation pane, choose **Test**, then choose **MQTT test client** to open the MQTT client.

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

When the demo project successfully runs on your device you see "Hello World\$1" sent multiple times to the topic that you subscribed to.

## Build and run the FreeRTOS demo project
<a name="win-build-and-run-example"></a>

You can use Visual Studio or CMake to build FreeRTOS projects.

### Building and running the FreeRTOS demo project with the Visual Studio IDE
<a name="win-build-and-run-vs"></a>

1. Load the project into Visual Studio.

   In Visual Studio, from the **File** menu, choose **Open**. Choose **File/Solution**, navigate to the `projects/pc/windows/visual_studio/aws_demos/aws_demos.sln` file, and then choose **Open**.

1. Retarget the demo project.

   The provided demo project depends on the Windows SDK, but it does not have a Windows SDK version specified. By default, the IDE might attempt to build the demo with an SDK version not present on your machine. To set the Windows SDK version, right-click on `aws_demos` and then choose **Retarget Projects**. This opens the **Review Solution Actions** window. Choose a Windows SDK version that is present on your machine (the initial value in the dropdown is fine), and then choose **OK**.

1. Build and run the project.

   From the **Build** menu, choose **Build Solution**, and make sure the solution builds without errors or warnings. Choose **Debug**, **Start Debugging** to run the project. On the first run, you must [select a network interface](#win-network-interface).

### Building and running the FreeRTOS demo project with CMake
<a name="win-build-and-run-cmake"></a>

We recommend that you use the CMake GUI instead of the CMake command line tool to build the demo project for the Windows Simulator.

After you install CMake, open the CMake GUI. On Windows, you can find this from the Start menu under **CMake**, **CMake (cmake-gui)**.

1. Set the FreeRTOS source code directory.

   In the GUI, set the FreeRTOS source code directory (`freertos`) for **Where is the source code**.

   Set `freertos/build` for **Where to build the binaries**.

1. Configure the CMake Project.

   In the CMake GUI, choose **Add Entry**, and on the **Add Cache Entry** window, set the following values:  
**Name**  
AFR\$1BOARD  
**Type**  
STRING  
**Value**  
pc.windows  
**Description**  
(Optional)

1. Choose **Configure**. If CMake prompts you to create the build directory, choose **Yes**, and then select a generator under **Specify the generator for this project**. We recommend using Visual Studio as the generator, but Ninja is also supported. (Note that when using Visual Studio 2019, the platform should be set to Win32 instead of its default setting.) Keep the other generator options unchanged and choose **Finish**.

1. Generate and Open the CMake Project.

   After you have configured the project, the CMake GUI shows all options available for the generated project. For the purposes of this tutorial, you can leave the options at their default values.

   Choose **Generate** to create a Visual Studio solution, and then choose **Open Project** to open the project in Visual Studio.

   In Visual Studio, right-click the `aws_demos` project and choose **Set as StartUp Project**. This enables you to build and run the project. On the first run, you must [select a network interface](#win-network-interface).

For more information about using CMake with FreeRTOS, see [Using CMake with FreeRTOS](getting-started-cmake.md).

### Configure your network interface
<a name="win-network-interface"></a>

On the first run of the demo project, you must select the network interface to use. The program counts your network interfaces. Find the number for your hard-wired Ethernet interface. The output should look like this:

```
0 0 [None] FreeRTOS_IPInit
1 0 [None] vTaskStartScheduler
1. rpcap://\Device\NPF_{AD01B877-A0C1-4F33-8256-EE1F4480B70D}
(Network adapter 'Intel(R) Ethernet Connection (4) I219-LM' on local host)

2. rpcap://\Device\NPF_{337F7AF9-2520-4667-8EFF-2B575A98B580}
(Network adapter 'Microsoft' on local host)

The interface that will be opened is set by "configNETWORK_INTERFACE_TO_USE", which
should be defined in FreeRTOSConfig.h

ERROR:  configNETWORK_INTERFACE_TO_USE is set to 0, which is an invalid value.
Please set configNETWORK_INTERFACE_TO_USE to one of the interface numbers listed above,
then re-compile and re-start the application.  Only Ethernet (as opposed to Wi-Fi)
interfaces are supported.
```

After you have identified the number for your hard-wired Ethernet interface, close the application window. In the previous example, the number to use is `1`.

Open `FreeRTOSConfig.h` and set `configNETWORK_INTERFACE_TO_USE` to the number that corresponds to your hard-wired network interface.

**Important**  
Only Ethernet interfaces are supported. Wi-Fi isn't supported. 

## Troubleshooting
<a name="windows-troubleshooting"></a>

### Troubleshooting common problems on Windows
<a name="windows-troubleshooting-common"></a>

You might run into the following error when trying to build the demo project with Visual Studio:

```
Error "The Windows SDK version X.Y was not found" when building the provided Visual Studio solution.
```

The project must be targeted to a Windows SDK version present on your computer.

For general troubleshooting information about getting started with FreeRTOS, see [Troubleshooting getting started](gsg-troubleshooting.md).

# Getting started with the Xilinx Avnet MicroZed Industrial IoT Kit
<a name="getting_started_xilinx"></a>

**Important**  <a name="deprecation-message"></a>
This reference integration is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).

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](https://devices.amazonaws.com/detail/a3G0L00000AANtqUAH/MicroZed-IIoT-Bundle-with-Amazon-FreeRTOS).

Before you begin, you must configure AWS IoT and your FreeRTOS download to connect your device to the AWS Cloud. See [First steps](freertos-prereqs.md) for instructions. In this tutorial, the path to the FreeRTOS download directory is referred to as `freertos`.

## Overview
<a name="xilinx-overview"></a>

This tutorial contains instructions for the following getting started steps:

1. Connecting your board to a host machine.

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

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

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

## Set up the MicroZed hardware
<a name="xilinx-setup-hardware"></a>

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

![\[AVNet microcontroller board with Power Good LED, User LED and push button, JTAG access, 10/100/1000 Ethernet and USB host, microSD slot, USB-UART, Done LED, Reset button, and Boot MODE jumpers highlighted.\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/microzed.png)


**To set up the MicroZed board**

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

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

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

## Set up your development environment
<a name="xilinx-setup-env"></a>

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
<a name="install-xsdk"></a>

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

**To download the XSDK**

1. Go to the [ Software Development Kit Standalone WebInstall Client](https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/embedded-design-tools/2019-1.html) download page.

1. Choose the option appropriate for your operating system.

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

   If you have an account with Xilinx, enter your sign-in credentials 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. 

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

1. Save the `Xilinx_SDK_version_os` file.

**To install the XSDK**

1. Open the `Xilinx_SDK_version_os` file.

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

1. 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](https://www.xilinx.com/support/documentation/boards_and_kits/install/ug1033-cp210x-usb-uart-install.pdf).

For more information about XSDK, see the [Getting Started with Xilinx SDK](https://www.xilinx.com/html_docs/xilinx2018_2/SDK_Doc/index.html) on the Xilink website.

## Monitoring MQTT messages on the cloud
<a name="xilinx-monitor-mqtt"></a>

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](https://console.aws.amazon.com/iotv2/).

1. In the navigation pane, choose **Test**, then choose **MQTT test client** to open the MQTT client.

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

## Build and run the FreeRTOS demo project
<a name="xilinx-build-and-run-example"></a>

### Open the FreeRTOS demo in the XSDK IDE
<a name="xilinx-freertos-import-project"></a>

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

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

1. From the menu, choose **File**, and then choose **Import**.

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

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

1. With all of the projects selected, choose **Finish**. 

1. 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 \$13 but with the root directory set to `freertos/vendors/xilinx`, and import `aws_bsp`, `fsbl`, and `MicroZed_hw_platform_0`.

1. From the menu, choose **Window**, and then choose **Preferences**.

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

1. In **New String Substitution Variable**, for **Name**, enter **AFR\$1ROOT**. 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
<a name="xilinx-freertos-build-project"></a>

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

1. 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
<a name="xilinx-build-boot-image"></a>

1. In the XSDK IDE, right-click **aws\$1demos**, and then choose **Create Boot Image**. 

1. In **Create Boot Image**, choose **Create new BIF file**.

1. 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`.

1. Choose **Add**. 

1. 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`.

1. For the **Partition type**, choose **bootloader**, and then choose **OK**.

1. 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
<a name="xilinx-jtag"></a>

1. Set your MicroZed board's boot mode jumpers to the JTAG boot mode.  
![\[Circuit board header connectors and jumper settings.\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/xilinx-jtag.png)

1. 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:  
![\[FreeRTOS evaluation board with connectivity options.\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/xilinx-jtag-full-board.png)

1. In the XSDK IDE, right-click **aws\$1demos**, choose **Debug As**, and then choose **1 Launch on System Hardware (System Debugger)**.

1. 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](#xilinx-build-boot-image) and [Run the FreeRTOS demo project](#xilinx-run).

### Run the FreeRTOS demo project
<a name="xilinx-run"></a>

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](#xilinx-setup-hardware). Make sure that you have connected your MicroZed board to your computer.

#### Boot the FreeRTOS project from a MicroSD card
<a name="xilinx-build-boot-sd"></a>

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

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

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

1. Set the MicroZed boot mode jumpers to SD boot mode.  
![\[SD Card with three slots labeled JP1, JP2, JP3 and a coin cell battery holder.\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/xilinx-sd.png)

1. 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
<a name="xilinx-build-boot-qspi"></a>

1. Set your MicroZed board's boot mode jumpers to the JTAG boot mode.  
![\[Circuit board header connectors and jumper settings.\]](http://docs.aws.amazon.com/freertos/latest/userguide/images/xilinx-jtag.png)

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

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

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

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

1. In **Offset**, enter **0x0**.

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

1. Choose **Program** to program your board.

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

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

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

1. 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
<a name="xilinx-troubleshooting"></a>

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](#xilinx-freertos-build-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](gsg-troubleshooting.md).

# Next steps with FreeRTOS
<a name="getting-started-next-steps"></a>

**Important**  <a name="deprecation-message-general"></a>
This page refers to the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).

After you build, flash, and run the FreeRTOS demo project for your board, you can visit the FreeRTOS.org website to learn more about [ Creating a New FreeRTOS Project](https://www.freertos.org/Creating-a-new-FreeRTOS-project.html). There are also demos for many FreeRTOS libraries that show how to perform important tasks, interact with AWS IoT services, and program board-specific capabilities (such as cellular modems). For more information, see the [FreeRTOS Library Categories](https://www.freertos.org/libraries/categories.html) page. 

The FreeRTOS.org website also has in-depth information on [ the FreeRTOS Kernel](https://www.freertos.org/RTOS.html) as well as fundamental real-time operating system concepts. For more information, see the [FreeRTOS Kernel Developer Docs](https://www.freertos.org/features.html) and [FreeRTOS Kernel Secondary Docs](https://www.freertos.org/kernel/secondarydocs.html) pages.