Prerequisites
This section describes the prerequisites for testing microcontrollers with Amazon IoT Device Tester.
Prepare for FreeRTOS qualification
Note
Amazon IoT Device Tester for FreeRTOS strongly recommends using the latest patch release of the most recently FreeRTOS-LTS version.
IDT for FRQ 2.0 is a qualification for FreeRTOS. Before running IDT FRQ 2.0 for qualification,
you must complete Qualifying
your board in the FreeRTOS Qualification Guide. To port libraries,
tests, and setup the manifest.yml
, see Porting the FreeRTOS
libraries in the FreeRTOS Porting Guide. FRQ 2.0 contains a different
process for qualification. See Latest changes in
qualification in the FreeRTOS qualification guide for details.
The FreeRTOS-Libraries-Integration-Testsmanifest.yml
located
in the root of your project, for IDT to run.
Note
IDT is dependent on the tests repository's implementation of
UNITY_OUTPUT_CHAR
. The test output logs and the device logs must not
interleave with each other. See
Implementing the library logging macros section in the FreeRTOS Porting
Guide for further details.
Download IDT for FreeRTOS
Every version of FreeRTOS has a corresponding version of IDT for FreeRTOS to perform
qualification tests. Download the appropriate version of IDT for FreeRTOS from
Supported versions of Amazon IoT Device Tester for FreeRTOS
Extract IDT for FreeRTOS to a location on the file system where you have read and write
permissions. Since Microsoft Windows has a character limit for the path length, extract IDT
for FreeRTOS into a root directory such as C:\
or
D:\
.
Note
Multiple users must not run IDT from a shared location, such as an NFS directory or a Windows network shared folder. This will result in crashes or data corruption. We recommend that you extract the IDT package to a local drive.
Download Git
IDT must have Git installed as a prerequisite to ensure source code integrity.
Follow the instructions in the GitHubgit --version
at the terminal.
Warning
IDT uses Git to align with a directory's status of clean or dirty. If Git is not
installed, the FreeRTOSIntegrity
test groups will either fail, or won't run as
expected. If IDT returns an error such as git executable not found
or
git command not found
, install or re-install Git and try again.
Create and configure an Amazon account
Note
The full IDT qualification suite is supported only in the following Amazon Web Services Regions
-
US East (N. Virginia)
-
US West (Oregon)
-
Asia Pacific (Tokyo)
-
Europe (Ireland)
In order to test your device, IDT for FreeRTOS creates resources like Amazon IoT things, FreeRTOS groups and Lambda functions. To create those resources, IDT for FreeRTOS requires you to create and configure an Amazon account, and an IAM policy that grants IDT for FreeRTOS permission to access resources on your behalf while running tests.
The following steps are to create and configure your Amazon account.
-
If you already have an Amazon account, skip to the next step. Else create an Amazon account
. -
Follow the steps in Creating IAM roles. Do not add permissions or policies at this time.
-
To run OTA qualification tests, go to Step 4. Else go to Step 5.
-
Attach the OTA IAM permissions inline policy to your IAM role.
-
Important
The following policy template grants IDT permission to create roles, create policies, and attach policies to roles. IDT for FreeRTOS uses these permissions for tests that create roles. Although the policy template doesn't provide administrator privileges to the user, the permissions can be used to gain administrator access to your Amazon account.
-
Follow the steps below to attach the necessary permissions to your IAM role:
-
On the Permissions page, choose Add permissions.
-
Choose Create inline policy.
-
Choose the JSON tab and copy the following permissions in to the JSON text box. Use the template under Most Regions if you are not in the China region. If you are in the China region, use the template under Beijing and Ningxia Regions.
-
When you're finished, choose Review policy.
-
Enter IDTFreeRTOSIAMPermissions as the policy name.
-
Choose Create policy.
-
-
-
Attach AWSIoTDeviceTesterForFreeRTOSFullAccess to your IAM role.
-
To attach the necessary permissions to your IAM role:
-
On the Permissions page, choose Add permissions.
-
Choose Attach policies.
-
Search for the AWSIoTDeviceTesterForFreeRTOSFullAccess policy. Check the box.
-
-
Choose Add permissions.
-
-
Export credentials for IDT. See Getting IAM role credentials for CLI access for details.
Amazon IoT Device Tester managed policy
The AWSIoTDeviceTesterForFreeRTOSFullAccess
managed policy contains the
following Amazon IoT Device Tester permissions for version checking, auto update features, and collection of metrics.
-
iot-device-tester:SupportedVersion
Grants Amazon IoT Device Tester permission to fetch the list of supported products, test suites and IDT versions.
-
iot-device-tester:LatestIdt
Grants Amazon IoT Device Tester permission to fetch the latest IDT version available for download.
-
iot-device-tester:CheckVersion
Grants Amazon IoT Device Tester permission to check version compatibility for IDT, test suites and products.
-
iot-device-tester:DownloadTestSuite
Grants Amazon IoT Device Tester permission to download test suite updates.
-
iot-device-tester:SendMetrics
Grants Amazon permission to collect metrics about Amazon IoT Device Tester internal usage.
(Optional) Install the Amazon Command Line Interface
You might prefer to use the Amazon CLI to perform some operations. If you don't have the Amazon CLI installed, follow the instructions at Install the Amazon CLI.
Configure the Amazon CLI for the Amazon Region you want to use by running aws configure from a command line. For information about the Amazon Regions that support IDT for FreeRTOS, see Amazon Regions and Endpoints. For more information about aws configure see Quick configuration with aws configure.