Setting up your AWS account and permissions Registering your MCU board with AWS IoT Downloading FreeRTOS Configuring the FreeRTOS demos

First steps

Important

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

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.
If you're using the Nordic nRF52840-DK, skip these steps and go to Getting started with the Nordic nRF52840-DK.

Setting up your AWS account and permissions
Registering your MCU board with AWS IoT
Downloading FreeRTOS
Configuring the FreeRTOS demos

Setting up your AWS account and permissions

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

To sign up for an AWS account

Open https://portal.aws.amazon.com/billing/signup.
Follow the online instructions.

Part of the sign-up procedure involves receiving a phone call 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.

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/ 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

Sign in to the AWS Management Console 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 in the AWS Sign-In User Guide.
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) in the IAM User Guide.

Create a user with administrative access

Enable IAM Identity Center.

For instructions, see Enabling AWS IAM Identity Center in the AWS IAM Identity Center User Guide.
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 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 in the AWS Sign-In User Guide.

Assign access to additional users

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 in the AWS IAM Identity Center User Guide.
Assign users to a group, and then assign single sign-on access to the group.

For instructions, see Add groups 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 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) 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 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) in the IAM User Guide.

Registering your MCU board with AWS IoT

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

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, 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. 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.
Browse to the AWS IoT console.
In the navigation pane, choose Secure, choose Policies, and then choose Create.
Enter a name to identify your policy.

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.


{
    "Version": "2012-10-17",
    "Statement": [
    {
        "Effect": "Allow",
        "Action": "iot:Connect",
        "Resource":"arn:aws:iot:aws-region:aws-account-id:*"
    }, 
    {
        "Effect": "Allow",
        "Action": "iot:Publish",
        "Resource": "arn:aws:iot:aws-region:aws-account-id:*"
    },
    {
         "Effect": "Allow",
         "Action": "iot:Subscribe",
         "Resource": "arn:aws:iot:aws-region:aws-account-id:*"
    },
    {
         "Effect": "Allow",
         "Action": "iot:Receive",
         "Resource": "arn:aws:iot:aws-region:aws-account-id:*"
    }
    ]
}

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.

Choose Create.

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

Browse to the AWS IoT console.
In the navigation pane, choose Manage, and then choose Things.
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.
On the Creating AWS IoT things page, choose Create a single thing.
On the Add your device to the thing registry page, enter a name for your thing, and then choose Next.
On the Add a certificate for your thing page, under One-click certificate creation, choose Create certificate.
Download your private key and certificate by choosing the Download links for each.
Choose Activate to activate your certificate. Certificates must be activated prior to use.
Choose Attach a policy to attach a policy to your certificate that grants your device access to AWS IoT operations.
Choose the policy you just created and choose Register thing.

After your board is registered with AWS IoT, you can continue to Downloading FreeRTOS.

Downloading FreeRTOS

You can download FreeRTOS from the FreeRTOS GitHub repository.

After you download FreeRTOS, you can continue to Configuring the FreeRTOS demos.

Configuring the FreeRTOS demos

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.

Browse to the AWS IoT console.
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.
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.
Open demos/include/aws_clientcredential.h.
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.

demos/include/aws_clientcredential.h.
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.

In a browser window, open tools/certificate_configuration/CertificateConfigurator.html.
Under Certificate PEM file, choose the ID-certificate.pem.crt that you downloaded from the AWS IoT console.
Under Private Key PEM file, choose the ID-private.pem.key that you downloaded from the AWS IoT console.
Choose Generate and save aws_clientcredential_keys.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. 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.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

FreeRTOS demo application

Troubleshooting

First steps

Important

Note

Setting up your AWS account and permissions

Sign up for an AWS account

To sign up for an AWS account

Create a user with administrative access

Secure your AWS account root user

Create a user with administrative access

Sign in as the user with administrative access

Assign access to additional users

Registering your MCU board with AWS IoT

To create an AWS IoT policy

Note

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

Downloading FreeRTOS

Configuring the FreeRTOS demos

To configure your AWS IoT endpoint

To configure your Wi-Fi

To format your AWS IoT credentials

Note

Note