# Use the IDT user interface to run the FreeRTOS qualification suite
Starting with IDT v4.3.0, AWS IoT Device Tester for FreeRTOS (IDT-FreeRTOS) includes a web-based user interface that enables you to interact with the IDT command line executable and related configuration files. You can use the IDT-FreeRTOS UI to create a new configuration to run IDT tests, or to modify an existing configuration. You can also use the UI to invoke the IDT executable and run tests.
The IDT-FreeRTOS UI provides the following functions:
+ Simplify setting up configuration files for IDT-FreeRTOS tests.
+ Simplify using IDT-FreeRTOS to run qualification tests.
For information about the using the command line to run qualification tests, see [First test of your microcontroller board](qual-steps.md).
This section describes the prerequisites for using the IDT-FreeRTOS UI, and shows you how to get started running qualification tests in the UI.
**Topics**
+ [
# Set up the prerequisites to run the FreeRTOS qualification suite
](dev-tester-ui-prereqs.md)
+ [
# Get started with the IDT-FreeRTOS UI
](dev-tester-ui-getting-started.md)
# Set up the prerequisites to run the FreeRTOS qualification suite
This section describes the prerequisites for testing microcontrollers with AWS IoT Device Tester.
**Topics**
+ [
## Use a supported web browser
](#idt-ui-supported-web-browser)
+ [
## Download FreeRTOS
](#ui-download-afr)
+ [
## Download IDT for FreeRTOS
](#ui-download-dev-tester-afr)
+ [
## Create and configure an AWS account
](#ui-config-aws-account)
+ [
## AWS IoT Device Tester managed policy
](#ui-managed-policy)
## Use a supported web browser
The IDT-FreeRTOS UI supports the following web browsers.
| Browser | Version |
| --- | --- |
| Google Chrome | Latest three major versions |
| Mozilla Firefox | Latest three major versions |
| Microsoft Edge | Latest three major versions |
| Apple Safari for macOS | Latest three major versions |
We recommend that you use Google Chrome or Mozilla Firefox for a better experience.
**Note**
The IDT-FreeRTOS UI doesn't support Microsoft Internet Explorer.
## Download FreeRTOS
You can download a release of FreeRTOS from [GitHub](https://github.com/aws/amazon-freertos) with the following command:
```
git clone --branch --recurse-submodules https://github.com/aws/amazon-freertos.git
cd amazon-freertos
git submodule update --checkout --init --recursive
```
where is a version of FreeRTOS (for example, 202007.00) corresponding to an IDT version listed in [Supported versions of AWS IoT Device Tester](dev-test-versions-afr.md). This ensures you have the full source code, including submodules, and are using the correct version of IDT for your version of FreeRTOS, and vice versa.
Windows has a path length limitation of 260 characters. The path structure of FreeRTOS is many levels deep, so if you're using Windows, keep your file paths under the 260-character limit. For example, clone FreeRTOS to `C:\FreeRTOS` rather than `C:\Users\username\programs\projects\myproj\FreeRTOS\`.
### Considerations for LTS qualification (qualification for FreeRTOS that uses LTS libraries)
+ In order for your microcontroller to be designated as supporting long-term support (LTS) based versions of FreeRTOS in the AWS Partner Device Catalog, you must provide a manifest file. For more information, see the [FreeRTOS Qualification Checklist](https://docs.aws.amazon.com/freertos/latest/qualificationguide/afq-checklist.html) in the *FreeRTOS Qualification Guide*.
+ In order to validate that your microcontroller supports LTS based versions of FreeRTOS and qualify it for submission to the AWS Partner Device Catalog, you must use AWS IoT Device Tester (IDT) with FreeRTOS Qualification (FRQ) test suite version v1.4.x.
+ Support for LTS based versions of FreeRTOS is limited to the 202012.xx version of FreeRTOS.
## Download IDT for FreeRTOS
Every version of FreeRTOS has a corresponding version of IDT for FreeRTOS for performing qualification tests. Download the appropriate version of IDT for FreeRTOS from [Supported versions of AWS IoT Device Tester](dev-test-versions-afr.md).
Extract IDT for FreeRTOS to a location on the file system where you have read and write permissions. Because Microsoft Windows has a character limit for the path length, extract IDT for FreeRTOS into a root directory such as `C:\` or `D:\`.
**Note**
We recommend that you extract the IDT package to a local drive.Allowing multiple users to run IDT from a shared location, such as an NFS directory or a Windows network shared folder, might result in the system not responding or data corruption.
## Create and configure an AWS account
### Sign up for an AWS account
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
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*.
## AWS IoT Device Tester managed policy
To enable device tester to run and to collect metrics, the `AWSIoTDeviceTesterForFreeRTOSFullAccess` managed policy contains the following permissions:
+ `iot-device-tester:SupportedVersion`
Grants permission to get the list of FreeRTOS versions and test suite versions supported by IDT, so that they're available from the AWS CLI.
+ `iot-device-tester:LatestIdt`
Grants permission to get the latest AWS IoT Device Tester version that is available for download.
+ `iot-device-tester:CheckVersion`
Grants permission to check that a combination of product, test suite, and AWS IoT Device Tester versions are compatible.
+ `iot-device-tester:DownloadTestSuite`
Grants permission to AWS IoT Device Tester to download test suites.
+ `iot-device-tester:SendMetrics`
Grants permission to publish AWS IoT Device Tester usage metrics data.
# Get started with the IDT-FreeRTOS UI
This section shows you how to use the IDT-FreeRTOS UI to create or modify your configuration, and then shows you how to run tests.
**Topics**
+ [
## Configure AWS credentials
](#configure-aws-credentials)
+ [
## Open the IDT-FreeRTOS UI
](#open-idt-ui)
+ [
## Create a new configuration
](#create-new-configuration)
+ [
## Modify an existing configuration
](#modify-existing-configuration)
+ [
## Run qualification tests
](#run-tests-from-ui)
## Configure AWS credentials
You must configure credentials for the AWS user that you created in [Create and configure an AWS account](dev-tester-ui-prereqs.md#ui-config-aws-account). You can specify your credentials in one of two ways:
+ In a credentials file
+ As environment variables
### Configure AWS credentials with a credentials file
IDT uses the same credentials file as the AWS CLI. For more information, see [Configuration and credential files](https://docs.aws.amazon.com/cli/latest/userguide/cli-config-files.html).
The location of the credentials file varies, depending on the operating system you're using:
+ macOS, Linux: `~/.aws/credentials`
+ Windows: `C:\Users\UserName\.aws\credentials`
Add your AWS credentials to the `credentials` file in the following format:
```
[default]
aws_access_key_id =
aws_secret_access_key =
```
**Note**
If you don't use the `default` AWS profile, be sure to specify the profile name in the IDT-FreeRTOS UI. For more information about profiles, see [Configuration and credential file settings](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html).
### Configure AWS credentials with environment variables
Environment variables are variables maintained by the operating system and used by system commands. They're not saved if you close the SSH session. The IDT-FreeRTOS UI uses the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables to store your AWS credentials.
To set these variables on Linux, macOS, or Unix, use **export**:
```
export AWS_ACCESS_KEY_ID=
export AWS_SECRET_ACCESS_KEY=
```
To set these variables on Windows, use **set**:
```
set AWS_ACCESS_KEY_ID=
set AWS_SECRET_ACCESS_KEY=
```
## Open the IDT-FreeRTOS UI
**To open the IDT-FreeRTOS UI**
1. Download a supported IDT-FreeRTOS version and extract the downloaded archive into a location on your file system where you have read and write permissions.
1. Run the following command to navigate to the IDT-FreeRTOS installation directory:
```
cd devicetester-extract-location/bin
```
1. Run the following command to open the IDT-FreeRTOS UI:
------
#### [ Linux ]
```
.devicetestergui_linux_x86-64.exe
```
------
#### [ Windows ]
```
./devicetestergui_win_x64-64
```
------
#### [ macOS ]
```
./devicetestergui_mac_x86-64
```
**Note**
On Mac, to allow your system to run the UI, go to **System Preferences -> Security & Privacy**. When you run the tests, you may need to do this three more times.
------
The IDT-FreeRTOS UI opens in your default browser. For information about supported browsers, see [Use a supported web browser](dev-tester-ui-prereqs.md#idt-ui-supported-web-browser).
## Create a new configuration
If you're a first-time user, then you must create a new configuration to set up the JSON configuration files that IDT-FreeRTOS requires to run tests. You can then run tests or modify the configuration that was created.
For examples of the `config.json`, `device.json`, and `userdata.json` files, see [First test of your microcontroller board](qual-steps.md). For an example of the `resource.json` file that is used only for running Bluetooth Low Energy (BLE) tests, see [Run Bluetooth Low Energy tests](afr-bridgekeeper-dt-bt.md).
**To create a new configuration**
1. In the IDT-FreeRTOS UI, open the navigation menu, and then choose **Create new configuration**.
**Important**
You must configure your AWS credentials before you open the UI. If you haven't configured your credentials, close the IDT-FreeRTOS UI browser window, follow the steps in [Configure AWS credentials](#configure-aws-credentials), and then reopen the IDT-FreeRTOS UI.
1. Follow the configuration wizard to enter the IDT configuration settings that are used to run qualification tests. The wizard configures the following settings in JSON configuration files that are located in the `devicetester-extract-location/config` directory.
+ **AWS settings**—The AWS account information that IDT-FreeRTOS uses to create AWS resources during test runs. These settings are configured in the `config.json` file.
+ **FreeRTOS repository**—The absolute path to the FreeRTOS repository and ported code, and the type of qualification you want to perform. These settings are configured in the `userdata.json` file.
You must port FreeRTOS for your device before you can run qualification tests. For more information, see the [FreeRTOS Porting Guide](https://docs.aws.amazon.com/freertos/latest/portingguide/)
+ **Build and flash**—The build and flash commands for your hardware that allow IDT to build and flash tests on to your board automatically. These settings are configured in the `userdata.json` file.
+ **Devices**—The device pool settings for the devices to be tested. These settings are configured in `id` and `sku` fields, and the `devices` block for the device pool in the `device.json` file.
+ **Networking**—The settings to test network communication support for your devices. These settings are configured in the `features` block of the `device.json` file, and in the `clientWifiConfig` and `testWifiConfig` blocks in the `userdata.json` file.
+ **Echo server**—The echo server configuration settings for secure socket tests. These settings are configured in the `userdata.json` file.
For more information about echo server configuration, see [https://docs.aws.amazon.com/freertos/latest/portingguide/afr-echo-server.html](https://docs.aws.amazon.com/freertos/latest/portingguide/afr-echo-server.html).
+ **CMake**—(Optional) The settings to run CMake build functionality tests. This configuration is required only if you're using CMake as your build system. These settings are configured in the `userdata.json` file.
+ **BLE**—The settings to run Bluetooth Low Energy functionality tests. These settings are configured in the `features` block of the `device.json` file and in the `resource.json` file.
+ **OTA**—The settings to run OTA functionality tests. These settings are configured in the `features` block of the `device.json` file and in the `userdata.json` file.
1. On the **Review** page, verify your configuration information.
After you finish reviewing your configuration, to run your qualification tests, choose **Run tests**.
## Modify an existing configuration
If you have already set up configuration files for IDT, then you can use the IDT-FreeRTOS UI to modify your existing configuration. Make sure that your existing configuration files are available in the `devicetester-extract-location/config` directory.
**To modify a new configuration**
1. In the IDT-FreeRTOS UI, open the navigation menu, and then choose **Edit existing configuration**.
The configuration dashboard displays information about your existing configuration settings. If a configuration is incorrect or unavailable, the status for that configuration is `Error validating configuration`.
1. To modify an existing configuration setting, complete the following steps:
1. Choose the name of a configuration setting to open its settings page.
1. Modify the settings, and then choose **Save** to regenerate the corresponding configuration file.
After you finish modifying your configuration, verify that all of your configuration settings pass validation. If the status for each configuration setting is `Valid`, you can run your qualification tests using this configuration.
## Run qualification tests
After you have created a configuration for IDT-FreeRTOS, you can run your qualification tests.
**To run qualification tests**
1. Validate your configuration.
1. In the navigation menu, choose **Run tests**.
1. To start the test run, choose **Start tests**.
IDT-FreeRTOS runs the qualification tests, and displays the test run summary and any errors in the **Test runner** console. After the test run is complete, you can view the test results and logs from the following locations:
+ Test results are located in the `devicetester-extract-location/results/execution-id` directory.
+ Test logs are located in the `devicetester-extract-location/results/execution-id/logs` directory.
For more information about test results and logs, see [View the IDT for FreeRTOS results](view-results-frq.md) and [View the IDT for FreeRTOS logs](view-logs-frq.md).